flang/docs/GettingStarted.md

   1 <!--===- docs/GettingStarted.md
   2
   3    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4    See https://llvm.org/LICENSE.txt for license information.
   5    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6
   7 -->
   8
   9 # Getting Started
  10
  11 ```{contents}
  12 ---
  13 local:
  14 ---
  15 ```
  16
  17 ## Building flang
  18 There are two ways to build flang. The first method is to build it at the same
  19 time that you build all of the projects on which it depends. This is called
  20 building in tree. The second method is to first do an in tree build to create
  21 all of the projects on which flang depends.  Then, after creating this base
  22 build, only build the flang code itself. This is called building standalone.
  23 Building standalone has the advantage of being smaller and faster. Once you
  24 create the base build and base install areas, you can create multiple
  25 standalone builds using them.
  26
  27 Note that instructions for building LLVM can be found at
  28 https://llvm.org/docs/GettingStarted.html.
  29
  30 All of the examples below use GCC as the C/C++ compilers and ninja as the build
  31 tool.
  32
  33 ### Building flang in tree
  34 Building flang in tree means building flang along with all of the projects on
  35 which it depends.  These projects include mlir, clang, flang, openmp, and
  36 compiler-rt.  Note that compiler-rt is only needed to access libraries that
  37 support 16 bit floating point numbers.  It's not needed to run the automated
  38 tests.  You can use several different C++ compilers for most of the build,
  39 includig GNU and clang.  But building compiler-rt requres using the clang
  40 compiler built in the initial part of the build.
  41
  42 Here's a directory structure that works.  Create a root directory for the
  43 cloned and built files.  Under that root directory, clone the source code
  44 into a directory called llvm-project.  The build will also
  45 create subdirectories under the root directory called build (holds most of
  46 the built files), install (holds the installed files, and compiler-rt (holds
  47 the result of building compiler-rt).
  48
  49 Here's a complete set of commands to clone all of the necessary source and do
  50 the build.
  51
  52 First, create the root directory and `cd` into it.
  53 ```bash
  54 mkdir root
  55 cd root
  56 ```
  57
  58 Now clone the source:
  59 ```bash
  60 git clone https://github.com/llvm/llvm-project.git
  61 ```
  62 Once the clone is complete, execute the following commands:
  63 ```bash
  64 rm -rf build
  65 mkdir build
  66 rm -rf install
  67 mkdir install
  68 ROOTDIR=`pwd`
  69 INSTALLDIR=$ROOTDIR/install
  70
  71 cd build
  72
  73 cmake \
  74   -G Ninja \
  75   -DCMAKE_BUILD_TYPE=Release \
  76   -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
  77   -DCMAKE_CXX_STANDARD=17 \
  78   -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
  79   -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
  80   -DFLANG_ENABLE_WERROR=ON \
  81   -DLLVM_ENABLE_ASSERTIONS=ON \
  82   -DLLVM_TARGETS_TO_BUILD=host \
  83   -DLLVM_LIT_ARGS=-v \
  84   -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;openmp" \
  85   -DLLVM_ENABLE_RUNTIMES="compiler-rt" \
  86   ../llvm-project/llvm
  87
  88 ninja
  89 ```
  90
  91 On Darwin, to make flang able to link binaries with the default sysroot without
  92 having to specify additional flags, use the `DEFAULT_SYSROOT` CMake flag, e.g.
  93 `-DDEFAULT_SYSROOT="$(xcrun --show-sdk-path)"`.
  94
  95 By default flang tests that do not specify an explicit `--target` flag use
  96 LLVM's default target triple. For these tests, if there is a need to test on a
  97 different triple by overriding the default, the following needs to be added to
  98 the cmake command above:
  99 `-DLLVM_TARGET_TRIPLE_ENV="<some string>" -DFLANG_TEST_TARGET_TRIPLE="<your triple>"`.
 100
 101 To run the flang tests on this build, execute the command in the "build"
 102 directory:
 103 ```bash
 104 ninja check-flang
 105 ```
 106
 107 To create the installed files:
 108 ```bash
 109 ninja install
 110
 111 echo "latest" > $INSTALLDIR/bin/versionrc
 112 ```
 113
 114 To build compiler-rt:
 115 ```bash
 116 cd $ROOTDIR
 117 rm -rf compiler-rt
 118 mkdir compiler-rt
 119 cd compiler-rt
 120 CC=$INSTALLDIR/bin/clang \
 121 CXX=$INSTALLDIR/bin/clang++ \
 122 cmake \
 123   -G Ninja \
 124   ../llvm-project/compiler-rt \
 125   -DCMAKE_BUILD_TYPE=Release \
 126   -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
 127   -DCMAKE_CXX_STANDARD=11 \
 128   -DCMAKE_C_CFLAGS=-mlong-double-128 \
 129   -DCMAKE_CXX_CFLAGS=-mlong-double-128 \
 130   -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
 131   -DCOMPILER_RT_BUILD_ORC=OFF \
 132   -DCOMPILER_RT_BUILD_XRAY=OFF \
 133   -DCOMPILER_RT_BUILD_MEMPROF=OFF \
 134   -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
 135   -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
 136   -DLLVM_CONFIG_PATH=$INSTALLDIR/bin/llvm-config
 137
 138 ninja
 139 ninja install
 140 ```
 141
 142 Note that these instructions specify flang as one of the projects to build in
 143 the in tree build.  This is not strictly necessary for subsequent standalone
 144 builds, but doing so lets you run the flang tests to verify that the source
 145 code is in good shape.
 146
 147 ### Building flang standalone
 148 To do the standalone build, start by building flang in tree as described above.
 149 This build can be used as the  base build for several subsequent standalone
 150 builds.  Set the environment variable **ROOT_DIR** to the directory that
 151 contains the subdirectory `build` that was created previously, for example:
 152 ```bash
 153 export ROOTDIR=/home/user/root
 154 ```
 155 Start each standalone build the same way by cloning the source for
 156 llvm-project:
 157 ```bash
 158 mkdir standalone
 159 cd standalone
 160 git clone https://github.com/llvm/llvm-project.git
 161 ```
 162 Once the clone is complete, execute the following commands:
 163 ```bash
 164 cd llvm-project/flang
 165 rm -rf build
 166 mkdir build
 167 cd build
 168
 169 cmake \
 170   -G Ninja \
 171   -DCMAKE_BUILD_TYPE=Release \
 172   -DCMAKE_CXX_STANDARD=17 \
 173   -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
 174   -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
 175   -DFLANG_ENABLE_WERROR=ON \
 176   -DLLVM_TARGETS_TO_BUILD=host \
 177   -DLLVM_ENABLE_ASSERTIONS=ON \
 178   -DLLVM_BUILD_MAIN_SRC_DIR=$ROOTDIR/build/lib/cmake/llvm \
 179   -DLLVM_EXTERNAL_LIT=$ROOTDIR/build/bin/llvm-lit \
 180   -DLLVM_LIT_ARGS=-v \
 181   -DLLVM_DIR=$ROOTDIR/build/lib/cmake/llvm \
 182   -DCLANG_DIR=$ROOTDIR/build/lib/cmake/clang \
 183   -DMLIR_DIR=$ROOTDIR/build/lib/cmake/mlir \
 184   ..
 185
 186 ninja
 187 ```
 188
 189 To run the flang tests on this build, execute the command in the `flang/build`
 190 directory:
 191 ```bash
 192 ninja check-flang
 193 ```
 194
 195 ### Building flang runtime for accelerators
 196 Flang runtime can be built for accelerators in experimental mode, i.e.
 197 complete enabling is WIP.  CUDA and OpenMP target offload builds
 198 are currently supported.
 199
 200 #### Building out-of-tree
 201
 202 ##### CUDA build
 203 Clang with NVPTX backend and NVCC compilers are supported.
 204
 205 ```bash
 206 cd llvm-project/flang
 207 rm -rf build_flang_runtime
 208 mkdir build_flang_runtime
 209 cd build_flang_runtime
 210
 211 cmake \
 212   -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \
 213   -DCMAKE_CUDA_ARCHITECTURES=80 \
 214   -DCMAKE_C_COMPILER=clang \
 215   -DCMAKE_CXX_COMPILER=clang++ \
 216   -DCMAKE_CUDA_COMPILER=clang \
 217   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
 218   ../runtime/
 219 make -j FortranRuntime
 220 ```
 221
 222 Note that the used version of `clang` must [support](https://releases.llvm.org/16.0.0/tools/clang/docs/ReleaseNotes.html#cuda-support)
 223 CUDA toolkit version installed on the build machine.  If there are multiple
 224 CUDA toolkit installations, please use `-DCUDAToolkit_ROOT=/some/path`
 225 to specify the compatible version.
 226
 227 ```bash
 228 cd llvm-project/flang
 229 rm -rf build_flang_runtime
 230 mkdir build_flang_runtime
 231 cd build_flang_runtime
 232
 233 cmake \
 234   -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \
 235   -DCMAKE_CUDA_ARCHITECTURES=80 \
 236   -DCMAKE_C_COMPILER=clang \
 237   -DCMAKE_CXX_COMPILER=clang++ \
 238   -DCMAKE_CUDA_COMPILER=nvcc \
 239   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
 240   ../runtime/
 241
 242 make -j FortranRuntime
 243 ```
 244
 245 Note that `nvcc` might limit support to certain
 246 [versions](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#host-compiler-support-policy) of `CMAKE_CUDA_HOST_COMPILER`,
 247 so please use compatible versions.
 248
 249 The result of the build is a "fat" library with the host and device
 250 code.  Note that the packaging of the libraries is different
 251 between [Clang](https://clang.llvm.org/docs/OffloadingDesign.html#linking-target-device-code) and NVCC, so the library must be linked using
 252 compatible compiler drivers.
 253
 254 #### Building in-tree
 255 One may build Flang runtime library along with building Flang itself
 256 by providing these additional CMake variables on top of the Flang in-tree
 257 build config:
 258
 259 For example:
 260 ```bash
 261   -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \
 262   -DCMAKE_CUDA_ARCHITECTURES=80 \
 263   -DCMAKE_C_COMPILER=clang \
 264   -DCMAKE_CXX_COMPILER=clang++ \
 265   -DCMAKE_CUDA_COMPILER=clang \
 266   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
 267 ```
 268
 269 Or:
 270 ```bash
 271   -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \
 272   -DCMAKE_CUDA_ARCHITECTURES=80 \
 273   -DCMAKE_C_COMPILER=gcc \
 274   -DCMAKE_CXX_COMPILER=g++ \
 275   -DCMAKE_CUDA_COMPILER=nvcc \
 276   -DCMAKE_CUDA_HOST_COMPILER=g++ \
 277 ```
 278
 279 Normal `make -j check-flang` will work with such CMake configuration.
 280
 281 ##### OpenMP target offload build
 282 Only Clang compiler is currently supported.
 283
 284 ```bash
 285 cd llvm-project/flang
 286 rm -rf build_flang_runtime
 287 mkdir build_flang_runtime
 288 cd build_flang_runtime
 289
 290 cmake \
 291   -DFLANG_EXPERIMENTAL_OMP_OFFLOAD_BUILD="host_device" \
 292   -DCMAKE_C_COMPILER=clang \
 293   -DCMAKE_CXX_COMPILER=clang++ \
 294   -DFLANG_OMP_DEVICE_ARCHITECTURES="all" \
 295   ../runtime/
 296
 297 make -j FortranRuntime
 298 ```
 299
 300 The result of the build is a "device-only" library, i.e. the host
 301 part of the library is just a container for the device code.
 302 The resulting library may be linked to user programs using
 303 Clang-like device linking pipeline.
 304
 305 The same set of CMake variables works for Flang in-tree build.
 306
 307 ### Build options
 308
 309 One may provide optional CMake variables to customize the build. Available options:
 310
 311 * `-DFLANG_RUNTIME_F128_MATH_LIB=libquadmath`: enables build of
 312   `FortranFloat128Math` library that provides `REAL(16)` math APIs
 313   for intrinsics such as `SIN`, `COS`, etc. GCC `libquadmath`'s header file
 314   `quadmath.h` must be available to the build compiler.
 315   [More details](Real16MathSupport.md).
 316
 317 ## Supported C++ compilers
 318
 319 Flang is written in C++17.
 320
 321 The code has been compiled and tested with GCC versions from 7.2.0 to 9.3.0.
 322
 323 The code has been compiled and tested with clang version 7.0, 8.0, 9.0 and 10.0
 324 using either GNU's libstdc++ or LLVM's libc++.
 325
 326 The code has been compiled on AArch64, x86_64 and ppc64le servers with CentOS7,
 327 Ubuntu18.04, Rhel, MacOs, Mojave, XCode and Apple Clang version 10.0.1.
 328
 329 Note that flang is not supported on 32 bit CPUs.
 330
 331 ### Building flang with GCC
 332
 333 By default,
 334 cmake will search for g++ on your PATH.
 335 The g++ version must be one of the supported versions
 336 in order to build flang.
 337
 338 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
 339 the full path to the compiler or a name that will be found on your PATH, e.g.
 340 g++-8.3, assuming g++-8.3 is on your PATH.
 341
 342 ```bash
 343 export CXX=g++-8.3
 344 ```
 345 or
 346 ```bash
 347 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
 348 ```
 349
 350 ### Building flang with clang
 351
 352 To build flang with clang,
 353 cmake needs to know how to find clang++
 354 and the GCC library and tools that were used to build clang++.
 355
 356 CXX should include the full path to clang++
 357 or clang++ should be found on your PATH.
 358
 359 ```bash
 360 export CXX=clang++
 361 ```
 362
 363 ### Installation Directory
 364
 365 To specify a custom install location,
 366 add
 367 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
 368 to the cmake command
 369 where `<INSTALL_PREFIX>`
 370 is the path where flang should be installed.
 371
 372 ### Build Types
 373
 374 To create a debug build,
 375 add
 376 `-DCMAKE_BUILD_TYPE=Debug`
 377 to the cmake command.
 378 Debug builds execute slowly.
 379
 380 To create a release build,
 381 add
 382 `-DCMAKE_BUILD_TYPE=Release`
 383 to the cmake command.
 384 Release builds execute quickly.
 385
 386 ## How to Run Tests
 387
 388 Flang supports 2 different categories of tests
 389 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
 390 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
 391
 392 ### For standalone builds
 393 To run all tests:
 394 ```bash
 395 cd ~/flang/build
 396 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
 397 ninja check-all
 398 ```
 399
 400 To run individual regression tests llvm-lit needs to know the lit
 401 configuration for flang. The parameters in charge of this are:
 402 flang_site_config and flang_config. And they can be set as shown below:
 403 ```bash
 404 <path-to-llvm-lit>/llvm-lit \
 405  --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
 406  --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
 407   <path-to-fortran-test>
 408
 409 ```
 410
 411 Unit tests:
 412
 413 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to generate unittests.
 414 Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries.
 415
 416 There are various ways to run unit-tests.
 417
 418 ```
 419
 420 1. ninja check-flang-unit
 421 2. ninja check-all or ninja check-flang
 422 3. <path-to-llvm-lit>/llvm-lit \
 423         test/Unit
 424 4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
 425
 426 ```
 427
 428
 429 ### For in tree builds
 430 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to
 431 generate unittests.
 432
 433 To run all of the flang unit tests use the `check-flang-unit` target:
 434 ```bash
 435 ninja check-flang-unit
 436 ```
 437 To run all of the flang regression tests use the `check-flang` target:
 438 ```bash
 439 ninja check-flang
 440 ```
 441
 442 ## How to Generate Documentation
 443
 444 ### Generate FIR Documentation
 445 If flang was built with `-DLINK_WITH_FIR=ON` (`ON` by default), it is possible to
 446 generate FIR language documentation by running `ninja flang-doc`. This will
 447 create `<build-dir>/tools/flang/docs/Dialect/FIRLangRef.md` in flang build directory.
 448
 449 ### Generate Doxygen-based Documentation
 450 To generate doxygen-style documentation from source code
 451 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
 452
 453 ```bash
 454 cd ~/llvm-project/build
 455 cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
 456 ninja doxygen-flang
 457 ```
 458
 459 It will generate html in
 460
 461 ```bash
 462     <build-dir>/tools/flang/docs/doxygen/html # for flang docs
 463 ```
 464 ### Generate Sphinx-based Documentation
 465 [Flang documentation](https://flang.llvm.org/docs/) 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
 466 is mostly meant to be processed by the Sphinx documentation generation
 467 system to create HTML pages which would be hosted on the webpage of flang and
 468 updated periodically.
 469
 470 If you would like to generate and view the HTML locally:
 471 - Install [Sphinx](http://sphinx-doc.org/), and the required extensions
 472   using `pip install --user -r ~/llvm-projects/docs/requirements.txt`
 473 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
 474
 475 ```bash
 476 cd ~/llvm-project/build
 477 cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
 478 ninja docs-flang-html
 479 ```
 480
 481 It will generate html in
 482
 483 ```bash
 484    $BROWSER <build-dir>/tools/flang/docs/html/
 485 ```
 486