Update cuda build instructions (#1043)

.github/pull_request_template.md

@@ -20,4 +20,4 @@ If you're a core developer, add one of each label:
 - Change type: {bug, documentation, enhancement, minor}
 - Category: {app, core, external, field, orange, performance, physics, user}
 
-See [https://github.com/celeritas-project/celeritas/blob/develop/doc/appendices/administration.rst#review-process](review process) for descriptions of the labels and requirements.
+See [review process](https://github.com/celeritas-project/celeritas/blob/develop/doc/appendix/administration.rst#code-review) for descriptions of the labels and requirements.

README.md

@@ -35,7 +35,7 @@ Then see the "Downstream usage as a library" section of the [installation
 documentation][install] for how to use Celeritas in your application or framework.
 
 [spack-start]: https://spack.readthedocs.io/en/latest/getting_started.html
-[install]: doc/installation.rst
+[install]: doc/main/installation.rst
 
 # Installation for developers
 
@@ -52,10 +52,10 @@ directory:
 ```console
 # Set up CUDA (optional)
 $ spack external find cuda
-$ spack config add packages:all:variants:"+cuda cuda_arch=70"
 # Install celeritas dependencies
 $ spack env create celeritas scripts/spack.yaml
 $ spack env activate celeritas
+$ spack config add packages:all:variants:"cxxstd=17 +cuda cuda_arch=70"
 $ spack install
 # Configure, build, and test
 $ ./build.sh base
@@ -71,24 +71,30 @@ $ make && ctest
 ```
 
 Celeritas guarantees full compatibility and correctness only on the
-combinations of compilers and dependencies tested under continuous integration.
-Currently supported compilers are GCC 11.2 + NVCC 11.8, and HIP-Clang 15.0, but
-since we compile with extra warning flags and avoid non-portable code, most
+combinations of compilers and dependencies tested under continuous integration:
+- Compilers:
+    - GCC 8.4, 12.3
+    - GCC 11.3 + NVCC 11.8
+    - HIP-Clang 10.0, 15.0
+- Dependencies:
+    - Geant4 11.0.3
+    - VecGeom 1.2.5
+
+Since we compile with extra warning flags and avoid non-portable code, most
 other compilers *should* work.
-Currently Geant4 11.0 and VecGeom 1.2 are the only versions that are guaranteed
-to work, but older versions might be OK.
-The full set of configurations is viewable on [the CI web site][jenkins].
+The full set of configurations is viewable on CI platforms ([Jenkins][jenkins] and [GitHub Actions][gha]).
 Compatibility fixes that do not cause newer versions to fail are welcome.
 
 [spack]: https://github.com/spack/spack
-[install]: doc/installation.rst
-[jenkins]: https://cloud.cees.ornl.gov/jenkins-ci/blue/organizations/jenkins/Celeritas/activity?branch=master
+[install]: doc/main/installation.rst
+[jenkins]: https://cloud.cees.ornl.gov/jenkins-ci/job/celeritas/job/develop
+[gha]: https://github.com/celeritas-project/celeritas/actions
 
 # Development
 
 See the [contribution guide](CONTRIBUTING.rst) for the contribution process,
-[the development guidelines](doc/appendices/development.rst) for further
-details on coding in Celeritas, and [the administration guidelines](doc/appendices/administration.rst) for community standards and roles.
+[the development guidelines](doc/appendix/development.rst) for further
+details on coding in Celeritas, and [the administration guidelines](doc/appendix/administration.rst) for community standards and roles.
 
 # Citing Celeritas
 

doc/main/installation.rst

@@ -97,13 +97,14 @@ dependencies:
 - Clone and load Spack following its `getting started instructions
   <https://spack.readthedocs.io/en/latest/getting_started.html>`_.
 - If using CUDA: run ``spack external find cuda`` to inform Spack of the existing
-  installation, and tell Spack to default to building with CUDA support with
-  the command ``spack config add packages:all:variants:"+cuda
+  installation
+- Create the Celeritas development environment with ``spack env create
+  celeritas scripts/spack.yaml``.
+- Tell Spack to default to building with CUDA support with
+  the command ``spack -e celeritas config add packages:all:variants:"cxxstd=17 +cuda
   cuda_arch=<ARCH>"``, where ``<ARCH>`` is the numeric portion of the
   `CUDA architecture flags
   <https://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/>`_.
-- Create the Celeritas development environment with ``spack env create
-  celeritas scripts/spack.yaml``.
 - Install all the dependencies with ``spack -e celeritas install``.
 
 The current Spack environment for full-featured development is:

scripts/spack.yaml

@@ -17,7 +17,7 @@ spack:
     - py-sphinxcontrib-bibtex
     - "root@6.24: cxxstd=17"
     - "swig@4.1:"
-    - "vecgeom@1.2.3: +gdml cxxstd=17"
+    - "vecgeom@1.2.4: +gdml cxxstd=17"
   view: true
   concretizer:
     unify: true
@@ -30,6 +30,6 @@ spack:
         blas: [openblas]
         lapack: [openblas]
         mpi: [openmpi]
-      variants: cxxstd=17
-      # NOTE: add `+cuda cuda_arch=70` (or similar) to your site packages.py
-      # spack config add --scope=site packages:all:variants:"+cuda cuda_arch=70"
+      # Uncomment to enable cuda build or run within the spack env:
+      # spack config add packages:all:variants:"cxxstd=17 +cuda cuda_arch=<ARCH>"
+      variants: cxxstd=17 # +cuda cuda_arch=<ARCH>