Skip to content

Commit 2de9e32

Browse files
rousonrouson
authored
Merge pull request #121 from BerkeleyLab/fix-scaffold-for-gfortran
Work around gfortran/NAG compiler issues in the scaffold app
2 parents 48c3373 + 07b4bb8 commit 2de9e32

1 file changed

Lines changed: 57 additions & 39 deletions

File tree

‎demo/README.md‎

Lines changed: 57 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -10,31 +10,43 @@ Please try [running the demonstration tests] and [generating test scaffolding].
1010

1111
Writing tests
1212
-------------
13-
Testing with Julienne centers around the `test_t` abstract derived type.
14-
Users extend `test_t`, definoing non-abstract child types capturing groups of tests.
15-
Doing so requires defining the inherited deferred bindings: the `subject` and `results` functions.
16-
17-
* `subject` has no argumetns and defines a `character` string result describing what is being tested,
18-
* `results` has no arguments defines a `test_result_t` array result by invoking the inherited `run` function on a child instance, and
19-
* `run` uses a `test_descripton_t` array argument to construct a `test_result_t` array result.
20-
21-
Users construct each `test_description_t` array element by invoking a `test_description_t` constructor function, which has two arguments:
22-
23-
* A `character` string describing whata the test does, typically beginning with a gerund: a word ending in `-ing`, and
24-
* The name of a function conforming to Julienne's `diagnosis_function_i` abstract interface.
25-
26-
The `diagnosis_function_i` function implementations have no arguments and construct a `test_diagnosis_t` result by
27-
28-
* Writing an expression in a Julienne idiom with defined operations (.e.g, `.all.(['a','b','c'] .isBefore. 'efg')`) or
13+
Testing with Julienne centers around the `test_t` abstract derived type. Users
14+
extend `test_t`, defining non-abstract child types capturing groups of tests.
15+
Doing so requires defining the inherited deferred bindings: the `subject` and
16+
`results` functions.
17+
18+
* `subject` has no arguments and defines a `character` string result describing
19+
what is being tested,
20+
* `results` has no arguments defines a `test_result_t` array result by invoking
21+
the inherited `run` function on a child instance, and
22+
* `run` uses its `test_description_t` array argument to construct a
23+
`test_result_t` array result.
24+
25+
Users construct each `test_description_t` array element by invoking a
26+
`test_description_t` constructor function, which has two arguments:
27+
28+
* A `character` string describing what the test does, typically beginning with a
29+
gerund: a word ending in `-ing`, and
30+
* The name of a function conforming to Julienne's `diagnosis_function_i`
31+
abstract interface.
32+
33+
The `diagnosis_function_i` function implementations have no arguments and
34+
construct a `test_diagnosis_t` result by
35+
36+
* Writing an expression in a Julienne idiom with defined operations (.e.g,
37+
`.all.(['a','b','c'] .isBefore. 'efg')`) or
2938
* Invoking the `test_diagnosis_t` constructor if no convenient idiom exists.
3039

3140
The `test_diagnosis_t` constructor has two arguments:
3241

3342
* `test_passed`: `logical` expression defining the test condition (.e.g, `
34-
* `diagnostics_string`: a `string_t` or `character`. Please see [Forming Diagnostics Strings] and [String-Handling Functions].
43+
* `diagnostics_string`: a `string_t` or `character`. Please see
44+
[Forming Diagnostics Strings] and [String-Handling Functions].
3545

36-
Please see the `test` subdirectory for code examples.
37-
Also, please see the following Unified Modeling Language ([UML]) class diagram for a summary of user-facing derived types, including type relationships and object constructors.
46+
47+
Please see the `test` subdirectory for code examples. Also, please see the
48+
following Unified Modeling Language ([UML]) class diagram for a summary of
49+
user-facing derived types, including type relationships and object constructors.
3850
Users invoke constructor functions via generic names matching the type of the constructed object result.
3951

4052
```mermaid
@@ -73,21 +85,23 @@ class string_t{
7385

7486
Running the demonstration tests
7587
-------------------------------
76-
With the Fortran Package Manager (`fpm`) installed, please set the `demo` subdirectory as your present working directory in a shell.
77-
Then run the demonstration test suite using the command below for your compiler.
88+
With the Fortran Package Manager (`fpm`) installed, please set the `demo`
89+
subdirectory as your present working directory in a shell. Then run the
90+
demonstration test suite using the command below for your compiler.
7891

7992
|Vendor | Version(s) Tested | Example shell command |
80-
|-------|-------------------------------------|--------------------------------------------------|
81-
|LLVM | 20.1.8, 21.1.0 | `fpm test --compiler flang-new --flag "-O3"` |
82-
|GCC | 13.4.0<sup>1</sup>, 14.3.0, 15.1.0 | `fpm test --compiler gfortran --profile release` |
83-
|NAG | 7.2 Build 7235 | `fpm test --compiler nagfor --flag "-O3 -fpp"` |
84-
|Intel | 2025.1.0 Build 20250728 | `fpm test --compiler ifx --flag "-fpp -O3"` |
93+
|-------|-------------------------|--------------------------------------------------|
94+
|LLVM | 20-21 | `fpm test --compiler flang-new --flag "-O3"` |
95+
|GCC | 13-15<sup>1</sup> | `fpm test --compiler gfortran --profile release` |
96+
|NAG | 7.2 Build 7235 | `fpm test --compiler nagfor --flag "-O3 -fpp"` |
97+
|Intel | 2025.2.1 Build 20250806 | `fpm test --compiler ifx --flag "-fpp -O3"` |
8598

8699
<sup>1</sup>With GCC 13, please append `--flag "-ffree-line-length-none"` to the listed `fpm test` command.
87100

88101
Generating test scaffolding
89102
---------------------------
90-
To recreate the `test` directory contents, pass the following `test-suite.json` file to Julienne's `scaffold` program:
103+
To recreate the `test` directory contents, pass the following `test-suite.json`
104+
file to Julienne's `scaffold` program:
91105
```
92106
{
93107
"test suite": {
@@ -96,17 +110,18 @@ To recreate the `test` directory contents, pass the following `test-suite.json`
96110
}
97111
```
98112
Please maintain the above format by not inserting, deleting, or combining any lines.
99-
Please run following command in a `bash` or `zsh` shell with Julienne's source-tree roottree as your present working directory:
113+
Please run following command in a `bash` or `zsh` shell with Julienne's root
114+
directory as your present working directory:
100115
```
101116
fpm run scaffold \
102117
--compiler flang-new \
103118
-- --json-file demo/test-suite.json \
104119
--suite-path demo/test
105120
```
106-
where a similar command works with the other supported compilers after changing
107-
the command-line arguments to mirror those used the source-tree root directory's
108-
[README.md](../README.md) file. The above `fpm` command generates the files in
109-
the `demo/test` subdirectory of the following `demo` source tree:
121+
where a similar command works with the other supported compilers after editing
122+
the `fpm` arguments to mirror those used in [Running the demonstration tests].
123+
The above `fpm` command generates the files in the `demo/test` subdirectory of
124+
the following `demo` source tree:
110125
```
111126
demo
112127
├── src
@@ -117,7 +132,8 @@ demo
117132
   ├── specimen_test_m.f90
118133
   └── widget_test_m.f90
119134
```
120-
The modules inside the `specimen_test_m.f90` and `widget_test_m.f90` files each contain three tests:
135+
The modules inside the `specimen_test_m.f90` and `widget_test_m.f90` files each
136+
contain three tests:
121137
1. One test intentionally fails and demonstrates the construction of a test
122138
diagnosis via an idiom using Julienne's defined operations:
123139
```
@@ -137,9 +153,10 @@ The modules inside the `specimen_test_m.f90` and `widget_test_m.f90` files each
137153
function in the corresponding test description, which is useful when a test
138154
is known to crash with a specific build configuration for example.
139155

140-
The driver program imports the `test_t` child types.
141-
The driver then constructs a `test_harness_t` object from an array of `test_fixture_t` objects.
142-
The driver constructs `test_fixture_t` objects from structure constructors provided by the language standard for each test type.
156+
The driver program imports the `test_t` child types. The driver then constructs
157+
a `test_harness_t` object from an array of `test_fixture_t` objects.
158+
The driver constructs `test_fixture_t` objects from structure constructors
159+
provided by the language standard for each test type.
143160

144161
Forming diagnostic strings
145162
--------------------------
@@ -181,8 +198,8 @@ To support a common array notation, Julienne also supports bracketing strings.
181198

182199
Diagnosis Functions
183200
-------------------
184-
The Unified Modeling Language ([UML]) class diagram below depicts some of the class
185-
relationships involved in making the above example work:
201+
The Unified Modeling Language ([UML]) class diagram below depicts some of the
202+
class relationships involved in making the above example work:
186203

187204
```mermaid
188205
%%{init: { 'theme':'default', "class" : {"hideEmptyMembersBox": true} } }%%
@@ -231,7 +248,7 @@ preprocessor macro:
231248
#endif
232249
```
233250
which presently appears in Julienne `test/string_test_m.f90` test in order to
234-
work around a runtime crash known to be caused by a `gfortran` bug.
251+
work around a runtime crash known to be caused by a `gfortran` 13 bug.
235252

236253
String-Handling Functions
237254
-------------------------
@@ -273,3 +290,4 @@ class string_t{
273290
[generating test scaffolding]: #generating-test-scaffolding
274291
[Forming Diagnostics Strings]: #forming-diagnostics-strings
275292
[String-Handling Functions]: #string-handling-functions
293+
[Running the demonstration tests]: #running-the-demonstration-tests

0 commit comments

Comments
 (0)