[flang-commits] [flang] c0add16 - [flang] Fix the documentation on how to build flang
Peter Steinfeld via flang-commits
flang-commits at lists.llvm.org
Mon Jan 10 11:54:17 PST 2022
Author: Peter Steinfeld
Date: 2022-01-10T11:54:00-08:00
New Revision: c0add1636d3a8ddb35b223b9684ec35ae34bf867
URL: https://github.com/llvm/llvm-project/commit/c0add1636d3a8ddb35b223b9684ec35ae34bf867
DIFF: https://github.com/llvm/llvm-project/commit/c0add1636d3a8ddb35b223b9684ec35ae34bf867.diff
LOG: [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
Added:
Modified:
flang/README.md
Removed:
################################################################################
diff --git a/flang/README.md b/flang/README.md
index eef0a1cad6cff..bf6517f759f27 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
diff erent 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/
```
More information about the flang-commits
mailing list