Building Flang

We build Classic Flang on Intel/AMD x86-64, AArch64 and OpenPOWER hardware running either Ubuntu or Red Hat.

Note: The Classic Flang project predates the llvm/flang (f18) project and it cannot be enabled and used together with llvm/flang.

Prerequisites

Building LLVM requires a fairly modern compiler toolchain and CMake (at least 3.3); check Getting started with LLVM and Building LLVM with CMake for the full list of tools required to build Classic Flang.

Dependencies

Classic Flang depends on a fork of the LLVM project. The fork has been modified to support compilation of Fortran files with the Classic Flang toolchain, as well as Fortran-specific command-line options and debug metadata, and may contain bug fixes that have been exposed by Classic Flang but have not yet been fixed in the upstream LLVM project. The fork should be built with the -DLLVM_ENABLE_CLASSIC_FLANG=ON option.

The master branch of Classic Flang is compatible with the release_15x branch of classic-flang-llvm-project. If you require the release_14x branch (or older branches) of classic-flang-llvm-project for some reason, check out the legacy branch of Classic Flang.

Building Classic Flang

Classic Flang is built outside of the LLVM source tree.

Most people find it easiest to build Clang, LLVM, and OpenMP with gcc and g++, and then build 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 Classic 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 and Classic Flang for can speed up your builds. For example, to build only for X86 processors, add this CMake option: -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 
    -DCMAKE_Fortran_COMPILER_ID=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.

Clone the llvm-project fork, build and install it (including Clang and OpenMP). 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 -b release_100 https://github.com/flang-compiler/classic-flang-llvm-project.git
fi

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

Clone the flang repository, 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 Classic Flang. To also build an annotated index of the source code with Doxygen, add -DLLVM_ENABLE_DOXYGEN=ON as well.