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 The code does not compile with Windows and a compiler that does not have
 154 support for C++17.
 155
 156 ### Building flang with GCC
 157
 158 By default,
 159 cmake will search for g++ on your PATH.
 160 The g++ version must be one of the supported versions
 161 in order to build flang.
 162
 163 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
 164 the full path to the compiler or a name that will be found on your PATH, e.g.
 165 g++-8.3, assuming g++-8.3 is on your PATH.
 166
 167 ```bash
 168 export CXX=g++-8.3
 169 ```
 170 or
 171 ```bash
 172 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
 173 ```
 174
 175 ### Building flang with clang
 176
 177 To build flang with clang,
 178 cmake needs to know how to find clang++
 179 and the GCC library and tools that were used to build clang++.
 180
 181 CXX should include the full path to clang++
 182 or clang++ should be found on your PATH.
 183 ```bash
 184 export CXX=clang++
 185 ```
 186
 187 ### Installation Directory
 188
 189 To specify a custom install location,
 190 add
 191 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
 192 to the cmake command
 193 where `<INSTALL_PREFIX>`
 194 is the path where flang should be installed.
 195
 196 ### Build Types
 197
 198 To create a debug build,
 199 add
 200 `-DCMAKE_BUILD_TYPE=Debug`
 201 to the cmake command.
 202 Debug builds execute slowly.
 203
 204 To create a release build,
 205 add
 206 `-DCMAKE_BUILD_TYPE=Release`
 207 to the cmake command.
 208 Release builds execute quickly.
 209
 210 # How to Run Tests
 211
 212 Flang supports 2 different categories of tests
 213 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
 214 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
 215
 216 ## For standalone builds
 217 To run all tests:
 218 ```bash
 219 cd ~/flang/build
 220 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
 221 ninja check-all
 222 ```
 223
 224 To run individual regression tests llvm-lit needs to know the lit
 225 configuration for flang. The parameters in charge of this are:
 226 flang_site_config and flang_config. And they can be set as shown below:
 227 ```bash
 228 <path-to-llvm-lit>/llvm-lit \
 229  --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
 230  --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
 231   <path-to-fortran-test>
 232
 233 ```
 234
 235 Unit tests:
 236
 237 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`ON` by default), it is possible to generate unittests.
 238 Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries.
 239
 240 There are various ways to run unit-tests.
 241
 242 ```
 243
 244 1. ninja check-flang-unit
 245 2. ninja check-all or ninja check-flang
 246 3. <path-to-llvm-lit>/llvm-lit \
 247         test/Unit
 248 4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
 249
 250 ```
 251
 252
 253 ## For in tree builds
 254 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`On` by default), it is possible to
 255 generate unittests.
 256
 257 To run all of the flang unit tests use the `check-flang-unit` target:
 258 ```bash
 259 ninja check-flang-unit
 260 ```
 261 To run all of the flang regression tests use the `check-flang` target:
 262 ```bash
 263 ninja check-flang
 264 ```
 265
 266 # How to Generate Documentation
 267
 268 ## Generate FIR Documentation
 269 If flang was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
 270 generate FIR language documentation by running `ninja flang-doc`. This will
 271 create `docs/Dialect/FIRLangRef.md` in flang build directory.
 272
 273 ## Generate Doxygen-based Documentation
 274 To generate doxygen-style documentation from source code
 275 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
 276
 277 ```bash
 278 cd ~/llvm-project/build
 279 cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
 280 ninja doxygen-flang
 281 ```
 282
 283 It will generate html in
 284
 285 ```bash
 286     <build-dir>/tools/flang/docs/doxygen/html # for flang docs
 287 ```
 288 ## Generate Sphinx-based Documentation
 289 <!TODO: Add webpage once we have a website.
 290 !>
 291 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
 292 is mostly meant to be processed by the Sphinx documentation generation
 293 system to create HTML pages which would be hosted on the webpage of flang and
 294 updated periodically.
 295
 296 If you would like to generate and view the HTML locally:
 297 - Install [Sphinx](http://sphinx-doc.org/), including the [sphinx-markdown-tables](https://pypi.org/project/sphinx-markdown-tables/) extension.
 298 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
 299
 300 ```bash
 301 cd ~/llvm-project/build
 302 cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
 303 ninja docs-flang-html
 304 ```
 305
 306 It will generate html in
 307
 308 ```bash
 309    $BROWSER <build-dir>/tools/flang/docs/html/
 310 ```