flang/README.md

   1 # Flang
   2
   3 Flang is a ground-up implementation of a Fortran front end written in modern
   4 C++. It started off as the f18 project (https://github.com/flang-compiler/f18)
   5 with an aim to replace the previous flang project
   6 (https://github.com/flang-compiler/flang) and address its various deficiencies.
   7 F18 was subsequently accepted into the LLVM project and rechristened as Flang.
   8
   9 Please note that flang is not ready yet for production usage.
  10
  11 ## Getting Started
  12
  13 Read more about flang in the [docs directory](docs).
  14 Start with the [compiler overview](docs/Overview.md).
  15
  16 To better understand Fortran as a language
  17 and the specific grammar accepted by flang,
  18 read [Fortran For C Programmers](docs/FortranForCProgrammers.md)
  19 and
  20 flang's specifications of the [Fortran grammar](docs/f2018-grammar.md)
  21 and
  22 the [OpenMP grammar](docs/OpenMP-4.5-grammar.md).
  23
  24 Treatment of language extensions is covered
  25 in [this document](docs/Extensions.md).
  26
  27 To understand the compilers handling of intrinsics,
  28 see the [discussion of intrinsics](docs/Intrinsics.md).
  29
  30 To understand how a flang program communicates with libraries at runtime,
  31 see the discussion of [runtime descriptors](docs/RuntimeDescriptor.md).
  32
  33 If you're interested in contributing to the compiler,
  34 read the [style guide](docs/C++style.md)
  35 and
  36 also review [how flang uses modern C++ features](docs/C++17.md).
  37
  38 If you are interested in writing new documentation, follow
  39 [LLVM's Markdown style guide](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
  40
  41 ## Building flang
  42 There are two ways to build flang. The first method is to build it at the same
  43 time that you build all of the projects on which it depends. This is called
  44 building in tree. The second method is to first do an in tree build to create
  45 all of the projects on which flang depends.  Then, after creating this base
  46 build, only build the flang code itself. This is called building standalone.
  47 Building standalone has the advantage of being smaller and faster. Once you
  48 create the base build and base install areas, you can create multiple
  49 standalone builds using them.
  50
  51 Note that instructions for building LLVM can be found at
  52 https://llvm.org/docs/GettingStarted.html.
  53
  54 All of the examples below use GCC as the C/C++ compilers and ninja as the build
  55 tool.
  56
  57 ### Building flang in tree
  58 Building flang in tree means building flang along with all of the projects on
  59 which it depends.  These projects include mlir, clang, flang, openmp, and
  60 compiler-rt.  Note that compiler-rt is only needed to access libraries that
  61 support 16 bit floating point numbers.  It's not needed to run the automated
  62 tests.  You can use several different C++ compilers for most of the build,
  63 includig GNU and clang.  But building compiler-rt requres using the clang
  64 compiler built in the initial part of the build.
  65
  66 Here's a directory structure that works.  Create a root directory for the
  67 cloned and built files.  Under that root directory, clone the source code
  68 into a directory called llvm-project.  The build will also
  69 create subdirectories under the root directory called build (holds most of
  70 the built files), install (holds the installed files, and compiler-rt (holds
  71 the result of building compiler-rt).
  72
  73 Here's a complete set of commands to clone all of the necessary source and do
  74 the build.
  75
  76 First, create the root directory and `cd` into it.
  77 ```bash
  78 mkdir root
  79 cd root
  80
  81 Now clone the source:
  82 ```bash
  83 git clone https://github.com/llvm/llvm-project.git
  84 ```
  85 Once the clone is complete, execute the following commands:
  86 ```bash
  87 rm -rf build
  88 mkdir build
  89 rm -rf install
  90 mkdir install
  91 ROOTDIR=`pwd`
  92 INSTALLDIR=$ROOTDIR/install
  93
  94 cd build
  95
  96 cmake \
  97   -G Ninja \
  98   -DCMAKE_BUILD_TYPE=Release \
  99   -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
 100   -DCMAKE_CXX_STANDARD=17 \
 101   -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
 102   -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
 103   -DFLANG_ENABLE_WERROR=ON \
 104   -DLLVM_ENABLE_ASSERTIONS=ON \
 105   -DLLVM_TARGETS_TO_BUILD=host \
 106   -DLLVM_LIT_ARGS=-v \
 107   -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;openmp" \
 108   -DLLVM_ENABLE_RUNTIMES="compiler-rt" \
 109   ../llvm-project/llvm
 110
 111 ninja
 112 ```
 113
 114 By default flang tests that do not specify an explicit `--target` flag use
 115 LLVM's default target triple. For these tests, if there is a need to test on a
 116 different triple by overriding the default, the following needs to be added to
 117 the cmake command above:
 118 `-DLLVM_TARGET_TRIPLE_ENV="<some string>" -DFLANG_TEST_TARGET_TRIPLE="<your triple>"`.
 119
 120 To run the flang tests on this build, execute the command in the "build"
 121 directory:
 122 ```bash
 123 ninja check-flang
 124 ```
 125
 126 To create the installed files:
 127 ```bash
 128 ninja install
 129
 130 echo "latest" > $INSTALLDIR/bin/versionrc
 131 ```
 132
 133 To build compiler-rt:
 134 ```bash
 135 cd $ROOTDIR
 136 rm -rf compiler-rt
 137 mkdir compiler-rt
 138 cd compiler-rt
 139 CC=$INSTALLDIR/bin/clang \
 140 CXX=$INSTALLDIR/bin/clang++ \
 141 cmake \
 142   -G Ninja \
 143   ../llvm-project/compiler-rt \
 144   -DCMAKE_BUILD_TYPE=Release \
 145   -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
 146   -DCMAKE_CXX_STANDARD=11 \
 147   -DCMAKE_C_CFLAGS=-mlong-double-128 \
 148   -DCMAKE_CXX_CFLAGS=-mlong-double-128 \
 149   -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
 150   -DCOMPILER_RT_BUILD_ORC=OFF \
 151   -DCOMPILER_RT_BUILD_XRAY=OFF \
 152   -DCOMPILER_RT_BUILD_MEMPROF=OFF \
 153   -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
 154   -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
 155   -DLLVM_CONFIG_PATH=$INSTALLDIR/bin/llvm-config
 156
 157 ninja
 158 ninja install
 159 ```
 160
 161 Note that these instructions specify flang as one of the projects to build in
 162 the in tree build.  This is not strictly necessary for subsequent standalone
 163 builds, but doing so lets you run the flang tests to verify that the source
 164 code is in good shape.
 165 ### Building flang standalone
 166 To do the standalone build, start by building flang in tree as described above.
 167 This build is base build for subsequent standalone builds.  Start each
 168 standalone build the same way by cloning the source for llvm-project:
 169 ```bash
 170 mkdir standalone
 171 cd standalone
 172 git clone https://github.com/llvm/llvm-project.git
 173 ```
 174 Once the clone is complete, execute the following commands:
 175 ```bash
 176 cd llvm-project/flang
 177 rm -rf build
 178 mkdir build
 179 cd build
 180
 181 cmake \
 182   -G Ninja \
 183   -DCMAKE_BUILD_TYPE=Release \
 184   -DCMAKE_CXX_STANDARD=17 \
 185   -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
 186   -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
 187   -DFLANG_ENABLE_WERROR=ON \
 188   -DLLVM_TARGETS_TO_BUILD=host \
 189   -DLLVM_ENABLE_ASSERTIONS=ON \
 190   -DLLVM_BUILD_MAIN_SRC_DIR=$ROOTDIR/build/lib/cmake/llvm \
 191   -DLLVM_EXTERNAL_LIT=$ROOTDIR/build/bin/llvm-lit \
 192   -DLLVM_LIT_ARGS=-v \
 193   -DLLVM_DIR=$ROOTDIR/build/lib/cmake/llvm \
 194   -DCLANG_DIR=$ROOTDIR/build/lib/cmake/clang \
 195   -DMLIR_DIR=$ROOTDIR/build/lib/cmake/mlir \
 196   ..
 197
 198 ninja
 199 ```
 200
 201 To run the flang tests on this build, execute the command in the "flang/build"
 202 directory:
 203 ```bash
 204 ninja check-flang
 205 ```
 206
 207 ## Supported C++ compilers
 208
 209 Flang is written in C++17.
 210
 211 The code has been compiled and tested with GCC versions from 7.2.0 to 9.3.0.
 212
 213 The code has been compiled and tested with clang version 7.0, 8.0, 9.0 and 10.0
 214 using either GNU's libstdc++ or LLVM's libc++.
 215
 216 The code has been compiled on AArch64, x86_64 and ppc64le servers with CentOS7,
 217 Ubuntu18.04, Rhel, MacOs, Mojave, XCode and Apple Clang version 10.0.1.
 218
 219 Note that flang is not supported on 32 bit CPUs.
 220
 221 ### Building flang with GCC
 222
 223 By default,
 224 cmake will search for g++ on your PATH.
 225 The g++ version must be one of the supported versions
 226 in order to build flang.
 227
 228 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
 229 the full path to the compiler or a name that will be found on your PATH, e.g.
 230 g++-8.3, assuming g++-8.3 is on your PATH.
 231
 232 ```bash
 233 export CXX=g++-8.3
 234 ```
 235 or
 236 ```bash
 237 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
 238 ```
 239
 240 ### Building flang with clang
 241
 242 To build flang with clang,
 243 cmake needs to know how to find clang++
 244 and the GCC library and tools that were used to build clang++.
 245
 246 CXX should include the full path to clang++
 247 or clang++ should be found on your PATH.
 248 ```bash
 249 export CXX=clang++
 250 ```
 251
 252 ### Installation Directory
 253
 254 To specify a custom install location,
 255 add
 256 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
 257 to the cmake command
 258 where `<INSTALL_PREFIX>`
 259 is the path where flang should be installed.
 260
 261 ### Build Types
 262
 263 To create a debug build,
 264 add
 265 `-DCMAKE_BUILD_TYPE=Debug`
 266 to the cmake command.
 267 Debug builds execute slowly.
 268
 269 To create a release build,
 270 add
 271 `-DCMAKE_BUILD_TYPE=Release`
 272 to the cmake command.
 273 Release builds execute quickly.
 274
 275 # How to Run Tests
 276
 277 Flang supports 2 different categories of tests
 278 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
 279 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
 280
 281 ## For standalone builds
 282 To run all tests:
 283 ```bash
 284 cd ~/flang/build
 285 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
 286 ninja check-all
 287 ```
 288
 289 To run individual regression tests llvm-lit needs to know the lit
 290 configuration for flang. The parameters in charge of this are:
 291 flang_site_config and flang_config. And they can be set as shown below:
 292 ```bash
 293 <path-to-llvm-lit>/llvm-lit \
 294  --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
 295  --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
 296   <path-to-fortran-test>
 297
 298 ```
 299
 300 Unit tests:
 301
 302 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to generate unittests.
 303 Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries.
 304
 305 There are various ways to run unit-tests.
 306
 307 ```
 308
 309 1. ninja check-flang-unit
 310 2. ninja check-all or ninja check-flang
 311 3. <path-to-llvm-lit>/llvm-lit \
 312         test/Unit
 313 4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
 314
 315 ```
 316
 317
 318 ## For in tree builds
 319 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to
 320 generate unittests.
 321
 322 To run all of the flang unit tests use the `check-flang-unit` target:
 323 ```bash
 324 ninja check-flang-unit
 325 ```
 326 To run all of the flang regression tests use the `check-flang` target:
 327 ```bash
 328 ninja check-flang
 329 ```
 330
 331 # How to Generate Documentation
 332
 333 ## Generate FIR Documentation
 334 If flang was built with `-DLINK_WITH_FIR=ON` (`ON` by default), it is possible to
 335 generate FIR language documentation by running `ninja flang-doc`. This will
 336 create `<build-dir>/tools/flang/docs/Dialect/FIRLangRef.md` in flang build directory.
 337
 338 ## Generate Doxygen-based Documentation
 339 To generate doxygen-style documentation from source code
 340 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
 341
 342 ```bash
 343 cd ~/llvm-project/build
 344 cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
 345 ninja doxygen-flang
 346 ```
 347
 348 It will generate html in
 349
 350 ```bash
 351     <build-dir>/tools/flang/docs/doxygen/html # for flang docs
 352 ```
 353 ## Generate Sphinx-based Documentation
 354 <!TODO: Add webpage once we have a website.
 355 !>
 356 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
 357 is mostly meant to be processed by the Sphinx documentation generation
 358 system to create HTML pages which would be hosted on the webpage of flang and
 359 updated periodically.
 360
 361 If you would like to generate and view the HTML locally:
 362 - Install [Sphinx](http://sphinx-doc.org/), including the [sphinx-markdown-tables](https://pypi.org/project/sphinx-markdown-tables/) extension.
 363 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
 364
 365 ```bash
 366 cd ~/llvm-project/build
 367 cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
 368 ninja docs-flang-html
 369 ```
 370
 371 It will generate html in
 372
 373 ```bash
 374    $BROWSER <build-dir>/tools/flang/docs/html/
 375 ```