Lines Matching +full:docs +full:- +full:lld +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
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 |:--:|
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
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
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
108 `flang/tools/flang-driver/driver.cpp`. Flang's compiler driver is implemented
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
157 forward compiler options to the frontend driver, `flang -fc1`.
160 Internals](https://clang.llvm.org/docs/DriverInternals.html).
164 external linker command (e.g., LLVM's `lld`) and invokes it to create the final
177 $ flang -v -o example example.o
178 "/usr/bin/ld" [...] example.o [...] "-lFortranRuntime" "-lFortranDecimal" [...]
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>`.
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,
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`)
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
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
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)
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