[clang][modules] Don't prevent translation of FW_Private includes when explicitly...
[llvm-project.git] / flang / docs / GettingStarted.md
blobc6cd18db2e15d0afa83cd2b52d9c18630cbb142e
1 <!--===- docs/GettingStarted.md
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
7 -->
9 # Getting Started
11 ```{contents}
12 ---
13 local:
14 ---
15 ```
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.
27 Note that instructions for building LLVM can be found at
28 https://llvm.org/docs/GettingStarted.html.
30 All of the examples below use GCC as the C/C++ compilers and ninja as the build
31 tool.
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.
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).
49 Here's a complete set of commands to clone all of the necessary source and do
50 the build.
52 First, create the root directory and `cd` into it.
53 ```bash
54 mkdir root
55 cd root
56 ```
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
71 cd build
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
88 ninja
89 ```
91 By default flang tests that do not specify an explicit `--target` flag use
92 LLVM's default target triple. For these tests, if there is a need to test on a
93 different triple by overriding the default, the following needs to be added to
94 the cmake command above:
95 `-DLLVM_TARGET_TRIPLE_ENV="<some string>" -DFLANG_TEST_TARGET_TRIPLE="<your triple>"`.
97 To run the flang tests on this build, execute the command in the "build"
98 directory:
99 ```bash
100 ninja check-flang
103 To create the installed files:
104 ```bash
105 ninja install
107 echo "latest" > $INSTALLDIR/bin/versionrc
110 To build compiler-rt:
111 ```bash
112 cd $ROOTDIR
113 rm -rf compiler-rt
114 mkdir compiler-rt
115 cd compiler-rt
116 CC=$INSTALLDIR/bin/clang \
117 CXX=$INSTALLDIR/bin/clang++ \
118 cmake \
119   -G Ninja \
120   ../llvm-project/compiler-rt \
121   -DCMAKE_BUILD_TYPE=Release \
122   -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
123   -DCMAKE_CXX_STANDARD=11 \
124   -DCMAKE_C_CFLAGS=-mlong-double-128 \
125   -DCMAKE_CXX_CFLAGS=-mlong-double-128 \
126   -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
127   -DCOMPILER_RT_BUILD_ORC=OFF \
128   -DCOMPILER_RT_BUILD_XRAY=OFF \
129   -DCOMPILER_RT_BUILD_MEMPROF=OFF \
130   -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
131   -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
132   -DLLVM_CONFIG_PATH=$INSTALLDIR/bin/llvm-config
134 ninja
135 ninja install
138 Note that these instructions specify flang as one of the projects to build in
139 the in tree build.  This is not strictly necessary for subsequent standalone
140 builds, but doing so lets you run the flang tests to verify that the source
141 code is in good shape.
143 ### Building flang standalone
144 To do the standalone build, start by building flang in tree as described above.
145 This build can be used as the  base build for several subsequent standalone
146 builds.  Set the environment variable **ROOT_DIR** to the directory that
147 contains the subdirectory `build` that was created previously, for example:
148 ```bash
149 export ROOTDIR=/home/user/root
151 Start each standalone build the same way by cloning the source for
152 llvm-project:
153 ```bash
154 mkdir standalone
155 cd standalone
156 git clone https://github.com/llvm/llvm-project.git
158 Once the clone is complete, execute the following commands:
159 ```bash
160 cd llvm-project/flang
161 rm -rf build
162 mkdir build
163 cd build
165 cmake \
166   -G Ninja \
167   -DCMAKE_BUILD_TYPE=Release \
168   -DCMAKE_CXX_STANDARD=17 \
169   -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
170   -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
171   -DFLANG_ENABLE_WERROR=ON \
172   -DLLVM_TARGETS_TO_BUILD=host \
173   -DLLVM_ENABLE_ASSERTIONS=ON \
174   -DLLVM_BUILD_MAIN_SRC_DIR=$ROOTDIR/build/lib/cmake/llvm \
175   -DLLVM_EXTERNAL_LIT=$ROOTDIR/build/bin/llvm-lit \
176   -DLLVM_LIT_ARGS=-v \
177   -DLLVM_DIR=$ROOTDIR/build/lib/cmake/llvm \
178   -DCLANG_DIR=$ROOTDIR/build/lib/cmake/clang \
179   -DMLIR_DIR=$ROOTDIR/build/lib/cmake/mlir \
180   ..
182 ninja
185 To run the flang tests on this build, execute the command in the `flang/build`
186 directory:
187 ```bash
188 ninja check-flang
191 ### Building flang runtime for accelerators
192 Flang runtime can be built for accelerators in experimental mode, i.e.
193 complete enabling is WIP.  CUDA and OpenMP target offload builds
194 are currently supported.
196 #### Building out-of-tree
198 ##### CUDA build
199 Clang with NVPTX backend and NVCC compilers are supported.
201 ```bash
202 cd llvm-project/flang
203 rm -rf build_flang_runtime
204 mkdir build_flang_runtime
205 cd build_flang_runtime
207 cmake \
208   -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \
209   -DCMAKE_CUDA_ARCHITECTURES=80 \
210   -DCMAKE_C_COMPILER=clang \
211   -DCMAKE_CXX_COMPILER=clang++ \
212   -DCMAKE_CUDA_COMPILER=clang \
213   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
214   ../runtime/
215 make -j FortranRuntime
218 Note that the used version of `clang` must [support](https://releases.llvm.org/16.0.0/tools/clang/docs/ReleaseNotes.html#cuda-support)
219 CUDA toolkit version installed on the build machine.  If there are multiple
220 CUDA toolkit installations, please use `-DCUDAToolkit_ROOT=/some/path`
221 to specify the compatible version.
223 ```bash
224 cd llvm-project/flang
225 rm -rf build_flang_runtime
226 mkdir build_flang_runtime
227 cd build_flang_runtime
229 cmake \
230   -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \
231   -DCMAKE_CUDA_ARCHITECTURES=80 \
232   -DCMAKE_C_COMPILER=clang \
233   -DCMAKE_CXX_COMPILER=clang++ \
234   -DCMAKE_CUDA_COMPILER=nvcc \
235   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
236   ../runtime/
238 make -j FortranRuntime
241 Note that `nvcc` might limit support to certain
242 [versions](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#host-compiler-support-policy) of `CMAKE_CUDA_HOST_COMPILER`,
243 so please use compatible versions.
245 The result of the build is a "fat" library with the host and device
246 code.  Note that the packaging of the libraries is different
247 between [Clang](https://clang.llvm.org/docs/OffloadingDesign.html#linking-target-device-code) and NVCC, so the library must be linked using
248 compatible compiler drivers.
250 ### Bulding in-tree
251 One may build Flang runtime library along with building Flang itself
252 by providing these additional CMake variables on top of the Flang in-tree
253 build config:
255 For example:
256 ```bash
257   -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \
258   -DCMAKE_CUDA_ARCHITECTURES=80 \
259   -DCMAKE_C_COMPILER=clang \
260   -DCMAKE_CXX_COMPILER=clang++ \
261   -DCMAKE_CUDA_COMPILER=clang \
262   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
266 ```bash
267   -DFLANG_EXPERIMENTAL_CUDA_RUNTIME=ON \
268   -DCMAKE_CUDA_ARCHITECTURES=80 \
269   -DCMAKE_C_COMPILER=gcc \
270   -DCMAKE_CXX_COMPILER=g++ \
271   -DCMAKE_CUDA_COMPILER=nvcc \
272   -DCMAKE_CUDA_HOST_COMPILER=g++ \
275 Normal `make -j check-flang` will work with such CMake configuration.
277 ##### OpenMP target offload build
278 Only Clang compiler is currently supported.
280 ```bash
281 cd llvm-project/flang
282 rm -rf build_flang_runtime
283 mkdir build_flang_runtime
284 cd build_flang_runtime
286 cmake \
287   -DFLANG_EXPERIMENTAL_OMP_OFFLOAD_BUILD="host_device" \
288   -DCMAKE_C_COMPILER=clang \
289   -DCMAKE_CXX_COMPILER=clang++ \
290   -DFLANG_OMP_DEVICE_ARCHITECTURES="all" \
291   ../runtime/
293 make -j FortranRuntime
296 The result of the build is a "device-only" library, i.e. the host
297 part of the library is just a container for the device code.
298 The resulting library may be linked to user programs using
299 Clang-like device linking pipeline.
301 The same set of CMake variables works for Flang in-tree build.
303 ## Supported C++ compilers
305 Flang is written in C++17.
307 The code has been compiled and tested with GCC versions from 7.2.0 to 9.3.0.
309 The code has been compiled and tested with clang version 7.0, 8.0, 9.0 and 10.0
310 using either GNU's libstdc++ or LLVM's libc++.
312 The code has been compiled on AArch64, x86_64 and ppc64le servers with CentOS7,
313 Ubuntu18.04, Rhel, MacOs, Mojave, XCode and Apple Clang version 10.0.1.
315 Note that flang is not supported on 32 bit CPUs.
317 ### Building flang with GCC
319 By default,
320 cmake will search for g++ on your PATH.
321 The g++ version must be one of the supported versions
322 in order to build flang.
324 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
325 the full path to the compiler or a name that will be found on your PATH, e.g.
326 g++-8.3, assuming g++-8.3 is on your PATH.
328 ```bash
329 export CXX=g++-8.3
332 ```bash
333 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
336 ### Building flang with clang
338 To build flang with clang,
339 cmake needs to know how to find clang++
340 and the GCC library and tools that were used to build clang++.
342 CXX should include the full path to clang++
343 or clang++ should be found on your PATH.
345 ```bash
346 export CXX=clang++
349 ### Installation Directory
351 To specify a custom install location,
353 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
354 to the cmake command
355 where `<INSTALL_PREFIX>`
356 is the path where flang should be installed.
358 ### Build Types
360 To create a debug build,
362 `-DCMAKE_BUILD_TYPE=Debug`
363 to the cmake command.
364 Debug builds execute slowly.
366 To create a release build,
368 `-DCMAKE_BUILD_TYPE=Release`
369 to the cmake command.
370 Release builds execute quickly.
372 ## How to Run Tests
374 Flang supports 2 different categories of tests
375 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
376 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
378 ### For standalone builds
379 To run all tests:
380 ```bash
381 cd ~/flang/build
382 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
383 ninja check-all
386 To run individual regression tests llvm-lit needs to know the lit
387 configuration for flang. The parameters in charge of this are:
388 flang_site_config and flang_config. And they can be set as shown below:
389 ```bash
390 <path-to-llvm-lit>/llvm-lit \
391  --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
392  --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
393   <path-to-fortran-test>
397 Unit tests:
399 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to generate unittests.
400 Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries.
402 There are various ways to run unit-tests.
406 1. ninja check-flang-unit
407 2. ninja check-all or ninja check-flang
408 3. <path-to-llvm-lit>/llvm-lit \
409         test/Unit
410 4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
415 ### For in tree builds
416 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to
417 generate unittests.
419 To run all of the flang unit tests use the `check-flang-unit` target:
420 ```bash
421 ninja check-flang-unit
423 To run all of the flang regression tests use the `check-flang` target:
424 ```bash
425 ninja check-flang
428 ## How to Generate Documentation
430 ### Generate FIR Documentation
431 If flang was built with `-DLINK_WITH_FIR=ON` (`ON` by default), it is possible to
432 generate FIR language documentation by running `ninja flang-doc`. This will
433 create `<build-dir>/tools/flang/docs/Dialect/FIRLangRef.md` in flang build directory.
435 ### Generate Doxygen-based Documentation
436 To generate doxygen-style documentation from source code
437 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
439 ```bash
440 cd ~/llvm-project/build
441 cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
442 ninja doxygen-flang
445 It will generate html in
447 ```bash
448     <build-dir>/tools/flang/docs/doxygen/html # for flang docs
450 ### Generate Sphinx-based Documentation
451 [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
452 is mostly meant to be processed by the Sphinx documentation generation
453 system to create HTML pages which would be hosted on the webpage of flang and
454 updated periodically.
456 If you would like to generate and view the HTML locally:
457 - Install [Sphinx](http://sphinx-doc.org/), and the required extensions
458   using `pip install --user -r ~/llvm-projects/docs/requirements.txt`
459 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
461 ```bash
462 cd ~/llvm-project/build
463 cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
464 ninja docs-flang-html
467 It will generate html in
469 ```bash
470    $BROWSER <build-dir>/tools/flang/docs/html/