Lines Matching +full:flang +full:- +full:build
1 <!--===- docs/FlangDriver.md
5 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 -->
9 # Flang drivers
12 ---
14 ---
17 There are two main drivers in Flang:
18 * the compiler driver, `flang`
19 * the frontend driver, `flang -fc1`
22 preprocessing, semantic checks, code-generation, code-optimisation, lowering
24 Fortran compilation job and delegates it to `flang -fc1`, the frontend
31 not yet available in Flang, but will be relatively easy to support once such
32 libraries become available. Flang's compiler driver is intended for Flang's
33 end-users - its interface needs to remain stable. Otherwise, Flang's users will
34 have to adjust their build scripts every time a compiler flag is changed.
37 |:--:|
38 | *Flang’s compiler driver and the **tools** that it runs* |
40 The **frontend driver** glues together and drives all of the Flang's frontend
41 libraries. As such, it provides an easy-to-use and intuitive interface to the
42 frontend. It uses MLIR and LLVM for code-generation and can be viewed as a
43 driver for Flang, LLVM and MLIR libraries. Contrary to the compiler driver, it
46 accepts many frontend-specific options not available in `flang` and as such
48 intended for Flang developers. In particular, there are no guarantees about the
53 |:-:|
54 | *Flang's frontend driver and the **libraries** that it drives* |
56 Note that similarly to `-Xclang` in `clang`, you can use `-Xflang` to forward a
61 flang -Xflang -fdebug-dump-parse-tree input.f95
64 In the invocation above, `-fdebug-dump-parse-tree` is forwarded to `flang
65 -fc1`. Without the forwarding flag, `-Xflang`, you would see the following
69 flang: warning: argument unused during compilation:
72 As `-fdebug-dump-parse-tree` is only supported by `flang -fc1`, `flang`
76 As hinted above, `flang` and `flang -fc1` are two separate tools. The
77 fact that these tools are accessed through one binary, `flang`, is just an
82 specialised tools. In particular, `flang` is not aware of various
84 checks). It does not have to be. Conversely, the frontend driver, `flang
85 -fc1`, needs not to be concerned with linkers or other external tools like
91 * the compiler driver is an end-user tool
97 implemented in Clang (`clang` vs `clang -cc1` vs `clang -cc1as`), which is
100 In fact, Flang needs to adhere to this model in order to be able to re-use
102 GFortran](https://gcc.gnu.org/onlinedocs/gcc-4.7.4/gfortran/About-GNU-Fortran.html)
103 than Clang, then `flang` corresponds to `gfortran` and `flang -fc1` to
107 The main entry point for Flang's compiler driver is implemented in
108 `flang/tools/flang-driver/driver.cpp`. Flang's compiler driver is implemented
113 One implication of this dependency on Clang is that all of Flang's compiler
116 Flang and Clang, the corresponding definitions are shared.
126 * `-E` for `PreprocessJobClass`,
127 * `-c` for `CompileJobClass`.
131 `-ccc-print-phases` flag to see the sequence of actions that the driver will
134 flang -ccc-print-phases -E file.f
135 +- 0: input, "file.f", f95-cpp-input
138 As you can see, for `-E` the driver creates only two jobs and stops immediately
139 after preprocessing. The first job simply prepares the input. For `-c`, the
142 flang -ccc-print-phases -c file.f
143 +- 0: input, "file.f", f95-cpp-input
144 +- 1: preprocessor, {0}, f95
145 +- 2: compiler, {1}, ir
146 +- 3: backend, {2}, assembler
149 The other phases are printed nonetheless when using `-ccc-print-phases`, as
155 `clang::driver::Tool`. For Flang we introduced a specialisation of this class:
156 `clang::driver::Flang`. This class implements the logic to either translate or
157 forward compiler options to the frontend driver, `flang -fc1`.
163 When used as a linker, Flang's frontend driver assembles the command line for an
168 By default, the Flang linker driver adds several libraries to the linker
177 $ flang -v -o example example.o
178 "/usr/bin/ld" [...] example.o [...] "-lFortranRuntime" "-lFortranDecimal" [...]
183 * `FortranRuntime`: Provides most of the Flang runtime library.
187 or Flang as the linker driver. If Clang is used, it will automatically all
190 `FortranRuntime` and/or `FortranDecimal`. An alternative is to use Flang to link.
194 must be specified. This can be done with the CMake build flag `DEFAULT_SYSROOT`
195 or by using the `-isysroot` flag when linking a binary. On other targets
196 `-isysroot` doesn't change the linker command line (it only affects the header
197 search path). While with Clang `-isysroot` also changes the sysroot for
198 includes, with Flang (and Fortran in general) it only affects Darwin libraries'
202 Flang's frontend driver is the main interface between compiler developers and
203 the Flang frontend. The high-level design is similar to Clang's frontend
204 driver, `clang -cc1` and consists of the following classes:
212 invocation of the compiler as derived from the command-line options and the
219 directly from the users (through command-line flags) or are derived from
224 (e.g. `-E`, `-fdebug-unparse`). These classes also contain various hooks that
225 allow you to e.g. fine-tune the configuration of the frontend based on the
230 implemented in `flang/tools/flang-driver/driver.cpp`. It can be accessed by
231 invoking the compiler driver, `flang`, with the `-fc1` flag.
235 is `ParseSyntaxOnlyAction`, which corresponds to `-fsyntax-only`. In other
236 words, `flang -fc1 <input-file>` is equivalent to `flang -fc1 -fsyntax-only
237 <input-file>`.
240 Adding a new compiler option in Flang consists of two steps:
245 All of Flang's compiler and frontend driver options are defined in
247 Flang, you will either:
249 in one of Clang's drivers (e.g. `clang`), but not yet available in Flang, or
260 following Flang specific visibility flags to control this:
261 * `FlangOption` - this option will be available in the `flang` compiler driver,
262 * `FC1Option` - this option will be available in the `flang -fc1` frontend driver,
265 `Visibility`, and options that are only supported in Flang should not specify
271 * `Action_Group` - options that define an action to run (e.g.
272 `-fsyntax-only`, `-E`)
273 * `f_Group` - target independent compiler flags (e.g. `-ffixed-form`,
274 `-fopenmp`)
279 First, every option needs to be parsed. Flang compiler options are parsed in
282 * frontend driver: `flang/lib/Frontend/CompilerInvocation.cpp`,
283 * compiler driver: `clang/lib/Driver/ToolChains/Flang.cpp`.
289 by the frontend, make sure that it is either forwarded to `flang -fc1` or
292 flags, we usually just forward from `flang` to `flang -fc1`. This is
293 then tested in `flang/test/Driver/frontend-forward.F90`.
296 option. In general, regular compiler flags (e.g. `-ffree-form`) are mapped to
299 flags (e.g. `-fsyntax-only`) are usually more complex overall, but also more
305 `flang/include/flang/Frontend/FrontendOptions.h`. For example, for
306 `-fsyntax-only` we defined:
315 `ParseSyntaxOnly` for `-fsyntax-only`) and a corresponding `case` in
327 `-fsyntax-only`:
337 As of [#7246](https://gitlab.kitware.com/cmake/cmake/-/merge_requests/7246)
338 (CMake 3.28.0), `cmake` can detect `flang` as a
340 `flang` as follows:
342 cmake -DCMAKE_Fortran_COMPILER=<path/to/flang> <src/dir>
346 -- The Fortran compiler identification is LLVMFlang <version>
348 where `<version>` corresponds to the LLVM Flang version.
351 In LIT, we define two variables that you can use to invoke Flang's drivers:
352 * `%flang` is expanded as `flang` (i.e. the compiler driver)
353 * `%flang_fc1` is expanded as `flang -fc1` (i.e. the frontend driver)
357 `%flang` or `%flang_fc1` is used. However, when you are using `%flang` instead
359 driver invocation (i.e. `flang -fc1 -<extra-flags>`). In some cases that might
361 flags by using the `-###` compiler driver command line option.
365 test as only available on Unix-like systems (i.e. systems that contain a Unix
373 semantic checks. Similarly to Clang, Flang leverages `LoadLibraryPermanently`
376 * [Creating a plugin](#creating-a-plugin)
377 * [Loading and running a plugin](#loading-and-running-a-plugin)
379 Flang plugins are limited to `flang -fc1` and are currently only available /
384 1. [`PluginParseTreeAction` subclass](#a-pluginparsetreeaction-subclass)
385 1. [Implementation of `ExecuteAction`](#implementation-of-executeaction)
386 1. [Plugin registration](#plugin-registration)
388 There is an example plugin located in `flang/example/PrintFlangFunctionNames`
395 `PluginParseTreeAction` (defined in `flang/include/flang/FrontendActions.h`), in
422 `flang/include/flang/Parser/parse-tree-visitor.h`.
442 defined in `flang/include/flang/Parser/parse-tree.h`. In the example, there is a
449 plugins. The Flang plugin registry, defined in
450 `flang/include/flang/Frontend/FrontendPluginRegistry.h`, is an alias of
454 and allow it to be used. The format is as follows, with `print-fns` being the
459 "print-fns", "Print Function names");
464 frontend driver, `flang -fc1`:
465 * [`-load <dsopath>`](#the--load-dsopath-option) for loading the dynamic shared
467 * [`-plugin <name>`](#the--plugin-name-option) for calling the registered plugin
471 flang -fc1 -load flangPrintFunctionNames.so -plugin print-fns file.f90
474 Both these options are parsed in `flang/lib/Frontend/CompilerInvocation.cpp` and
476 `flang/lib/FrontendTool/ExecuteCompilerInvocation.cpp`
478 #### The `-load <dsopath>` option
484 #### The `-plugin <name>` option
490 ### Enabling In-Tree Plugins
491 For in-tree plugins, there is the CMake flag `FLANG_PLUGIN_SUPPORT`, enabled by
492 default, that controls the exporting of executable symbols from `flang`,
496 `flang/example` directory and added as a `sub_directory` to the
497 `flang/examples/CMakeLists.txt`, for example, the `PrintFlangFunctionNames`
498 plugin. It is also possible to develop plugins out-of-tree.
513 to re-analyze expressions and modify scope or symbols. You can check
520 in `flang/lib/Optimizer/Passes/Pipelines.cpp` contains extension point callback
522 `invokeFIROptLastEPCallbacks` for Flang drivers to be able to insert additonal
525 default inliner pass in `flang`.
530 passes. The `-fpass-plugin` option enables these passes to be passed to the
531 middle-end where they are added to the optimization pass pipeline and run after
538 The framework to enable pass plugins in `flang` uses the exact same
543 shared object which is then loaded using the `-fpass-plugin` option.
546 flang -fpass-plugin=/path/to/plugin.so <file.f90>
555 statically. Setting `-DLLVM_${NAME}_LINK_INTO_TOOLS` to `ON` in the cmake
557 be Polly, e.g., using `-DLLVM_POLLY_LINK_INTO_TOOLS=ON` would link Polly passes
558 into `flang` as built-in middle-end passes.
565 `-Ofast` in Flang means `-O3 -ffast-math -fstack-arrays`.
567 `-ffast-math` means the following:
568 - `-fno-honor-infinities`
569 - `-fno-honor-nans`
570 - `-fassociative-math`
571 - `-freciprocal-math`
572 - `-fapprox-func`
573 - `-fno-signed-zeros`
574 - `-ffp-contract=fast`
577 https://llvm.org/docs/LangRef.html#fast-math-flags
579 When `-ffast-math` is specified, any linker steps generated by the compiler
587 GCC/GFortran translate `-Ofast` to
588 `-O3 -ffast-math -fstack-arrays -fno-semantic-interposition`.
589 `-fno-semantic-interposition` is not used because Clang does not enable this as
590 part of `-Ofast` as the default behaviour is similar.
592 GCC/GFortran has a wider definition of `-ffast-math`: also including
593 `-fno-trapping-math`, `-fno-rounding-math`, and `-fsignaling-nans`; these
594 aren't included in Flang because Flang currently has no support for strict
597 GCC/GFortran will also set flush-to-zero mode: linking `crtfastmath.o`, the same
598 as Flang.
600 The only GCC/GFortran warning option currently supported is `-Werror`. Passing
601 any unsupported GCC/GFortran warning flags into Flang's compiler driver will
605 nvfortran defines `-fast` as
606 `-O2 -Munroll=c:1 -Mnoframe -Mlre -Mpre -Mvect=simd -Mcache_align -Mflushz -Mvect`.
607 - `-O2 -Munroll=c:1 -Mlre -Mautoinline -Mpre -Mvect-simd` affect code
608 optimization. `flang -O3` should enable all optimizations for execution time,
609 similarly to `clang -O3`. The `-O3` pipeline has passes that perform
612 - `-Mnoframe`: the equivalent flag would be `-fomit-frame-pointer`. This flag
613 is not yet supported in Flang and so Flang follows GFortran in not including
614 this in `-Ofast`. There is no plan to include this flag as part of `-Ofast`.
615 - `-Mcache_align`: there is no equivalent flag in Flang or Clang.
616 - `-Mflushz`: flush-to-zero mode - when `-ffast-math` is specified, Flang will