Lines Matching +full:docs +full:- +full:clang +full:- +full:tools +full:- +full:html
1 <!--===- docs/FlangDriver.md
5 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 -->
12 ---
14 ---
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
26 LLVM's [`lld`](https://lld.llvm.org/)). It can also call other tools such as
28 Clang, the compiler driver can also link the generated binaries with LLVM's
30 [MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html)). This is
33 end-users - its interface needs to remain stable. Otherwise, Flang's users will
37 |:--:|
38 | *Flang’s compiler driver and the **tools** that it runs* |
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
44 is not capable of calling any external tools (including linkers). It is aware
46 accepts many frontend-specific options not available in `flang` and as such
53 |:-:|
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
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
79 in the same file: `clang/include/clang/Driver/Options.td`.
82 specialised tools. In particular, `flang` is not aware of various
85 -fc1`, needs not to be concerned with linkers or other external tools like
89 One helpful way of differentiating these tools is to keep in mind that:
91 * the compiler driver is an end-user tool
94 Also, Since the compiler driver can call external tools, e.g. linkers, it can
96 tools and hence can only generate **object files**. A similar model is
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
101 Clang's driver library. If you are more familiar with the [architecture of
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
108 `flang/tools/flang-driver/driver.cpp`. Flang's compiler driver is implemented
109 in terms of Clang's driver library, `clangDriver`. This approach allows us to:
110 * benefit from Clang's support for various targets, platforms and operating systems
111 * leverage Clang's ability to drive various backends available in LLVM, as well
113 One implication of this dependency on Clang is that all of Flang's compiler
114 options are defined alongside Clang's options in
115 `clang/include/clang/Driver/Options.td`. For options that are common for both
116 Flang and Clang, the corresponding definitions are shared.
121 `clang::driver::Action::ActionClass` enum. There are also other, more
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
154 instance of `clang::driver::Command`). Every command is bound to an instance of
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`.
159 You can read more on the design of `clangDriver` in Clang's [Driver Design &
160 Internals](https://clang.llvm.org/docs/DriverInternals.html).
177 $ flang -v -o example example.o
178 "/usr/bin/ld" [...] example.o [...] "-lFortranRuntime" "-lFortranDecimal" [...]
186 If the code is C/C++ based and invokes Fortran routines, one can either use Clang
187 or Flang as the linker driver. If Clang is used, it will automatically all
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
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>`.
246 `clang/include/clang/Driver/Options.td` in Clang. When adding a new option to
249 in one of Clang's drivers (e.g. `clang`), but not yet available in Flang, or
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,
264 Options that are supported by clang should explicitly specify `ClangOption` in
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`)
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
306 `-fsyntax-only` we defined:
315 `ParseSyntaxOnly` for `-fsyntax-only`) and a corresponding `case` in
318 case clang::driver::options::OPT_fsyntax_only:
327 `-fsyntax-only`:
337 As of [#7246](https://gitlab.kitware.com/cmake/cmake/-/merge_requests/7246)
342 cmake -DCMAKE_Fortran_COMPILER=<path/to/flang> <src/dir>
346 -- The Fortran compiler identification is LLVMFlang <version>
353 * `%flang_fc1` is expanded as `flang -fc1` (i.e. the frontend driver)
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)
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
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
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
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
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
535 [`llvm::PassBuilder`](https://llvm.org/doxygen/classllvm_1_1PassBuilder.html)
539 machinery as that used by `clang` and thus has the same capabilities and
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.
561 [`WritingAnLLVMNewPMPass`](https://llvm.org/docs/WritingAnLLVMNewPMPass.html#id9)
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
597 GCC/GFortran will also set flush-to-zero mode: linking `crtfastmath.o`, the same
600 The only GCC/GFortran warning option currently supported is `-Werror`. Passing
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
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