Lines Matching +full:build +full:- +full:docs
1 <!--===- docs/GettingStarted.md
5 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 -->
12 ---
14 ---
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
22 build, only build the flang code itself. This is called building standalone.
24 create the base build and base install areas, you can create multiple
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
36 compiler-rt. Note that compiler-rt is only needed to access libraries that
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.
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).
50 the build.
60 git clone https://github.com/llvm/llvm-project.git
64 rm -rf build
65 mkdir build
66 rm -rf install
71 cd build
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
93 `-DDEFAULT_SYSROOT="$(xcrun --show-sdk-path)"`.
95 By default flang tests that do not specify an explicit `--target` flag use
99 `-DLLVM_TARGET_TRIPLE_ENV="<some string>" -DFLANG_TEST_TARGET_TRIPLE="<your triple>"`.
101 To run the flang tests on this build, execute the command in the "build"
104 ninja check-flang
114 To build compiler-rt:
117 rm -rf compiler-rt
118 mkdir compiler-rt
119 cd compiler-rt
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
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
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
151 contains the subdirectory `build` that was created previously, for example:
155 Start each standalone build the same way by cloning the source for
156 llvm-project:
160 git clone https://github.com/llvm/llvm-project.git
164 cd llvm-project/flang
165 rm -rf build
166 mkdir build
167 cd build
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 \
189 To run the flang tests on this build, execute the command in the `flang/build`
192 ninja check-flang
200 #### Building out-of-tree
202 ##### CUDA build
206 cd llvm-project/flang
207 rm -rf build_flang_runtime
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++ \
219 make -j FortranRuntime
222 …g` 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`
228 cd llvm-project/flang
229 rm -rf build_flang_runtime
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++ \
242 make -j FortranRuntime
246 [versions](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#host-compiler-supp…
249 The result of the build is a "fat" library with the host and device
251 between [Clang](https://clang.llvm.org/docs/OffloadingDesign.html#linking-target-device-code) and N…
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:
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++ \
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++ \
279 Normal `make -j check-flang` will work with such CMake configuration.
281 ##### OpenMP target offload build
285 cd llvm-project/flang
286 rm -rf build_flang_runtime
291 -DFLANG_EXPERIMENTAL_OMP_OFFLOAD_BUILD="host_device" \
292 -DCMAKE_C_COMPILER=clang \
293 -DCMAKE_CXX_COMPILER=clang++ \
294 -DFLANG_OMP_DEVICE_ARCHITECTURES="all" \
297 make -j FortranRuntime
300 The result of the build is a "device-only" library, i.e. the host
303 Clang-like device linking pipeline.
305 The same set of CMake variables works for Flang in-tree build.
307 ### Build options
309 One may provide optional CMake variables to customize the build. Available options:
311 * `-DFLANG_RUNTIME_F128_MATH_LIB=libquadmath`: enables build of
314 `quadmath.h` must be available to the build compiler.
336 in order to build flang.
340 g++-8.3, assuming g++-8.3 is on your PATH.
343 export CXX=g++-8.3
347 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
352 To build flang with clang,
354 and the GCC library and tools that were used to build clang++.
367 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
372 ### Build Types
374 To create a debug build,
376 `-DCMAKE_BUILD_TYPE=Debug`
380 To create a release build,
382 `-DCMAKE_BUILD_TYPE=Release`
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)
395 cd ~/flang/build
396 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
397 ninja check-all
400 To run individual regression tests llvm-lit needs to know the lit
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>
413 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to generate un…
414 Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include go…
416 There are various ways to run unit-tests.
420 1. ninja check-flang-unit
421 2. ninja check-all or ninja check-flang
422 3. <path-to-llvm-lit>/llvm-lit \
424 4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
430 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to
433 To run all of the flang unit tests use the `check-flang-unit` target:
435 ninja check-flang-unit
437 To run all of the flang regression tests use the `check-flang` target:
439 ninja check-flang
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.
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.
454 cd ~/llvm-project/build
455 cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_DOXYGE…
456 ninja doxygen-flang
462 <build-dir>/tools/flang/docs/doxygen/html # for flang docs
464 ### Generate Sphinx-based Documentation
465 [Flang documentation](https://flang.llvm.org/docs/) should preferably be written in `markdown(.md)`…
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.
476 cd ~/llvm-project/build
477 cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;flang" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_SPHINX…
478 ninja docs-flang-html
484 $BROWSER <build-dir>/tools/flang/docs/html/