commit | 7f424da7da02d44c08b1543da5c01663bad37966 | [log] [tgz] |
---|---|---|
author | Andrzej Warzynski <andrzej.warzynski@arm.com> | Wed Jun 30 10:57:48 2021 +0000 |
committer | Copybara-Service <copybara-worker@google.com> | Thu Aug 05 21:24:39 2021 -0700 |
tree | 4bc90385d0f439be7fd59c584168a21f91c0c5a8 | |
parent | 167b0e6518d31b0d1e079d4b311b5b552af37bc6 [diff] |
[flang][driver] Refactor boolean options For boolean options, e.g. `-fxor-operator`/`-fno-xor-operator`, we ought to be using TableGen multi-classes. This way, we only have to write one definition to have both forms auto-generated. This patch refactors all of Flang's boolean options to use two new multi-classes: `OptInFC1FFOption` and `OptOutFC1FFOption`. These multi-classes are based on `OptInFFOption`/`OptOutFFOption`, respectively. I've also simplified the processing of the updated options in CompilerInvocation.cpp. With the new approach, "empty" help text (i.e. no `HelpText`) is now replaced with an empty string (i.e. HelpText<"">). When running flang-new --help, that's considered as non-empty help messages, which is then printed (that's controlled by `printHelp` from llvm/lib/Option/OptTable.cpp). This means that with this patch, flang-new --help will start printing e.g. -fno-backslash, even though there is no actual help text to print for this option (apart from the empty string ""). Tests are updated accordingly. Note that with this patch, both `-fxor-operator` and `-fno-xor-operator` (and other boolean options refactored here) remain available in `flang-new` and `flang-new -fc1`. In this respect, nothing changes. In a forthcoming patch, I will refine this so that `flang-new -fc1` only accepts `-ffoo` (`OptInFC1FFOption`) or `-fno-foo` (`OptOutCC1FFOption`). For clarity, `OptInFFOption`/`OptOutFFOption` are renamed as `OptInCC1FFOption`/`OptOutCC1FFOption`, respectively. Otherwise, this is an NFC from Clang's perspective. Differential Revision: https://reviews.llvm.org/D105881 GitOrigin-RevId: 55a96155995465416118774add8ef09c30dbebda
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.
Read more about flang in the docs directory. Start with the compiler overview.
To better understand Fortran as a language and the specific grammar accepted by flang, read Fortran For C Programmers and flang's specifications of the Fortran grammar and the OpenMP grammar.
Treatment of language extensions is covered in this document.
To understand the compilers handling of intrinsics, see the discussion of intrinsics.
To understand how a flang program communicates with libraries at runtime, see the discussion of runtime descriptors.
If you're interested in contributing to the compiler, read the style guide and also review how flang uses modern C++ features.
If you are interested in writing new documentation, follow markdown style guide from LLVM.
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.
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.
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 componentsMLIR_DIR
to find the installed MLIR componentsCLANG_DIR
to find the installed Clang componentsTo 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.
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.
export CXX=g++-8.3
or
CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
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.
export CXX=clang++
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.
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.
cd ~/flang/build cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR -DCLANG_DIR=$CLANG ~/flang/src make
The new Flang compiler driver, flang-new
, is implemented in terms of clangDriver
and hence it introduces a dependency on Clang. This dependency is otherwise not required. If you do not require the new driver, you can disable it by adding -DFLANG_BUILD_NEW_DRIVER=OFF
to your CMake invocation. With the new driver disabled, you no longer need to add clang
to LLVM_ENABLE_PROJECTS
(or to specify CLANG_DIR
when building out-of-tree).
Flang supports 2 different categories of tests
To run all tests:
cd ~/flang/build cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src make test 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:
<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 out-of-tree 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 3. <path-to-llvm-lit>/llvm-lit \ test/Unit 4. Invoking tests from <out-of-tree flang build>/unittests/<respective unit test folder>
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:
make check-flang-unit
To run all of the flang regression tests use the check-flang
target:
make check-flang
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 create docs/Dialect/FIRLangRef.md
in flang build directory.
To generate doxygen-style documentation from source code
-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON
to the cmake command.cd ~/llvm-project/build cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm make doxygen-flang
It will generate html in
<build-dir>/tools/flang/docs/doxygen/html # for flang docs
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:
-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF
to the cmake command.cd ~/llvm-project/build cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm make docs-flang-html
It will generate html in
$BROWSER <build-dir>/tools/flang/docs/html/