Magic-Mirror/llvm-capstone
1
0
Fork 0
mirror of https://github.com/capstone-engine/llvm-capstone.git synced 2024-12-12 18:02:43 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[flang] Fix the documentation on how to build flang

Browse Source 
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
This commit is contained in:
Peter Steinfeld 2022-01-03 16:13:28 -08:00
parent 4609e30f50
commit c0add1636d
1 changed files with 134 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
flang/README.md
View File

@ -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/
```