Finish conversion of testing to Julienne infrastructure

docs/README-maintainers.md

@@ -4,18 +4,28 @@ README-maintainers.md
 
 Conventions for Git and Pull Requests
 -------------
-This repository aims to maintain a mostly linear history. In order to achieve this, please
+
+This repository follows the [fork-and-pull](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model) model of development.
+If you would like to contribute some changes, please
+[fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks) this repository,
+push your proposed edits to a feature branch in your fork, and then
+[open a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests) against this repo when the changes are ready for review.
+
+
+This repository aims to maintain a strictly linear git history. In order to achieve this, please
 observe the following workflow:
-* Checkout a feature branch and open a PR when the changes are ready for review
-* After your PR has been approved, make sure to rebase your feature branch with `origin/main`.
+
+* After your PR has been approved, your feature branch will be rebased onto `origin/main` before merge.
 * In general you should try to avoid rebasing a non-draft PR with pending approvals until the
   last step before merge, because it complicates iterative review.
-* Only after your feature branch is up-to-date with `origin/main`, then you may merge the branch
+* Only after your feature branch is up-to-date with `origin/main` may it then be merged
   into `main` with a merge commit.
 
-Additional git policies:
-* Never force push to `main`
+Additional git policies for the primary Caffeine repository:
 
+* Never force push to `main`
+* All code changes and non-trivial documentation changes require a pull request
+* No stray branches, except for rare cases of long-lived parallel development
 
 Conventions for code and commits in Caffeine
 -------------
@@ -29,7 +39,7 @@ Conventions for code and commits in Caffeine
 * C functions and global variables lacking a `caf_` prefix must be `static`
 * Identifiers named `image` and `rank` refer to processes. Any identifier named `image` represents
   the process as 1-based number (Fortran-style), while `rank` represents the process as 0-based
-  number (C-style) (i.e. rank = image -1)
+  number (C-style) (i.e. rank == image - 1)
 * When writing or making changes to BIND(C) interfaces, be vigilant when checking that the types
   and attributes of the arguments and return values are equivalent across the Fortran and
   C declarations
@@ -41,4 +51,18 @@ Conventions for code and commits in Caffeine
 * Similarly if you need to move blocks of lines unchanged between distant locations or rename files,
   please also isolate those changes in a separate commit with a commit message 
   explaining the lack of meaningful change.
-* Tab characters should NOT be used in source code
+* Tab characters should NEVER appear in source code
+
+Conventions for test code
+-------------------------
+* All significant features should have non-trivial correctness tests in `test/`
+* Every PRIF procedure must be invoked by at least one test
+* Correctness tests should aim to achieve complete code coverage of internal paths,
+  and exercise any important corner-cases.
+* Test functions should return a Julienne `test_diagnosis_t` named `diag`
+  - If a complete diagnosis can be computed using a single Fortran expression `expr`,
+    then the statement `diag = expr` should appear near the end of the procedure.
+  - Otherwise, the statement `diag = .true.` must appear as the first executable
+    statement in the procedure, and the `ALSO/ALSO2` macros defined by 
+    [test-utils.F90](../test/test-utils.F90) should be invoked to build an incremental diagnosis.
+

install.sh

@@ -487,6 +487,8 @@ cat << EOF > $RUN_FPM_SH
 #!/bin/sh
 #-- DO NOT EDIT -- created by caffeine/install.sh
 fpm="${FPM}"
+FPM_DRIVER=\${FPM_DRIVER:-\`realpath \$0\`}
+export FPM_DRIVER
 fpm_sub_cmd=\$1; shift
 if echo "--help -help --version -version --list -list new update list clean publish" | grep -w -q -e "\$fpm_sub_cmd" ; then
   set -x

manifest/fpm.toml.template

@@ -7,9 +7,7 @@ copyright = "2021-2025 The Regents of the University of California, through Lawr
 
 [dev-dependencies]
 assert = {git = "https://github.com/berkeleylab/assert.git", tag = "3.0.0"}
-veggies = {git = "https://gitlab.com/everythingfunctional/veggies", tag = "v1.2.1"}
-iso_varying_string = {git = "https://gitlab.com/everythingfunctional/iso_varying_string.git", tag = "v3.0.4"}
-julienne = {git = "https://github.com/berkeleylab/julienne.git", tag = "3.3.0"}
+julienne = {git = "https://github.com/berkeleylab/julienne.git", tag = "3.5.0"}
 
 [install]
 library = true

src/caffeine/unit_test_parameters_m.F90

@@ -12,32 +12,57 @@ module unit_test_parameters_m
       ! used in stop/error-stop unit tests and example/test-support supporting programs
 
   character(len=:), allocatable :: subjob_prefix
+  character(len=:), allocatable :: fpm_driver
 
 contains
 
+  ! Retrieve an environment parameter or its default value
+  subroutine getenv_withdefault(key, default, result)
+    use iso_fortran_env, only: error_unit
+    character(len=*), intent(in) :: key, default
+    character(len=:), allocatable, intent(inout) :: result
+    character(len=:), allocatable :: suffix
+
+    character :: dummy
+    integer :: len
+
+    ! TODO: it would be preferable to consult the GASNet global environment, when available
+    call get_environment_variable(key, dummy, len)
+    if (len > 0) then
+      allocate(character(len=len)::result)
+      call get_environment_variable(key, result, len)
+      result = trim(adjustl(result))
+      suffix = ""
+    else 
+      result = default
+      suffix = " (default)"
+    endif
+
+    ! report the envvar in verbose mode
+    call get_environment_variable("GASNET_VERBOSEENV", dummy, len)
+    if (len > 0) then
+      write(error_unit, '(A, T64, A)') "ENV parameter: "//key//"='"//result//"'", suffix
+    end if
+  end subroutine
+
   ! subjob support used by stop/error-stop unit tests
   ! setup for subjob launch, initializes subjob_prefix and
   ! returns whether this is the first image
   function subjob_setup() result(result_)
-    character(len=*), parameter :: envvar = "SUBJOB_PREFIX"
     logical :: result_
-    integer :: me, len
-    character :: dummy
+    integer :: me
 
     if (.not. allocated(subjob_prefix)) then
-      call get_environment_variable(envvar, dummy, len)
-      if (len > 0) then
-        allocate(character(len=len+1)::subjob_prefix)
-        call get_environment_variable(envvar, subjob_prefix, len)
-      else 
-        subjob_prefix = ""
-      endif
-      !print *,"SUBJOB_PREFIX='"//subjob_prefix//"' len=",len
+      call getenv_withdefault("SUBJOB_PREFIX", "", subjob_prefix)
+      if (len(subjob_prefix) > 0) subjob_prefix = subjob_prefix//" "
+    end if
+    if (.not. allocated(fpm_driver)) then
+      call getenv_withdefault("FPM_DRIVER", "./build/run-fpm.sh", fpm_driver)
     end if
 
     call prif_sync_all()
     call prif_this_image_no_coarray(this_image=me)
-    result_ = (me == 1) .and. (subjob_prefix /= "skip")
+    result_ = (me == 1) .and. (trim(subjob_prefix) /= "skip")
   end function 
 
 

test/julienne-driver.F90

@@ -2,32 +2,67 @@
 ! Terms of use are as specified in LICENSE.txt
 
 program test_suite_driver
-  use julienne_m, only : test_fixture_t, test_harness_t
-  use prif_init_test_m, only : prif_init_test_t
-  use prif_coarray_inquiry_test_m, only :  prif_coarray_inquiry_test_t
+  use julienne_m, only : test_fixture_t, test_harness_t, test_diagnosis_t
+  use prif_init_test_m, only : prif_init_test_t, check_caffeination
+  use prif_num_images_test_m, only : prif_num_images_test_t
+  use prif_this_image_no_coarray_test_m, only : prif_this_image_no_coarray_test_t
+  use prif_image_queries_test_m, only : prif_image_queries_test_t
+  use prif_types_test_m, only : prif_types_test_t
   use prif_co_broadcast_test_m, only : prif_co_broadcast_test_t
+  use prif_co_sum_test_m, only : prif_co_sum_test_t
   use prif_co_max_test_m, only : prif_co_max_test_t
   use prif_co_min_test_m, only : prif_co_min_test_t
   use prif_co_reduce_test_m, only :prif_co_reduce_test_t 
-  use prif_co_sum_test_m, only : prif_co_sum_test_t
-  use prif_image_queries_test_m, only : prif_image_queries_test_t
-  use prif_num_images_test_m, only : prif_num_images_test_t
   use prif_sync_images_test_m, only : prif_sync_images_test_t
-  use prif_this_image_no_coarray_test_m, only : prif_this_image_no_coarray_test_t
+  use prif_image_index_test_m, only : prif_image_index_test_t
+  use prif_allocate_test_m, only : prif_allocate_test_t
+  use prif_coarray_inquiry_test_m, only :  prif_coarray_inquiry_test_t
+  use prif_teams_test_m, only : prif_teams_test_t 
+  use prif_rma_test_m, only : prif_rma_test_t   
+  use prif_strided_test_m, only : prif_strided_test_t
+  use prif_event_test_m, only : prif_event_test_t 
+  use prif_image_queries_test_m, only : prif_image_queries_test_t
+  use prif_atomic_test_m, only : prif_atomic_test_t
+  use prif_error_stop_test_m, only : prif_error_stop_test_t
+  use prif_stop_test_m, only : prif_stop_test_t  
   implicit none
 
+  type(test_diagnosis_t) :: dummy
+  dummy = check_caffeination() ! ensure an early call to prif_init
+
   associate(test_harness => test_harness_t([ &
-     test_fixture_t( prif_init_test_t() ) &  ! must come first
+    ! tests for basic functionality that are mostly self-contained
+     test_fixture_t( prif_init_test_t() ) &
     ,test_fixture_t( prif_num_images_test_t() ) &
     ,test_fixture_t( prif_this_image_no_coarray_test_t() ) &
     ,test_fixture_t( prif_image_queries_test_t() ) &
+    ,test_fixture_t( prif_types_test_t() ) &
+
+    ! collectives tests
     ,test_fixture_t( prif_co_broadcast_test_t() ) &
     ,test_fixture_t( prif_co_sum_test_t() ) &
     ,test_fixture_t( prif_co_max_test_t() ) &
     ,test_fixture_t( prif_co_min_test_t() ) &
     ,test_fixture_t( prif_co_reduce_test_t() ) &
+
+    ! tests that rely primarily upon coarrays
+    ,test_fixture_t( prif_allocate_test_t() ) & ! should be first coarray test
     ,test_fixture_t( prif_coarray_inquiry_test_t() ) &
-    ,test_fixture_t( prif_sync_images_test_t() ) &
+    ,test_fixture_t( prif_image_index_test_t() ) &
+    ,test_fixture_t( prif_rma_test_t() ) &
+    ,test_fixture_t( prif_strided_test_t() ) &
+
+    ! synchronization and data race tests
+    ,test_fixture_t( prif_event_test_t() ) &
+    ,test_fixture_t( prif_atomic_test_t() ) &
+    ,test_fixture_t( prif_sync_images_test_t() ) & ! internally uses coarrays and events
+
+    ! complicated multi-feature tests
+    ,test_fixture_t( prif_teams_test_t() ) &
+
+    ! exit tests
+    ,test_fixture_t( prif_error_stop_test_t() ) &
+    ,test_fixture_t( prif_stop_test_t() ) &
   ]))
     call test_harness%report_results
   end associate