llvm-project/flang
Andrzej Warzynski dda366ed37 [flang][cmake] Make CMake copy "omp_lib.h" into the build directory
Any header or module file in the Flang source directory is of no use to
the compiler unless it is copied into the build directory. Indeed, all
compiler search paths are relative to the compiler executable (flang-new
in our case). Hence, "omp_lib.h" should be copied into the build
directory alongside other compiler-provided files that can be "included"
(header files) or "used" (module files).

For now, "omp_lib.h" is copied into "<build-dir>/include/flang/OpenMP".
We may decide to change this in future. For example, Clang copies a
bunch of runtime headers into “<build-dir>/lib/clang/<version-number>”.
We could also consider using a similar header from a different
sub-project.

Flang's driver search path is updated accordingly. A rule for
"installing" the "omp_lib.h" header is _yet to be added_ (we will also
need to determine the suitable location for this).

Differential Revision: https://reviews.llvm.org/D122015
2022-04-05 08:25:26 +00:00
..
cmake/modules [CMake] Factor out config prefix finding logic 2022-01-07 20:16:18 +00:00
docs Replace links to archived mailing lists by links to Discourse forums 2022-03-23 10:10:20 -04:00
examples [flang][Parser] Add a node for individual sections in sections construct 2022-03-18 21:55:35 +05:30
include [flang] Fold instantiated PDT character component length when needed 2022-04-04 09:47:15 +02:00
lib [flang][cmake] Make CMake copy "omp_lib.h" into the build directory 2022-04-05 08:25:26 +00:00
module [flang] Mark C_ASSOCIATED specific procedures as PURE 2022-03-25 15:04:26 -07:00
runtime [flang] Allow user to recover from bad edit descriptor with INTEGER 2022-03-31 10:57:13 +02:00
test [flang][cmake] Make CMake copy "omp_lib.h" into the build directory 2022-04-05 08:25:26 +00:00
tools [flang][cmake] Make CMake copy "omp_lib.h" into the build directory 2022-04-05 08:25:26 +00:00
unittests [flang][runtime] Ensure PointerDeallocate actually deallocate pointers 2022-03-28 10:22:08 +02:00
.clang-format [flang] Remove non-alignment based divergences from LLVM formatting. 2020-03-23 17:52:22 +00:00
.clang-tidy [flang] Add clang-tidy check for braces around if 2021-06-16 09:13:53 +00:00
.drone.star [flang] [mlir rebase] Add MLIR config and react to MLIR name changes (flang-compiler/f18#1090) 2020-03-27 09:23:32 -07:00
.gitignore [flang] A rework of the cmake build components for in and out of tree builds. 2020-03-26 18:17:04 +00:00
CMakeLists.txt Reapply "[cmake] Prefix gtest and gtest_main with "llvm_"." 2022-03-04 13:45:43 -08:00
CODE_OWNERS.TXT [flang] fix typo (flang-compiler/f18#1067) 2020-03-12 10:25:22 -07:00
LICENSE.TXT Rename top-level LICENSE.txt files to LICENSE.TXT 2021-03-10 21:26:24 -08:00
README.md Update all LLVM documentation mentioning runtimes in LLVM_ENABLE_PROJECTS 2022-02-10 15:05:23 -05:00

README.md

Flang

Flang is a ground-up implementation of a Fortran front end written in modern C++. It started off as the f18 project (https://github.com/flang-compiler/f18) with an aim to replace the previous flang project (https://github.com/flang-compiler/flang) and address its various deficiencies. F18 was subsequently accepted into the LLVM project and rechristened as Flang.

Getting Started

Read more about flang in the docs directory. Start with the compiler overview.

To better understand Fortran as a language and the specific grammar accepted by flang, read Fortran For C Programmers and flang's specifications of the Fortran grammar and the OpenMP grammar.

Treatment of language extensions is covered in this document.

To understand the compilers handling of intrinsics, see the discussion of intrinsics.

To understand how a flang program communicates with libraries at runtime, see the discussion of runtime descriptors.

If you're interested in contributing to the compiler, read the style guide and also review how flang uses modern C++ features.

If you are interested in writing new documentation, follow LLVM's Markdown style guide.

Building flang

There are two ways to build flang. The first method is to build it at the same time that you build all of the projects on which it depends. This is called building in tree. The second method is to first do an in tree build to create all of the projects on which flang depends, and then only build the flang code itself. This is called building standalone. Building standalone has the advantage of being smaller and faster. Once you create the base build and base install areas, you can create multiple standalone builds using them.

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

Building flang in tree

Building flang in tree means building flang along with all of the projects on which it depends. These projects include mlir, clang, flang, and compiler-rt. Note that compiler-rt is only needed to access libraries that support 16 bit floating point numbers. It's not needed to run the automated tests.

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

First clone the source:

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

Once the clone is complete, execute the following commands:

cd my-project

rm -rf build
mkdir -p build

cd build

cmake \
  -G Ninja \
  ../llvm \
  -DCMAKE_BUILD_TYPE=Release \
  -DFLANG_ENABLE_WERROR=On \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DLLVM_TARGETS_TO_BUILD=host \
  -DCMAKE_INSTALL_PREFIX=$INSTALLDIR
  -DLLVM_LIT_ARGS=-v \
  -DLLVM_ENABLE_PROJECTS="clang;mlir;flang" \
  -DLLVM_ENABLE_RUNTIMES="compiler-rt"

ninja

To run the flang tests on this build, execute the command in the "build" directory:

ninja check-flang

Note that these instructions specify flang as one of the projects to build in the in tree build. This is not strictly necessary for subsequent standalone builds, but doing so lets you run the flang tests to verify that the source code is in good shape.

Building flang standalone

To do the standalone build, start by building flang in tree as described above. This build is base build for subsequent standalone builds. Start each standalone build the same way by cloning the source for llvm-project:

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

Once the clone is complete, execute the following commands:

cd standalone
base=<directory that contains the in tree build>

cd flang
rm -rf build
mkdir build
cd build

cmake \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DFLANG_ENABLE_WERROR=On \
  -DLLVM_TARGETS_TO_BUILD=host \
  -DLLVM_ENABLE_ASSERTIONS=On \
  -DLLVM_BUILD_MAIN_SRC_DIR=$base/build/lib/cmake/llvm \
  -DLLVM_LIT_ARGS=-v \
  -DLLVM_DIR=$base/build/lib/cmake/llvm \
  -DCLANG_DIR=$base/build/lib/cmake/clang \
  -DMLIR_DIR=$base/build/lib/cmake/mlir \
  ..

ninja

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

ninja check-flang

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

The code does not compile with Windows and a compiler that does not have support for C++17.

Building flang with GCC

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

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

or

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 command where <INSTALL_PREFIX> is the path where flang should be installed.

Build Types

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

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

How to Run Tests

Flang supports 2 different categories of tests

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

For standalone builds

To run all tests:

cd ~/flang/build
cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
ninja check-all

To run individual regression tests llvm-lit needs to know the lit configuration 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-unit
2. ninja check-all or ninja check-flang
3. <path-to-llvm-lit>/llvm-lit \
        test/Unit
4. 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 to generate 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 to generate FIR language documentation by running ninja flang-doc. This will create 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/build
cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
ninja 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), it is mostly meant to be processed by the Sphinx documentation generation system to create HTML pages which would be hosted on the webpage of flang and updated periodically.

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

  • Install Sphinx, including the sphinx-markdown-tables extension.
  • Pass -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF to the cmake command.
cd ~/llvm-project/build
cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
ninja docs-flang-html

It will generate html in

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