@@ -15,17 +15,13 @@ local:
15
15
```
16
16
17
17
There are two main drivers in Flang:
18
- * the compiler driver, ` flang-new `
19
- * the frontend driver, ` flang-new -fc1 `
20
-
21
- > ** _ NOTE:_ ** The diagrams in this document refer to ` flang ` as opposed to
22
- > ` flang-new ` . Eventually, ` flang-new ` will be renamed as ` flang ` and the
23
- > diagrams reflect the final design that we are still working towards.
18
+ * the compiler driver, ` flang `
19
+ * the frontend driver, ` flang -fc1 `
24
20
25
21
The ** compiler driver** will allow you to control all compilation phases (e.g.
26
22
preprocessing, semantic checks, code-generation, code-optimisation, lowering
27
23
and linking). For frontend specific tasks, the compiler driver creates a
28
- Fortran compilation job and delegates it to ` flang-new -fc1 ` , the frontend
24
+ Fortran compilation job and delegates it to ` flang -fc1 ` , the frontend
29
25
driver. For linking, it creates a linker job and calls an external linker (e.g.
30
26
LLVM's [ ` lld ` ] ( https://lld.llvm.org/ ) ). It can also call other tools such as
31
27
external assemblers (e.g. [ ` as ` ] ( https://www.gnu.org/software/binutils/ ) ). In
@@ -47,7 +43,7 @@ frontend. It uses MLIR and LLVM for code-generation and can be viewed as a
47
43
driver for Flang, LLVM and MLIR libraries. Contrary to the compiler driver, it
48
44
is not capable of calling any external tools (including linkers). It is aware
49
45
of all the frontend internals that are "hidden" from the compiler driver. It
50
- accepts many frontend-specific options not available in ` flang-new ` and as such
46
+ accepts many frontend-specific options not available in ` flang ` and as such
51
47
it provides a finer control over the frontend. Note that this tool is mostly
52
48
intended for Flang developers. In particular, there are no guarantees about the
53
49
stability of its interface and compiler developers can use it to experiment
@@ -62,30 +58,30 @@ frontend specific flag from the _compiler_ directly to the _frontend_ driver,
62
58
e.g.:
63
59
64
60
``` bash
65
- flang-new -Xflang -fdebug-dump-parse-tree input.f95
61
+ flang -Xflang -fdebug-dump-parse-tree input.f95
66
62
```
67
63
68
- In the invocation above, ` -fdebug-dump-parse-tree ` is forwarded to `flang-new
64
+ In the invocation above, ` -fdebug-dump-parse-tree ` is forwarded to `flang
69
65
-fc1` . Without the forwarding flag, ` -Xflang`, you would see the following
70
66
warning:
71
67
72
68
``` bash
73
- flang-new : warning: argument unused during compilation:
69
+ flang: warning: argument unused during compilation:
74
70
```
75
71
76
- As ` -fdebug-dump-parse-tree ` is only supported by ` flang-new -fc1 ` , ` flang-new `
72
+ As ` -fdebug-dump-parse-tree ` is only supported by ` flang -fc1 ` , ` flang `
77
73
will ignore it when used without ` Xflang ` .
78
74
79
75
## Why Do We Need Two Drivers?
80
- As hinted above, ` flang-new ` and ` flang-new -fc1 ` are two separate tools. The
81
- fact that these tools are accessed through one binary, ` flang-new ` , is just an
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
78
implementation detail. Each tool has a separate list of options, albeit defined
83
79
in the same file: ` clang/include/clang/Driver/Options.td ` .
84
80
85
81
The separation helps us split various tasks and allows us to implement more
86
- specialised tools. In particular, ` flang-new ` is not aware of various
82
+ specialised tools. In particular, ` flang ` is not aware of various
87
83
compilation phases within the frontend (e.g. scanning, parsing or semantic
88
- checks). It does not have to be. Conversely, the frontend driver, `flang-new
84
+ checks). It does not have to be. Conversely, the frontend driver, `flang
89
85
-fc1`, needs not to be concerned with linkers or other external tools like
90
86
assemblers. Nor does it need to know where to look for various systems
91
87
libraries, which is usually OS and platform specific.
@@ -104,7 +100,7 @@ GCC](https://en.wikibooks.org/wiki/GNU_C_Compiler_Internals/GNU_C_Compiler_Archi
104
100
In fact, Flang needs to adhere to this model in order to be able to re-use
105
101
Clang's driver library. If you are more familiar with the [ architecture of
106
102
GFortran] ( https://gcc.gnu.org/onlinedocs/gcc-4.7.4/gfortran/About-GNU-Fortran.html )
107
- than Clang, then ` flang-new ` corresponds to ` gfortran ` and ` flang-new -fc1 ` to
103
+ than Clang, then ` flang ` corresponds to ` gfortran ` and ` flang -fc1 ` to
108
104
` f951 ` .
109
105
110
106
## Compiler Driver
@@ -135,15 +131,15 @@ output from one action is the input for the subsequent one. You can use the
135
131
` -ccc-print-phases ` flag to see the sequence of actions that the driver will
136
132
create for your compiler invocation:
137
133
``` bash
138
- flang-new -ccc-print-phases -E file.f
134
+ flang -ccc-print-phases -E file.f
139
135
+- 0: input, " file.f" , f95-cpp-input
140
136
1: preprocessor, {0}, f95
141
137
```
142
138
As you can see, for ` -E ` the driver creates only two jobs and stops immediately
143
139
after preprocessing. The first job simply prepares the input. For ` -c ` , the
144
140
pipeline of the created jobs is more complex:
145
141
``` bash
146
- flang-new -ccc-print-phases -c file.f
142
+ flang -ccc-print-phases -c file.f
147
143
+- 0: input, " file.f" , f95-cpp-input
148
144
+- 1: preprocessor, {0}, f95
149
145
+- 2: compiler, {1}, ir
@@ -158,7 +154,7 @@ command to call the frontend driver is generated (more specifically, an
158
154
instance of ` clang::driver::Command ` ). Every command is bound to an instance of
159
155
` clang::driver::Tool ` . For Flang we introduced a specialisation of this class:
160
156
` clang::driver::Flang ` . This class implements the logic to either translate or
161
- forward compiler options to the frontend driver, ` flang-new -fc1 ` .
157
+ forward compiler options to the frontend driver, ` flang -fc1 ` .
162
158
163
159
You can read more on the design of ` clangDriver ` in Clang's [ Driver Design &
164
160
Internals] ( https://clang.llvm.org/docs/DriverInternals.html ) .
@@ -232,12 +228,12 @@ driver, `clang -cc1` and consists of the following classes:
232
228
This list is not exhaustive and only covers the main classes that implement the
233
229
driver. The main entry point for the frontend driver, ` fc1_main ` , is
234
230
implemented in ` flang/tools/flang-driver/driver.cpp ` . It can be accessed by
235
- invoking the compiler driver, ` flang-new ` , with the ` -fc1 ` flag.
231
+ invoking the compiler driver, ` flang ` , with the ` -fc1 ` flag.
236
232
237
233
The frontend driver will only run one action at a time. If you specify multiple
238
234
action flags, only the last one will be taken into account. The default action
239
235
is ` ParseSyntaxOnlyAction ` , which corresponds to ` -fsyntax-only ` . In other
240
- words, ` flang-new -fc1 <input-file> ` is equivalent to `flang-new -fc1 -fsyntax-only
236
+ words, ` flang -fc1 <input-file> ` is equivalent to `flang -fc1 -fsyntax-only
241
237
<input-file >`.
242
238
243
239
## Adding new Compiler Options
@@ -262,8 +258,8 @@ similar semantics to your new option and start by copying that.
262
258
For every new option, you will also have to define the visibility of the new
263
259
option. This is controlled through the ` Visibility ` field. You can use the
264
260
following Flang specific visibility flags to control this:
265
- * ` FlangOption ` - this option will be available in the ` flang-new ` compiler driver,
266
- * ` FC1Option ` - this option will be available in the ` flang-new -fc1 ` frontend driver,
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,
267
263
268
264
Options that are supported by clang should explicitly specify ` ClangOption ` in
269
265
` Visibility ` , and options that are only supported in Flang should not specify
@@ -290,10 +286,10 @@ The parsing will depend on the semantics encoded in the TableGen definition.
290
286
291
287
When adding a compiler driver option (i.e. an option that contains
292
288
` FlangOption ` among in it's ` Visibility ` ) that you also intend to be understood
293
- by the frontend, make sure that it is either forwarded to ` flang-new -fc1 ` or
289
+ by the frontend, make sure that it is either forwarded to ` flang -fc1 ` or
294
290
translated into some other option that is accepted by the frontend driver. In
295
291
the case of options that contain both ` FlangOption ` and ` FC1Option ` among its
296
- flags, we usually just forward from ` flang-new ` to ` flang-new -fc1 ` . This is
292
+ flags, we usually just forward from ` flang ` to ` flang -fc1 ` . This is
297
293
then tested in ` flang/test/Driver/frontend-forward.F90 ` .
298
294
299
295
What follows is usually very dependant on the meaning of the corresponding
@@ -339,11 +335,11 @@ just added using your new frontend option.
339
335
340
336
## CMake Support
341
337
As of [ #7246 ] ( https://gitlab.kitware.com/cmake/cmake/-/merge_requests/7246 )
342
- (and soon to be released CMake 3.24 .0 ), `cmake` can detect `flang- new ` as a
338
+ (CMake 3.28 .0 ), `cmake` can detect `flang` as a
343
339
supported Fortran compiler. You can configure your CMake projects to use
344
- `flang- new ` as follows:
340
+ `flang` as follows:
345
341
```bash
346
- cmake -DCMAKE_Fortran_COMPILER=<path/to/flang- new > <src/dir>
342
+ cmake -DCMAKE_Fortran_COMPILER=<path/to/flang> <src/dir>
347
343
```
348
344
You should see the following in the output:
349
345
```
@@ -353,14 +349,14 @@ where `<version>` corresponds to the LLVM Flang version.
353
349
354
350
## Testing
355
351
In LIT, we define two variables that you can use to invoke Flang's drivers:
356
- * ` %flang ` is expanded as ` flang-new ` (i.e. the compiler driver)
357
- * ` %flang_fc1 ` is expanded as ` flang-new -fc1 ` (i.e. the frontend driver)
352
+ * ` %flang ` is expanded as ` flang ` (i.e. the compiler driver)
353
+ * ` %flang_fc1 ` is expanded as ` flang -fc1 ` (i.e. the frontend driver)
358
354
359
355
For most regression tests for the frontend, you will want to use ` %flang_fc1 ` .
360
356
In some cases, the observable behaviour will be identical regardless of whether
361
357
` %flang ` or ` %flang_fc1 ` is used. However, when you are using ` %flang ` instead
362
358
of ` %flang_fc1 ` , the compiler driver will add extra flags to the frontend
363
- driver invocation (i.e. ` flang-new -fc1 -<extra-flags> ` ). In some cases that might
359
+ driver invocation (i.e. ` flang -fc1 -<extra-flags> ` ). In some cases that might
364
360
be exactly what you want to test. In fact, you can check these additional
365
361
flags by using the ` -### ` compiler driver command line option.
366
362
@@ -380,7 +376,7 @@ plugins. The process for using plugins includes:
380
376
* [ Creating a plugin] ( #creating-a-plugin )
381
377
* [ Loading and running a plugin] ( #loading-and-running-a-plugin )
382
378
383
- Flang plugins are limited to ` flang-new -fc1 ` and are currently only available /
379
+ Flang plugins are limited to ` flang -fc1 ` and are currently only available /
384
380
been tested on Linux.
385
381
386
382
### Creating a Plugin
@@ -465,14 +461,14 @@ static FrontendPluginRegistry::Add<PrintFunctionNamesAction> X(
465
461
466
462
### Loading and Running a Plugin
467
463
In order to use plugins, there are 2 command line options made available to the
468
- frontend driver, ` flang-new -fc1 ` :
464
+ frontend driver, ` flang -fc1 ` :
469
465
* [ ` -load <dsopath> ` ] ( #the--load-dsopath-option ) for loading the dynamic shared
470
466
object of the plugin
471
467
* [ ` -plugin <name> ` ] ( #the--plugin-name-option ) for calling the registered plugin
472
468
473
469
Invocation of the example plugin is done through:
474
470
``` bash
475
- flang-new -fc1 -load flangPrintFunctionNames.so -plugin print-fns file.f90
471
+ flang -fc1 -load flangPrintFunctionNames.so -plugin print-fns file.f90
476
472
```
477
473
478
474
Both these options are parsed in ` flang/lib/Frontend/CompilerInvocation.cpp ` and
@@ -493,7 +489,7 @@ reports an error diagnostic and returns `nullptr`.
493
489
494
490
### Enabling In-Tree Plugins
495
491
For in-tree plugins, there is the CMake flag ` FLANG_PLUGIN_SUPPORT ` , enabled by
496
- default, that controls the exporting of executable symbols from ` flang-new ` ,
492
+ default, that controls the exporting of executable symbols from ` flang ` ,
497
493
which plugins need access to. Additionally, there is the CMake flag
498
494
` LLVM_BUILD_EXAMPLES ` , turned off by default, that is used to control if the
499
495
example programs are built. This includes plugins that are in the
@@ -526,7 +522,7 @@ invocations `invokeFIROptEarlyEPCallbacks`, `invokeFIRInlinerCallback`, and
526
522
`invokeFIROptLastEPCallbacks` for Flang drivers to be able to insert additonal
527
523
passes at different points of the default pass pipeline. An example use of these
528
524
extension point callbacks is shown in `registerDefaultInlinerPass` to invoke the
529
- default inliner pass in `flang- new `.
525
+ default inliner pass in `flang`.
530
526
531
527
## LLVM Pass Plugins
532
528
@@ -539,15 +535,15 @@ documentation for
539
535
[`llvm::PassBuilder`](https:// llvm.org/doxygen/classllvm_1_1PassBuilder.html)
540
536
for details.
541
537
542
- The framework to enable pass plugins in `flang- new ` uses the exact same
538
+ The framework to enable pass plugins in `flang` uses the exact same
543
539
machinery as that used by `clang` and thus has the same capabilities and
544
540
limitations.
545
541
546
542
In order to use a pass plugin, the pass (es) must be compiled into a dynamic
547
543
shared object which is then loaded using the ` -fpass-plugin ` option.
548
544
549
545
```
550
- flang-new -fpass-plugin=/path/to/plugin.so <file.f90>
546
+ flang -fpass-plugin=/path/to/plugin.so <file.f90>
551
547
```
552
548
553
549
This option is available in both the compiler driver and the frontend driver.
@@ -559,7 +555,7 @@ Pass extensions are similar to plugins, except that they can also be linked
559
555
statically. Setting ` -DLLVM_${NAME}_LINK_INTO_TOOLS ` to ` ON ` in the cmake
560
556
command turns the project into a statically linked extension. An example would
561
557
be Polly, e.g., using ` -DLLVM_POLLY_LINK_INTO_TOOLS=ON ` would link Polly passes
562
- into ` flang-new ` as built-in middle-end passes.
558
+ into ` flang ` as built-in middle-end passes.
563
559
564
560
See the
565
561
[ ` WritingAnLLVMNewPMPass ` ] ( https://llvm.org/docs/WritingAnLLVMNewPMPass.html#id9 )
0 commit comments