|
173
|
1 # Flang
|
|
|
2
|
|
|
3 Flang is a ground-up implementation of a Fortran front end written in modern
|
|
|
4 C++. It started off as the f18 project (https://github.com/flang-compiler/f18)
|
|
|
5 with an aim to replace the previous flang project
|
|
|
6 (https://github.com/flang-compiler/flang) and address its various deficiencies.
|
|
|
7 F18 was subsequently accepted into the LLVM project and rechristened as Flang.
|
|
|
8
|
|
|
9 ## Getting Started
|
|
|
10
|
|
221
|
11 Read more about flang in the [docs directory](docs).
|
|
|
12 Start with the [compiler overview](docs/Overview.md).
|
|
173
|
13
|
|
|
14 To better understand Fortran as a language
|
|
|
15 and the specific grammar accepted by flang,
|
|
221
|
16 read [Fortran For C Programmers](docs/FortranForCProgrammers.md)
|
|
173
|
17 and
|
|
221
|
18 flang's specifications of the [Fortran grammar](docs/f2018-grammar.md)
|
|
173
|
19 and
|
|
221
|
20 the [OpenMP grammar](docs/OpenMP-4.5-grammar.md).
|
|
173
|
21
|
|
|
22 Treatment of language extensions is covered
|
|
221
|
23 in [this document](docs/Extensions.md).
|
|
173
|
24
|
|
|
25 To understand the compilers handling of intrinsics,
|
|
221
|
26 see the [discussion of intrinsics](docs/Intrinsics.md).
|
|
173
|
27
|
|
|
28 To understand how a flang program communicates with libraries at runtime,
|
|
221
|
29 see the discussion of [runtime descriptors](docs/RuntimeDescriptor.md).
|
|
173
|
30
|
|
|
31 If you're interested in contributing to the compiler,
|
|
221
|
32 read the [style guide](docs/C++style.md)
|
|
173
|
33 and
|
|
221
|
34 also review [how flang uses modern C++ features](docs/C++17.md).
|
|
|
35
|
|
236
|
36 If you are interested in writing new documentation, follow
|
|
|
37 [LLVM's Markdown style guide](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
|
|
|
38
|
|
|
39 ## Building flang
|
|
|
40 There are two ways to build flang. The first method is to build it at the same
|
|
|
41 time that you build all of the projects on which it depends. This is called
|
|
|
42 building in tree. The second method is to first do an in tree build to create
|
|
|
43 all of the projects on which flang depends. Then, after creating this base
|
|
|
44 build, only build the flang code itself. This is called building standalone.
|
|
|
45 Building standalone has the advantage of being smaller and faster. Once you
|
|
|
46 create the base build and base install areas, you can create multiple
|
|
|
47 standalone builds using them.
|
|
|
48
|
|
|
49 Note that instructions for building LLVM can be found at
|
|
|
50 https://llvm.org/docs/GettingStarted.html.
|
|
|
51
|
|
|
52 All of the examples below use GCC as the C/C++ compilers and ninja as the build
|
|
|
53 tool.
|
|
|
54
|
|
|
55 ### Building flang in tree
|
|
|
56 Building flang in tree means building flang along with all of the projects on
|
|
|
57 which it depends. These projects include mlir, clang, flang, openmp, and
|
|
|
58 compiler-rt. Note that compiler-rt is only needed to access libraries that
|
|
|
59 support 16 bit floating point numbers. It's not needed to run the automated
|
|
|
60 tests. You can use several different C++ compilers for most of the build,
|
|
|
61 includig GNU and clang. But building compiler-rt requres using the clang
|
|
|
62 compiler built in the initial part of the build.
|
|
|
63
|
|
|
64 Here's a directory structure that works. Create a root directory for the
|
|
|
65 cloned and built files. Under that root directory, clone the source code
|
|
|
66 into a directory called llvm-project. The build will also
|
|
|
67 create subdirectories under the root directory called build (holds most of
|
|
|
68 the built files), install (holds the installed files, and compiler-rt (holds
|
|
|
69 the result of building compiler-rt).
|
|
|
70
|
|
|
71 Here's a complete set of commands to clone all of the necessary source and do
|
|
|
72 the build.
|
|
|
73
|
|
|
74 First, create the root directory and `cd` into it.
|
|
|
75 ```bash
|
|
|
76 mkdir root
|
|
|
77 cd root
|
|
|
78
|
|
|
79 Now clone the source:
|
|
|
80 ```bash
|
|
|
81 git clone https://github.com/llvm/llvm-project.git
|
|
|
82 ```
|
|
|
83 Once the clone is complete, execute the following commands:
|
|
|
84 ```bash
|
|
|
85 rm -rf build
|
|
|
86 mkdir build
|
|
|
87 rm -rf install
|
|
|
88 mkdir install
|
|
|
89 ROOTDIR=`pwd`
|
|
|
90 INSTALLDIR=$ROOTDIR/install
|
|
|
91
|
|
|
92 cd build
|
|
|
93
|
|
|
94 cmake \
|
|
|
95 -G Ninja \
|
|
|
96 -DCMAKE_BUILD_TYPE=Release \
|
|
|
97 -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
|
|
|
98 -DCMAKE_CXX_STANDARD=17 \
|
|
|
99 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
|
|
|
100 -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
|
|
|
101 -DFLANG_ENABLE_WERROR=ON \
|
|
|
102 -DLLVM_ENABLE_ASSERTIONS=ON \
|
|
|
103 -DLLVM_TARGETS_TO_BUILD=host \
|
|
|
104 -DLLVM_LIT_ARGS=-v \
|
|
|
105 -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;openmp" \
|
|
|
106 -DLLVM_ENABLE_RUNTIMES="compiler-rt" \
|
|
|
107 ../llvm-project/llvm
|
|
|
108
|
|
|
109 ninja
|
|
|
110 ```
|
|
|
111
|
|
|
112 To run the flang tests on this build, execute the command in the "build"
|
|
|
113 directory:
|
|
|
114 ```bash
|
|
|
115 ninja check-flang
|
|
|
116 ```
|
|
|
117
|
|
|
118 To create the installed files:
|
|
|
119 ```bash
|
|
|
120 ninja install
|
|
|
121
|
|
|
122 echo "latest" > $INSTALLDIR/bin/versionrc
|
|
|
123 ```
|
|
|
124
|
|
|
125 To build compiler-rt:
|
|
|
126 ```bash
|
|
|
127 cd $ROOTDIR
|
|
|
128 rm -rf compiler-rt
|
|
|
129 mkdir compiler-rt
|
|
|
130 cd compiler-rt
|
|
|
131 CC=$INSTALLDIR/bin/clang \
|
|
|
132 CXX=$INSTALLDIR/bin/clang++ \
|
|
|
133 cmake \
|
|
|
134 -G Ninja \
|
|
|
135 ../llvm-project/compiler-rt \
|
|
|
136 -DCMAKE_BUILD_TYPE=Release \
|
|
|
137 -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
|
|
|
138 -DCMAKE_CXX_STANDARD=11 \
|
|
|
139 -DCMAKE_C_CFLAGS=-mlong-double-128 \
|
|
|
140 -DCMAKE_CXX_CFLAGS=-mlong-double-128 \
|
|
|
141 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
|
|
|
142 -DCOMPILER_RT_BUILD_ORC=OFF \
|
|
|
143 -DCOMPILER_RT_BUILD_XRAY=OFF \
|
|
|
144 -DCOMPILER_RT_BUILD_MEMPROF=OFF \
|
|
|
145 -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
|
|
|
146 -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
|
|
|
147 -DLLVM_CONFIG_PATH=$INSTALLDIR/bin/llvm-config
|
|
|
148
|
|
|
149 ninja
|
|
|
150 ninja install
|
|
|
151 ```
|
|
|
152
|
|
|
153 Note that these instructions specify flang as one of the projects to build in
|
|
|
154 the in tree build. This is not strictly necessary for subsequent standalone
|
|
|
155 builds, but doing so lets you run the flang tests to verify that the source
|
|
|
156 code is in good shape.
|
|
|
157 ### Building flang standalone
|
|
|
158 To do the standalone build, start by building flang in tree as described above.
|
|
|
159 This build is base build for subsequent standalone builds. Start each
|
|
|
160 standalone build the same way by cloning the source for llvm-project:
|
|
|
161 ```bash
|
|
|
162 mkdir standalone
|
|
|
163 cd standalone
|
|
|
164 git clone https://github.com/llvm/llvm-project.git
|
|
|
165 ```
|
|
|
166 Once the clone is complete, execute the following commands:
|
|
|
167 ```bash
|
|
|
168 cd llvm-project/flang
|
|
|
169 rm -rf build
|
|
|
170 mkdir build
|
|
|
171 cd build
|
|
|
172
|
|
|
173 cmake \
|
|
|
174 -G Ninja \
|
|
|
175 -DCMAKE_BUILD_TYPE=Release \
|
|
|
176 -DCMAKE_CXX_STANDARD=17 \
|
|
|
177 -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
|
|
|
178 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
|
|
|
179 -DFLANG_ENABLE_WERROR=ON \
|
|
|
180 -DLLVM_TARGETS_TO_BUILD=host \
|
|
|
181 -DLLVM_ENABLE_ASSERTIONS=ON \
|
|
|
182 -DLLVM_BUILD_MAIN_SRC_DIR=$ROOTDIR/build/lib/cmake/llvm \
|
|
|
183 -DLLVM_EXTERNAL_LIT=$ROOTDIR/build/bin/llvm-lit \
|
|
|
184 -DLLVM_LIT_ARGS=-v \
|
|
|
185 -DLLVM_DIR=$ROOTDIR/build/lib/cmake/llvm \
|
|
|
186 -DCLANG_DIR=$ROOTDIR/build/lib/cmake/clang \
|
|
|
187 -DMLIR_DIR=$ROOTDIR/build/lib/cmake/mlir \
|
|
|
188 ..
|
|
|
189
|
|
|
190 ninja
|
|
|
191 ```
|
|
|
192
|
|
|
193 To run the flang tests on this build, execute the command in the "flang/build"
|
|
|
194 directory:
|
|
|
195 ```bash
|
|
|
196 ninja check-flang
|
|
|
197 ```
|
|
173
|
198
|
|
|
199 ## Supported C++ compilers
|
|
|
200
|
|
|
201 Flang is written in C++17.
|
|
|
202
|
|
|
203 The code has been compiled and tested with
|
|
|
204 GCC versions from 7.2.0 to 9.3.0.
|
|
|
205
|
|
|
206 The code has been compiled and tested with
|
|
|
207 clang version 7.0, 8.0, 9.0 and 10.0
|
|
|
208 using either GNU's libstdc++ or LLVM's libc++.
|
|
|
209
|
|
|
210 The code has been compiled on
|
|
|
211 AArch64, x86\_64 and ppc64le servers
|
|
|
212 with CentOS7, Ubuntu18.04, Rhel, MacOs, Mojave, XCode and
|
|
|
213 Apple Clang version 10.0.1.
|
|
|
214
|
|
|
215 ### Building flang with GCC
|
|
|
216
|
|
|
217 By default,
|
|
|
218 cmake will search for g++ on your PATH.
|
|
|
219 The g++ version must be one of the supported versions
|
|
|
220 in order to build flang.
|
|
|
221
|
|
|
222 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
|
|
|
223 the full path to the compiler or a name that will be found on your PATH, e.g.
|
|
|
224 g++-8.3, assuming g++-8.3 is on your PATH.
|
|
|
225
|
|
236
|
226 ```bash
|
|
173
|
227 export CXX=g++-8.3
|
|
|
228 ```
|
|
|
229 or
|
|
236
|
230 ```bash
|
|
173
|
231 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
|
|
|
232 ```
|
|
|
233
|
|
|
234 ### Building flang with clang
|
|
|
235
|
|
|
236 To build flang with clang,
|
|
|
237 cmake needs to know how to find clang++
|
|
|
238 and the GCC library and tools that were used to build clang++.
|
|
|
239
|
|
|
240 CXX should include the full path to clang++
|
|
|
241 or clang++ should be found on your PATH.
|
|
236
|
242 ```bash
|
|
173
|
243 export CXX=clang++
|
|
|
244 ```
|
|
|
245
|
|
|
246 ### Installation Directory
|
|
|
247
|
|
|
248 To specify a custom install location,
|
|
|
249 add
|
|
|
250 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
|
|
|
251 to the cmake command
|
|
|
252 where `<INSTALL_PREFIX>`
|
|
|
253 is the path where flang should be installed.
|
|
|
254
|
|
|
255 ### Build Types
|
|
|
256
|
|
|
257 To create a debug build,
|
|
|
258 add
|
|
|
259 `-DCMAKE_BUILD_TYPE=Debug`
|
|
|
260 to the cmake command.
|
|
|
261 Debug builds execute slowly.
|
|
|
262
|
|
|
263 To create a release build,
|
|
|
264 add
|
|
|
265 `-DCMAKE_BUILD_TYPE=Release`
|
|
|
266 to the cmake command.
|
|
|
267 Release builds execute quickly.
|
|
|
268
|
|
221
|
269 # How to Run Tests
|
|
|
270
|
|
|
271 Flang supports 2 different categories of tests
|
|
|
272 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
|
|
|
273 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
|
|
|
274
|
|
236
|
275 ## For standalone builds
|
|
173
|
276 To run all tests:
|
|
236
|
277 ```bash
|
|
173
|
278 cd ~/flang/build
|
|
|
279 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
|
|
236
|
280 ninja check-all
|
|
173
|
281 ```
|
|
|
282
|
|
|
283 To run individual regression tests llvm-lit needs to know the lit
|
|
|
284 configuration for flang. The parameters in charge of this are:
|
|
221
|
285 flang_site_config and flang_config. And they can be set as shown below:
|
|
236
|
286 ```bash
|
|
173
|
287 <path-to-llvm-lit>/llvm-lit \
|
|
|
288 --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
|
|
|
289 --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
|
|
|
290 <path-to-fortran-test>
|
|
221
|
291
|
|
|
292 ```
|
|
|
293
|
|
|
294 Unit tests:
|
|
|
295
|
|
236
|
296 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to generate unittests.
|
|
|
297 Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries.
|
|
221
|
298
|
|
|
299 There are various ways to run unit-tests.
|
|
|
300
|
|
|
301 ```
|
|
|
302
|
|
236
|
303 1. ninja check-flang-unit
|
|
|
304 2. ninja check-all or ninja check-flang
|
|
221
|
305 3. <path-to-llvm-lit>/llvm-lit \
|
|
|
306 test/Unit
|
|
236
|
307 4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
|
|
221
|
308
|
|
|
309 ```
|
|
|
310
|
|
|
311
|
|
|
312 ## For in tree builds
|
|
236
|
313 If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to
|
|
221
|
314 generate unittests.
|
|
|
315
|
|
|
316 To run all of the flang unit tests use the `check-flang-unit` target:
|
|
236
|
317 ```bash
|
|
|
318 ninja check-flang-unit
|
|
221
|
319 ```
|
|
|
320 To run all of the flang regression tests use the `check-flang` target:
|
|
236
|
321 ```bash
|
|
|
322 ninja check-flang
|
|
173
|
323 ```
|
|
|
324
|
|
|
325 # How to Generate Documentation
|
|
|
326
|
|
|
327 ## Generate FIR Documentation
|
|
236
|
328 If flang was built with `-DLINK_WITH_FIR=ON` (`ON` by default), it is possible to
|
|
|
329 generate FIR language documentation by running `ninja flang-doc`. This will
|
|
173
|
330 create `docs/Dialect/FIRLangRef.md` in flang build directory.
|
|
|
331
|
|
|
332 ## Generate Doxygen-based Documentation
|
|
|
333 To generate doxygen-style documentation from source code
|
|
|
334 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
|
|
|
335
|
|
236
|
336 ```bash
|
|
173
|
337 cd ~/llvm-project/build
|
|
|
338 cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
|
|
236
|
339 ninja doxygen-flang
|
|
221
|
340 ```
|
|
173
|
341
|
|
|
342 It will generate html in
|
|
|
343
|
|
236
|
344 ```bash
|
|
173
|
345 <build-dir>/tools/flang/docs/doxygen/html # for flang docs
|
|
|
346 ```
|
|
221
|
347 ## Generate Sphinx-based Documentation
|
|
|
348 <!TODO: Add webpage once we have a website.
|
|
|
349 !>
|
|
|
350 Flang documentation 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
|
|
|
351 is mostly meant to be processed by the Sphinx documentation generation
|
|
|
352 system to create HTML pages which would be hosted on the webpage of flang and
|
|
|
353 updated periodically.
|
|
173
|
354
|
|
221
|
355 If you would like to generate and view the HTML locally:
|
|
|
356 - Install [Sphinx](http://sphinx-doc.org/), including the [sphinx-markdown-tables](https://pypi.org/project/sphinx-markdown-tables/) extension.
|
|
|
357 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
|
|
|
358
|
|
236
|
359 ```bash
|
|
221
|
360 cd ~/llvm-project/build
|
|
|
361 cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
|
|
236
|
362 ninja docs-flang-html
|
|
221
|
363 ```
|
|
|
364
|
|
|
365 It will generate html in
|
|
|
366
|
|
236
|
367 ```bash
|
|
221
|
368 $BROWSER <build-dir>/tools/flang/docs/html/
|
|
|
369 ```
|
