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.

On a typical Ubuntu system, the build dependencies can be installed with the following command:

sudo apt-get install build-essential cmake ccache git libffi-dev libtinfo-dev ninja-build zlib1g-dev zstd

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 when building 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.
Try building a hello-world program with your newly installed Classic Flang compiler. Save this file into hello.f90:
```
program hello
  print *, "hello world"
end program
```
To compile the program, issue this command:
```
$INSTALL_PREFIX/bin/flang hello.f90 -o hello.exe
```
Running the program should succeed, e.g.
```
$ ./hello.exe
 hello world
```
If running the program fails with error while loading shared libraries: libflang.so, then you have probably installed the compiler in a custom location, instead of a system directory such as /usr/local. In this case, export LD_LIBRARY_PATH to point to your toolchain, then try again, e.g.
```
$ export LD_LIBRARY_PATH=$INSTALL_PREFIX/lib
$ ./hello.exe
 hello world
```

Using the build scripts

The flang and classic-flang-llvm-project repositories contain build scripts that our GitHub workflows use to build and test the compiler (scripts/build_flang.py and scripts/build_llvm_project.py, respectively). You can use these scripts instead of the step-by-step instructions above or writing your own scripts. You should run build_llvm_project.py in the classic-flang-llvm-project clone first and, after Clang/LLVM have been installed successfully, run build_flang.py in the flang clone. Remember to use the same install prefix (-p option) in both cases, and for build_flang.py, add the -l option to point to the LLVM source directory. Running the scripts with --help will list the available options. For an example of how the scripts are used, see .github/workflows/flang-test.yml.