Land the build/CI overhaul's shared workflows and actions

.github/actions/cmake_build/action.yml

@@ -0,0 +1,139 @@
+# Copyright 2025 NWChemEx-Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: CMake Build
+description: >-
+  Configure, build, and optionally test a repository with CMake using a
+  native (apt/Homebrew) compiler toolchain on Linux or macOS. The calling
+  job must provide python/pip on PATH (e.g. via actions/setup-python) for
+  the Python test step.
+
+inputs:
+  compiler:
+    description: "One of: gcc-14, clang-18. Installed via the native package manager (apt on Linux, Homebrew on macOS)."
+    required: true
+  run_cmake_tests:
+    description: "Whether to build and run the CTest (C++) test suite (sets -DBUILD_TESTING)."
+    required: false
+    default: "true"
+  run_python_tests:
+    description: "Whether to run the pytest (Python) test suite against the built pybind11 module."
+    required: false
+    default: "true"
+  cmake_opts:
+    description: "Additional CMake options to pass at configure time."
+    required: false
+    default: ""
+  extra_pip_packages:
+    description: "Extra packages to pip install into the ambient Python before the C++ test step (e.g. CTest-driven Python tests that import a pip-installed package)."
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Setup NWX Dev Environment
+      uses: NWChemEx/.github/.github/actions/setup_nwx_dev_env@master
+      with:
+        compiler: ${{ inputs.compiler }}
+
+    # Some repos' CMake build invokes a Python codegen script at configure or
+    # build time (e.g. GauXC's gau2grid dependency imports numpy to generate
+    # C source), so this needs to run before Configure/Build below, not only
+    # before the Python test step later in this same file.
+    - name: Install Python Requirements
+      shell: bash
+      run: |
+        if [ -f requirements.txt ]; then
+          pip install --quiet -r requirements.txt
+        fi
+
+    - name: Cache Dependency Build Tree
+      uses: actions/cache@v4
+      with:
+        path: build/_deps
+        key: deps-${{ runner.os }}-${{ inputs.compiler }}-${{ github.run_id }}
+        restore-keys: |
+          deps-${{ runner.os }}-${{ inputs.compiler }}-
+
+    - name: Configure
+      shell: bash
+      run: |
+        build_testing=${{ inputs.run_cmake_tests == 'true' && 'ON' || 'OFF' }}
+
+        # Pin CMake's FindPython to the interpreter actions/setup-python put on
+        # PATH (and that "Install Python Requirements" above just installed
+        # into). Without this, CMake's own search can prefer a different
+        # ambient interpreter (e.g. a macOS Homebrew framework Python),
+        # leaving configure-time-installed packages invisible to build-time
+        # codegen scripts that embed a Python interpreter.
+        cmake -Bbuild -H. -GNinja \
+          -DCMAKE_INSTALL_PREFIX=./install \
+          -DCMAKE_C_COMPILER="${CC}" \
+          -DCMAKE_CXX_COMPILER="${CXX}" \
+          -DBUILD_TESTING="${build_testing}" \
+          -DPython_EXECUTABLE="$(command -v python3)" \
+          ${{ inputs.cmake_opts }}
+
+    - name: Build
+      shell: bash
+      run: cmake --build build --parallel
+
+    - name: Install Extra Pip Packages
+      if: inputs.extra_pip_packages != ''
+      shell: bash
+      # Runs before "Test C++" because CTest-driven Python tests use the
+      # ambient Python_EXECUTABLE, whose sys.path always includes
+      # site-packages regardless of CTest's PYTHONPATH override -- so any
+      # package such a test imports needs to be pip-installed here.
+      run: pip install --quiet ${{ inputs.extra_pip_packages }}
+
+    - name: Test C++
+      if: inputs.run_cmake_tests == 'true'
+      shell: bash
+      working-directory: build
+      # Some C++ tests embed a Python interpreter that imports this repo's
+      # own (and its dependencies') built pybind11 modules -- same PYTHONPATH
+      # need as the pytest step below, just computed relative to build/.
+      run: |
+        total_tests=$(ctest -N | grep "Total Tests:" | grep -oE "[0-9]+$")
+        if [ "${total_tests:-0}" -eq 0 ]; then
+            echo "::error::run_cmake_tests is true but zero CTest tests were found."
+            exit 1
+        fi
+        pythonpath=$(find . -name "*.so" -exec dirname {} \; | sort -u | paste -sd: -)
+        PYTHONPATH="$pythonpath" ctest -VV
+
+    - name: Test Python
+      if: inputs.run_python_tests == 'true'
+      shell: bash
+      run: |
+        pip install --quiet pytest
+
+        pythonpath=$(find build -name "*.so" -exec dirname {} \; | sort -u | paste -sd: -)
+        if [ -z "$pythonpath" ]; then
+            echo "::error::run_python_tests is true but no built Python module (*.so) was found under build/."
+            exit 1
+        fi
+
+        set +e
+        PYTHONPATH="$pythonpath" pytest -v
+        pytest_exit=$?
+        set -e
+
+        if [ "$pytest_exit" -eq 5 ]; then
+            echo "::error::run_python_tests is true but zero pytest tests were found."
+            exit 1
+        fi
+        exit "$pytest_exit"

.github/actions/pip_build/action.yml

@@ -0,0 +1,98 @@
+# Copyright 2025 NWChemEx-Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Pip Build
+description: >-
+  Build and optionally test a repository's Python package with pip, using a
+  native (apt/Homebrew) compiler toolchain on Linux or macOS. The calling
+  job must provide python/pip on PATH (e.g. via actions/setup-python).
+
+inputs:
+  compiler:
+    description: "One of: gcc-14, clang-18. Installed via the native package manager (apt on Linux, Homebrew on macOS)."
+    required: true
+  run_cmake_tests:
+    description: "Whether to build and run the CTest (C++) test suite (sets -DBUILD_TESTING)."
+    required: false
+    default: "true"
+  run_python_tests:
+    description: "Whether to install the package editable with its dev extras and run the pytest (Python) test suite."
+    required: false
+    default: "true"
+  pip_opts:
+    description: "Additional options to pass to pip install."
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Setup NWX Dev Environment
+      uses: NWChemEx/.github/.github/actions/setup_nwx_dev_env@master
+      with:
+        compiler: ${{ inputs.compiler }}
+
+    - name: Cache Dependency Build Tree
+      uses: actions/cache@v4
+      with:
+        path: build/_deps
+        key: deps-${{ runner.os }}-${{ inputs.compiler }}-${{ github.run_id }}
+        restore-keys: |
+          deps-${{ runner.os }}-${{ inputs.compiler }}-
+
+    - name: Install
+      shell: bash
+      run: |
+        build_testing=${{ inputs.run_cmake_tests == 'true' && 'ON' || 'OFF' }}
+
+        if [ "${{ inputs.run_python_tests }}" == "true" ]; then
+            pip install -e ".[dev]" \
+              --config-settings=cmake.define.CMAKE_C_COMPILER="${CC}" \
+              --config-settings=cmake.define.CMAKE_CXX_COMPILER="${CXX}" \
+              --config-settings=cmake.define.BUILD_TESTING="${build_testing}" \
+              ${{ inputs.pip_opts }}
+        else
+            pip install . \
+              --config-settings=cmake.define.CMAKE_C_COMPILER="${CC}" \
+              --config-settings=cmake.define.CMAKE_CXX_COMPILER="${CXX}" \
+              --config-settings=cmake.define.BUILD_TESTING="${build_testing}" \
+              ${{ inputs.pip_opts }}
+        fi
+
+    - name: Test Python
+      if: inputs.run_python_tests == 'true'
+      shell: bash
+      run: |
+        set +e
+        pytest -v
+        pytest_exit=$?
+        set -e
+
+        if [ "$pytest_exit" -eq 5 ]; then
+            echo "::error::run_python_tests is true but zero pytest tests were found."
+            exit 1
+        fi
+        exit "$pytest_exit"
+
+    - name: Test C++
+      if: inputs.run_cmake_tests == 'true'
+      shell: bash
+      working-directory: build
+      run: |
+        total_tests=$(ctest -N | grep "Total Tests:" | grep -oE "[0-9]+$")
+        if [ "${total_tests:-0}" -eq 0 ]; then
+            echo "::error::run_cmake_tests is true but zero CTest tests were found."
+            exit 1
+        fi
+        ctest -VV

.github/actions/setup_nwx_dev_env/action.yml

@@ -0,0 +1,120 @@
+# Copyright 2026 NWChemEx-Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Setup NWX Dev Environment
+description: >-
+  Installs a C/C++ compiler plus CMake, Ninja, MPI, Boost, BLAS/LAPACK, and
+  Eigen3 via the native package manager (apt on Linux, Homebrew on macOS),
+  and exports CC/CXX to $GITHUB_ENV for later steps in the same job. Single
+  source of truth for this, shared by cmake_build and pip_build.
+
+inputs:
+  compiler:
+    description: "One of: gcc-14, clang-18."
+    required: true
+  needs_nwchem:
+    description: >-
+      Whether to install a real NWChem binary, for friend-integration tests
+      that shell out to the external NWChem quantum chemistry program (e.g.
+      FriendZone's nwx2molssi/nwx2ase NWChem wrappers, and NWChemEx's
+      compute_energy tests -- both gated behind
+      friendzone.friends.is_nwchem_enabled(), which checks whether `nwchem`
+      is on PATH). No apt or pip package ships the actual NWChem binary, only
+      Homebrew (macOS) and conda-forge (Linux, via a standalone micromamba
+      bootstrap -- no full Anaconda needed) do. Off by default: this is a
+      large, slow install that only a couple of repos' test suites need.
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - name: Install Compiler and Dependencies
+      shell: bash
+      run: |
+        case "${{ runner.os }}_${{ inputs.compiler }}" in
+          Linux_gcc-14)
+            sudo apt-get update -y
+            sudo apt-get install -y gcc-14 g++-14 cmake ninja-build libopenmpi-dev openmpi-bin libboost-dev libopenblas-dev liblapack-dev libeigen3-dev
+            echo "CC=gcc-14"  >> "$GITHUB_ENV"
+            echo "CXX=g++-14" >> "$GITHUB_ENV"
+            ;;
+          Linux_clang-18)
+            sudo apt-get update -y
+            sudo apt-get install -y clang-18 libomp-18-dev cmake ninja-build libopenmpi-dev openmpi-bin libboost-dev libopenblas-dev liblapack-dev libeigen3-dev
+            echo "CC=clang-18"    >> "$GITHUB_ENV"
+            echo "CXX=clang++-18" >> "$GITHUB_ENV"
+            ;;
+          macOS_gcc-14)
+            brew install gcc@14 cmake ninja open-mpi boost openblas eigen
+            echo "CC=gcc-14"  >> "$GITHUB_ENV"
+            echo "CXX=g++-14" >> "$GITHUB_ENV"
+            echo "CMAKE_PREFIX_PATH=$(brew --prefix openblas)" >> "$GITHUB_ENV"
+            ;;
+          macOS_clang-18)
+            brew install llvm@18 libomp cmake ninja open-mpi boost openblas eigen
+            prefix=$(brew --prefix llvm@18)
+            libomp_prefix=$(brew --prefix libomp)
+            echo "CC=${prefix}/bin/clang"    >> "$GITHUB_ENV"
+            echo "CXX=${prefix}/bin/clang++" >> "$GITHUB_ENV"
+            echo "CMAKE_PREFIX_PATH=$(brew --prefix openblas);${libomp_prefix}" >> "$GITHUB_ENV"
+            # llvm@18's own clang has no bundled OpenMP runtime; find_package(OpenMP)
+            # needs omp.h/libomp.dylib on the compiler's default search paths to pass
+            # its "-fopenmp compiles" check and locate the library, and CPATH/LIBRARY_PATH
+            # are how Clang picks those up without needing explicit -I/-L flags threaded
+            # through every cmake_opts caller.
+            echo "CPATH=${libomp_prefix}/include" >> "$GITHUB_ENV"
+            echo "LIBRARY_PATH=${libomp_prefix}/lib" >> "$GITHUB_ENV"
+            ;;
+          *)
+            echo "::error::Unsupported (os, compiler): (${{ runner.os }}, ${{ inputs.compiler }})"
+            exit 1
+            ;;
+        esac
+
+    - name: Install NWChem
+      if: inputs.needs_nwchem == 'true'
+      shell: bash
+      run: |
+        case "${{ runner.os }}" in
+          Linux)
+            # No apt/pip package ships the real NWChem binary -- conda-forge
+            # is the only source of a precompiled one. Bootstrap a
+            # standalone micromamba (not a full Anaconda/conda install),
+            # install NWChem into its own env, then put just that env's
+            # bin/ on PATH via GITHUB_PATH rather than `conda activate`,
+            # so it doesn't shadow the Python venv the rest of the job uses.
+            "${SHELL}" <(curl -L micro.mamba.pm/install.sh)
+            "$HOME/.local/bin/micromamba" create -y -n nwchem -c conda-forge nwchem
+            echo "$HOME/micromamba/envs/nwchem/bin" >> "$GITHUB_PATH"
+            # conda-forge's nwchem is compiled with a hardcoded default
+            # NWCHEM_BASIS_LIBRARY pointing at the feedstock's own build
+            # directory (doesn't exist outside the build container), so
+            # basis set lookups fail unless overridden. The package's own
+            # etc/conda/activate.d/nwchem_env.sh sets these two vars
+            # correctly, but only on `conda activate`, which we don't do
+            # (just PATH, to avoid shadowing the job's Python venv) -- so
+            # set them explicitly instead. Confirmed via local repro
+            # (Docker) that a bare `nwchem` invocation missing these vars
+            # can hang indefinitely on some tasks (e.g. CCSD(T)) rather
+            # than fail cleanly, instead of the fast/clean "failed opening
+            # basis file" abort seen on simpler tasks (e.g. CCSD) --
+            # confirmed fixed by setting these.
+            echo "NWCHEM_BASIS_LIBRARY=$HOME/micromamba/envs/nwchem/share/nwchem/libraries/" >> "$GITHUB_ENV"
+            echo "NWCHEM_NWPW_LIBRARY=$HOME/micromamba/envs/nwchem/share/nwchem/libraryps/" >> "$GITHUB_ENV"
+            ;;
+          macOS)
+            brew install nwchem
+            ;;
+        esac

.github/workflows/deploy_nwx_docs.yaml

@@ -41,6 +41,22 @@ jobs:
             core.setFailed("doc_target must not be blank.")
       - name: Checkout Source
         uses: actions/checkout@v4
+      # Some repos' CMake build invokes a Python codegen script at configure
+      # or build time (e.g. GauXC's gau2grid dependency imports numpy to
+      # generate C source) using whichever python3 is on PATH by default in
+      # this container -- install into that same interpreter here, before
+      # CMake ever runs, rather than in the module-docs/Sphinx steps below
+      # (those activate /pyenv instead, a separate environment).
+      - name: Install Repo Python Build Dependencies
+        if: inputs.generate_module_docs == true
+        run: |
+          if [ -f requirements.txt ]; then
+            # This container's system python3 is PEP 668
+            # externally-managed; --break-system-packages is safe here
+            # since the whole container is ephemeral CI state anyway.
+            python3 -m pip install --quiet --break-system-packages -r requirements.txt
+          fi
+        shell: bash
       # These next two steps will configure CMake if required
       - name: Configure Only Docs
         if: |