diff --git a/flang/README.md b/flang/README.md --- a/flang/README.md +++ b/flang/README.md @@ -36,6 +36,105 @@ 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. + +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 +``` +### Building flang standalone +To do the standalone build, start 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 +154,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 +165,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 +181,7 @@ CXX should include the full path to clang++ or clang++ should be found on your PATH. -``` +```bash export CXX=clang++ ``` @@ -138,31 +208,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 +236,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 +256,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 +298,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/ ```