diff --git a/flang/README.md b/flang/README.md --- a/flang/README.md +++ b/flang/README.md @@ -36,6 +36,106 @@ 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= + +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 +155,6 @@ 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=/lib/cmake/llvm \ -MLIR=/lib/cmake/mlir \ -CLANG=/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 +166,11 @@ 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 +182,7 @@ CXX should include the full path to clang++ or clang++ should be found on your PATH. -``` +```bash export CXX=clang++ ``` @@ -138,31 +209,24 @@ 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 /llvm-lit \ --param flang_site_config=/test-lit/lit.site.cfg.py \ --param flang_config=/test-lit/lit.cfg.py \ @@ -173,17 +237,17 @@ 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. /llvm-lit \ test/Unit -4. Invoking tests from /unittests/ +4. Invoking tests from /unittests/ ``` @@ -193,34 +257,34 @@ 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 /tools/flang/docs/doxygen/html # for flang docs ``` ## Generate Sphinx-based Documentation @@ -235,14 +299,14 @@ - 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 /tools/flang/docs/html/ ```