6c16aa4f67
In general all the basic functionality seems to work and removes some redundancy
and more complicated features in favor of borrowing infrastructure from LLVM
build configurations. Here's a quick summary of details and remaining issues:
* Testing has spanned Ubuntu 18.04 & 19.10, CentOS 7, RHEL 8, and
MacOS/darwin. Architectures include x86_64 and Arm. Without
access to Window nothing has been tested there yet.
* As we change file and directory naming schemes (i.e.,
capitalization) some odd things can occur on MacOS systems with
case preserving but not case senstive file system configurations.
Can be painful and certainly something to watch out for as any
any such changes continue.
* Testing infrastructure still needs to be tuned up and worked on.
Note that there do appear to be cases of some tests hanging (on
MacOS in particular). They appear unrelated to the build
process.
* Shared library configurations need testing (and probably fixing).
* Tested both standalone and 'in-mono repo' builds. Changes for
supporting the mono repo builds will require LLVM-level changes that
are straightforward when the time comes.
* The configuration contains a work-around for LLVM's C++ standard mode
passing down into Flang/F18 builds (i.e., LLVM CMake configuration would
force a -std=c++11 flag to show up in command line arguments. The
current configuration removes that automatically and is more strict in
following new CMake guidelines for enforcing C++17 mode across all the
CMake files.
* Cleaned up a lot of repetition in the command line arguments. It
is likely that more work is still needed to both allow for
customization and working around CMake defailts (or those
inherited from LLVM's configuration files). On some platforms agressive
optimization flags (e.g. -O3) can actually break builds due to the inlining
of templates in .cpp source files that then no longer are available for use
cases outside those source files (shows up as link errors). Sticking at -O2
appears to fix this. Currently this CMake configuration forces this in
release mode but at the cost of stomping on any CMake, or user customized,
settings for the release flags.
* Made the lit tests non-source directory dependent where appropriate. This is
done by configuring certain test shell files to refer to the correct paths
whether an in or out of tree build is being performed. These configured
files are output in the build directory. A %B substitution is introduced in
lit to refer to the build directory, mirroring the %S substitution for the
source directory, so that the tests can refer to the configured shell scripts.
Co-authored-by: David Truby <david.truby@arm.com>
Original-commit: flang-compiler/f18@d1c7184159
Reviewed-on: https://github.com/flang-compiler/f18/pull/1045
F18
F18 is a ground-up implementation of a Fortran front end written in modern C++. F18, when combined with LLVM, is intended to replace the Flang compiler.
Flang is a Fortran compiler targeting LLVM. Visit the Flang wiki for more information about Flang.
Getting Started
Read more about f18 in the documentation directory. Start with the compiler overview.
To better understand Fortran as a language and the specific grammar accepted by f18, read Fortran For C Programmers and f18'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 an f18 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 f18 uses modern C++ features.
Building F18
Get the Source Code
cd where/you/want/the/source
git clone https://github.com/flang-compiler/f18.git
Supported C++ compilers
F18 is written in C++17.
The code has been compiled and tested with GCC versions 7.2.0, 7.3.0, 8.1.0, and 8.2.0.
The code has been compiled and tested with clang version 7.0 and 8.0 using either GNU's libstdc++ or LLVM's libc++.
LLVM dependency
F18 uses components from LLVM.
The instructions to build LLVM can be found at https://llvm.org/docs/GettingStarted.html.
We highly recommend using the same compiler to compile both llvm and f18.
The f18 CMakeList.txt file uses
the variable LLVM_DIR to find the installed components.
To get the correct LLVM libraries included in your f18 build, define LLVM_DIR on the cmake command line.
LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm cmake -DLLVM_DIR=$LLVM ...
where LLVM_BUILD_DIR is
the top-level directory where LLVM was built.
LLVM dependency when building f18 with Fortran IR
If you do not want to build Fortran IR, add -DLINK_WITH_FIR=Off to f18 cmake
command and ignore the rest of this section.
If you intend to build f18 with Fortran IR (-DLINK_WITH_FIR On by default),
you must:
- build LLVM with the same compiler and options as the one you are using to build F18.
- pass
-DCMAKE_CXX_STANDARD=17 -DLLVM_ENABLE_PROJECTS="mlir"to LLVM cmake command. - install LLVM somewhere with
make installin order to get the required AddMLIR cmake file (it is not generated in LLVM build directory).
Installing LLVM from packages is most likely not an option as it will not include MLIR and not be built following C++17 standard.
MLIR is under active development and the most recent development version
may be incompatible. A branch named f18 is available inside LLVM fork in
https://github.com/flang-compiler/f18-llvm-project. It contains a version of LLVM
that is known be compatible to build f18 with FIR.
The fastest way to get set up is to do:
cd where/you/want/to/build/llvm
git clone --depth=1 -b f18 https://github.com/flang-compiler/f18-llvm-project.git
mkdir build
mkdir install
cd build
cmake ../f18-llvm-project/llvm -DCMAKE_BUILD_TYPE=Release \
-DLLVM_ENABLE_PROJECTS=mlir -DCMAKE_CXX_STANDARD=17 \
-DLLVM_INSTALL_UTILS=On \
-DCMAKE_INSTALL_PREFIX=../install
make
make install
Then, -DLLVM_DIR would have to be set to
<where/you/want/to/build/llvm>/install/lib/cmake/llvm in f18 cmake command.
To run lit tests,
-DLLVM_EXTERNAL_LIT=<where/you/want/to/build/llvm>/build/bin/llvm-lit must be
added to f18 cmake command. This is because llvm-lit is not part of
LLVM installation.
Note that when using some advanced options from f18 cmake file it may be necessary to reproduce their effects in LLVM cmake command.
Building f18 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 f18.
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++-7.2, assuming g++-7.2 is on your PATH.
export CXX=g++-7.2
or
CXX=/opt/gcc-7.2/bin/g++-7.2 cmake ...
Building f18 with clang
To build f18 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++
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 f18 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.
Build F18
cd ~/f18/build
cmake -DLLVM_DIR=$LLVM ~/f18/src
make
How to Run the Regression Tests
To run all tests:
cd ~/f18/build
cmake -DLLVM_DIR=$LLVM ~/f18/src
make test check-all
To run individual regression tests llvm-lit needs to know the lit configuration for f18. The parameters in charge of this are: flang_site_config and flang_config. And they can be set as shown bellow:
<path-to-llvm-lit>/llvm-lit \
--param flang_site_config=<path-to-f18-build>/test-lit/lit.site.cfg.py \
--param flang_config=<path-to-f18-build>/test-lit/lit.cfg.py \
<path-to-fortran-test>
How to Generate FIR Documentation
If f18 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 f18 build directory.