Lines Matching +full:docs +full:- +full:flang +full:- +full:html
1 <!--===- docs/GettingStarted.md
5 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 -->
12 ---
14 ---
17 ## Building flang
18 There are two ways to build flang. The first method is to build it at the same
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.
28 https://llvm.org/docs/GettingStarted.html.
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
39 includig GNU and clang. But building compiler-rt requres using the clang
44 into a directory called llvm-project. The build will also
46 the built files), install (holds the installed files, and compiler-rt (holds
47 the result of building compiler-rt).
60 git clone https://github.com/llvm/llvm-project.git
64 rm -rf build
66 rm -rf install
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
91 On Darwin, to make flang able to link binaries with the default sysroot without
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
144 builds, but doing so lets you run the flang tests to verify that the source
147 ### Building flang standalone
148 To do the standalone build, start by building flang in tree as described above.
156 llvm-project:
160 git clone https://github.com/llvm/llvm-project.git
164 cd llvm-project/flang
165 rm -rf 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
195 ### Building flang runtime for accelerators
196 Flang runtime can be built for accelerators in experimental mode, i.e.
200 #### Building out-of-tree
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)
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…
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
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.
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.
311 * `-DFLANG_RUNTIME_F128_MATH_LIB=libquadmath`: enables build of
319 Flang is written in C++17.
329 Note that flang is not supported on 32 bit CPUs.
331 ### Building flang with GCC
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 ...
350 ### Building flang with clang
352 To build flang with clang,
367 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
370 is the path where flang should be installed.
376 `-DCMAKE_BUILD_TYPE=Debug`
382 `-DCMAKE_BUILD_TYPE=Release`
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)
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
401 configuration for flang. The parameters in charge of this are:
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
459 It will generate html in
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)`…
467 system to create HTML pages which would be hosted on the webpage of flang and
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.
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
481 It will generate html in
484 $BROWSER <build-dir>/tools/flang/docs/html/