xref: /llvm-project/flang/docs/GettingStarted.md (revision 25ebbe3851c54f035875fd3d7d2569d79cacf803)
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