[flang] Fix the documentation on how to build flang

I recently had an email exchange on flang-dev that revealed that the
documentation on how to build flang is incorrect.  This update fixes
that.

Differential Revision: https://reviews.llvm.org/D116566

1 files changed, 134 insertions, 58 deletions

diff --git a/flang/README.md b/flang/README.md
index eef0a1cad6cf..bf6517f759f2 100644
--- a/flang/README.md
+++ b/flang/README.md
@@ -36,6 +36,118 @@ also review [how flang uses modern C++ features](docs/C++17.md).
 If you are interested in writing new documentation, follow 
 [markdown style guide from LLVM](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
 
+## Building flang
+There are two ways to build flang.  The first method is to build it at the same
+time that you build all of the projects on which it depends.  This is called
+building in tree.  The second method is to first do an in tree build to create
+all of the projects on which flang depends, then build an install area for
+these projects, and then only build the flang code itself.  This is called
+building standalone.  Building standalone has the advantage of being smaller
+and faster.  Once you create the base build and base install areas, you can
+create multiple standalone builds using them.  
+
+Note that instructions for building LLVM can be found at
+https://llvm.org/docs/GettingStarted.html.
+
+### Building flang in tree
+Building flang in tree means building flang along with all of the projects on
+which it depends.  These projects include mlir, clang, flang, and compiler-rt.
+Note that compiler-rt is only needed to access libraries that support 16 bit
+floating point numbers.  It's not needed to run the automated tests.
+
+Here's a complete set of commands to clone all of the necessary source and do
+the build.  
+
+First clone the source:
+```bash
+git clone https://github.com/llvm/llvm-project.git my-project
+```
+Once the clone is complete, execute the following commands:
+```bash
+cd my-project
+INSTALLDIR=`pwd`/install
+
+rm -rf build
+rm -rf install
+mkdir -p build
+
+cd build
+
+cmake \
+  -G Ninja \
+  ../llvm \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DFLANG_ENABLE_WERROR=On \
+  -DLLVM_ENABLE_ASSERTIONS=ON \
+  -DLLVM_TARGETS_TO_BUILD=host \
+  -DCMAKE_INSTALL_PREFIX=$INSTALLDIR
+  -DLLVM_LIT_ARGS=-v \
+  -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;compiler-rt"
+
+ninja
+```
+
+To run the flang tests on this build, execute the command in the "build"
+directory:
+```bash
+ninja check-flang
+```
+
+If you're happy with the results, the next step is to create the install area.
+While in the `build` directory, run the command:
+```bash
+ninja install
+```
+
+Note that these instructions specify flang as one of the projects to build in
+the in tree build.  This is not strictly necessary for subsequent standalone
+builds, but doing so lets you run the flang tests to verify that the source
+code is in good shape.
+### Building flang standalone
+To do the standalone build, start by building flang in tree as described above.
+This build is base build for subsequent standalone builds.  Start each
+standalone build the same way by cloning the source for llvm-project:
+```bash
+git clone https://github.com/llvm/llvm-project.git standalone
+```
+Once the clone is complete, execute the following commands:
+```bash
+cd standalone
+base=<directory that contains the in tree build>
+
+cd flang
+rm -rf build
+mkdir build
+cd build
+
+cmake \
+  -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DFLANG_ENABLE_WERROR=On \
+  -DLLVM_TARGETS_TO_BUILD=host \
+  -DLLVM_ENABLE_ASSERTIONS=On \
+  -DLLVM_BUILD_MAIN_SRC_DIR=$base/build/lib/cmake/llvm \
+  -DLLVM_LIT_ARGS=-v \
+  -DLLVM_DIR=$base/build/lib/cmake/llvm \
+  -DCLANG_DIR=$base/install/lib/cmake/clang \
+  -DMLIR_DIR=$base/install/lib/cmake/mlir \
+  ..
+
+ninja
+```
+Note that for Clang and MLIR you use the installation directory ($base/install)
+and for LLVM you use the build directory (`$base/build`).   This is not a typo
+in the script.  Rather, it is because running the tests requires the GTest
+infrastructure which is only available in the LLVM build area.  The build also
+requires the `AddClang.cmake` script from Clang, which is only available in the
+install area.
+
+To run the flang tests on this build, execute the command in the "flang/build"
+directory:
+```bash
+ninja check-flang
+```
+
 ## Supported C++ compilers
 
 Flang is written in C++17.
@@ -55,35 +167,6 @@ Apple Clang version 10.0.1.
 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. 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 flang.
-
-The flang CMakeList.txt file uses
-* `LLVM_DIR` to find the installed LLVM components
-* `MLIR_DIR` to find the installed MLIR components
-* `CLANG_DIR` to find the installed Clang components
-
-To get the correct LLVM, MLIR and Clang libraries included in your flang build,
-define `LLVM_DIR`, `MLIR_DIR` and `CLANG_DIR` on the cmake command line.
-```
-LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm \
-MLIR=<LLVM_BUILD_DIR>/lib/cmake/mlir \
-CLANG=<LLVM_BUILD_DIR>/lib/cmake/clang \
-cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR -DCLANG_DIR=$CLANG ...
-```
-where `LLVM_BUILD_DIR` is
-the top-level directory where LLVM was built.
-
 ### Building flang with GCC
 
 By default,
@@ -95,11 +178,11 @@ 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.
 
-```
+```bash
 export CXX=g++-8.3
 ```
 or
-```
+```bash
 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
 ```
 
@@ -111,7 +194,7 @@ and the GCC library and tools that were used to build clang++.
 
 CXX should include the full path to clang++
 or clang++ should be found on your PATH.
-```
+```bash
 export CXX=clang++
 ```
 
@@ -138,31 +221,24 @@ add
 to the cmake command.
 Release builds execute quickly.
 
-### Build Flang out of tree
-```
-cd ~/flang/build
-cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR -DCLANG_DIR=$CLANG ~/flang/src
-make
-```
-
 # How to Run Tests
 
 Flang supports 2 different categories of tests
 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
 
-## For out of tree builds
+## For standalone builds
 To run all tests:
-```
+```bash
 cd ~/flang/build
 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
-make test check-all
+ninja check-all
 ```
 
 To run individual regression tests llvm-lit needs to know the lit
 configuration for flang. The parameters in charge of this are:
 flang_site_config and flang_config. And they can be set as shown below:
-```
+```bash
 <path-to-llvm-lit>/llvm-lit \
  --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 \
@@ -173,17 +249,17 @@ flang_site_config and flang_config. And they can be set as shown below:
 Unit tests:
 
 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`ON` by default), it is possible to generate unittests.
-Note: Unit-tests will be skipped for LLVM install for an out-of-tree build as it does not include googletest related headers and libraries.
+Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries.
 
 There are various ways to run unit-tests.
 
 ```
 
-1. make check-flang-unit
-2. make check-all or make check-flang
+1. ninja check-flang-unit
+2. ninja check-all or ninja check-flang
 3. <path-to-llvm-lit>/llvm-lit \
         test/Unit
-4. Invoking tests from <out-of-tree flang build>/unittests/<respective unit test folder>
+4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
 
 ```
 
@@ -193,34 +269,34 @@ If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`On` by default), it is poss
 generate unittests.
 
 To run all of the flang unit tests use the `check-flang-unit` target:
-```
-make check-flang-unit
+```bash
+ninja check-flang-unit
 ```
 To run all of the flang regression tests use the `check-flang` target:
-```
-make check-flang
+```bash
+ninja check-flang
 ```
 
 # How to Generate Documentation
 
 ## Generate FIR Documentation
 If flang was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
-generate FIR language documentation by running `make flang-doc`. This will
+generate FIR language documentation by running `ninja flang-doc`. This will
 create `docs/Dialect/FIRLangRef.md` in flang build directory.
 
 ## Generate Doxygen-based Documentation
 To generate doxygen-style documentation from source code
 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
 
-```
+```bash
 cd ~/llvm-project/build
 cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
-make doxygen-flang
+ninja doxygen-flang
 ```
 
 It will generate html in
 
-```
+```bash
     <build-dir>/tools/flang/docs/doxygen/html # for flang docs
 ```
 ## Generate Sphinx-based Documentation
@@ -235,14 +311,14 @@ If you would like to generate and view the HTML locally:
 - Install [Sphinx](http://sphinx-doc.org/), including the [sphinx-markdown-tables](https://pypi.org/project/sphinx-markdown-tables/) extension.
 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
 
-```
+```bash
 cd ~/llvm-project/build
 cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
-make docs-flang-html
+ninja docs-flang-html
 ```
 
 It will generate html in
 
-```
+```bash
    $BROWSER <build-dir>/tools/flang/docs/html/
 ```