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 ## Getting Started
  10
  11 Read more about flang in the [docs directory](docs).
  12 Start with the [compiler overview](docs/Overview.md).
  13
  14 To better understand Fortran as a language
  15 and the specific grammar accepted by flang,
  16 read [Fortran For C Programmers](docs/FortranForCProgrammers.md)
  17 and
  18 flang's specifications of the [Fortran grammar](docs/f2018-grammar.md)
  19 and
  20 the [OpenMP grammar](docs/OpenMP-4.5-grammar.md).
  21
  22 Treatment of language extensions is covered
  23 in [this document](docs/Extensions.md).
  24
  25 To understand the compilers handling of intrinsics,
  26 see the [discussion of intrinsics](docs/Intrinsics.md).
  27
  28 To understand how a flang program communicates with libraries at runtime,
  29 see the discussion of [runtime descriptors](docs/RuntimeDescriptor.md).
  30
  31 If you're interested in contributing to the compiler,
  32 read the [style guide](docs/C++style.md)
  33 and
  34 also review [how flang uses modern C++ features](docs/C++17.md).
  35
  36 If you are interested in writing new documentation, follow
  37 [markdown style guide from LLVM](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
  38
  39 ## Supported C++ compilers
  40
  41 Flang is written in C++17.
  42
  43 The code has been compiled and tested with
  44 GCC versions from 7.2.0 to 9.3.0.
  45
  46 The code has been compiled and tested with
  47 clang version 7.0, 8.0, 9.0 and 10.0
  48 using either GNU's libstdc++ or LLVM's libc++.
  49
  50 The code has been compiled on
  51 AArch64, x86\_64 and ppc64le servers
  52 with CentOS7, Ubuntu18.04, Rhel, MacOs, Mojave, XCode and
  53 Apple Clang version 10.0.1.
  54
  55 The code does not compile with Windows and a compiler that does not have
  56 support for C++17.
  57
  58 ## Building Flang out of tree
  59 These instructions are for building Flang separately from LLVM; if you are
  60 building Flang alongside LLVM then follow the standard LLVM build instructions
  61 and add flang to `LLVM_ENABLE_PROJECTS` instead, as detailed there.
  62
  63 ### LLVM dependency
  64
  65 The instructions to build LLVM can be found at
  66 https://llvm.org/docs/GettingStarted.html. If you are building flang as part
  67 of LLVM, follow those instructions and add flang to `LLVM_ENABLE_PROJECTS`.
  68
  69 We highly recommend using the same compiler to compile both llvm and flang.
  70
  71 The flang CMakeList.txt file uses
  72 * `LLVM_DIR` to find the installed LLVM components
  73 * `MLIR_DIR` to find the installed MLIR components
  74 * `CLANG_DIR` to find the installed Clang components
  75
  76 To get the correct LLVM, MLIR and Clang libraries included in your flang build,
  77 define `LLVM_DIR`, `MLIR_DIR` and `CLANG_DIR` on the cmake command line.
  78 ```
  79 LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm \
  80 MLIR=<LLVM_BUILD_DIR>/lib/cmake/mlir \
  81 CLANG=<LLVM_BUILD_DIR>/lib/cmake/clang \
  82 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR -DCLANG_DIR=$CLANG ...
  83 ```
  84 where `LLVM_BUILD_DIR` is
  85 the top-level directory where LLVM was built.
  86
  87 ### Building flang with GCC
  88
  89 By default,
  90 cmake will search for g++ on your PATH.
  91 The g++ version must be one of the supported versions
  92 in order to build flang.
  93
  94 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
  95 the full path to the compiler or a name that will be found on your PATH, e.g.
  96 g++-8.3, assuming g++-8.3 is on your PATH.
  97
  98 ```
  99 export CXX=g++-8.3
 100 ```
 101 or
 102 ```
 103 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
 104 ```
 105
 106 ### Building flang with clang
 107
 108 To build flang with clang,
 109 cmake needs to know how to find clang++
 110 and the GCC library and tools that were used to build clang++.
 111
 112 CXX should include the full path to clang++
 113 or clang++ should be found on your PATH.
 114 ```
 115 export CXX=clang++
 116 ```
 117
 118 ### Installation Directory
 119
 120 To specify a custom install location,
 121 add
 122 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
 123 to the cmake command
 124 where `<INSTALL_PREFIX>`
 125 is the path where flang should be installed.
 126
 127 ### Build Types
 128
 129 To create a debug build,
 130 add
 131 `-DCMAKE_BUILD_TYPE=Debug`
 132 to the cmake command.
 133 Debug builds execute slowly.
 134
 135 To create a release build,
 136 add
 137 `-DCMAKE_BUILD_TYPE=Release`
 138 to the cmake command.
 139 Release builds execute quickly.
 140
 141 ### Build Flang out of tree
 142 ```
 143 cd ~/flang/build
 144 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR -DCLANG_DIR=$CLANG ~/flang/src
 145 make
 146 ```
 147
 148 ### Disable The New Flang Driver
 149 The new Flang compiler driver, `flang-new`, is implemented in terms of
 150 `clangDriver` and hence it introduces a dependency on Clang. This dependency is
 151 otherwise not required. If you do not require the new driver, you can disable
 152 it by adding `-DFLANG_BUILD_NEW_DRIVER=OFF` to your CMake invocation. With the
 153 new driver disabled, you no longer need to add `clang` to
 154 `LLVM_ENABLE_PROJECTS` (or to specify `CLANG_DIR` when building out-of-tree).
 155
 156 # How to Run Tests
 157
 158 Flang supports 2 different categories of tests
 159 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
 160 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
 161
 162 ## For out of tree builds
 163 To run all tests:
 164 ```
 165 cd ~/flang/build
 166 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
 167 make test check-all
 168 ```
 169
 170 To run individual regression tests llvm-lit needs to know the lit
 171 configuration for flang. The parameters in charge of this are:
 172 flang_site_config and flang_config. And they can be set as shown below:
 173 ```
 174 <path-to-llvm-lit>/llvm-lit \
 175  --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
 176  --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
 177   <path-to-fortran-test>
 178
 179 ```
 180
 181 Unit tests:
 182
 183 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`ON` by default), it is possible to generate unittests.
 184 Note: Unit-tests will be skipped for LLVM install for an out-of-tree build as it does not include googletest related headers and libraries.
 185
 186 There are various ways to run unit-tests.
 187
 188 ```
 189
 190 1. make check-flang-unit
 191 2. make check-all or make check-flang
 192 3. <path-to-llvm-lit>/llvm-lit \
 193         test/Unit
 194 4. Invoking tests from <out-of-tree flang build>/unittests/<respective unit test folder>
 195
 196 ```
 197
 198
 199 ## For in tree builds
 200 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`On` by default), it is possible to
 201 generate unittests.
 202
 203 To run all of the flang unit tests use the `check-flang-unit` target:
 204 ```
 205 make check-flang-unit
 206 ```
 207 To run all of the flang regression tests use the `check-flang` target:
 208 ```
 209 make check-flang
 210 ```
 211
 212 # How to Generate Documentation
 213
 214 ## Generate FIR Documentation
 215 If flang was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
 216 generate FIR language documentation by running `make flang-doc`. This will
 217 create `docs/Dialect/FIRLangRef.md` in flang build directory.
 218
 219 ## Generate Doxygen-based Documentation
 220 To generate doxygen-style documentation from source code
 221 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
 222
 223 ```
 224 cd ~/llvm-project/build
 225 cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
 226 make doxygen-flang
 227 ```
 228
 229 It will generate html in
 230
 231 ```
 232     <build-dir>/tools/flang/docs/doxygen/html # for flang docs
 233 ```
 234 ## Generate Sphinx-based Documentation
 235 <!TODO: Add webpage once we have a website.
 236 !>
 237 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
 238 is mostly meant to be processed by the Sphinx documentation generation
 239 system to create HTML pages which would be hosted on the webpage of flang and
 240 updated periodically.
 241
 242 If you would like to generate and view the HTML locally:
 243 - Install [Sphinx](http://sphinx-doc.org/), including the [sphinx-markdown-tables](https://pypi.org/project/sphinx-markdown-tables/) extension.
 244 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
 245
 246 ```
 247 cd ~/llvm-project/build
 248 cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
 249 make docs-flang-html
 250 ```
 251
 252 It will generate html in
 253
 254 ```
 255    $BROWSER <build-dir>/tools/flang/docs/html/
 256 ```