Skip to content

Commit 9548da3

Browse files
rousonbonachea
authored andcommitted
doc(README): desc use in pure procs, ref Julienne
other minor edits
1 parent aa8dbf2 commit 9548da3

File tree

1 file changed

+27
-9
lines changed

1 file changed

+27
-9
lines changed

README.md

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ When the `ASSERTIONS` preprocessor macro is not defined to any value,
3030
the default is that assertions are *disabled* and will not check the condition.
3131

3232
To enable assertion enforcement (e.g., for a debug build), define the
33-
preprocessor ASSERTIONS to non-zero, eg:
33+
preprocessor ASSERTIONS to non-zero, e.g.,
3434
```
3535
fpm build --flag "-DASSERTIONS"
3636
```
@@ -45,10 +45,27 @@ Use Cases
4545
---------
4646
Two common use cases include
4747

48-
1. [Enforcing programming contracts] throughout a project via runtime checks.
49-
2. Producing output in `pure` procedures for debugging purposes.
48+
1. [Producing output in pure procedures] for debugging purposes.
49+
2. [Enforcing programming contracts] throughout a project via runtime checks.
5050

51-
### Enforcing programming contracts
51+
### Producing output in pure procedures
52+
Writing pure procedures communicates useful information to a compiler or a developer.
53+
Specifically, the pure attribute conveys compliance with several constraints that clarify data dependencies and preclude side effects.
54+
For a compiler, these constraints support optimizations, including automatic parallelization on a central processing unit (CPU) or offloading to a graphics processing unit (GPU).
55+
For a developer, the constraints support refactoring tasks such as code movement.
56+
57+
A developer seeking output inside a procedure presumably has an expectation regarding what ranges of output values represent correct program execution.
58+
A developer can state such expectations in an assertion such as `call_assert(i>0 .and. j<0)`.
59+
Enforce the assertion by defining the `ASSERTIONS` macro when compiling.
60+
If the expectation is not met, the program error terminates and prints a stop code showing the assertion's file and line location and a description.
61+
By default, the description is the literal text of what was asserted: `i>0 .and. j<0` in the aforementioned example.
62+
Alternatively, the user can provide a custom description.
63+
64+
For richer diagnostic messages from failed assertions, please see the [Julienne] correctness-checking framework.
65+
Julienne wraps Assert and defines idioms that automatically generate diagnostic messages containing program data.
66+
Julienne also offers string-handling utilities to assist users with customizing diagnostic messages by, for example, converting an array of numeric type into string representing comma-separated values as text.
67+
68+
## Enforcing programming contracts
5269
Programming can be thought of as requirements for correct execution of a procedure and assurances for the result of correct execution.
5370
The requirements and assurances might be constraints of three kinds:
5471

@@ -193,17 +210,17 @@ limit. This can result in compile-time errors like the following from gfortran:
193210
Error: Line truncated at (1) [-Werror=line-truncation]
194211
```
195212

196-
Some compilers offer a command-line argument that can be used to workaround this legacy limit, eg:
213+
Some compilers offer a command-line argument that can be used to workaround this legacy limit, e.g.,
197214

198-
* `gfortran -ffree-line-length-0` aka `gfortran -ffree-line-length-none`
215+
* `gfortran -ffree-line-length-0` or equivalently `gfortran -ffree-line-length-none`
199216

200-
When using `fpm`, one can pass such a flag to the compiler using the `fpm --flag` option, eg:
217+
When using `fpm`, one can pass such a flag to the compiler using the `fpm --flag` option, e.g.,
201218

202219
```shell
203220
$ fpm test --profile release --flag -ffree-line-length-0
204221
```
205222

206-
Thankfully Fortran 2023 raised this obscolecent line limit to 10,000
223+
Thankfully, Fortran 2023 raised this obsolescent line limit to 10,000
207224
characters, so by using newer compilers you might never encounter this problem.
208225
In the case of gfortran, this appears to have been resolved by default starting in release 14.1.0.
209226

@@ -283,7 +300,8 @@ See the [LICENSE](LICENSE) file for copyright and licensing information.
283300
[Single-image execution]: #single-image-execution
284301
[example/README.md]: ./example/README.md
285302
[tests]: ./tests
286-
[src]: ./src
287303
[Fortran Package Manager]: https://github.com/fortran-lang/fpm
288304
[OCL]: https://en.wikipedia.org/wiki/Object_Constraint_Language
289305
[example/invoke-via-macro.F90]: ./example/invoke-via-macro.F90
306+
[Producing output in pure procedures]: #producing-output-in-pure-procedures
307+
[Julienne]: https://go.lbl.gov/julienne

0 commit comments

Comments
 (0)