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 (and newer branches) 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 the just-built clang and clang++. During the build process, flang will be installed as a symbolic link to clang, and it will be used to compile the Classic Flang runtime libraries. A pre-existing Fortran compiler is not needed.

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 search path when building and running Classic Flang.

LLVM_MAIN_SRC_DIR

If you want to run Classic Flang regression tests, you must specify the LLVM source directory for the Classic Flang build by specifying -DLLVM_MAIN_SRC_DIR=<PATH_TO_CLASSIC_FLANG_LLVM_PROJECT>/llvm/.

CMAKE_C_COMPILER, CMAKE_CXX_COMPILER and CMAKE_Fortran_COMPILER

If you use a custom install location, and the bin directory in that location is not on your search path, when building Classic Flang you must specify the locations of clang, clang++, and flang with -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 the -DLLVM_TARGETS_TO_BUILD=X86 CMake option. Classic Flang supports X86, PowerPC and AArch64.

Note that while LLVM can be built to support multiple targets simultaneously, the Classic Flang frontend and runtime libraries only support one target at a time.

Step-by-step instructions

Create a build directory and define the CMake variables you will need. In the examples below, we will assume that 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 is a sample setup.sh that the other build scripts can use to define common variables. We specify a custom installation location, and indicate that we 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 \
    -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 Classic Flang with experimental and unsupported OpenMP target offload functionality, add -DFLANG_OPENMP_GPU_NVIDIA=ON to 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_16x 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 the Classic Flang frontend and runtime libraries.

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.