diff --git a/flang/README.md b/flang/README.md --- a/flang/README.md +++ b/flang/README.md @@ -36,6 +36,101 @@ 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 out of tree. Building out of tree has the advantage of being smaller +and faster. Once you create the base build and base install areas, you can +create multiple out of tree 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 include llvm, mlir, clang, and compiler-rt. + +First clone the source for llvm-project, and then `cd` into the root directory +that contains the llvm, clang, mlir, flang, and compiler-rt directories. Then +execute the following commands, to do the build: +``` +INSTALLDIR=`pwd`/install + +rm -rf build +rm -rf install +mkdir -p build + +cd build + +cmake \ + -G Ninja \ + ../llvm \ + -DCMAKE_BUILD_TYPE=Release \ + -DLLVM_LIT_ARGS=-v \ + -DFLANG_ENABLE_WERROR=On \ + -DCMAKE_CXX_STANDARD=17 \ + -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;compiler-rt" \ + -DLLVM_BUILD_TOOLS=On \ + -DLLVM_INSTALL_UTILS=On \ + -DLLVM_TARGETS_TO_BUILD=host \ + -DLLVM_ENABLE_ASSERTIONS=ON \ + -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \ + -DCMAKE_INSTALL_PREFIX=$INSTALLDIR + +ninja +``` + +To run the flang tests on this build, execute the command in the "build" +directory: +``` +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: +``` +ninja install +``` +### Building flang out of tree +To do the out of tree build, start the same way by cloning the source for +llvm-project, and then `cd` into the root directory that contains the llvm, +clang, mlir, flang, and compiler-rt directories. Then execute the following +commands, to do the build: +``` +base= + +cd flang +rm -rf build +mkdir build +cd build + +cmake \ + -G Ninja \ + -DCMAKE_BUILD_TYPE=Release \ + -DLLVM_DIR=$base/build/lib/cmake/llvm \ + -DCLANG_DIR=$base/install/lib/cmake/clang \ + -DMLIR_DIR=$base/install/lib/cmake/mlir \ + -DLLVM_LIT_ARGS=-v \ + -DFLANG_ENABLE_WERROR=On \ + -DCMAKE_CXX_STANDARD=17 \ + -DLLVM_TARGETS_TO_BUILD=host \ + -DLLVM_ENABLE_ASSERTIONS=On \ + -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \ + -DLLVM_EXTERNAL_LIT=$base/build/bin/llvm-lit \ + -DLLVM_BUILD_MAIN_SRC_DIR=$base/build/lib/cmake/llvm \ + .. + +ninja +``` +To run the flang tests on this build, execute the command in the "flang/build" +directory: +``` +ninja check-flang +``` + ## Supported C++ compilers Flang is written in C++17. @@ -55,35 +150,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, @@ -138,13 +204,6 @@ 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 @@ -156,7 +215,7 @@ ``` 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 @@ -179,8 +238,8 @@ ``` -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/ @@ -194,18 +253,18 @@ To run all of the flang unit tests use the `check-flang-unit` target: ``` -make check-flang-unit +ninja check-flang-unit ``` To run all of the flang regression tests use the `check-flang` target: ``` -make check-flang +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 @@ -215,7 +274,7 @@ ``` 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 @@ -238,7 +297,7 @@ ``` 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