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--- 13local: 14--- 15``` 16 17## Building flang 18There are two ways to build flang. The first method is to build it at the same 19time that you build all of the projects on which it depends. This is called 20building in tree. The second method is to first do an in tree build to create 21all of the projects on which flang depends. Then, after creating this base 22build, only build the flang code itself. This is called building standalone. 23Building standalone has the advantage of being smaller and faster. Once you 24create the base build and base install areas, you can create multiple 25standalone builds using them. 26 27Note that instructions for building LLVM can be found at 28https://llvm.org/docs/GettingStarted.html. 29 30All of the examples below use GCC as the C/C++ compilers and ninja as the build 31tool. 32 33### Building flang in tree 34Building flang in tree means building flang along with all of the projects on 35which it depends. These projects include mlir, clang, flang, openmp, and 36compiler-rt. Note that compiler-rt is only needed to access libraries that 37support 16 bit floating point numbers. It's not needed to run the automated 38tests. You can use several different C++ compilers for most of the build, 39includig GNU and clang. But building compiler-rt requres using the clang 40compiler built in the initial part of the build. 41 42Here's a directory structure that works. Create a root directory for the 43cloned and built files. Under that root directory, clone the source code 44into a directory called llvm-project. The build will also 45create subdirectories under the root directory called build (holds most of 46the built files), install (holds the installed files, and compiler-rt (holds 47the result of building compiler-rt). 48 49Here's a complete set of commands to clone all of the necessary source and do 50the build. 51 52First, create the root directory and `cd` into it. 53```bash 54mkdir root 55cd root 56``` 57 58Now clone the source: 59```bash 60git clone https://github.com/llvm/llvm-project.git 61``` 62Once the clone is complete, execute the following commands: 63```bash 64rm -rf build 65mkdir build 66rm -rf install 67mkdir install 68ROOTDIR=`pwd` 69INSTALLDIR=$ROOTDIR/install 70 71cd build 72 73cmake \ 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 88ninja 89``` 90 91On Darwin, to make flang able to link binaries with the default sysroot without 92having to specify additional flags, use the `DEFAULT_SYSROOT` CMake flag, e.g. 93`-DDEFAULT_SYSROOT="$(xcrun --show-sdk-path)"`. 94 95By default flang tests that do not specify an explicit `--target` flag use 96LLVM's default target triple. For these tests, if there is a need to test on a 97different triple by overriding the default, the following needs to be added to 98the cmake command above: 99`-DLLVM_TARGET_TRIPLE_ENV="<some string>" -DFLANG_TEST_TARGET_TRIPLE="<your triple>"`. 100 101To run the flang tests on this build, execute the command in the "build" 102directory: 103```bash 104ninja check-flang 105``` 106 107To create the installed files: 108```bash 109ninja install 110 111echo "latest" > $INSTALLDIR/bin/versionrc 112``` 113 114To build compiler-rt: 115```bash 116cd $ROOTDIR 117rm -rf compiler-rt 118mkdir compiler-rt 119cd compiler-rt 120CC=$INSTALLDIR/bin/clang \ 121CXX=$INSTALLDIR/bin/clang++ \ 122cmake \ 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 138ninja 139ninja install 140``` 141 142Note that these instructions specify flang as one of the projects to build in 143the in tree build. This is not strictly necessary for subsequent standalone 144builds, but doing so lets you run the flang tests to verify that the source 145code is in good shape. 146 147### Building flang standalone 148To do the standalone build, start by building flang in tree as described above. 149This build can be used as the base build for several subsequent standalone 150builds. Set the environment variable **ROOT_DIR** to the directory that 151contains the subdirectory `build` that was created previously, for example: 152```bash 153export ROOTDIR=/home/user/root 154``` 155Start each standalone build the same way by cloning the source for 156llvm-project: 157```bash 158mkdir standalone 159cd standalone 160git clone https://github.com/llvm/llvm-project.git 161``` 162Once the clone is complete, execute the following commands: 163```bash 164cd llvm-project/flang 165rm -rf build 166mkdir build 167cd build 168 169cmake \ 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 186ninja 187``` 188 189To run the flang tests on this build, execute the command in the `flang/build` 190directory: 191```bash 192ninja check-flang 193``` 194 195### Building flang runtime for accelerators 196Flang runtime can be built for accelerators in experimental mode, i.e. 197complete enabling is WIP. CUDA and OpenMP target offload builds 198are currently supported. 199 200#### Building out-of-tree 201 202##### CUDA build 203Clang with NVPTX backend and NVCC compilers are supported. 204 205```bash 206cd llvm-project/flang 207rm -rf build_flang_runtime 208mkdir build_flang_runtime 209cd build_flang_runtime 210 211cmake \ 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/ 219make -j FortranRuntime 220``` 221 222Note that the used version of `clang` must [support](https://releases.llvm.org/16.0.0/tools/clang/docs/ReleaseNotes.html#cuda-support) 223CUDA toolkit version installed on the build machine. If there are multiple 224CUDA toolkit installations, please use `-DCUDAToolkit_ROOT=/some/path` 225to specify the compatible version. 226 227```bash 228cd llvm-project/flang 229rm -rf build_flang_runtime 230mkdir build_flang_runtime 231cd build_flang_runtime 232 233cmake \ 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 242make -j FortranRuntime 243``` 244 245Note 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`, 247so please use compatible versions. 248 249The result of the build is a "fat" library with the host and device 250code. Note that the packaging of the libraries is different 251between [Clang](https://clang.llvm.org/docs/OffloadingDesign.html#linking-target-device-code) and NVCC, so the library must be linked using 252compatible compiler drivers. 253 254#### Building in-tree 255One may build Flang runtime library along with building Flang itself 256by providing these additional CMake variables on top of the Flang in-tree 257build config: 258 259For 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 269Or: 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 279Normal `make -j check-flang` will work with such CMake configuration. 280 281##### OpenMP target offload build 282Only Clang compiler is currently supported. 283 284```bash 285cd llvm-project/flang 286rm -rf build_flang_runtime 287mkdir build_flang_runtime 288cd build_flang_runtime 289 290cmake \ 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 297make -j FortranRuntime 298``` 299 300The result of the build is a "device-only" library, i.e. the host 301part of the library is just a container for the device code. 302The resulting library may be linked to user programs using 303Clang-like device linking pipeline. 304 305The same set of CMake variables works for Flang in-tree build. 306 307### Build options 308 309One 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 319Flang is written in C++17. 320 321The code has been compiled and tested with GCC versions from 7.2.0 to 9.3.0. 322 323The code has been compiled and tested with clang version 7.0, 8.0, 9.0 and 10.0 324using either GNU's libstdc++ or LLVM's libc++. 325 326The code has been compiled on AArch64, x86_64 and ppc64le servers with CentOS7, 327Ubuntu18.04, Rhel, MacOs, Mojave, XCode and Apple Clang version 10.0.1. 328 329Note that flang is not supported on 32 bit CPUs. 330 331### Building flang with GCC 332 333By default, 334cmake will search for g++ on your PATH. 335The g++ version must be one of the supported versions 336in order to build flang. 337 338Or, cmake will use the variable CXX to find the C++ compiler. CXX should include 339the full path to the compiler or a name that will be found on your PATH, e.g. 340g++-8.3, assuming g++-8.3 is on your PATH. 341 342```bash 343export CXX=g++-8.3 344``` 345or 346```bash 347CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ... 348``` 349 350### Building flang with clang 351 352To build flang with clang, 353cmake needs to know how to find clang++ 354and the GCC library and tools that were used to build clang++. 355 356CXX should include the full path to clang++ 357or clang++ should be found on your PATH. 358 359```bash 360export CXX=clang++ 361``` 362 363### Installation Directory 364 365To specify a custom install location, 366add 367`-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>` 368to the cmake command 369where `<INSTALL_PREFIX>` 370is the path where flang should be installed. 371 372### Build Types 373 374To create a debug build, 375add 376`-DCMAKE_BUILD_TYPE=Debug` 377to the cmake command. 378Debug builds execute slowly. 379 380To create a release build, 381add 382`-DCMAKE_BUILD_TYPE=Release` 383to the cmake command. 384Release builds execute quickly. 385 386## How to Run Tests 387 388Flang supports 2 different categories of tests 3891. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests) 3902. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests) 391 392### For standalone builds 393To run all tests: 394```bash 395cd ~/flang/build 396cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src 397ninja check-all 398``` 399 400To run individual regression tests llvm-lit needs to know the lit 401configuration for flang. The parameters in charge of this are: 402flang_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 411Unit tests: 412 413If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to generate unittests. 414Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries. 415 416There are various ways to run unit-tests. 417 418``` 419 4201. ninja check-flang-unit 4212. ninja check-all or ninja check-flang 4223. <path-to-llvm-lit>/llvm-lit \ 423 test/Unit 4244. Invoking tests from <standalone flang build>/unittests/<respective unit test folder> 425 426``` 427 428 429### For in tree builds 430If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to 431generate unittests. 432 433To run all of the flang unit tests use the `check-flang-unit` target: 434```bash 435ninja check-flang-unit 436``` 437To run all of the flang regression tests use the `check-flang` target: 438```bash 439ninja check-flang 440``` 441 442## How to Generate Documentation 443 444### Generate FIR Documentation 445If flang was built with `-DLINK_WITH_FIR=ON` (`ON` by default), it is possible to 446generate FIR language documentation by running `ninja flang-doc`. This will 447create `<build-dir>/tools/flang/docs/Dialect/FIRLangRef.md` in flang build directory. 448 449### Generate Doxygen-based Documentation 450To generate doxygen-style documentation from source code 451- Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command. 452 453```bash 454cd ~/llvm-project/build 455cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm 456ninja doxygen-flang 457``` 458 459It 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 466is mostly meant to be processed by the Sphinx documentation generation 467system to create HTML pages which would be hosted on the webpage of flang and 468updated periodically. 469 470If 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 476cd ~/llvm-project/build 477cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm 478ninja docs-flang-html 479``` 480 481It will generate html in 482 483```bash 484 $BROWSER <build-dir>/tools/flang/docs/html/ 485``` 486 487