Building Flang

We build Flang on Intel x86-64 and OpenPOWER hardware running either Ubuntu or Red Hat.

Prerequisites

Building LLVM requires a fairly modern compiler toolchain and CMake, check Getting started with LLVM and Building LLVM with CMake for the full list of tools required to build flang.

Dependencies

Flang depends on forks of clang and llvm.

The clang fork, flang-compiler/flang-driver, has been modified to support compilation of Fortran files, Fortran-specific command-line options, and the flang toolchain.

The llvm fork, flang-compiler/llvm, has been extended to support enhanced debug metadata specific to Fortran. It also may contain bug fixes that have been exposed by flang but have not yet been fixed in the llvm repository.

The latest supported LLVM version is 9.0.

Starting with LLVM 10.0, all modifications to clang and llvm are made in the fork of the monorepo, flang-compiler/classic-flang-llvm-project.

Building Flang

Flang is built outside of the llvm source tree.

Most people find it easiest to build LLVM and the flang-driver with gcc and g++, and then build OpenMP, libpgmath and flang with clang and clang++.

The Linux command-line examples below will install everything into a custom location. To install to a standard system location, remove the references to INSTALL_PREFIX and -DCMAKE_INSTALL_PREFIX in the cmake commands below.

CMake variables used to build flang

CMAKE_INSTALL_PREFIX

To specify a custom install location, in each step below add -DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX> to every CMake command.

If you use CMAKE_INSTALL_PREFIX in any step, you must use the same CMAKE_INSTALL_PREFIX in every step.

When using a custom install location, you must make sure that the bin directory is on your PATH when building and running flang.

LLVM_CONFIG

If llvm-config is not in your search path, specify LLVM_CONFIG=<INSTALL_PREFIX>/bin/llvm-config so CMake can find it.

CMAKE_C_COMPILER, CMAKE_CXX_COMPILER and CMAKE_Fortran_COMPILER

If the C, C++ or Fortran compilers are not in your path, specify something like: -DCMAKE_CXX_COMPILER=<INSTALL_PREFIX>/bin/clang++, -DCMAKE_C_COMPILER=<INSTALL_PREFIX>/bin/clang, and -DCMAKE_Fortran_COMPILER=<INSTALL_PREFIX>/bin/flang.

LLVM_TARGETS_TO_BUILD

Specifying specific targets to build LLVM, flang-driver and flang for can speed up your builds. For example, building only for X86 processors: -DLLVM_TARGETS_TO_BUILD=X86"

Flang supports the following options here: X86, PowerPC and AArch64.

Step-by-step instructions

Create a build directory and define the CMake variables you will need. In the examples below, we'll assume you want to install in the install directory of wherever you will do the builds.
```
cd /where/you/want/to/build/flang
mkdir install
```
Here's a sample setup.sh that the other build scripts can use. We specify a custom installation location and that we generally want to build for X86 with clang.
```
INSTALL_PREFIX=`pwd`/install

# Targets to build should be one of: X86 PowerPC AArch64
CMAKE_OPTIONS="-DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX \
    -DLLVM_CONFIG=$INSTALL_PREFIX/bin/llvm-config \
    -DCMAKE_CXX_COMPILER=$INSTALL_PREFIX/bin/clang++ \
    -DCMAKE_C_COMPILER=$INSTALL_PREFIX/bin/clang \
    -DCMAKE_Fortran_COMPILER=$INSTALL_PREFIX/bin/flang \
    -DLLVM_TARGETS_TO_BUILD=X86"
```
To build flang with OpenMP target offload support (LLVM 7.0 and higher), add
```
    -DFLANG_OPENMP_GPU_NVIDIA=ON
```
to the CMAKE_OPTIONS.

Not all variables are used in every build, so you may see some warnings about unused definitions.
If you would like to build Flang on LLVM 10.0 or newer, skip ahead to step 6.

Get Flang LLVM, build and install it according to instructions. Here is a build-llvm.sh script (using gcc and g++ to bootstrap LLVM):

. setup.sh

if [[ ! -d llvm ]]; then
    git clone https://github.com/flang-compiler/llvm.git
    (cd llvm && git checkout release_90)
fi

cd llvm

# Use local GCC to bootstrap LLVM
mkdir -p build && cd build
cmake $CMAKE_OPTIONS -DCMAKE_C_COMPILER=/usr/bin/gcc -DCMAKE_CXX_COMPILER=/usr/bin/g++ ..
make
sudo make install

Get the flang driver, build and install it. Here is a build-flang-driver.sh script (using gcc and g++ to bootstrap flang-driver):

. setup.sh

if [[ ! -d flang-driver ]]; then
    git clone https://github.com/flang-compiler/flang-driver.git
    (cd flang-driver && git checkout release_90)
fi

# Use local GCC to bootstrap flang-driver
cd flang-driver
mkdir -p build && cd build
cmake $CMAKE_OPTIONS -DCMAKE_C_COMPILER=/usr/bin/gcc -DCMAKE_CXX_COMPILER=/usr/bin/g++ ..
make
sudo make install

Get the OpenMP runtime library, build and install it. Here's a sample build-openmp.sh script (using clang to build):

. setup.sh

if [[ ! -d openmp ]]; then
    git clone https://github.com/llvm-mirror/openmp.git
    (cd openmp && git checkout release_90)
fi

cd openmp
mkdir -p build && cd build
cmake $CMAKE_OPTIONS ..
make
sudo make install

Skip the next step to continue building libpgmath and flang.

To build flang on top of LLVM 10, get the llvm-project fork, build and install it. Here is a build-llvm-project.sh script (using gcc and g++ to bootstrap the toolchain):

. setup.sh

if [[ ! -d classic-flang-llvm-project ]]; then
    git clone https://github.com/flang-compiler/classic-flang-llvm-project.git
    (cd classic-flang-llvm-project && git checkout release_100)
fi

# Use local GCC to bootstrap the toolchain.
cd classic-flang-llvm-project
mkdir -p build && cd build
cmake $CMAKE_OPTIONS -DCMAKE_C_COMPILER=/usr/bin/gcc -DCMAKE_CXX_COMPILER=/usr/bin/g++ -DLLVM_ENABLE_CLASSIC_FLANG=ON -DLLVM_ENABLE_PROJECTS="clang;openmp" ../llvm
make
sudo make install

Get the flang source code and build libpgmath and flang. Here's a sample build-flang.sh script (using clang to build). The script first builds libpgmath, and then builds flang.

Note that libpgmath on x86 requires a toolchain that understands AVX-512 instructions, such as gcc 7.2 or clang.
```
. setup.sh

if [[ ! -d flang ]]; then
    git clone https://github.com/flang-compiler/flang.git
fi

(cd flang/runtime/libpgmath
 mkdir -p build && cd build
 cmake $CMAKE_OPTIONS ..
 make
 sudo make install)

cd flang
mkdir -p build && cd build
cmake $CMAKE_OPTIONS -DFLANG_LLVM_EXTENSIONS=ON ..
make
sudo make install
```
To build the HTML documentation with Sphinx, add -DLLVM_INCLUDE_DOCS=ON or -DFLANG_INCLUDE_DOCS=ON to the cmake command when building Flang. To also build an annotated index of the source code with Doxygen, add -DLLVM_ENABLE_DOXYGEN=ON as well.