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 [LLVM's Markdown style guide](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
  38
  39 ## Building flang
  40 There are two ways to build flang. The first method is to build it at the same
  41 time that you build all of the projects on which it depends. This is called
  42 building in tree. The second method is to first do an in tree build to create
  43 all of the projects on which flang depends, and then only build the flang code
  44 itself. This is called building standalone. Building standalone has the
  45 advantage of being smaller and faster. Once you create the base build and base
  46 install areas, you can create multiple standalone builds using them.
  47
  48 Note that instructions for building LLVM can be found at
  49 https://llvm.org/docs/GettingStarted.html.
  50
  51 ### Building flang in tree
  52 Building flang in tree means building flang along with all of the projects on
  53 which it depends.  These projects include mlir, clang, flang, and compiler-rt.
  54 Note that compiler-rt is only needed to access libraries that support 16 bit
  55 floating point numbers.  It's not needed to run the automated tests.
  56
  57 Here's a complete set of commands to clone all of the necessary source and do
  58 the build.
  59
  60 First clone the source:
  61 ```bash
  62 git clone https://github.com/llvm/llvm-project.git my-project
  63 ```
  64 Once the clone is complete, execute the following commands:
  65 ```bash
  66 cd my-project
  67
  68 rm -rf build
  69 mkdir -p build
  70
  71 cd build
  72
  73 cmake \
  74   -G Ninja \
  75   ../llvm \
  76   -DCMAKE_BUILD_TYPE=Release \
  77   -DFLANG_ENABLE_WERROR=On \
  78   -DLLVM_ENABLE_ASSERTIONS=ON \
  79   -DLLVM_TARGETS_TO_BUILD=host \
  80   -DCMAKE_INSTALL_PREFIX=$INSTALLDIR
  81   -DLLVM_LIT_ARGS=-v \
  82   -DLLVM_ENABLE_PROJECTS="clang;mlir;flang" \
  83   -DLLVM_ENABLE_RUNTIMES="compiler-rt"
  84
  85 ninja
  86 ```
  87
  88 To run the flang tests on this build, execute the command in the "build"
  89 directory:
  90 ```bash
  91 ninja check-flang
  92 ```
  93
  94 Note that these instructions specify flang as one of the projects to build in
  95 the in tree build.  This is not strictly necessary for subsequent standalone
  96 builds, but doing so lets you run the flang tests to verify that the source
  97 code is in good shape.
  98 ### Building flang standalone
  99 To do the standalone build, start by building flang in tree as described above.
 100 This build is base build for subsequent standalone builds.  Start each
 101 standalone build the same way by cloning the source for llvm-project:
 102 ```bash
 103 git clone https://github.com/llvm/llvm-project.git standalone
 104 ```
 105 Once the clone is complete, execute the following commands:
 106 ```bash
 107 cd standalone
 108 base=<directory that contains the in tree build>
 109
 110 cd flang
 111 rm -rf build
 112 mkdir build
 113 cd build
 114
 115 cmake \
 116   -G Ninja \
 117   -DCMAKE_BUILD_TYPE=Release \
 118   -DFLANG_ENABLE_WERROR=On \
 119   -DLLVM_TARGETS_TO_BUILD=host \
 120   -DLLVM_ENABLE_ASSERTIONS=On \
 121   -DLLVM_BUILD_MAIN_SRC_DIR=$base/build/lib/cmake/llvm \
 122   -DLLVM_LIT_ARGS=-v \
 123   -DLLVM_DIR=$base/build/lib/cmake/llvm \
 124   -DCLANG_DIR=$base/build/lib/cmake/clang \
 125   -DMLIR_DIR=$base/build/lib/cmake/mlir \
 126   ..
 127
 128 ninja
 129 ```
 130
 131 To run the flang tests on this build, execute the command in the "flang/build"
 132 directory:
 133 ```bash
 134 ninja check-flang
 135 ```
 136
 137 ## Supported C++ compilers
 138
 139 Flang is written in C++17.
 140
 141 The code has been compiled and tested with
 142 GCC versions from 7.2.0 to 9.3.0.
 143
 144 The code has been compiled and tested with
 145 clang version 7.0, 8.0, 9.0 and 10.0
 146 using either GNU's libstdc++ or LLVM's libc++.
 147
 148 The code has been compiled on
 149 AArch64, x86\_64 and ppc64le servers
 150 with CentOS7, Ubuntu18.04, Rhel, MacOs, Mojave, XCode and
 151 Apple Clang version 10.0.1.
 152
 153 ### Building flang with GCC
 154
 155 By default,
 156 cmake will search for g++ on your PATH.
 157 The g++ version must be one of the supported versions
 158 in order to build flang.
 159
 160 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
 161 the full path to the compiler or a name that will be found on your PATH, e.g.
 162 g++-8.3, assuming g++-8.3 is on your PATH.
 163
 164 ```bash
 165 export CXX=g++-8.3
 166 ```
 167 or
 168 ```bash
 169 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
 170 ```
 171
 172 ### Building flang with clang
 173
 174 To build flang with clang,
 175 cmake needs to know how to find clang++
 176 and the GCC library and tools that were used to build clang++.
 177
 178 CXX should include the full path to clang++
 179 or clang++ should be found on your PATH.
 180 ```bash
 181 export CXX=clang++
 182 ```
 183
 184 ### Installation Directory
 185
 186 To specify a custom install location,
 187 add
 188 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
 189 to the cmake command
 190 where `<INSTALL_PREFIX>`
 191 is the path where flang should be installed.
 192
 193 ### Build Types
 194
 195 To create a debug build,
 196 add
 197 `-DCMAKE_BUILD_TYPE=Debug`
 198 to the cmake command.
 199 Debug builds execute slowly.
 200
 201 To create a release build,
 202 add
 203 `-DCMAKE_BUILD_TYPE=Release`
 204 to the cmake command.
 205 Release builds execute quickly.
 206
 207 # How to Run Tests
 208
 209 Flang supports 2 different categories of tests
 210 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
 211 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
 212
 213 ## For standalone builds
 214 To run all tests:
 215 ```bash
 216 cd ~/flang/build
 217 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
 218 ninja check-all
 219 ```
 220
 221 To run individual regression tests llvm-lit needs to know the lit
 222 configuration for flang. The parameters in charge of this are:
 223 flang_site_config and flang_config. And they can be set as shown below:
 224 ```bash
 225 <path-to-llvm-lit>/llvm-lit \
 226  --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
 227  --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
 228   <path-to-fortran-test>
 229
 230 ```
 231
 232 Unit tests:
 233
 234 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`ON` by default), it is possible to generate unittests.
 235 Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries.
 236
 237 There are various ways to run unit-tests.
 238
 239 ```
 240
 241 1. ninja check-flang-unit
 242 2. ninja check-all or ninja check-flang
 243 3. <path-to-llvm-lit>/llvm-lit \
 244         test/Unit
 245 4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
 246
 247 ```
 248
 249
 250 ## For in tree builds
 251 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`On` by default), it is possible to
 252 generate unittests.
 253
 254 To run all of the flang unit tests use the `check-flang-unit` target:
 255 ```bash
 256 ninja check-flang-unit
 257 ```
 258 To run all of the flang regression tests use the `check-flang` target:
 259 ```bash
 260 ninja check-flang
 261 ```
 262
 263 # How to Generate Documentation
 264
 265 ## Generate FIR Documentation
 266 If flang was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
 267 generate FIR language documentation by running `ninja flang-doc`. This will
 268 create `docs/Dialect/FIRLangRef.md` in flang build directory.
 269
 270 ## Generate Doxygen-based Documentation
 271 To generate doxygen-style documentation from source code
 272 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
 273
 274 ```bash
 275 cd ~/llvm-project/build
 276 cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
 277 ninja doxygen-flang
 278 ```
 279
 280 It will generate html in
 281
 282 ```bash
 283     <build-dir>/tools/flang/docs/doxygen/html # for flang docs
 284 ```
 285 ## Generate Sphinx-based Documentation
 286 <!TODO: Add webpage once we have a website.
 287 !>
 288 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
 289 is mostly meant to be processed by the Sphinx documentation generation
 290 system to create HTML pages which would be hosted on the webpage of flang and
 291 updated periodically.
 292
 293 If you would like to generate and view the HTML locally:
 294 - Install [Sphinx](http://sphinx-doc.org/), including the [sphinx-markdown-tables](https://pypi.org/project/sphinx-markdown-tables/) extension.
 295 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
 296
 297 ```bash
 298 cd ~/llvm-project/build
 299 cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
 300 ninja docs-flang-html
 301 ```
 302
 303 It will generate html in
 304
 305 ```bash
 306    $BROWSER <build-dir>/tools/flang/docs/html/
 307 ```