Getting Started — The Flang Compiler (2024)

Building flang¶

There are two ways to build flang. The first method is to build it at the sametime that you build all of the projects on which it depends. This is calledbuilding in tree. The second method is to first do an in tree build to createall of the projects on which flang depends. Then, after creating this basebuild, only build the flang code itself. This is called building standalone.Building standalone has the advantage of being smaller and faster. Once youcreate the base build and base install areas, you can create multiplestandalone builds using them.

Note that instructions for building LLVM can be found athttps://llvm.org/docs/GettingStarted.html.

All of the examples below use GCC as the C/C++ compilers and ninja as the buildtool.

Building flang in tree¶

Building flang in tree means building flang along with all of the projects onwhich it depends. These projects include mlir, clang, flang, openmp, andcompiler-rt. Note that compiler-rt is only needed to access libraries thatsupport 16 bit floating point numbers. It’s not needed to run the automatedtests. You can use several different C++ compilers for most of the build,includig GNU and clang. But building compiler-rt requres using the clangcompiler built in the initial part of the build.

Here’s a directory structure that works. Create a root directory for thecloned and built files. Under that root directory, clone the source codeinto a directory called llvm-project. The build will alsocreate subdirectories under the root directory called build (holds most ofthe built files), install (holds the installed files, and compiler-rt (holdsthe result of building compiler-rt).

Here’s a complete set of commands to clone all of the necessary source and dothe build.

First, create the root directory and cd into it.

mkdir rootcd root

Now clone the source:

git clone https://github.com/llvm/llvm-project.git

Once the clone is complete, execute the following commands:

rm -rf buildmkdir buildrm -rf installmkdir installROOTDIR=`pwd`INSTALLDIR=$ROOTDIR/installcd buildcmake \ -G Ninja \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \ -DCMAKE_CXX_STANDARD=17 \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \ -DFLANG_ENABLE_WERROR=ON \ -DLLVM_ENABLE_ASSERTIONS=ON \ -DLLVM_TARGETS_TO_BUILD=host \ -DLLVM_LIT_ARGS=-v \ -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;openmp" \ -DLLVM_ENABLE_RUNTIMES="compiler-rt" \ ../llvm-project/llvmninja

Building flang standalone¶

To do the standalone build, start by building flang in tree as described above.This build can be used as the base build for several subsequent standalonebuilds. Set the environment variable ROOT_DIR to the directory thatcontains the subdirectory build that was created previously, for example:

export ROOTDIR=/home/user/root

Start each standalone build the same way by cloning the source forllvm-project:

mkdir standalonecd standalonegit clone https://github.com/llvm/llvm-project.git

Once the clone is complete, execute the following commands:

cd llvm-project/flangrm -rf buildmkdir buildcd buildcmake \ -G Ninja \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_CXX_STANDARD=17 \ -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DFLANG_ENABLE_WERROR=ON \ -DLLVM_TARGETS_TO_BUILD=host \ -DLLVM_ENABLE_ASSERTIONS=ON \ -DLLVM_BUILD_MAIN_SRC_DIR=$ROOTDIR/build/lib/cmake/llvm \ -DLLVM_EXTERNAL_LIT=$ROOTDIR/build/bin/llvm-lit \ -DLLVM_LIT_ARGS=-v \ -DLLVM_DIR=$ROOTDIR/build/lib/cmake/llvm \ -DCLANG_DIR=$ROOTDIR/build/lib/cmake/clang \ -DMLIR_DIR=$ROOTDIR/build/lib/cmake/mlir \ ..ninja

To run the flang tests on this build, execute the command in the flang/builddirectory:

ninja check-flang

Building flang runtime for accelerators¶

Flang runtime can be built for accelerators in experimental mode, i.e.complete enabling is WIP. CUDA and OpenMP target offload buildsare currently supported.

Building out-of-tree¶

CUDA build¶

Clang with NVPTX backend and NVCC compilers are supported.

cd llvm-project/flangrm -rf build_flang_runtimemkdir build_flang_runtimecd build_flang_runtimecmake \ -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \ -DCMAKE_CUDA_ARCHITECTURES=80 \ -DCMAKE_C_COMPILER=clang \ -DCMAKE_CXX_COMPILER=clang++ \ -DCMAKE_CUDA_COMPILER=clang \ -DCMAKE_CUDA_HOST_COMPILER=clang++ \ ../runtime/make -j FortranRuntime

Note that the used version of clang must supportCUDA toolkit version installed on the build machine. If there are multipleCUDA toolkit installations, please use -DCUDAToolkit_ROOT=/some/pathto specify the compatible version.

cd llvm-project/flangrm -rf build_flang_runtimemkdir build_flang_runtimecd build_flang_runtimecmake \ -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \ -DCMAKE_CUDA_ARCHITECTURES=80 \ -DCMAKE_C_COMPILER=clang \ -DCMAKE_CXX_COMPILER=clang++ \ -DCMAKE_CUDA_COMPILER=nvcc \ -DCMAKE_CUDA_HOST_COMPILER=clang++ \ ../runtime/make -j FortranRuntime

Note that nvcc might limit support to certainversions of CMAKE_CUDA_HOST_COMPILER,so please use compatible versions.

The result of the build is a “fat” library with the host and devicecode. Note that the packaging of the libraries is differentbetween Clang and NVCC, so the library must be linked usingcompatible compiler drivers.

Building in-tree¶

One may build Flang runtime library along with building Flang itselfby providing these additional CMake variables on top of the Flang in-treebuild config:

OpenMP target offload build¶

Only Clang compiler is currently supported.

cd llvm-project/flangrm -rf build_flang_runtimemkdir build_flang_runtimecd build_flang_runtimecmake \ -DFLANG_EXPERIMENTAL_OMP_OFFLOAD_BUILD="host_device" \ -DCMAKE_C_COMPILER=clang \ -DCMAKE_CXX_COMPILER=clang++ \ -DFLANG_OMP_DEVICE_ARCHITECTURES="all" \ ../runtime/make -j FortranRuntime

The result of the build is a “device-only” library, i.e. the hostpart of the library is just a container for the device code.The resulting library may be linked to user programs usingClang-like device linking pipeline.

The same set of CMake variables works for Flang in-tree build.

Build options¶

One may provide optional CMake variables to customize the build. Available options:

-DFLANG_RUNTIME_F128_MATH_LIB=libquadmath: enables build ofFortranFloat128Math library that provides REAL(16) math APIsfor intrinsics such as SIN, COS, etc. GCC libquadmath’s header filequadmath.h must be available to the build compiler.More details.

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.0using 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.

Note that flang is not supported on 32 bit CPUs.

Building flang with GCC¶

By default,cmake will search for g++ on your PATH.The g++ version must be one of the supported versionsin order to build flang.

Or, cmake will use the variable CXX to find the C++ compiler. CXX should includethe 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

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.

export CXX=clang++

Installation Directory¶

To specify a custom install location,add-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>to the cmake commandwhere <INSTALL_PREFIX>is the path where flang should be installed.

Build Types¶

To create a debug build,add-DCMAKE_BUILD_TYPE=Debugto the cmake command.Debug builds execute slowly.

To create a release build,add-DCMAKE_BUILD_TYPE=Releaseto the cmake command.Release builds execute quickly.

How to Run Tests¶

Flang supports 2 different categories of tests

Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)

For standalone builds¶

To run all tests:

cd ~/flang/buildcmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/srcninja check-all

To run individual regression tests llvm-lit needs to know the litconfiguration 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 standalone build as it does not include googletest related headers and libraries.

There are various ways to run unit-tests.

1. ninja check-flang-unit2. ninja check-all or ninja check-flang3. <path-to-llvm-lit>/llvm-lit \ test/Unit4. 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 togenerate unittests.

To run all of the flang unit tests use the check-flang-unit target:

ninja check-flang-unit

To run all of the flang regression tests use the check-flang target:

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 togenerate FIR language documentation by running ninja flang-doc. This willcreate <build-dir>/tools/flang/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.

cd ~/llvm-project/buildcmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvmninja doxygen-flang

It will generate html in

 <build-dir>/tools/flang/docs/doxygen/html # for flang docs

Generate Sphinx-based Documentation¶

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), itis mostly meant to be processed by the Sphinx documentation generationsystem to create HTML pages which would be hosted on the webpage of flang andupdated periodically.

If you would like to generate and view the HTML locally:

Install Sphinx, and the required extensionsusing pip install --user -r ~/llvm-projects/docs/requirements.txt
Pass -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF to the cmake command.

cd ~/llvm-project/buildcmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvmninja docs-flang-html

It will generate html in

 $BROWSER <build-dir>/tools/flang/docs/html/