Install.sh overhaul

.github/workflows/build.yml

@@ -181,6 +181,20 @@ jobs:
             version: 0.63
             container: phhargrove/lfortran:0.63.0-1
 
+        # --- OPT coverage ---
+          - os: ubuntu-24.04
+            compiler: flang
+            version: 23
+            label: OPT
+            CONFIGURE_ARGS: --disable-debug
+            container: phhargrove/llvm-flang:23.1.0-latest
+          - os: ubuntu-22.04
+            compiler: lfortran
+            version: 0.65
+            label: OPT
+            CONFIGURE_ARGS: --disable-debug
+            container: ghcr.io/lfortran/lfortran:v0.65.0
+
         # --- PRIF-old coverage ---
           - os: ubuntu-24.04
             compiler: flang
@@ -236,6 +250,8 @@ jobs:
           - os: macos-15
             compiler: flang
             network: udp
+            label: FPM-0.10
+            FPM_VERSION: 0.10.0
           - os: macos-26
             compiler: flang
             network: udp
@@ -265,6 +281,8 @@ jobs:
             version: 23
             network: udp
             container: phhargrove/llvm-flang:23.1.0-latest
+            label: FPM-0.10
+            FPM_VERSION: 0.10.0
           - os: ubuntu-24.04
             compiler: flang
             version: latest
@@ -280,10 +298,10 @@ jobs:
       COMPILER_VERSION: ${{ matrix.version || needs.setup.outputs.BREW_FLANG_VERSION }}
       FFLAGS: ${{ matrix.FFLAGS }} ${{ inputs.fflags }}
       CFLAGS: ${{ matrix.CFLAGS }} ${{ inputs.cflags }}
-      PREFIX: install
+      FPM_VERSION: ${{ matrix.FPM_VERSION || '0.13.0' }}
       NETWORK_ARG: ${{ matrix.network && format('--network={0}',matrix.network) || '' }}
       CURL_OPTIONS: -L --retry 10 --retry-all-errors --fail 
-      GASNET_CONFIGURE_ARGS: --enable-rpath --enable-debug
+      CONFIGURE_ARGS: --prefix=install --enable-rpath --enable-debug --verbose ${{ matrix.CONFIGURE_ARGS }}
       GASNET_SPAWN_VERBOSE: 1
       GASNET_SPAWNFN: L
       GASNET_MASTERIP: 127.0.0.1
@@ -389,17 +407,25 @@ jobs:
         # Prepend Macports clang to PATH:
         echo "PATH=/opt/local/bin:${PATH}" >> "$GITHUB_ENV"
 
+    - name: Choose FPM
+      if: ${{ !matrix.brew_via_install }}
+      run: |
+        if [[ ${{ runner.arch == 'ARM64' && (runner.os == 'Linux' || env.FPM_VERSION < '0.13.0') }} == true ]] ; then
+          echo "FPM_BUILD=true" >> "$GITHUB_ENV"
+        else
+          echo "FPM_SETUP=true" >> "$GITHUB_ENV"
+        fi
+
     - name: Setup FPM
-      if: ${{ !matrix.brew_via_install && !(runner.os == 'Linux' && runner.arch == 'ARM64') }}
+      if: env.FPM_SETUP
       uses: fortran-lang/setup-fpm@main
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
-        fpm-version: latest
+        fpm-version: v${{ env.FPM_VERSION }}
 
     - name: Build FPM
-      if: ${{ !matrix.brew_via_install && runner.os == 'Linux' && runner.arch == 'ARM64' }}
+      if: env.FPM_BUILD
       run: |
-        export FPM_VERSION=0.13.0
         curl --retry 5 -LOsS https://github.com/fortran-lang/fpm/releases/download/v$FPM_VERSION/fpm-$FPM_VERSION.F90
         mkdir fpm-temp
         gfortran-14 -o fpm-temp/fpm fpm-$FPM_VERSION.F90
@@ -416,14 +442,18 @@ jobs:
         echo "CXX=g++-${COMPILER_VERSION}" >> "$GITHUB_ENV"
         # XCode 26 / gfortran bug workaround
         if [[ ${{ matrix.os }} =~ macos-26 ]] ; then
-          echo "GASNET_CONFIGURE_ARGS=$GASNET_CONFIGURE_ARGS --enable-force-posix-realtime" >> "$GITHUB_ENV"
+          echo "CONFIGURE_ARGS=$CONFIGURE_ARGS --enable-force-posix-realtime" >> "$GITHUB_ENV"
         fi
 
     - name: Set flang variables
       if: ${{ matrix.compiler == 'flang' }}
       run: |
         if [ -z "${{ matrix.brew_via_install }}" ] ; then
-          echo "FC=flang-new" >> "$GITHUB_ENV" 
+          if [[ $COMPILER_VERSION -le 19 ]] ; then
+            echo "FC=flang-new" >> "$GITHUB_ENV"
+          else
+            echo "FC=flang" >> "$GITHUB_ENV"
+          fi
           echo "CC=clang" >> "$GITHUB_ENV"
           echo "CXX=clang++" >> "$GITHUB_ENV"
         fi
@@ -498,11 +528,18 @@ jobs:
           find $RDIR $BDIR /usr/lib/ -name '*flang_rt*' -exec ls -al {} \; | sort | uniq
         fi
 
+    - name: Test install.sh outputs
+      run: |
+        ./install.sh --help 2>&1 | tee output
+          test ${PIPESTATUS[0]} = 0 && grep -q "fortran@lbl.gov" output
+        ./install.sh --prereqs 2>&1 | tee output
+          test ${PIPESTATUS[0]} = 0 && grep -q "GASNet-EX" output
+
     - name: Build Caffeine (install.sh)
       run: |
         for var in FC CC CXX FFLAGS CPPFLAGS CFLAGS CXXFLAGS LDFLAGS LIBS GASNET_CONFIGURE_ARGS ; do
             eval echo "$var=\$$var"; done
-        ./install.sh --prefix=${PREFIX} ${NETWORK_ARG} --verbose \
+        ./install.sh ${CONFIGURE_ARGS} ${NETWORK_ARG} \
                      ${{ inputs.install_args }} ${{ matrix.install_filter }}
         if ! grep -q 'NATIVEFLAGS=""' run-fpm.sh ; then
           echo "NATIVE_MULTI_IMAGE=true" >> "$GITHUB_ENV"
@@ -514,6 +551,8 @@ jobs:
     - name: Version info (run-fpm)
       run: |
         ./run-fpm.sh info
+        ./install/bin/ident ./install/lib/libcaffeine.a | tee output
+          test ${PIPESTATUS[0]} = 0 && grep -q "CaffeineAssertions" output
 
     - name: Run examples
       run: |
@@ -586,7 +625,7 @@ jobs:
       run: |
         for var in FC CC CXX FFLAGS CPPFLAGS CFLAGS LDFLAGS LIBS GASNET_CONFIGURE_ARGS ; do
             eval echo "$var=\$$var"; done
-        ./install.sh --prefix=${PREFIX} ${NETWORK_ARG} --enable-threads --verbose \
+        ./install.sh ${CONFIGURE_ARGS} ${NETWORK_ARG} --enable-threads \
                      ${{ inputs.install_args }} ${{ matrix.install_filter }}
         ./run-fpm.sh test --verbose -- ${{ inputs.julienne_args }}
 

README.md

@@ -48,29 +48,34 @@ their solution to support Fortran's multi-image parallel features.
 
 Prerequisites & Dependencies
 -------------
+Caffeine supports recent versions of Linux and macOS, running on x86\_64 (amd64) or ARM64 (aarch64) architectures.
+Other architectures and POSIX-like environments may also work, but are not regularly tested.
+
 ### Build prerequisites
-The `install.sh` script uses the following packages:
-* Fortran and C compilers
-    * We regularly test with: LLVM Flang versions 19:22 and GNU Fortran versions 13:15
-* [Fortran package manager] `fpm`
-* [pkg-config]
-* [realpath]
-* [make]
-* [git]
-* [curl]
-
-The script will invoke these if present in a user's `PATH`.
-If not present, the script will ask permission to use [Homebrew] to install the relevant package
+
+The `install.sh` script uses the following packages to build Caffeine:
+* Fortran and C compilers. We [regularly test](https://github.com/BerkeleyLab/caffeine/actions?query=branch%3Amain) with:
+   - LLVM Flang versions 19:23,
+   - GNU Fortran versions 13:16, and
+   - LFortran versions 0.64:
+* [`fpm`](https://github.com/fortran-lang/fpm), the Fortran package manager
+* [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
+* [GNU make](https://www.gnu.org/software/make/)
+* [git](https://git-scm.com)
+* [curl](https://curl.se)
+
+The `install.sh` script will invoke these if found in the user's `PATH`.
+If not present, the script will ask permission to use [Homebrew](https://brew.sh) to install the relevant package
 or, in some cases, ask the user to install the package.
 
 ### Build dependencies
 
 Caffeine also depends on the following packages that will be automatically installed as part
 of the build process.
 
-* [GASNet-EX] exascale networking middleware
-* [assert](https://go.lbl.gov/assert)
-* [julienne](https://go.lbl.gov/julienne)
+* [GASNet-EX] : exascale networking middleware, providing communication services
+* [assert](https://go.lbl.gov/assert) : Fortran assertion package, enforces invariants in debug mode
+* [julienne](https://go.lbl.gov/julienne) : Fortran test infrastructure (only for unit tests)
 
 Caffeine leverages the following non-parallel features of Fortran to simplify the writing of a portable, compact runtime-library that supports Fortran's parallel features:
 
@@ -131,6 +136,16 @@ written in Fortran, simulating the PRIF calls that a theoretical
 source-to-source Fortran compiler might generate for a simple program written
 using Fortran's multi-image features to print a message from each image.
 
+Caffeine also includes a broad "smoke test" of multi-image Fortran features.
+When Caffeine was installed using a PRIF-compatible Fortran compiler (currently
+LLVM Flang 22+ or LFortran 0.64+) the following command will invoke this smoke
+test:
+```bash
+env CAF_IMAGES=8 ./run-fpm.sh run
+```
+This will exercise the available PRIF feature set of the compiler version
+detected at install time.
+
 Run tests
 ---------
 
@@ -168,6 +183,21 @@ Here are *a few* of the most useful GASNet knobs:
 
 See [GASNet documentation](https://gasnet.lbl.gov/dist-ex/README) for full details on all settings.
 
+Troubleshooting
+---------------
+
+The Caffeine `./install.sh` script defaults to building the library in an optimized production mode,
+which is generally suitable for end users and should be preferred for any performance-oriented runs.
+
+If you're developing compiler transformations targeting PRIF, or if you encounter a correctness 
+problem at runtime, then its **highly** recommended to instead build Caffeine in debug mode:
+```
+./install.sh --enable-debug
+```
+The `--enable-debug` flag disables compiler optimization and enables thousands
+of correctness checks system-wide. This includes sanity checking of PRIF subroutine
+arguments, and often provides an automated diagnosis that can pinpoint the problem.
+
 PRIF Implementation Status
 --------------------------
 
@@ -228,10 +258,3 @@ See [LICENSE.txt](LICENSE.txt) for usage terms and conditions.
 [CLaSS]: https://go.lbl.gov/class
 [Berkeley Lab]: https://lbl.gov
 [MPI]: https://www.mpi-forum.org
-[Homebrew]: https://brew.sh
-[Fortran package manager]: https://github.com/fortran-lang/fpm
-[pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/
-[realpath]: https://man7.org/linux/man-pages/man3/realpath.3.html
-[make]: https://www.gnu.org/software/make/
-[git]: https://git-scm.com
-[curl]: https://curl.se