[flang] [NFC] Adjust README.md for upstreaming.

This changes the references and build instructions for Flang so that
they are correct now that F18 has been rechristened Flang and merged
with LLVM.

Reviewed at: flang-compiler/f18#909

Author: DavidTruby

flang/README.md

@@ -1,30 +1,21 @@
-<!--===- README.md
+# Flang
 
-   Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
-   See https://llvm.org/LICENSE.txt for license information.
-   SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-
--->
-
-# F18
-
-F18 is a ground-up implementation of a Fortran front end written in modern C++.
-F18, when combined with LLVM, is intended to replace the Flang compiler.
-
-Flang is a Fortran compiler targeting LLVM.
-Visit the [Flang wiki](https://github.com/flang-compiler/flang/wiki)
-for more information about Flang.
+Flang is a ground-up implementation of a Fortran front end written in modern
+C++. It started off as the f18 project (https://github.com/flang-compiler/f18)
+with an aim to replace the previous flang project
+(https://github.com/flang-compiler/flang) and address its various deficiencies.
+F18 was subsequently accepted into the LLVM project and rechristened as Flang.
 
 ## Getting Started
 
-Read more about f18 in the [documentation directory](documentation).
+Read more about flang in the [documentation directory](documentation).
 Start with the [compiler overview](documentation/Overview.md).
 
 To better understand Fortran as a language
-and the specific grammar accepted by f18,
+and the specific grammar accepted by flang,
 read [Fortran For C Programmers](documentation/FortranForCProgrammers.md)
 and
-f18's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
+flang's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
 and
 the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt).
 
@@ -34,49 +25,52 @@ in [this document](documentation/Extensions.md).
 To understand the compilers handling of intrinsics,
 see the [discussion of intrinsics](documentation/Intrinsics.md).
 
-To understand how an f18 program communicates with libraries at runtime,
+To understand how a flang program communicates with libraries at runtime,
 see the discussion of [runtime descriptors](documentation/RuntimeDescriptor.md).
 
 If you're interested in contributing to the compiler,
 read the [style guide](documentation/C++style.md)
 and
-also review [how f18 uses modern C++ features](documentation/C++17.md).
+also review [how flang uses modern C++ features](documentation/C++17.md).
 
-## Building F18
-
-### Get the Source Code
-
-```
-cd where/you/want/the/source
-git clone https://github.com/flang-compiler/f18.git
-```
+## Supported C++ compilers
 
-### Supported C++ compilers
-
-F18 is written in C++17.
+Flang is written in C++17.
 
 The code has been compiled and tested with
-GCC versions 7.2.0, 7.3.0, 8.1.0, and 8.2.0.
+GCC versions from 7.2.0 to 9.3.0.
 
 The code has been compiled and tested with
-clang version 7.0 and 8.0
+clang version 7.0, 8.0, 9.0 and 10.0
 using either GNU's libstdc++ or LLVM's libc++.
 
-### LLVM dependency
+The code has been compiled on
+AArch64, x86\_64 and ppc64le servers
+with CentOS7, Ubuntu18.04, Rhel, MacOs, Mojave, XCode and
+Apple Clang version 10.0.1.
 
-F18 uses components from LLVM.
+The code does not compile with Windows and a compiler that does not have
+support for C++17.
+
+## Building Flang out of tree
+These instructions are for building Flang separately from LLVM; if you are
+building Flang alongside LLVM then follow the standard LLVM build instructions
+and add flang to `LLVM_ENABLE_PROJECTS` instead, as detailed there.
+
+### LLVM dependency
 
 The instructions to build LLVM can be found at
-https://llvm.org/docs/GettingStarted.html.
+https://llvm.org/docs/GettingStarted.html. If you are building flang as part
+of LLVM, follow those instructions and add flang to `LLVM_ENABLE_PROJECTS`.
 
-We highly recommend using the same compiler to compile both llvm and f18.
+We highly recommend using the same compiler to compile both llvm and flang.
 
-The f18 CMakeList.txt file uses
+The flang CMakeList.txt file uses
 the variable `LLVM_DIR` to find the installed LLVM components
 and
 the variable `MLIR_DIR` to find the installed MLIR components.
 
-To get the correct LLVM and MLIR libraries included in your f18 build,
+To get the correct LLVM and MLIR libraries included in your flang build,
 define LLVM_DIR and MLIR_DIR on the cmake command line.
 ```
 LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm \
@@ -86,71 +80,17 @@ cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ...
 where `LLVM_BUILD_DIR` is
 the top-level directory where LLVM was built.
 
-### LLVM dependency when building f18 with Fortran IR
-
-If you do not want to build Fortran IR, add `-DLINK_WITH_FIR=Off` to f18 cmake
-command and ignore the rest of this section.
-
-If you intend to build f18 with Fortran IR (`-DLINK_WITH_FIR` On by default),
-you must:
-- build LLVM with the same compiler and options as the one you are using
-to build F18.
-- pass `-DCMAKE_CXX_STANDARD=17 -DLLVM_ENABLE_PROJECTS="mlir"`
-to LLVM cmake command.
-- install LLVM somewhere with `make install` in order to get the required
-AddMLIR cmake file (it is not generated in LLVM build directory).
-
-Installing LLVM from packages is most likely not an option as it will not include
-MLIR and not be built following C++17 standard.
-
-MLIR is under active development and the most recent development version
-may be incompatible. A branch named `f18` is available inside LLVM fork in
-https://github.com/flang-compiler/f18-llvm-project. It contains a version of LLVM
-that is known be compatible to build f18 with FIR.
-
-The fastest way to get set up is to do:
-
-```
-cd where/you/want/to/build/llvm
-git clone --depth=1 -b f18 https://github.com/flang-compiler/f18-llvm-project.git
-mkdir build
-mkdir install
-cd build
-cmake ../f18-llvm-project/llvm -DCMAKE_BUILD_TYPE=Release \
-    -DLLVM_ENABLE_PROJECTS=mlir -DCMAKE_CXX_STANDARD=17 \
-    -DLLVM_INSTALL_UTILS=On \
-    -DCMAKE_INSTALL_PREFIX=../install
-make
-make install
-```
-
-Then, `-DLLVM_DIR` would have to be set to
- `<where/you/want/to/build/llvm>/install/lib/cmake/llvm`
-and, `-DMLIR_DIR` would have to be set to
- `<where/you/want/to/build/llvm>/install/lib/cmake/mlir`
-
-in f18 cmake command.
-
-To run lit tests,
-`-DLLVM_EXTERNAL_LIT=<where/you/want/to/build/llvm>/build/bin/llvm-lit` must be
-added to f18 cmake command. This is because `llvm-lit` is not part of
-LLVM installation.
-
-Note that when using some advanced options from f18 cmake file it may be
-necessary to reproduce their effects in LLVM cmake command.
-
-### Building f18 with GCC
+### Building flang with GCC
 
 By default,
 cmake will search for g++ on your PATH.
 The g++ version must be one of the supported versions
-in order to build f18.
+in order to build flang.
+
+Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
+the full path to the compiler or a name that will be found on your PATH, e.g.
+g++-8.3, assuming g++-8.3 is on your PATH.
 
-Or,
-cmake will use the variable CXX to find the C++ compiler.
-CXX should include the full path to the compiler
-or a name that will be found on your PATH,
-e.g. g++-8.3, assuming g++-8.3 is on your PATH.
 ```
 export CXX=g++-8.3
 ```
@@ -159,9 +99,9 @@ or
 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
 ```
 
-### Building f18 with clang
+### Building flang with clang
 
-To build f18 with clang,
+To build flang with clang,
 cmake needs to know how to find clang++
 and the GCC library and tools that were used to build clang++.
 
@@ -178,7 +118,7 @@ add
 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
 to the cmake command
 where `<INSTALL_PREFIX>`
-is the path where f18 should be installed.
+is the path where flang should be installed.
 
 ### Build Types
 
@@ -194,29 +134,28 @@ add
 to the cmake command.
 Release builds execute quickly.
 
-### Build F18
+### Build Flang out of tree
 ```
-cd ~/f18/build
-cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/f18/src
+cd ~/flang/build
+cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
 make
 ```
-
 ### How to Run the Regression Tests
 
 To run all tests:
 ```
-cd ~/f18/build
-cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/f18/src
+cd ~/flang/build
+cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
 make test check-all
 ```
 
 To run individual regression tests llvm-lit needs to know the lit
-configuration for f18. The parameters in charge of this are:
+configuration for flang. The parameters in charge of this are:
 flang_site_config and flang_config. And they can be set as shown bellow:
 ```
 <path-to-llvm-lit>/llvm-lit \
- --param flang_site_config=<path-to-f18-build>/test-lit/lit.site.cfg.py \
- --param flang_config=<path-to-f18-build>/test-lit/lit.cfg.py \
+ --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
+ --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
   <path-to-fortran-test>
 ```