Continuous Integration

The Axom project uses two CI tools, Azure Pipelines via GitHub and GitLab CI on the LLNL LC Collaboration Zone (CZ).

Azure Pipelines

Every Pull Request created on GitHub is automatically run through a series of CI jobs to ensure that the Axom source builds and passes our unit tests. These configurations mimic the LC compilers and systems as closely as possible via Docker containers that have our third-party libraries pre-built on them.

Axom’s GitHub project is also configured to require pull requests to pass checks from our LC GitLab CI (as described below).

Build and Test Axom in a Docker Container

  1. Install Docker Desktop

    • You can look at dockerdocs for tutorials on installing and using Docker.

  2. Ensure the Docker Desktop application is running on your computer

  3. Open Terminal/Powershell/Command Line prompt of choice

  4. Pull the Docker image

    docker pull <image name>
    
    • Checkout Azure Pipelines configuration file for latest images (denoted by <Compiler>_IMAGENAME).

    docker images
    
    • Verify you can see your image

  5. Create a Docker volume to save your work

    docker volume create <volume name>
    
    • This allows you to save your progress once you exit the container

    docker volume ls
    
    • Verify you can see your volume

  6. Run the Docker container with the volume mounted

    docker run -it --mount source=<volume name>,target=/home/axom --name <name you want to give container> <image id>
    
    • You can get the <image id> through the docker images command.

    • This will mount/attach your volume to the Docker image. When you exit your running Docker container, you will want to rerun this command to restart the container with your current progress.

    Note

    If you exit the container and attempt to restart, sometimes Docker will return a warning stating the initial container has not fully closed. Just run docker container prune command to cleanup the container and then you can reissue the run command.

  7. In the running Docker container, clone the axom github repository

    git clone https://github.com/LLNL/axom.git
    cd axom
    
  8. (optional) Checkout your branch

    git checkout <name of your branch>
    
  9. Setup submodules

    git submodule update --init
    
  10. Configure Axom

    python3 ./config-build.py -hc host-configs/docker/<CMake host-config for container> -bt Release -DENABLE_GTEST_DEATH_TESTS=ON -DBUILD_SHARED_LIBS=ON -DAXOM_QUEST_ENABLE_EXTRA_REGRESSION_TESTS:BOOL=ON -DENABLE_BENCHMARKS:BOOL=ON
    
    • The host-config for your Docker container can be found in the host-configs/docker/ directory.

    • The CMake flags (marked with -D) are derived from a job in the Azure Pipelines configuration file. The CMake flags are for mimicking a specific job setup, but are not required to configure Axom.

  11. Build Axom

    cd <build-* directory>
    make -j 8
    
  12. Run unit tests

You have several potential options:

# Run tests with verbose output using make
make VERBOSE=1 test

# Run tests with verbose output using ctest
ctest -VV

# Run specific tests with verbose output using ctest, filtering for tests that have a specific prefix
ctest -VV -R  "<some_test_prefix>*"

LC GitLab

We also maintain a mirror of the Axom project on LLNL’s LC GitLab instance primarily for testing Axom pull requests against the various LC System Types and compilers.

There are two types of GitLab plans. The first is triggered automatically by pull requests on GitHub, while the second runs nightly and tests Axom’s develop branch against a new build of our third-party library stack.

Our GitLab CI configuration also allows manual runs. To initiate a new run, navigate to the CI/CD page, click on the “Run pipeline” button and select the branch to test.