Skip to content

Commit

Permalink
[Fortran/gfortran][NFC] Update README.md (#108)
Browse files Browse the repository at this point in the history
* [Fortran/gfortran][NFC] Update README.md

Remove references to the "old" way of doing things which has now been removed.
Add text describing the correct handling of directives. Add notes describing
some other limitations that would be good to remove.
  • Loading branch information
tarunprabhu authored Mar 19, 2024
1 parent eb52edb commit 95a9f0d
Showing 1 changed file with 33 additions and 23 deletions.
56 changes: 33 additions & 23 deletions Fortran/gfortran/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ behavior of the binary produced by the compiler.
Currently, only the _execute_ tests are supported in `regression`. Both
`compile` and `execute` tests have been enabled in `torture`.

Of the supported tests, a number of tests have been disabled. There are four
Of the supported tests, a number of tests have been disabled. These are listed
in the `DisabledFiles.cmake` files that can be found in the various
subdirectories of `Fortran/gfortran`. There are four
categories of such tests:

- *Unsupported*: These are tests that use non-standard extensions/intrinsics
Expand Down Expand Up @@ -129,19 +131,13 @@ implemented at a steady pace. The relevant tests in this directory should be
enabled. This would involve building the test suite with one of the
`TEST_SUITE_FORTRAN_*` flags described above.

_*NOTE*: We are currently in the process of migrating to the static test
configuration described below. During that time, the configuration files and
associated scripts will be present in the repository but will not be used. When
the migration is completed, this note will be removed._

The build system uses static test configuration files named `tests.cmake` to be
found in the various subdirectories of the test suite. These are generated by
`utils/update-test-config.py`. The configuration files are the result of parsing
the relevant DejaGNU annotations from the test files and are used by the various
`CMakeLists.txt` files to set up the tests. This was a lot easier --- and
cleaner --- than parsing the annotations from `cmake`. These configuration files
are not intended to be edited by hand - any edits will be overwritten when
`update-test-config.py` is run.
`CMakeLists.txt` files to set up the tests. These configuration files *must not*
be edited by hand - any edits will be overwritten when `update-test-config.py`
is run.

The test configuration files consist of comment and non-comment lines. Comment
lines start with a `#`. Each non-comment line represents a single test. The line
Expand Down Expand Up @@ -182,7 +178,9 @@ The test files in `regression` and `torture` *must not* be modified.
If some of the items listed here are implemented, even in part, it should
allows us to make better use of the test-suite.

Several DejaGNU directives from the test files are currently ignored. In some
Several DejaGNU directives from the test files are either ignored or only
partially supported - i.e. only a subset of the options specified by the
directive are handled correctly. In some
cases, those directives check that the language feature/optimization being
exercised by the tests is actually handled correctly. By ignoring them, we are
simply checking that `flang` (or the code produced by it) does not crash at
Expand All @@ -196,7 +194,7 @@ vectorized the code.
It is not clear how much effort would be involved in correctly handling all the
DejaGNU directives.

### `dg-error` directive ###
#### `dg-error` directive ####

The `dg-error` directive indicates that the test should fail to compile with a
particular error. Obviously, this is a `gfortran`-specific error. `flang` may
Expand All @@ -210,7 +208,7 @@ are currently not implemented which results in a parse error (as opposed to the
triggering of a "not-yet-implemented" assertion) which is also deemed an "error",
thereby causing the test to pass.

### `dg-warning` directive ###
#### `dg-warning` directive ####

Currently, the `dg-warning` directive is ignored. It ought to be possible to
treat in a manner similar to `dg-error`.
Expand All @@ -227,15 +225,27 @@ the file for the presence or absence of certain text. To capture the same
behavior here, we would need to parse and translate the internal representation
of GCC to an equivalent representation in LLVM IR.

### `target` directive ###
#### `target` directive ####

The `target` directive is used to restrict tests to run on certain platforms
and/or systems. The directive can be fairly complex. While in most cases the
directive simply consists of a triple specifying the platform on which the
test is enabled (or disabled), negations, logical `and` and `or` operations are
also permitted. The directives can appear in several places within
a test file. In addition to "top-level" directives which control whether or
not the entire test is enabled, a `target` directive can also be used to
conditionally emit or suppress an error or a warning on certain platforms.
Currently, there is limited support for these directives.

- Logical operators on `target` directives are not supported. Directives
containing these operators are ignored entirely.

- Only "top-level" directives are handled. `target` directives that appear
inside other directives such as `dg-error` or `dg-warning` are ignored.

_*NOTE*: With the static test configuration, the "top-level" `target` directives
are correctly handled. This section will be updated when the switch to the
static test configurations is completed._
#### Platform-specific disabling of tests ####

The `target` directive is used to restrict tests to run on certain
platforms/systems. Currently, the target directive is ignored entirely and the
tests are always run. Currently, the gfortran tests are only enabled on *nix on
x86-64 and aarch64 and ignoring the directive seems to be ok. As support for
more systems and architectures are added, these directives will need to be
handled correctly.
Some tests fail on certain platforms but not on others. There is, currently, no
way to disable these tests on a specific platform and these are disabled
everywhere. This is obviously not ideal since the extra coverage that the tests
provide — even if on a limited set of platforms — is desirable.

0 comments on commit 95a9f0d

Please sign in to comment.