[Fortran/gfortran][NFC] Update README.md (#108)
* [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.
diff --git a/Fortran/gfortran/README.md b/Fortran/gfortran/README.md
index 04173b8..5006cd9 100644
--- a/Fortran/gfortran/README.md
+++ b/Fortran/gfortran/README.md
@@ -16,7 +16,9 @@
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
@@ -129,19 +131,13 @@
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
@@ -182,7 +178,9 @@
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
@@ -196,7 +194,7 @@
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
@@ -210,7 +208,7 @@
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`.
@@ -227,15 +225,27 @@
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 ####
-_*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._
+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.
-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.
+- 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.
+
+#### Platform-specific disabling of tests ####
+
+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.
