[flang][docs] Replace references to f18 in the docs with flang (Part 1)
In addition to the replacement, some light editing of the text was also carried out. These edits primarily address issues of grammar and style. The remaining references to "f18" will be replaced in a later commit.
This commit is contained in:
@@ -101,9 +101,9 @@ Assumed-rank dummies are also represented in the
|
|||||||
represent assumed-rank in procedure characteristics.
|
represent assumed-rank in procedure characteristics.
|
||||||
|
|
||||||
### Runtime Representation of Assumed-Ranks
|
### Runtime Representation of Assumed-Ranks
|
||||||
Assumed-ranks are implemented as CFI_cdesc_t (18.5.3) with the addition of an
|
Assumed-ranks are implemented as CFI_cdesc_t (18.5.3) with the addition of a
|
||||||
f18 specific addendum when required for the type. This is the usual f18
|
Flang specific addendum when required for the type. This is the usual Flang
|
||||||
descriptor, and no changes is required to represent assumed-ranks in this data
|
descriptor, and no changes are required to represent assumed-ranks in this data
|
||||||
structure. In fact, there is no difference between the runtime descriptor
|
structure. In fact, there is no difference between the runtime descriptor
|
||||||
created for an assumed shape and the runtime descriptor created when the
|
created for an assumed shape and the runtime descriptor created when the
|
||||||
corresponding entity is passed as an assumed-rank.
|
corresponding entity is passed as an assumed-rank.
|
||||||
|
|||||||
@@ -6,7 +6,7 @@
|
|||||||
|
|
||||||
-->
|
-->
|
||||||
|
|
||||||
# C++14/17 features used in f18
|
# C++14/17 features used in Flang
|
||||||
|
|
||||||
```{contents}
|
```{contents}
|
||||||
---
|
---
|
||||||
@@ -27,7 +27,7 @@ out the details of how our C++ code should look and gives
|
|||||||
guidance about feature usage.
|
guidance about feature usage.
|
||||||
|
|
||||||
We have chosen to use some features of the recent C++17
|
We have chosen to use some features of the recent C++17
|
||||||
language standard in f18.
|
language standard in Flang.
|
||||||
The most important of these are:
|
The most important of these are:
|
||||||
* sum types (discriminated unions) in the form of `std::variant`
|
* sum types (discriminated unions) in the form of `std::variant`
|
||||||
* `using` template parameter packs
|
* `using` template parameter packs
|
||||||
@@ -41,7 +41,7 @@ in this list because it's not particularly well known.)
|
|||||||
## Sum types
|
## Sum types
|
||||||
|
|
||||||
First, some background information to explain the need for sum types
|
First, some background information to explain the need for sum types
|
||||||
in f18.
|
in Flang.
|
||||||
|
|
||||||
Fortran is notoriously problematic to lex and parse, as tokenization
|
Fortran is notoriously problematic to lex and parse, as tokenization
|
||||||
depends on the state of the partial parse;
|
depends on the state of the partial parse;
|
||||||
@@ -57,7 +57,7 @@ a unified lexer/parser.
|
|||||||
We have chosen to do so because it is simpler and should reduce
|
We have chosen to do so because it is simpler and should reduce
|
||||||
both initial bugs and long-term maintenance.
|
both initial bugs and long-term maintenance.
|
||||||
|
|
||||||
Specifically, f18's parser uses the technique of recursive descent with
|
Specifically, Flang's parser uses the technique of recursive descent with
|
||||||
backtracking.
|
backtracking.
|
||||||
It is constructed as the incremental composition of pure parsing functions
|
It is constructed as the incremental composition of pure parsing functions
|
||||||
that each, when given a context (location in the input stream plus some state),
|
that each, when given a context (location in the input stream plus some state),
|
||||||
@@ -73,7 +73,7 @@ of Fortran.
|
|||||||
|
|
||||||
The specification of Fortran uses a form of BNF with alternatives,
|
The specification of Fortran uses a form of BNF with alternatives,
|
||||||
optional elements, sequences, and lists. Each of these constructs
|
optional elements, sequences, and lists. Each of these constructs
|
||||||
in the Fortran grammar maps directly in the f18 parser to both
|
in the Fortran grammar maps directly in Flang's parser to both
|
||||||
the means of combining other parsers as alternatives, &c., and to
|
the means of combining other parsers as alternatives, &c., and to
|
||||||
the declarations of the parse tree data structures that represent
|
the declarations of the parse tree data structures that represent
|
||||||
the results of successful parses.
|
the results of successful parses.
|
||||||
@@ -87,10 +87,10 @@ The bounded polymorphism supplied by the C++17 `std::variant` fits
|
|||||||
those needs exactly.
|
those needs exactly.
|
||||||
For example, production R502 in Fortran defines the top-level
|
For example, production R502 in Fortran defines the top-level
|
||||||
program unit of Fortran as being a function, subroutine, module, &c.
|
program unit of Fortran as being a function, subroutine, module, &c.
|
||||||
The `struct ProgramUnit` in the f18 parse tree header file
|
`struct ProgramUnit` in the Flang parse tree header file
|
||||||
represents each program unit with a member that is a `std::variant`
|
represents each program unit with a member that is a `std::variant`
|
||||||
over the six possibilities.
|
over the six possibilities.
|
||||||
Similarly, the parser for that type in the f18 grammar has six alternatives,
|
Similarly, the parser for that type in Flang's grammar has six alternatives,
|
||||||
each of which constructs an instance of `ProgramUnit` upon the result of
|
each of which constructs an instance of `ProgramUnit` upon the result of
|
||||||
parsing a `Module`, `FunctionSubprogram`, and so on.
|
parsing a `Module`, `FunctionSubprogram`, and so on.
|
||||||
|
|
||||||
@@ -99,7 +99,7 @@ parse is typically implemented with overloaded functions.
|
|||||||
A function instantiated on `ProgramUnit` will use `std::visit` to
|
A function instantiated on `ProgramUnit` will use `std::visit` to
|
||||||
identify the right alternative and perform the right actions.
|
identify the right alternative and perform the right actions.
|
||||||
The call to `std::visit` must pass a visitor that can handle all
|
The call to `std::visit` must pass a visitor that can handle all
|
||||||
of the possibilities, and f18 will fail to build if one is missing.
|
of the possibilities, and Flang will fail to build if one is missing.
|
||||||
|
|
||||||
Were we unable to use `std::variant` directly, we would likely
|
Were we unable to use `std::variant` directly, we would likely
|
||||||
have chosen to implement a local `SumType` replacement; in the
|
have chosen to implement a local `SumType` replacement; in the
|
||||||
|
|||||||
@@ -30,7 +30,7 @@ is clear on usage, follow it.
|
|||||||
is pretty good and comes with lots of justifications for its rules.
|
is pretty good and comes with lots of justifications for its rules.
|
||||||
* Reasonable exceptions to these guidelines can be made.
|
* Reasonable exceptions to these guidelines can be made.
|
||||||
* Be aware of some workarounds for known issues in older C++ compilers that should
|
* Be aware of some workarounds for known issues in older C++ compilers that should
|
||||||
still be able to compile f18. They are listed at the end of this document.
|
still be able to compile Flang. They are listed at the end of this document.
|
||||||
|
|
||||||
## In particular:
|
## In particular:
|
||||||
|
|
||||||
@@ -261,7 +261,7 @@ move semantics, member access, and comparison for equality; suitable for use in
|
|||||||
`std::variant<>`.
|
`std::variant<>`.
|
||||||
* `std::unique_ptr<>`: A nullable pointer with ownership, null by default,
|
* `std::unique_ptr<>`: A nullable pointer with ownership, null by default,
|
||||||
not copyable, reassignable.
|
not copyable, reassignable.
|
||||||
F18 has a helpful `Deleter<>` class template that makes `unique_ptr<>`
|
Flang has a helpful `Deleter<>` class template that makes `unique_ptr<>`
|
||||||
easier to use with forward-referenced data types.
|
easier to use with forward-referenced data types.
|
||||||
* `std::shared_ptr<>`: A nullable pointer with shared ownership via reference
|
* `std::shared_ptr<>`: A nullable pointer with shared ownership via reference
|
||||||
counting, null by default, shallowly copyable, reassignable, and slow.
|
counting, null by default, shallowly copyable, reassignable, and slow.
|
||||||
@@ -312,9 +312,9 @@ Consistency is one of many aspects in the pursuit of clarity,
|
|||||||
but not an end in itself.
|
but not an end in itself.
|
||||||
|
|
||||||
## C++ compiler bug workarounds
|
## C++ compiler bug workarounds
|
||||||
Below is a list of workarounds for C++ compiler bugs met with f18 that, even
|
Below is a list of workarounds for C++ compiler bugs encountered when building
|
||||||
if the bugs are fixed in latest C++ compiler versions, need to be applied so
|
Flang. Even if the bugs are fixed in latest C++ compiler versions, these need to
|
||||||
that all desired tool-chains can compile f18.
|
be applied so that all desired tool-chains can compile Flang.
|
||||||
|
|
||||||
### Explicitly move noncopyable local variable into optional results
|
### Explicitly move noncopyable local variable into optional results
|
||||||
|
|
||||||
@@ -338,7 +338,7 @@ std::optional<CantBeCopied> fooOK() {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
The underlying bug is actually not specific to `std::optional` but this is the most common
|
The underlying bug is actually not specific to `std::optional` but this is the most common
|
||||||
case in f18 where the issue may occur. The actual bug can be reproduced with any class `B`
|
case in Flang where the issue may occur. The actual bug can be reproduced with any class `B`
|
||||||
that has a perfect forwarding constructor taking `CantBeCopied` as argument:
|
that has a perfect forwarding constructor taking `CantBeCopied` as argument:
|
||||||
`template<typename CantBeCopied> B(CantBeCopied&& x) x_{std::forward<CantBeCopied>(x)} {}`.
|
`template<typename CantBeCopied> B(CantBeCopied&& x) x_{std::forward<CantBeCopied>(x)} {}`.
|
||||||
In such scenarios, Ubuntu 18.04 g++ fails to instantiate the move constructor
|
In such scenarios, Ubuntu 18.04 g++ fails to instantiate the move constructor
|
||||||
|
|||||||
@@ -529,7 +529,7 @@ PGI passes host instance links in descriptors in additional arguments
|
|||||||
that are not always successfully forwarded across implicit interfaces,
|
that are not always successfully forwarded across implicit interfaces,
|
||||||
sometimes leading to crashes when they turn out to be needed.
|
sometimes leading to crashes when they turn out to be needed.
|
||||||
|
|
||||||
F18 will manage a pool of trampolines in its runtime support library
|
Flang will manage a pool of trampolines in its runtime support library
|
||||||
that can be used to pass internal procedures as effective arguments
|
that can be used to pass internal procedures as effective arguments
|
||||||
to F77ish procedures, so that
|
to F77ish procedures, so that
|
||||||
a bare code address can serve to represent the effective argument.
|
a bare code address can serve to represent the effective argument.
|
||||||
@@ -569,14 +569,14 @@ Fortran 2018 explicitly enables us to do this with a correction to Fortran
|
|||||||
2003 in 4.3.4(5).
|
2003 in 4.3.4(5).
|
||||||
|
|
||||||
Last, there must be reasonably permanent naming conventions used
|
Last, there must be reasonably permanent naming conventions used
|
||||||
by the F18 runtime library for those unrestricted specific intrinsic
|
by Flang's runtime library for those unrestricted specific intrinsic
|
||||||
functions (table 16.2 in 16.8) and extensions that can be passed as
|
functions (table 16.2 in 16.8) and extensions that can be passed as
|
||||||
arguments.
|
arguments.
|
||||||
|
|
||||||
In these cases where external naming is at the discretion
|
In these cases where external naming is at the discretion
|
||||||
of the implementation, we should use names that are not in the C language
|
of the implementation, we should use names that are not in the C language
|
||||||
user namespace, begin with something that identifies
|
user namespace, begin with something that identifies
|
||||||
the current incompatible version of F18, the module, the submodule, and
|
the current incompatible version of Flang, the module, the submodule, and
|
||||||
elemental SIMD width, and are followed by the external name.
|
elemental SIMD width, and are followed by the external name.
|
||||||
The parts of the external name can be separated by some character that
|
The parts of the external name can be separated by some character that
|
||||||
is acceptable for use in LLVM IR and assembly language but not in user
|
is acceptable for use in LLVM IR and assembly language but not in user
|
||||||
|
|||||||
@@ -6,7 +6,7 @@
|
|||||||
|
|
||||||
-->
|
-->
|
||||||
|
|
||||||
# Implementation of `CHARACTER` types in f18
|
# Implementation of `CHARACTER` types in Flang
|
||||||
|
|
||||||
```{contents}
|
```{contents}
|
||||||
---
|
---
|
||||||
@@ -16,7 +16,7 @@ local:
|
|||||||
|
|
||||||
## Kinds and Character Sets
|
## Kinds and Character Sets
|
||||||
|
|
||||||
The f18 compiler and runtime support three kinds of the intrinsic
|
The Flang compiler and runtime support three kinds of the intrinsic
|
||||||
`CHARACTER` type of Fortran 2018.
|
`CHARACTER` type of Fortran 2018.
|
||||||
The default (`CHARACTER(KIND=1)`) holds 8-bit character codes;
|
The default (`CHARACTER(KIND=1)`) holds 8-bit character codes;
|
||||||
`CHARACTER(KIND=2)` holds 16-bit character codes;
|
`CHARACTER(KIND=2)` holds 16-bit character codes;
|
||||||
@@ -108,12 +108,12 @@ The result of `//` may be used
|
|||||||
* as the value of a specifier of an I/O statement,
|
* as the value of a specifier of an I/O statement,
|
||||||
* or as the value of a statement function.
|
* or as the value of a statement function.
|
||||||
|
|
||||||
The f18 compiler has a general (but slow) means of implementing concatenation
|
The Flang compiler has a general (but slow) means of implementing concatenation
|
||||||
and a specialized (fast) option to optimize the most common case.
|
and a specialized (fast) option to optimize the most common case.
|
||||||
|
|
||||||
### General concatenation
|
### General concatenation
|
||||||
|
|
||||||
In the most general case, the f18 compiler's generated code and
|
In the most general case, Flang's generated code and
|
||||||
runtime support library represent the result as a deferred-length allocatable
|
runtime support library represent the result as a deferred-length allocatable
|
||||||
`CHARACTER` temporary scalar or array variable that is initialized
|
`CHARACTER` temporary scalar or array variable that is initialized
|
||||||
as a zero-length array by `AllocatableInitCharacter()`
|
as a zero-length array by `AllocatableInitCharacter()`
|
||||||
|
|||||||
@@ -280,7 +280,8 @@ Specifically, an easy means is required that stipulates that localization
|
|||||||
should apply at most only to the obvious cases of local non-pointer
|
should apply at most only to the obvious cases of local non-pointer
|
||||||
non-allocatable scalars.
|
non-allocatable scalars.
|
||||||
|
|
||||||
In the LLVM Fortran compiler project (a/k/a "flang", "f18") we considered
|
In the LLVM Fortran compiler project (now known as "flang", previously also
|
||||||
|
known as "f18") we considered
|
||||||
several solutions to this problem.
|
several solutions to this problem.
|
||||||
1. Add syntax (e.g., `DO PARALLEL` or `DO CONCURRENT() DEFAULT(PARALLEL)`)
|
1. Add syntax (e.g., `DO PARALLEL` or `DO CONCURRENT() DEFAULT(PARALLEL)`)
|
||||||
by which one can inform the compiler that it should localize only
|
by which one can inform the compiler that it should localize only
|
||||||
|
|||||||
@@ -84,7 +84,7 @@ end
|
|||||||
be "local identifiers" and should be distinct in the "inclusive
|
be "local identifiers" and should be distinct in the "inclusive
|
||||||
scope" -- i.e., not scoped by `BLOCK` constructs.
|
scope" -- i.e., not scoped by `BLOCK` constructs.
|
||||||
As most (but not all) compilers implement `BLOCK` scoping of construct
|
As most (but not all) compilers implement `BLOCK` scoping of construct
|
||||||
names, so does f18, with a portability warning.
|
names, so does Flang, with a portability warning.
|
||||||
* 15.6.4 paragraph 2 prohibits an implicitly typed statement function
|
* 15.6.4 paragraph 2 prohibits an implicitly typed statement function
|
||||||
from sharing the same name as a symbol in its scope's host, if it
|
from sharing the same name as a symbol in its scope's host, if it
|
||||||
has one.
|
has one.
|
||||||
@@ -153,7 +153,7 @@ end
|
|||||||
that a call to intrinsic module procedure `ieee_support_halting` with
|
that a call to intrinsic module procedure `ieee_support_halting` with
|
||||||
a constant argument has a compile time constant result in `constant
|
a constant argument has a compile time constant result in `constant
|
||||||
expression` and `specification expression` contexts. In compilations
|
expression` and `specification expression` contexts. In compilations
|
||||||
where this information is not known at compile time, f18 generates code
|
where this information is not known at compile time, Flang generates code
|
||||||
to determine the absence or presence of this capability at runtime.
|
to determine the absence or presence of this capability at runtime.
|
||||||
A call to `ieee_support_halting` in contexts that the standard requires
|
A call to `ieee_support_halting` in contexts that the standard requires
|
||||||
to be constant will generate a compilation error. `ieee_support_standard`
|
to be constant will generate a compilation error. `ieee_support_standard`
|
||||||
@@ -366,7 +366,7 @@ end
|
|||||||
* The legacy extension intrinsic functions `IZEXT` and `JZEXT`
|
* The legacy extension intrinsic functions `IZEXT` and `JZEXT`
|
||||||
are supported; `ZEXT` has different behavior with various older
|
are supported; `ZEXT` has different behavior with various older
|
||||||
compilers, so it is not supported.
|
compilers, so it is not supported.
|
||||||
* f18 doesn't impose a limit on the number of continuation lines
|
* Flang doesn't impose a limit on the number of continuation lines
|
||||||
allowed for a single statement.
|
allowed for a single statement.
|
||||||
* When a type-bound procedure declaration statement has neither interface
|
* When a type-bound procedure declaration statement has neither interface
|
||||||
nor attributes, the "::" before the bindings is optional, even
|
nor attributes, the "::" before the bindings is optional, even
|
||||||
@@ -553,7 +553,7 @@ end
|
|||||||
* Fortran explicitly ignores type declaration statements when they
|
* Fortran explicitly ignores type declaration statements when they
|
||||||
attempt to type the name of a generic intrinsic function (8.2 p3).
|
attempt to type the name of a generic intrinsic function (8.2 p3).
|
||||||
One can declare `CHARACTER::COS` and still get a real result
|
One can declare `CHARACTER::COS` and still get a real result
|
||||||
from `COS(3.14159)`, for example. f18 will complain when a
|
from `COS(3.14159)`, for example. Flang will complain when a
|
||||||
generic intrinsic function's inferred result type does not
|
generic intrinsic function's inferred result type does not
|
||||||
match an explicit declaration. This message is a warning.
|
match an explicit declaration. This message is a warning.
|
||||||
|
|
||||||
@@ -570,7 +570,7 @@ end
|
|||||||
|
|
||||||
## Standard features that might as well not be
|
## Standard features that might as well not be
|
||||||
|
|
||||||
* f18 supports designators with constant expressions, properly
|
* Flang supports designators with constant expressions, properly
|
||||||
constrained, as initial data targets for data pointers in
|
constrained, as initial data targets for data pointers in
|
||||||
initializers of variable and component declarations and in
|
initializers of variable and component declarations and in
|
||||||
`DATA` statements; e.g., `REAL, POINTER :: P => T(1:10:2)`.
|
`DATA` statements; e.g., `REAL, POINTER :: P => T(1:10:2)`.
|
||||||
@@ -587,8 +587,8 @@ end
|
|||||||
* The standard doesn't explicitly require that a named constant that
|
* The standard doesn't explicitly require that a named constant that
|
||||||
appears as part of a complex-literal-constant be a scalar, but
|
appears as part of a complex-literal-constant be a scalar, but
|
||||||
most compilers emit an error when an array appears.
|
most compilers emit an error when an array appears.
|
||||||
f18 supports them with a portability warning.
|
Flang supports them with a portability warning.
|
||||||
* f18 does not enforce a blanket prohibition against generic
|
* Flang does not enforce a blanket prohibition against generic
|
||||||
interfaces containing a mixture of functions and subroutines.
|
interfaces containing a mixture of functions and subroutines.
|
||||||
We allow both to appear, unlike several other Fortran compilers.
|
We allow both to appear, unlike several other Fortran compilers.
|
||||||
This is especially desirable when two generics of the same
|
This is especially desirable when two generics of the same
|
||||||
@@ -655,7 +655,7 @@ end
|
|||||||
treat them as references to implicitly typed local variables, and
|
treat them as references to implicitly typed local variables, and
|
||||||
load uninitialized values.
|
load uninitialized values.
|
||||||
|
|
||||||
In f18, we chose to emit an error message for this case since the standard
|
In Flang, we chose to emit an error message for this case since the standard
|
||||||
is unclear, the usage is not portable, and the issue can be easily resolved
|
is unclear, the usage is not portable, and the issue can be easily resolved
|
||||||
by adding a declaration.
|
by adding a declaration.
|
||||||
|
|
||||||
@@ -686,7 +686,7 @@ end
|
|||||||
|
|
||||||
* When a `DATA` statement in a `BLOCK` construct could be construed as
|
* When a `DATA` statement in a `BLOCK` construct could be construed as
|
||||||
either initializing a host-associated object or declaring a new local
|
either initializing a host-associated object or declaring a new local
|
||||||
initialized object, f18 interprets the standard's classification of
|
initialized object, Flang interprets the standard's classification of
|
||||||
a `DATA` statement as being a "declaration" rather than a "specification"
|
a `DATA` statement as being a "declaration" rather than a "specification"
|
||||||
construct, and notes that the `BLOCK` construct is defined as localizing
|
construct, and notes that the `BLOCK` construct is defined as localizing
|
||||||
names that have specifications in the `BLOCK` construct.
|
names that have specifications in the `BLOCK` construct.
|
||||||
@@ -703,7 +703,7 @@ end subroutine
|
|||||||
Other Fortran compilers disagree with each other in their interpretations
|
Other Fortran compilers disagree with each other in their interpretations
|
||||||
of this example.
|
of this example.
|
||||||
The precedent among the most commonly used compilers
|
The precedent among the most commonly used compilers
|
||||||
agrees with f18's interpretation: a `DATA` statement without any other
|
agrees with Flang's interpretation: a `DATA` statement without any other
|
||||||
specification of the name refers to the host-associated object.
|
specification of the name refers to the host-associated object.
|
||||||
|
|
||||||
* Many Fortran compilers allow a non-generic procedure to be `USE`-associated
|
* Many Fortran compilers allow a non-generic procedure to be `USE`-associated
|
||||||
@@ -729,7 +729,7 @@ module m2
|
|||||||
end module
|
end module
|
||||||
```
|
```
|
||||||
|
|
||||||
This case elicits a warning from f18, as it should not be treated
|
This case elicits a warning from Flang, as it should not be treated
|
||||||
any differently than the same case with the non-generic procedure of
|
any differently than the same case with the non-generic procedure of
|
||||||
the same name being defined in the same scope rather than being
|
the same name being defined in the same scope rather than being
|
||||||
`USE`-associated into it, which is explicitly non-conforming in the
|
`USE`-associated into it, which is explicitly non-conforming in the
|
||||||
@@ -747,7 +747,7 @@ end module
|
|||||||
symbols, much less appear in specification inquiries, and there are
|
symbols, much less appear in specification inquiries, and there are
|
||||||
application codes that expect exterior symbols whose names match
|
application codes that expect exterior symbols whose names match
|
||||||
components to be visible in a derived-type definition's default initialization
|
components to be visible in a derived-type definition's default initialization
|
||||||
expressions, and so f18 follows that precedent.
|
expressions, and so Flang follows that precedent.
|
||||||
|
|
||||||
* 19.3.1p1 "Within its scope, a local identifier of an entity of class (1)
|
* 19.3.1p1 "Within its scope, a local identifier of an entity of class (1)
|
||||||
or class (4) shall not be the same as a global identifier used in that scope..."
|
or class (4) shall not be the same as a global identifier used in that scope..."
|
||||||
@@ -769,17 +769,17 @@ end module
|
|||||||
left-hand side for a pointer assignment statement, and we emit a
|
left-hand side for a pointer assignment statement, and we emit a
|
||||||
portability warning when it is not.
|
portability warning when it is not.
|
||||||
|
|
||||||
* F18 allows a `USE` statement to reference a module that is defined later
|
* Flang allows a `USE` statement to reference a module that is defined later
|
||||||
in the same compilation unit, so long as mutual dependencies do not form
|
in the same compilation unit, so long as mutual dependencies do not form
|
||||||
a cycle.
|
a cycle.
|
||||||
This feature forestalls any risk of such a `USE` statement reading an
|
This feature forestalls any risk of such a `USE` statement reading an
|
||||||
obsolete module file from a previous compilation and then overwriting
|
obsolete module file from a previous compilation and then overwriting
|
||||||
that file later.
|
that file later.
|
||||||
|
|
||||||
* F18 allows `OPTIONAL` dummy arguments to interoperable procedures
|
* Flang allows `OPTIONAL` dummy arguments to interoperable procedures
|
||||||
unless they are `VALUE` (C865).
|
unless they are `VALUE` (C865).
|
||||||
|
|
||||||
* F18 processes the `NAMELIST` group declarations in a scope after it
|
* Flang processes the `NAMELIST` group declarations in a scope after it
|
||||||
has resolved all of the names in that scope. This means that names
|
has resolved all of the names in that scope. This means that names
|
||||||
that appear before their local declarations do not resolve to host
|
that appear before their local declarations do not resolve to host
|
||||||
associated objects and do not elicit errors about improper redeclarations
|
associated objects and do not elicit errors about improper redeclarations
|
||||||
@@ -862,11 +862,11 @@ print *, [(j,j=1,10)]
|
|||||||
|
|
||||||
* The Fortran standard doesn't mention integer overflow explicitly. In many cases,
|
* The Fortran standard doesn't mention integer overflow explicitly. In many cases,
|
||||||
however, integer overflow makes programs non-conforming.
|
however, integer overflow makes programs non-conforming.
|
||||||
F18 follows other widely-used Fortran compilers. Specifically, f18 assumes
|
Flang follows other widely-used Fortran compilers. Specifically, Flang assumes
|
||||||
integer overflow never occurs in address calculations and increment of
|
integer overflow never occurs in address calculations and increment of
|
||||||
do-variable unless the option `-fwrapv` is enabled.
|
do-variable unless the option `-fwrapv` is enabled.
|
||||||
|
|
||||||
* Two new ieee_round_type values were added in f18 beyond the four values
|
* Two new ieee_round_type values were added in Flang beyond the four values
|
||||||
defined in f03 and f08: ieee_away and ieee_other. Contemporary hardware
|
defined in f03 and f08: ieee_away and ieee_other. Contemporary hardware
|
||||||
typically does not have support for these rounding modes;
|
typically does not have support for these rounding modes;
|
||||||
ieee_support_rounding calls for these values return false.
|
ieee_support_rounding calls for these values return false.
|
||||||
|
|||||||
@@ -304,7 +304,7 @@ Preprocessing behavior varies across implementations and one should not depend o
|
|||||||
much portability.
|
much portability.
|
||||||
Preprocessing is typically requested by the use of a capitalized filename
|
Preprocessing is typically requested by the use of a capitalized filename
|
||||||
suffix (e.g., "foo.F90") or a compiler command line option.
|
suffix (e.g., "foo.F90") or a compiler command line option.
|
||||||
(Since the F18 compiler always runs its built-in preprocessing stage,
|
(Since Flang always runs its built-in preprocessing stage,
|
||||||
no special option or filename suffix is required.)
|
no special option or filename suffix is required.)
|
||||||
|
|
||||||
## "Object Oriented" Programming
|
## "Object Oriented" Programming
|
||||||
|
|||||||
@@ -171,7 +171,7 @@ FIR is intentionally similar to SIL from the statement level up to the level of
|
|||||||
Program, procedure, region, and basic block all leverage code from LLVM, in much the same way as SIL. These data structures have significant investment and engineering behind their use in compilers, and it makes sense to leverage that work.
|
Program, procedure, region, and basic block all leverage code from LLVM, in much the same way as SIL. These data structures have significant investment and engineering behind their use in compilers, and it makes sense to leverage that work.
|
||||||
|
|
||||||
* Pro: Uses LLVM data structures, pervasive in compiler projects such as LLVM, SIL, etc.
|
* Pro: Uses LLVM data structures, pervasive in compiler projects such as LLVM, SIL, etc.
|
||||||
* Pro: Get used to seeing and using LLVM, as f18 aims to be an LLVM project
|
* Pro: Get used to seeing and using LLVM, as Flang aims to be an LLVM project
|
||||||
* Con: Uses LLVM data structures, which the project has been avoiding
|
* Con: Uses LLVM data structures, which the project has been avoiding
|
||||||
|
|
||||||
#### Alternative: C++ Standard Template Library
|
#### Alternative: C++ Standard Template Library
|
||||||
|
|||||||
@@ -41,7 +41,7 @@ Contributions to Flang are done using GitHub Pull Requests and follow the
|
|||||||
### Flang Slack Workspace
|
### Flang Slack Workspace
|
||||||
|
|
||||||
- There is a Slack workspace dedicated to Flang.
|
- There is a Slack workspace dedicated to Flang.
|
||||||
- There are a number of topic-oriented channels available (e.g., #driver, #f18-semantics, #fir).
|
- There are a number of topic-oriented channels available (e.g., #driver, #fir).
|
||||||
- Add yourself via the *[invitation link](https://join.slack.com/t/flang-compiler/shared_invite/zt-2pcn51lh-VrRQL_YUOkxA_1CEfMGQhw "title")*
|
- Add yourself via the *[invitation link](https://join.slack.com/t/flang-compiler/shared_invite/zt-2pcn51lh-VrRQL_YUOkxA_1CEfMGQhw "title")*
|
||||||
|
|
||||||
## Calls
|
## Calls
|
||||||
|
|||||||
@@ -19,7 +19,7 @@ of functions or subroutines with similar interfaces as an aid to
|
|||||||
comprehension beyond that which might be gained from the standard's
|
comprehension beyond that which might be gained from the standard's
|
||||||
alphabetical list.
|
alphabetical list.
|
||||||
|
|
||||||
A brief status of intrinsic procedure support in f18 is also given at the end.
|
A brief status of intrinsic procedure support in Flang is also given at the end.
|
||||||
|
|
||||||
Few procedures are actually described here apart from their interfaces; see the
|
Few procedures are actually described here apart from their interfaces; see the
|
||||||
Fortran 2018 standard (section 16) for the complete story.
|
Fortran 2018 standard (section 16) for the complete story.
|
||||||
@@ -733,20 +733,20 @@ In case the invocation would be an error if the procedure were the intrinsic
|
|||||||
leaves two choices to the compiler: emit an error about the intrinsic invocation,
|
leaves two choices to the compiler: emit an error about the intrinsic invocation,
|
||||||
or consider this is an external procedure and emit no error.
|
or consider this is an external procedure and emit no error.
|
||||||
|
|
||||||
f18 will always consider this case to be the intrinsic and emit errors, unless the procedure
|
Flang will always consider this case to be the intrinsic and emit errors, unless the procedure
|
||||||
is used as a function (resp. subroutine) and the intrinsic is a subroutine (resp. function).
|
is used as a function (resp. subroutine) and the intrinsic is a subroutine (resp. function).
|
||||||
The table below gives some examples of decisions made by Fortran compilers in such case.
|
The table below gives some examples of decisions made by Fortran compilers in such case.
|
||||||
|
|
||||||
| What is ACOS ? | Bad intrinsic call | External with warning | External no warning | Other error |
|
| What is ACOS ? | Bad intrinsic call | External with warning | External no warning | Other error |
|
||||||
| --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- |
|
||||||
| `print*, ACOS()` | gfortran, nag, xlf, f18 | ifort | nvfortran | |
|
| `print*, ACOS()` | gfortran, nag, xlf, flang | ifort | nvfortran | |
|
||||||
| `print*, ACOS(I)` | gfortran, nag, xlf, f18 | ifort | nvfortran | |
|
| `print*, ACOS(I)` | gfortran, nag, xlf, flang | ifort | nvfortran | |
|
||||||
| `print*, ACOS(X=I)` | gfortran, nag, xlf, f18 | ifort | | nvfortran (keyword on implicit extrenal )|
|
| `print*, ACOS(X=I)` | gfortran, nag, xlf, flang | ifort | | nvfortran (keyword on implicit extrenal )|
|
||||||
| `print*, ACOS(X, X)` | gfortran, nag, xlf, f18 | ifort | nvfortran | |
|
| `print*, ACOS(X, X)` | gfortran, nag, xlf, flang | ifort | nvfortran | |
|
||||||
| `CALL ACOS(X)` | | | gfortran, nag, xlf, nvfortran, ifort, f18 | |
|
| `CALL ACOS(X)` | | | gfortran, nag, xlf, nvfortran, ifort, flang | |
|
||||||
|
|
||||||
|
|
||||||
The rationale for f18 behavior is that when referring to a procedure with an
|
The rationale for Flang behavior is that when referring to a procedure with an
|
||||||
argument number or type that does not match the intrinsic specification, it seems safer to block
|
argument number or type that does not match the intrinsic specification, it seems safer to block
|
||||||
the rather likely case where the user is using the intrinsic the wrong way.
|
the rather likely case where the user is using the intrinsic the wrong way.
|
||||||
In case the user wanted to refer to an external function, he can add an explicit EXTERNAL
|
In case the user wanted to refer to an external function, he can add an explicit EXTERNAL
|
||||||
@@ -759,13 +759,13 @@ Also note that in general, the standard gives the compiler the right to consider
|
|||||||
any procedure that is not explicitly external as a non standard intrinsic (section 4.2 point 4).
|
any procedure that is not explicitly external as a non standard intrinsic (section 4.2 point 4).
|
||||||
So it is highly advised for the programmer to use EXTERNAL statements to prevent any ambiguity.
|
So it is highly advised for the programmer to use EXTERNAL statements to prevent any ambiguity.
|
||||||
|
|
||||||
## Intrinsic Procedure Support in f18
|
## Intrinsic Procedure Support in Flang
|
||||||
This section gives an overview of the support inside f18 libraries for the
|
This section gives an overview of the support inside Flang libraries for the
|
||||||
intrinsic procedures listed above.
|
intrinsic procedures listed above.
|
||||||
It may be outdated, refer to f18 code base for the actual support status.
|
It may be outdated, refer to Flang code base for the actual support status.
|
||||||
|
|
||||||
### Semantic Analysis
|
### Semantic Analysis
|
||||||
F18 semantic expression analysis phase detects intrinsic procedure references,
|
Flang semantic expression analysis phase detects intrinsic procedure references,
|
||||||
validates the argument types and deduces the return types.
|
validates the argument types and deduces the return types.
|
||||||
This phase currently supports all the intrinsic procedures listed above but the ones in the table below.
|
This phase currently supports all the intrinsic procedures listed above but the ones in the table below.
|
||||||
|
|
||||||
@@ -789,17 +789,17 @@ Constant Expressions may be used to define kind arguments. Therefore, the semant
|
|||||||
expression analysis phase must be able to fold references to intrinsic functions
|
expression analysis phase must be able to fold references to intrinsic functions
|
||||||
listed in section 10.1.12.
|
listed in section 10.1.12.
|
||||||
|
|
||||||
F18 intrinsic function folding is either performed by implementations directly
|
Flang intrinsic function folding is either performed by implementations directly
|
||||||
operating on f18 scalar types or by using host runtime functions and
|
operating on Flang scalar types or by using host runtime functions and
|
||||||
host hardware types. F18 supports folding elemental intrinsic functions over
|
host hardware types. Flang supports folding elemental intrinsic functions over
|
||||||
arrays when an implementation is provided for the scalars (regardless of whether
|
arrays when an implementation is provided for the scalars (regardless of whether
|
||||||
it is using host hardware types or not).
|
it is using host hardware types or not).
|
||||||
The status of intrinsic function folding support is given in the sub-sections below.
|
The status of intrinsic function folding support is given in the sub-sections below.
|
||||||
|
|
||||||
#### Intrinsic Functions with Host Independent Folding Support
|
#### Intrinsic Functions with Host Independent Folding Support
|
||||||
Implementations using f18 scalar types enables folding intrinsic functions
|
Implementations using Flang scalar types enables folding intrinsic functions
|
||||||
on any host and with any possible type kind supported by f18. The intrinsic functions
|
on any host and with any possible type kind supported by Flang. The intrinsic
|
||||||
listed below are folded using host independent implementations.
|
functions listed below are folded using host independent implementations.
|
||||||
|
|
||||||
| Return Type | Intrinsic Functions with Host Independent Folding Support|
|
| Return Type | Intrinsic Functions with Host Independent Folding Support|
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
@@ -810,12 +810,12 @@ listed below are folded using host independent implementations.
|
|||||||
|
|
||||||
#### Intrinsic Functions with Host Dependent Folding Support
|
#### Intrinsic Functions with Host Dependent Folding Support
|
||||||
Implementations using the host runtime may not be available for all supported
|
Implementations using the host runtime may not be available for all supported
|
||||||
f18 types depending on the host hardware types and the libraries available on the host.
|
Flang types depending on the hardware type of the host and the libraries available on it.
|
||||||
The actual support on a host depends on what the host hardware types are.
|
The actual support on a host depends on what the host hardware types are.
|
||||||
The list below gives the functions that are folded using host runtime and the related C/C++ types.
|
The list below gives the functions that are folded using host runtime and the related C/C++ types.
|
||||||
F18 automatically detects if these types match an f18 scalar type. If so,
|
Flang automatically detects if these types match an Flang scalar type. If so,
|
||||||
folding of the intrinsic functions will be possible for the related f18 scalar type,
|
folding of the intrinsic functions will be possible for the related Flang scalar type,
|
||||||
otherwise an error message will be produced by f18 when attempting to fold related intrinsic functions.
|
otherwise an error message will be produced by Flang when attempting to fold related intrinsic functions.
|
||||||
|
|
||||||
| C/C++ Host Type | Intrinsic Functions with Host Standard C++ Library Based Folding Support |
|
| C/C++ Host Type | Intrinsic Functions with Host Standard C++ Library Based Folding Support |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
@@ -823,17 +823,17 @@ otherwise an error message will be produced by f18 when attempting to fold relat
|
|||||||
| std::complex for float, double and long double| ACOS, ACOSH, ASIN, ASINH, ATAN, ATANH, COS, COSH, EXP, LOG, SIN, SINH, SQRT, TAN, TANH |
|
| std::complex for float, double and long double| ACOS, ACOSH, ASIN, ASINH, ATAN, ATANH, COS, COSH, EXP, LOG, SIN, SINH, SQRT, TAN, TANH |
|
||||||
|
|
||||||
On top of the default usage of C++ standard library functions for folding described
|
On top of the default usage of C++ standard library functions for folding described
|
||||||
in the table above, it is possible to compile f18 evaluate library with
|
in the table above, it is possible to compile Flang evaluate library with
|
||||||
[libpgmath](https://github.com/flang-compiler/flang/tree/master/runtime/libpgmath)
|
[libpgmath](https://github.com/flang-compiler/flang/tree/master/runtime/libpgmath)
|
||||||
so that it can be used for folding. To do so, one must have a compiled version
|
so that it can be used for folding. To do so, one must have a compiled version
|
||||||
of the libpgmath library available on the host and add
|
of the libpgmath library available on the host and add
|
||||||
`-DLIBPGMATH_DIR=<path to the compiled shared libpgmath library>` to the f18 cmake command.
|
`-DLIBPGMATH_DIR=<path to the compiled shared libpgmath library>` to the Flang cmake command.
|
||||||
|
|
||||||
Libpgmath comes with real and complex functions that replace C++ standard library
|
Libpgmath comes with real and complex functions that replace C++ standard library
|
||||||
float and double functions to fold all the intrinsic functions listed in the table above.
|
float and double functions to fold all the intrinsic functions listed in the table above.
|
||||||
It has no long double versions. If the host long double matches an f18 scalar type,
|
It has no long double versions. If the host long double matches a Flang scalar type,
|
||||||
C++ standard library functions will still be used for folding expressions with this scalar type.
|
C++ standard library functions will still be used for folding expressions with this scalar type.
|
||||||
Libpgmath adds the possibility to fold the following functions for f18 real scalar
|
Libpgmath adds the possibility to fold the following functions for Flang's real scalar
|
||||||
types related to host float and double types.
|
types related to host float and double types.
|
||||||
|
|
||||||
| C/C++ Host Type | Additional Intrinsic Function Folding Support with Libpgmath (Optional) |
|
| C/C++ Host Type | Additional Intrinsic Function Folding Support with Libpgmath (Optional) |
|
||||||
@@ -841,10 +841,10 @@ types related to host float and double types.
|
|||||||
|float and double| BESSEL_J0, BESSEL_J1, BESSEL_JN (elemental only), BESSEL_Y0, BESSEL_Y1, BESSEL_Yn (elemental only), DERFC_SCALED, ERFC_SCALED, QERFC_SCALED |
|
|float and double| BESSEL_J0, BESSEL_J1, BESSEL_JN (elemental only), BESSEL_Y0, BESSEL_Y1, BESSEL_Yn (elemental only), DERFC_SCALED, ERFC_SCALED, QERFC_SCALED |
|
||||||
|
|
||||||
Libpgmath comes in three variants (precise, relaxed and fast). So far, only the
|
Libpgmath comes in three variants (precise, relaxed and fast). So far, only the
|
||||||
precise version is used for intrinsic function folding in f18. It guarantees the greatest numerical precision.
|
precise version is used for intrinsic function folding in Flang. It guarantees the greatest numerical precision.
|
||||||
|
|
||||||
### Intrinsic Functions with Missing Folding Support
|
### Intrinsic Functions with Missing Folding Support
|
||||||
The following intrinsic functions are allowed in constant expressions but f18
|
The following intrinsic functions are allowed in constant expressions but Flang
|
||||||
is not yet able to fold them. Note that there might be constraints on the arguments
|
is not yet able to fold them. Note that there might be constraints on the arguments
|
||||||
so that these intrinsics can be used in constant expressions (see section 10.1.12 of Fortran 2018 standard).
|
so that these intrinsics can be used in constant expressions (see section 10.1.12 of Fortran 2018 standard).
|
||||||
|
|
||||||
@@ -1133,8 +1133,8 @@ end program rename_proc
|
|||||||
- **Standard:** GNU extension
|
- **Standard:** GNU extension
|
||||||
- **Class:** function
|
- **Class:** function
|
||||||
- **Syntax:** result = `SECNDS(refTime)`
|
- **Syntax:** result = `SECNDS(refTime)`
|
||||||
- **Arguments:**
|
- **Arguments:**
|
||||||
|
|
||||||
| ARGUMENT | INTENT | TYPE | KIND | Description |
|
| ARGUMENT | INTENT | TYPE | KIND | Description |
|
||||||
|-----------|--------|---------------|-------------------------|------------------------------------------|
|
|-----------|--------|---------------|-------------------------|------------------------------------------|
|
||||||
| `refTime` | `IN` | `REAL, scalar`| REAL(KIND=4), required | Reference time in seconds since midnight |
|
| `refTime` | `IN` | `REAL, scalar`| REAL(KIND=4), required | Reference time in seconds since midnight |
|
||||||
@@ -1157,16 +1157,16 @@ END PROGRAM example_secnds
|
|||||||
since midnight minus a user-supplied reference time `refTime`. Uses `REAL(KIND=8)` for higher precision.
|
since midnight minus a user-supplied reference time `refTime`. Uses `REAL(KIND=8)` for higher precision.
|
||||||
|
|
||||||
#### Usage and Info
|
#### Usage and Info
|
||||||
- **Standard:** PGI extension
|
- **Standard:** PGI extension
|
||||||
- **Class:** function
|
- **Class:** function
|
||||||
- **Syntax:** result = `DSECNDS(refTime)`
|
- **Syntax:** result = `DSECNDS(refTime)`
|
||||||
- **Arguments:**
|
- **Arguments:**
|
||||||
|
|
||||||
| ARGUMENT | INTENT | TYPE | KIND | Description |
|
| ARGUMENT | INTENT | TYPE | KIND | Description |
|
||||||
|-----------|--------|---------------|-------------------------|------------------------------------------|
|
|-----------|--------|---------------|-------------------------|------------------------------------------|
|
||||||
| `refTime` | `IN` | `REAL, scalar`| REAL(KIND=8), required | Reference time in seconds since midnight |
|
| `refTime` | `IN` | `REAL, scalar`| REAL(KIND=8), required | Reference time in seconds since midnight |
|
||||||
|
|
||||||
- **Return Value:** REAL(KIND=8), scalar — seconds elapsed since `refTime`.
|
- **Return Value:** REAL(KIND=8), scalar — seconds elapsed since `refTime`.
|
||||||
- **Purity:** Impure
|
- **Purity:** Impure
|
||||||
|
|
||||||
#### Example
|
#### Example
|
||||||
|
|||||||
Reference in New Issue
Block a user