llvm-project/flang/README.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

311 lines
9.2 KiB
Markdown
Raw Normal View History

# Flang
Flang is a ground-up implementation of a Fortran front end written in modern
C++. It started off as the f18 project (https://github.com/flang-compiler/f18)
with an aim to replace the previous flang project
(https://github.com/flang-compiler/flang) and address its various deficiencies.
F18 was subsequently accepted into the LLVM project and rechristened as Flang.
## Getting Started
Read more about flang in the [docs directory](docs).
Start with the [compiler overview](docs/Overview.md).
To better understand Fortran as a language
and the specific grammar accepted by flang,
read [Fortran For C Programmers](docs/FortranForCProgrammers.md)
and
2020-10-11 04:10:53 +08:00
flang's specifications of the [Fortran grammar](docs/f2018-grammar.md)
and
2020-10-11 04:10:53 +08:00
the [OpenMP grammar](docs/OpenMP-4.5-grammar.md).
Treatment of language extensions is covered
in [this document](docs/Extensions.md).
To understand the compilers handling of intrinsics,
see the [discussion of intrinsics](docs/Intrinsics.md).
To understand how a flang program communicates with libraries at runtime,
see the discussion of [runtime descriptors](docs/RuntimeDescriptor.md).
If you're interested in contributing to the compiler,
read the [style guide](docs/C++style.md)
and
also review [how flang uses modern C++ features](docs/C++17.md).
If you are interested in writing new documentation, follow
[LLVM's Markdown style guide](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, 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
rm -rf build
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" \
-DLLVM_ENABLE_RUNTIMES="compiler-rt"
ninja
```
To run the flang tests on this build, execute the command in the "build"
directory:
```bash
ninja check-flang
```
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/build/lib/cmake/clang \
-DMLIR_DIR=$base/build/lib/cmake/mlir \
..
ninja
```
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.
The code has been compiled and tested with
GCC versions from 7.2.0 to 9.3.0.
The code has been compiled and tested with
clang version 7.0, 8.0, 9.0 and 10.0
using either GNU's libstdc++ or LLVM's libc++.
The code has been compiled on
AArch64, x86\_64 and ppc64le servers
with CentOS7, Ubuntu18.04, Rhel, MacOs, Mojave, XCode and
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 with GCC
By default,
cmake will search for g++ on your PATH.
The g++ version must be one of the supported versions
in order to build flang.
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 ...
```
### Building flang with clang
To build flang with clang,
cmake needs to know how to find clang++
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++
```
### Installation Directory
To specify a custom install location,
add
`-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
to the cmake command
where `<INSTALL_PREFIX>`
is the path where flang should be installed.
### Build Types
To create a debug build,
add
`-DCMAKE_BUILD_TYPE=Debug`
to the cmake command.
Debug builds execute slowly.
To create a release build,
add
`-DCMAKE_BUILD_TYPE=Release`
to the cmake command.
Release builds execute quickly.
# 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 standalone builds
To run all tests:
```bash
cd ~/flang/build
cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
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 \
<path-to-fortran-test>
```
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 standalone build as it does not include googletest related headers and libraries.
There are various ways to run unit-tests.
```
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 <standalone flang build>/unittests/<respective unit test folder>
```
## For in tree builds
If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`On` by default), it is possible to
generate unittests.
To run all of the flang unit tests use the `check-flang-unit` target:
```bash
ninja check-flang-unit
```
To run all of the flang regression tests use the `check-flang` target:
```bash
ninja check-flang
```
[flang] Add Fortran IR (FIR) MLIR dialect implementation (flang-compiler/f18#1035) Adds FIR library that implements an MLIR dialect to which Fortran parse-tree will be lowered to. FIR is defined and documented inside FIROps.td added in this commit. It is possible to generate a more readable description FIRLangRef.md from FIROps.td following the related instructions added to the README.md by this commit. This patch adds FIR definition and implementation that allow parsing, printing, and verifying FIR. FIR transformations and lowering to Standard and LLVM dialects are not part of this patch. The FIR verifiers are verifying the basic properties of FIR operations in order to provide a sufficient frame for lowering. Verifiers for more advanced FIR properties can be added as needed. Coarrays are not covered by FIR defined in this patch. This patch also adds tco tool that is meant to process FIR input files and drives transformations on it. The tco tool is used for testing. In this patch, it is only used to demonstrate parsing/verifying/ and dumping FIR with round-trip tests. Note: This commit does not reflect an actual work log, it is a feature-based split of the changes done in the FIR experimental branch. The related work log can be found in the commits between: https://github.com/schweitzpgi/f18/commit/742edde572bd74d77cf7d447132ccf0949187fce and https://github.com/schweitzpgi/f18/commit/2ff55242126d86061f4fed9ef7b59d3636b5fd0b Changes on top of these original commits were made during this patch review. Original-commit: flang-compiler/f18@30b428a51e140e5fb12bd53a0619f10ff510f408 Reviewed-on: https://github.com/flang-compiler/f18/pull/1035
2020-03-12 12:47:22 +08:00
# How to Generate Documentation
[flang] Add Fortran IR (FIR) MLIR dialect implementation (flang-compiler/f18#1035) Adds FIR library that implements an MLIR dialect to which Fortran parse-tree will be lowered to. FIR is defined and documented inside FIROps.td added in this commit. It is possible to generate a more readable description FIRLangRef.md from FIROps.td following the related instructions added to the README.md by this commit. This patch adds FIR definition and implementation that allow parsing, printing, and verifying FIR. FIR transformations and lowering to Standard and LLVM dialects are not part of this patch. The FIR verifiers are verifying the basic properties of FIR operations in order to provide a sufficient frame for lowering. Verifiers for more advanced FIR properties can be added as needed. Coarrays are not covered by FIR defined in this patch. This patch also adds tco tool that is meant to process FIR input files and drives transformations on it. The tco tool is used for testing. In this patch, it is only used to demonstrate parsing/verifying/ and dumping FIR with round-trip tests. Note: This commit does not reflect an actual work log, it is a feature-based split of the changes done in the FIR experimental branch. The related work log can be found in the commits between: https://github.com/schweitzpgi/f18/commit/742edde572bd74d77cf7d447132ccf0949187fce and https://github.com/schweitzpgi/f18/commit/2ff55242126d86061f4fed9ef7b59d3636b5fd0b Changes on top of these original commits were made during this patch review. Original-commit: flang-compiler/f18@30b428a51e140e5fb12bd53a0619f10ff510f408 Reviewed-on: https://github.com/flang-compiler/f18/pull/1035
2020-03-12 12:47:22 +08:00
## 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 `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
ninja doxygen-flang
```
It will generate html in
```bash
<build-dir>/tools/flang/docs/doxygen/html # for flang docs
```
## Generate Sphinx-based Documentation
<!TODO: Add webpage once we have a website.
!>
Flang documentation should preferably be written in `markdown(.md)` syntax (they can be in `reStructuredText(.rst)` format as well but markdown is recommended in first place), it
is mostly meant to be processed by the Sphinx documentation generation
system to create HTML pages which would be hosted on the webpage of flang and
updated periodically.
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
ninja docs-flang-html
```
It will generate html in
```bash
$BROWSER <build-dir>/tools/flang/docs/html/
```