Doomhowl-Interactive/llvm-project
0
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

[flang][docs] Replace references to f18 in the docs with flang (Part 1)

Browse Source 
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:
Tarun Prabhu
2025-10-22 07:50:08 -06:00
committed by GitHub
parent 9abbec66bf
commit 0c7617d818
11 changed files with 81 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
flang/docs/AssumedRank.md
View File

@@ -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.

16
flang/docs/C++17.md
View File

@@ -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

12
flang/docs/C++style.md
View File

@@ -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

6
flang/docs/Calls.md
View File

@@ -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

8
flang/docs/Character.md
View File

@@ -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()`

3
flang/docs/DoConcurrent.md
View File

@@ -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

34
flang/docs/Extensions.md
View File

@@ -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.

2
flang/docs/FortranForCProgrammers.md
View File

@@ -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

2
flang/docs/FortranIR.md
View File

@@ -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

2
flang/docs/GettingInvolved.md
View File

@@ -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

56
flang/docs/Intrinsics.md
View File

@@ -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).