[mlir][sparse] add asserts on reading in tensor data
[lldb.git] / flang / README.md
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 [docs directory](docs).
12 Start with the [compiler overview](docs/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](docs/FortranForCProgrammers.md)
17 and
18 flang's specifications of the [Fortran grammar](docs/f2018-grammar.md)
19 and
20 the [OpenMP grammar](docs/OpenMP-4.5-grammar.md).
21
22 Treatment of language extensions is covered
23 in [this document](docs/Extensions.md).
24
25 To understand the compilers handling of intrinsics,
26 see the [discussion of intrinsics](docs/Intrinsics.md).
27
28 To understand how a flang program communicates with libraries at runtime,
29 see the discussion of [runtime descriptors](docs/RuntimeDescriptor.md).
30
31 If you're interested in contributing to the compiler,
32 read the [style guide](docs/C++style.md)
33 and
34 also review [how flang uses modern C++ features](docs/C++17.md).
35
36 If you are interested in writing new documentation, follow 
37 [markdown style guide from LLVM](https://github.com/llvm/llvm-project/blob/master/llvm/docs/MarkdownQuickstartTemplate.md).
38
39 ## Supported C++ compilers
40
41 Flang is written in C++17.
42
43 The code has been compiled and tested with
44 GCC versions from 7.2.0 to 9.3.0.
45
46 The code has been compiled and tested with
47 clang version 7.0, 8.0, 9.0 and 10.0
48 using either GNU's libstdc++ or LLVM's libc++.
49
50 The code has been compiled on
51 AArch64, x86\_64 and ppc64le servers
52 with CentOS7, Ubuntu18.04, Rhel, MacOs, Mojave, XCode and
53 Apple Clang version 10.0.1.
54
55 The code does not compile with Windows and a compiler that does not have
56 support for C++17.
57
58 ## Building Flang out of tree
59 These instructions are for building Flang separately from LLVM; if you are
60 building Flang alongside LLVM then follow the standard LLVM build instructions
61 and add flang to `LLVM_ENABLE_PROJECTS` instead, as detailed there.
62
63 ### LLVM dependency
64
65 The instructions to build LLVM can be found at
66 https://llvm.org/docs/GettingStarted.html. If you are building flang as part
67 of LLVM, follow those instructions and add flang to `LLVM_ENABLE_PROJECTS`.
68
69 We highly recommend using the same compiler to compile both llvm and flang.
70
71 The flang CMakeList.txt file uses
72 the variable `LLVM_DIR` to find the installed LLVM components
73 and
74 the variable `MLIR_DIR` to find the installed MLIR components.
75
76 To get the correct LLVM and MLIR libraries included in your flang build,
77 define LLVM_DIR and MLIR_DIR on the cmake command line.
78 ```
79 LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm \
80 MLIR=<LLVM_BUILD_DIR>/lib/cmake/mlir \
81 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ...
82 ```
83 where `LLVM_BUILD_DIR` is
84 the top-level directory where LLVM was built.
85
86 ### Building flang with GCC
87
88 By default,
89 cmake will search for g++ on your PATH.
90 The g++ version must be one of the supported versions
91 in order to build flang.
92
93 Or, cmake will use the variable CXX to find the C++ compiler. CXX should include
94 the full path to the compiler or a name that will be found on your PATH, e.g.
95 g++-8.3, assuming g++-8.3 is on your PATH.
96
97 ```
98 export CXX=g++-8.3
99 ```
100 or
101 ```
102 CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
103 ```
104
105 ### Building flang with clang
106
107 To build flang with clang,
108 cmake needs to know how to find clang++
109 and the GCC library and tools that were used to build clang++.
110
111 CXX should include the full path to clang++
112 or clang++ should be found on your PATH.
113 ```
114 export CXX=clang++
115 ```
116
117 ### Installation Directory
118
119 To specify a custom install location,
120 add
121 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
122 to the cmake command
123 where `<INSTALL_PREFIX>`
124 is the path where flang should be installed.
125
126 ### Build Types
127
128 To create a debug build,
129 add
130 `-DCMAKE_BUILD_TYPE=Debug`
131 to the cmake command.
132 Debug builds execute slowly.
133
134 To create a release build,
135 add
136 `-DCMAKE_BUILD_TYPE=Release`
137 to the cmake command.
138 Release builds execute quickly.
139
140 ### Build Flang out of tree
141 ```
142 cd ~/flang/build
143 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
144 make
145 ```
146
147 ### Build The New Flang Driver
148 The new Flang driver, `flang-new`, is currently under active development and
149 should be considered as an experimental feature. For this reason it is disabled
150 by default. This will change once the new driver replaces the _throwaway_
151 driver, `flang`.
152
153 In order to build the new driver, add `-DFLANG_BUILD_NEW_DRIVER=ON` to your
154 CMake invocation line. Additionally, when building out-of-tree, use `CLANG_DIR`
155 (similarly to `LLVM_DIR` and `MLIR_DIR`) to find the installed Clang
156 components.
157
158 **Note:** `CLANG_DIR` is only required when building the new Flang driver,
159 which currently depends on Clang.
160
161 # How to Run Tests
162
163 Flang supports 2 different categories of tests
164 1. Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
165 2. Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)
166
167 ## For out of tree builds
168 To run all tests:
169 ```
170 cd ~/flang/build
171 cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
172 make test check-all
173 ```
174
175 To run individual regression tests llvm-lit needs to know the lit
176 configuration for flang. The parameters in charge of this are:
177 flang_site_config and flang_config. And they can be set as shown below:
178 ```
179 <path-to-llvm-lit>/llvm-lit \
180  --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
181  --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
182   <path-to-fortran-test>
183
184 ```
185
186 Unit tests:
187
188 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`ON` by default), it is possible to generate unittests.
189 Note: Unit-tests will be skipped for LLVM install for an out-of-tree build as it does not include googletest related headers and libraries.
190
191 There are various ways to run unit-tests.
192
193 ```
194
195 1. make check-flang-unit
196 2. make check-all or make check-flang
197 3. <path-to-llvm-lit>/llvm-lit \
198         test/Unit
199 4. Invoking tests from <out-of-tree flang build>/unittests/<respective unit test folder>
200
201 ```
202
203
204 ## For in tree builds
205 If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`On` by default), it is possible to
206 generate unittests.
207
208 To run all of the flang unit tests use the `check-flang-unit` target:
209 ```
210 make check-flang-unit
211 ```
212 To run all of the flang regression tests use the `check-flang` target:
213 ```
214 make check-flang
215 ```
216
217 # How to Generate Documentation
218
219 ## Generate FIR Documentation
220 If flang was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
221 generate FIR language documentation by running `make flang-doc`. This will
222 create `docs/Dialect/FIRLangRef.md` in flang build directory.
223
224 ## Generate Doxygen-based Documentation
225 To generate doxygen-style documentation from source code
226 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
227
228 ```
229 cd ~/llvm-project/build
230 cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
231 make doxygen-flang
232 ```
233
234 It will generate html in
235
236 ```
237     <build-dir>/tools/flang/docs/doxygen/html # for flang docs
238 ```
239 ## Generate Sphinx-based Documentation
240 <!TODO: Add webpage once we have a website.
241 !>
242 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
243 is mostly meant to be processed by the Sphinx documentation generation
244 system to create HTML pages which would be hosted on the webpage of flang and
245 updated periodically.
246
247 If you would like to generate and view the HTML locally:
248 - Install [Sphinx](http://sphinx-doc.org/), including the [sphinx-markdown-tables](https://pypi.org/project/sphinx-markdown-tables/) extension.
249 - Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
250
251 ```
252 cd ~/llvm-project/build
253 cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
254 make docs-flang-html
255 ```
256
257 It will generate html in
258
259 ```
260    $BROWSER <build-dir>/tools/flang/docs/html/
261 ```