doc(README): reorg, update commands, add lfortran

Author: rouson

README.md

@@ -58,27 +58,49 @@ The requirements and assurances might be constraints of three kinds:
 
 The [example/README.md] file shows examples of writing constraints in notes on class diagrams using the formal syntax of the Object Constraint Language ([OCL]).
 
-Downloading, Building, and Running Examples
--------------------------------------------
+Running the Examples
+--------------------
+See the [./example](./example) subdirectory.
+
+Building and Testing
+--------------------
+
+- [Cray Compiler Environment (CCE) `ftn`](#cray-compiler-environment-cce-ftn)
+- [GNU Compiler Collection (GCC) `gfortran`](#gnu-compiler-collection-gcc-gfortran))
+- [Intel `ifx`](#intel-ifx))
+- [LFortran `lfortran`](#lfortran-lfortran)
+- [LLVM `flang-new`](#llvm-flang-new)
+- [Numerical Algorithms Group (NAG) `nagfor`](#numerical-algorithms-group-nag-nagfor)
+
+### Cray Compiler Environment (CCE) `ftn`
+Because `fpm` uses the compiler name to determine the compiler identity and because
+CCE provides one compiler wrapper, `ftn`, for invoking all compilers, you will
+need to invoke `ftn` in a shell script named to identify CCE compiler. For example,
+place a script named `crayftn.sh` in your path with the following contents and with
+executable privileges set appropriately:
+```
+#!/bin/bash
 
-### Downloading Assert
+ftn $@
+```
+Then build and test Assert with the command
 ```
-git clone git@github.com:berkeleylab/assert
-cd assert
+fpm test --compiler crayftn.sh --profile release
 ```
 
-### Building and testing with `gfortran`
+### GNU Compiler Collection (GCC) `gfortran`
+
 #### Single-image (serial) execution
-The command below builds Assert and runs the full test suite in a single image.
-For `gfortran` 14 or later, use
+With `gfortran` 14 or later, use
 ```
 fpm test --profile release
 ```
-For `gfortran` 13 or earlier, use
+With `gfortran` 13 or earlier, use
 ```
 fpm test --profile release --flag "-ffree-line-length-0"
 ```
 The above commands build the Assert library (with the default of assertion enforcement disabled) and runs the test suite.
+
 #### Multi-image (parallel) execution
 With `gfortran` 14 or later versions and OpenCoarrays installed, use
 ```
@@ -88,60 +110,65 @@ With `gfortran` 13 or earlier versions and OpenCoarrays installed,
 ```
 fpm test --compiler caf --profile release --runner "cafrun -n 2" --flag "-ffree-line-length-0"
 ```
-To build and test with the Numerical Algorithms Group (NAG) Fortran compiler version
-7.1 or later, use
-```
-fpm test --compiler=nagfor --profile release --flag "-coarray=cosmp -fpp -f2018"
-```
 
-### Building and testing with the Intel `ifx` compiler
+### Intel `ifx`
+
 #### Single-image (serial) execution
 ```
 fpm test --compiler ifx --profile release 
 ```
+
 #### Multi-image (parallel) execution 
 With Intel Fortran and Intel MPI installed,
 ```
 fpm test --compiler ifx --profile release --flag "-coarray -DASSERT_MULTI_IMAGE"
 ```
 
-### Building and testing with the LLVM `flang-new` compiler
-#### LLVM version 19
+### LLVM `flang-new`
+
+#### Single-image (serial) execution
+With `flang-new` version 19, use
 ```
 fpm test --compiler flang-new --flag "-mmlir -allow-assumed-rank -O3"
 ```
-#### LLVM version 20 or later
+With `flang-new` version 20 or later, use
 ```
 fpm test --compiler flang-new --flag "-O3"
 ```
 
-### Building and testing with the Numerical Algorithms Group (NAG) compiler
+#### Multi-image (parallel) execution
+With `flang-new` version 21 built from the SiPearl llvm-project fork's 
+[prif branch](https://github.com/SiPearl/llvm-project/tree/prif), use
 ```
-fpm test --compiler nagfor --profile release --flag "-fpp -coarray=cosmp"
+fpm test --compiler -caffeine -L<path-to-libcaffeine> -l<gasnet-conduit> -L<path-to-libgasnet>
 ```
+where, for example, `<gasnet-conduit>` might be `gasnet-smp-seq` for
+shared-memory execution.
 
-### Building and testing with the Cray Compiler Environment (CCE)
-Because `fpm` uses the compiler name to determine the compiler identity and because
-CCE provides one compiler wrapper, `ftn`, for invoking all compilers, you will
-need to invoke `ftn` in a shell script named to identify CCE compiler. For example,
-place a script named `crayftn.sh` in your path with the following contents and with
-executable privileges set appropriately:
-```
-#!/bin/bash
+### LFortran `lfortran`
 
-ftn $@
-```
-Then build and test Assert with the command
+#### Single-image (serial) execution
 ```
-fpm test --compiler crayftn.sh --profile release
+fpm test --compiler lfortran --profile release --flag --cpp
 ```
 
+### Numerical Algorithms Group (NAG) `nagfor`
 
-### Building and testing with other compilers
-To use Assert with other compilers, please submit an issue or pull request.  
+#### Single-image (serial) execution
+With `nagfor` version 7.1 or later, use
+```
+fpm test --compiler nagfor --profile release --flag -fpp
+```
 
-### Running the examples
-See the [./example](./example) subdirectory.
+#### Multi-image execution
+With `nagfor` 7.1, use
+```
+fpm test --compiler nagfor --profile release --flag "-fpp -coarray=cosmp -f2018"
+```
+With `nagfor` 7.2 or later, use
+```
+fpm test --compiler nagfor --profile release --flag -fpp
+```
 
 Documentation
 -------------