|author||Andrzej Warzynski <email@example.com>||Mon Apr 12 12:27:49 2021 +0000|
|committer||Copybara-Service <firstname.lastname@example.org>||Fri Apr 16 12:20:59 2021 -0700|
[flang] Update the regression tests to use the new driver when enabled This patch updates most of the remaining regression tests (~400) to use `flang-new` rather then `f18` when `FLANG_BUILD_NEW_DRIVER` is set. This allows us to share more Flang regression tests between `f18` and `flang-new`. A handful of tests have not been ported yet - these are currently either failing or not supported by the new driver. Summary of changes: * RUN lines in tests are updated to use `%flang_fc1` instead of `%f18` * option spellings in tests are updated to forms accepted by both `f18` and `flang-new` * variables in Bash scripts are renamed (e.g. F18 --> FLANG_FC1) The updated tests will now be run with the new driver, `flang-new`, whenever it is enabled (i.e when `FLANG_BUILD_NEW_DRIVER` is set). Although this patch touches many files, vast majority of the changes are automatic: ``` grep -IEZlr "%f18" flang/test/ | xargs -0 -l sed -i 's/%f18/%flang_fc1/g ``` Differential Revision: https://reviews.llvm.org/D100309 GitOrigin-RevId: e7be90bd27051c3dcd9a344cb1b347a0c9454c21
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.
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 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
We highly recommend using the same compiler to compile both llvm and flang.
The flang CMakeList.txt file uses the variable
LLVM_DIR to find the installed LLVM components and the variable
MLIR_DIR to find the installed MLIR components.
To get the correct LLVM and MLIR libraries included in your flang build, define LLVM_DIR and MLIR_DIR on the cmake command line.
LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm \ MLIR=<LLVM_BUILD_DIR>/lib/cmake/mlir \ cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ...
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.
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.
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 ~/flang/src make
The new Flang driver,
flang-new, is currently under active development and should be considered as an experimental feature. For this reason it is disabled by default. This will change once the new driver replaces the throwaway driver,
In order to build the new driver, add
-DFLANG_BUILD_NEW_DRIVER=ON to your CMake invocation line. Additionally, when building out-of-tree, use
CLANG_DIR (similarly to
MLIR_DIR) to find the installed Clang components.
CLANG_DIR is only required when building the new Flang driver, which currently depends on Clang.
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>
If flang was built with
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
On by default), it is possible to generate unittests.
To run all of the flang unit tests use the
To run all of the flang regression tests use the
If flang was built with
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=ONto 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=OFFto 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