|
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
|
|
|
11 Read more about flang in the [documentation directory](documentation).
|
|
|
12 Start with the [compiler overview](documentation/Overview.md).
|
|
|
13
|
|
|
14 To better understand Fortran as a language
|
|
|
15 and the specific grammar accepted by flang,
|
|
|
16 read [Fortran For C Programmers](documentation/FortranForCProgrammers.md)
|
|
|
17 and
|
|
|
18 flang's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
|
|
|
19 and
|
|
|
20 the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt).
|
|
|
21
|
|
|
22 Treatment of language extensions is covered
|
|
|
23 in [this document](documentation/Extensions.md).
|
|
|
24
|
|
|
25 To understand the compilers handling of intrinsics,
|
|
|
26 see the [discussion of intrinsics](documentation/Intrinsics.md).
|
|
|
27
|
|
|
28 To understand how a flang program communicates with libraries at runtime,
|
|
|
29 see the discussion of [runtime descriptors](documentation/RuntimeDescriptor.md).
|
|
|
30
|
|
|
31 If you're interested in contributing to the compiler,
|
|
|
32 read the [style guide](documentation/C++style.md)
|
|
|
33 and
|
|
|
34 also review [how flang uses modern C++ features](documentation/C++17.md).
|
|
|
35
|
|
|
36 ## Supported C++ compilers
|
|
|
37
|
|
|
38 Flang is written in C++17.
|
|
|
39
|
|
|
40 The code has been compiled and tested with
|
|
|
41 GCC versions from 7.2.0 to 9.3.0.
|
|
|
42
|
|
|
43 The code has been compiled and tested with
|
|
|
44 clang version 7.0, 8.0, 9.0 and 10.0
|
|
|
45 using either GNU's libstdc++ or LLVM's libc++.
|
|
|
46
|
|
|
47 The code has been compiled on
|
|
|
48 AArch64, x86\_64 and ppc64le servers
|
|
|
49 with CentOS7, Ubuntu18.04, Rhel, MacOs, Mojave, XCode and
|
|
|
50 Apple Clang version 10.0.1.
|
|
|
51
|
|
|
52 The code does not compile with Windows and a compiler that does not have
|
|
|
53 support for C++17.
|
|
|
54
|
|
|
55 ## Building Flang out of tree
|
|
|
56 These instructions are for building Flang separately from LLVM; if you are
|
|
|
57 building Flang alongside LLVM then follow the standard LLVM build instructions
|
|
|
58 and add flang to `LLVM_ENABLE_PROJECTS` instead, as detailed there.
|
|
|
59
|
|
|
60 ### LLVM dependency
|
|
|
61
|
|
|
62 The instructions to build LLVM can be found at
|
|
|
63 https://llvm.org/docs/GettingStarted.html. If you are building flang as part
|
|
|
64 of LLVM, follow those instructions and add flang to `LLVM_ENABLE_PROJECTS`.
|
|
|
65
|
|
|
66 We highly recommend using the same compiler to compile both llvm and flang.
|
|
|
67
|
|
|
68 The flang CMakeList.txt file uses
|
|
|
69 the variable `LLVM_DIR` to find the installed LLVM components
|
|
|
70 and
|
|
|
71 the variable `MLIR_DIR` to find the installed MLIR components.
|
|
|
72
|
|
|
73 To get the correct LLVM and MLIR libraries included in your flang build,
|
|
|
74 define LLVM_DIR and MLIR_DIR on the cmake command line.
|
|
|
75 ```
|
|
|
76 LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm \
|
|
|
77 MLIR=<LLVM_BUILD_DIR>/lib/cmake/mlir \
|
|
|
78 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ...
|
|
|
79 ```
|
|
|
80 where `LLVM_BUILD_DIR` is
|
|
|
81 the top-level directory where LLVM was built.
|
|
|
82
|
|
|
83 ### Building flang with GCC
|
|
|
84
|
|
|
85 By default,
|
|
|
86 cmake will search for g++ on your PATH.
|
|
|
87 The g++ version must be one of the supported versions
|
|
|
88 in order to build flang.
|
|
|
89
|
|
|
90 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
|
|
|
91 the full path to the compiler or a name that will be found on your PATH, e.g.
|
|
|
92 g++-8.3, assuming g++-8.3 is on your PATH.
|
|
|
93
|
|
|
94 ```
|
|
|
95 export CXX=g++-8.3
|
|
|
96 ```
|
|
|
97 or
|
|
|
98 ```
|
|
|
99 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
|
|
|
100 ```
|
|
|
101
|
|
|
102 ### Building flang with clang
|
|
|
103
|
|
|
104 To build flang with clang,
|
|
|
105 cmake needs to know how to find clang++
|
|
|
106 and the GCC library and tools that were used to build clang++.
|
|
|
107
|
|
|
108 CXX should include the full path to clang++
|
|
|
109 or clang++ should be found on your PATH.
|
|
|
110 ```
|
|
|
111 export CXX=clang++
|
|
|
112 ```
|
|
|
113
|
|
|
114 ### Installation Directory
|
|
|
115
|
|
|
116 To specify a custom install location,
|
|
|
117 add
|
|
|
118 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
|
|
|
119 to the cmake command
|
|
|
120 where `<INSTALL_PREFIX>`
|
|
|
121 is the path where flang should be installed.
|
|
|
122
|
|
|
123 ### Build Types
|
|
|
124
|
|
|
125 To create a debug build,
|
|
|
126 add
|
|
|
127 `-DCMAKE_BUILD_TYPE=Debug`
|
|
|
128 to the cmake command.
|
|
|
129 Debug builds execute slowly.
|
|
|
130
|
|
|
131 To create a release build,
|
|
|
132 add
|
|
|
133 `-DCMAKE_BUILD_TYPE=Release`
|
|
|
134 to the cmake command.
|
|
|
135 Release builds execute quickly.
|
|
|
136
|
|
|
137 ### Build Flang out of tree
|
|
|
138 ```
|
|
|
139 cd ~/flang/build
|
|
|
140 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
|
|
|
141 make
|
|
|
142 ```
|
|
|
143 ### How to Run the Regression Tests
|
|
|
144
|
|
|
145 To run all tests:
|
|
|
146 ```
|
|
|
147 cd ~/flang/build
|
|
|
148 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
|
|
|
149 make test check-all
|
|
|
150 ```
|
|
|
151
|
|
|
152 To run individual regression tests llvm-lit needs to know the lit
|
|
|
153 configuration for flang. The parameters in charge of this are:
|
|
|
154 flang_site_config and flang_config. And they can be set as shown bellow:
|
|
|
155 ```
|
|
|
156 <path-to-llvm-lit>/llvm-lit \
|
|
|
157 --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
|
|
|
158 --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
|
|
|
159 <path-to-fortran-test>
|
|
|
160 ```
|
|
|
161
|
|
|
162 # How to Generate Documentation
|
|
|
163
|
|
|
164 ## Generate FIR Documentation
|
|
|
165 If flang was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
|
|
|
166 generate FIR language documentation by running `make flang-doc`. This will
|
|
|
167 create `docs/Dialect/FIRLangRef.md` in flang build directory.
|
|
|
168
|
|
|
169 ## Generate Doxygen-based Documentation
|
|
|
170 To generate doxygen-style documentation from source code
|
|
|
171 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
|
|
|
172
|
|
|
173 ```
|
|
|
174 cd ~/llvm-project/build
|
|
|
175 cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
|
|
|
176 make doxygen-flang
|
|
|
177
|
|
|
178 It will generate html in
|
|
|
179
|
|
|
180 <build-dir>/tools/flang/docs/doxygen/html # for flang docs
|
|
|
181 ```
|
|
|
182
|
