Skip to content

Commit

Permalink
Merge pull request #1724 from LLNL/task/rhornung67/devguide-update
Browse files Browse the repository at this point in the history 
Updated Dev Guide to describe current CI workflows
  • Loading branch information
@rhornung67
rhornung67 authored Sep 4, 2024
2 parents ea55eed + 2d7bbf5 commit 9de96a7
Show file tree
Hide file tree
Showing 4 changed files with 240 additions and 151 deletions.
38 changes: 16 additions & 22 deletions docs/sphinx/dev_guide/build_configurations.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -154,9 +154,9 @@ Generating a host-config file
To generate a host-config file for a desired configuration, run the
``uberenv.py`` python script from the top-level RAJA directory.

.. important:: **Do not** run the ``uberenv.py`` script, which invokes Spack
in your LC home directory. Running Spack in your home directory
may cause you to exceed your LC disk space quota.
.. important:: **DO NOT** run the ``uberenv.py`` script, which invokes Spack,
in your LC home directory. **Running Spack in your home
directory may cause you to exceed your LC disk space quota.**

For example,

Expand Down Expand Up @@ -241,39 +241,33 @@ Reproducing Docker Builds Locally
==================================

RAJA uses Docker container images that it shares with other LLNL GitHub projects
for Azure CI testing (see :ref:`azure_ci-label` for more information).
We use Azure Pipelines for Linux, Windows, and MacOS builds. Typically, we
do RAJA testing for Linux on Azure with compilers, or compiler versions, that
for Azure and GitHub Actions CI testing (see :ref:`azure_ci-label` for more
information). We use Azure Pipelines and GitHub Actions for Linux, Windows,
and MacOS builds for build environments and compiler versions that
are not available on LLNL LC machines.

You can reproduce Azure builds locally for testing with the following steps if
you have Docker installed.
You can reproduce Azure and GitHub Actions builds locally for testing using
the following steps if you have access to Docker.

#. Run the command to build a local Docker image:

.. code-block:: bash
#. Run the command to build a local Docker image::

$ DOCKER_BUILDKIT=1 docker build --target <compiler> --no-cache

Here, ``<compiler>`` is one of the names following ``AS`` in the
`RAJA Dockerfile <https://github.com/LLNL/RAJA/blob/develop/Dockerfile>`_.


#. To get dropped into a terminal in the Docker image, run the following:

.. code-block:: bash
#. To get dropped into a terminal in the Docker image, run the following::
$ docker run -it ghcr.io/rse-ops/<os image>:<compiler> /bin/bash
$ docker run -it ghcr.io/llnl/radiuss:<os-image-compiler> /bin/bash

Here, ``<os image>:<compiler>`` is the OS image and compiler image you
want (see the aforementioned Dockerfile).
Here, ``<os-image-compiler>`` is the OS image and compiler image you
want (see the aforementioned Dockerfile description).
Then, you can build, run tests, edit files, etc. in the Docker image. Note that
the docker command has a ``-v`` argument that you can use to mount a local
directory in the image. For example

.. code-block:: bash
the Docker command has a ``-v`` argument that you can use to mount a local
directory in the image. For example::

& docker -v pwd:/opt/RAJA
docker -v pwd:/opt/RAJA

will mount your current local directory as ``/opt/RAJA`` in the image.
121 changes: 84 additions & 37 deletions docs/sphinx/dev_guide/ci.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,17 @@ Continuous Integration (CI) Testing
viewed by clicking the appropriate link in the **checks**
section of a GitHub pull request.

The RAJA project uses two CI tools to run tests:

* **Azure Pipelines** runs builds and tests for Linux, Windows, and MacOS
environments using compilers in container images maintained in the
`RSE Ops Project <https://github.com/rse-ops/docker-images>`_.
While we do some GPU builds on Azure, RAJA tests are only run for CPU-only
builds. The current set of builds run on Azure can be seen by looking at
the ``RAJA/azure-pipelines.yml`` and ``RAJA/Dockerfile`` files.
The RAJA project uses three CI tools to run tests:

* **Azure Pipelines** and **GitHub Actions** runs builds and tests for Linux,
Windows, and MacOS environments using compilers in container images
maintained in the `RADIUSS Docker Project <https://github.com/LLNL/radiuss-docker>`_.
While we do some GPU builds on Azure and GitHub Actions for CUDA, HIP, and
SYCL, RAJA tests are only run for CPU-only builds. The current set of
builds run on Azure and GitHub Actions can be seen by looking at the
``RAJA/azure-pipelines.yml`` and ``RAJA/.github/workflows/build.yml`` files,
respectively. The ``RAJA/Dockerfile`` file contains the CMake options used
to generate the build environment for each of the builds.

* **GitLab** instance in the Collaboration Zone (CZ) of the Livermore
Computing (LC) Center runs builds and tests on LC platforms using
Expand Down Expand Up @@ -102,7 +105,7 @@ process. More details about these steps will appear in the in later sections:

#. When test pipelines complete, results are reported to GitLab.

#. Lastly, GitLab reports to GitHub indicating the the status of checks there.
#. Lastly, GitLab reports to GitHub indicating the status of checks there.

.. figure:: ./figures/RAJA-Gitlab-Workflow2.png

Expand Down Expand Up @@ -302,29 +305,33 @@ plus RAJA-specific specs defined in files in the `RAJA/.gitlab/jobs <https://git

.. _azure_ci-label:

==================
Azure Pipelines CI
==================
======================================
Azure Pipelines and GitHub Actions CI
======================================

We use Azure Pipelines and GitHub Actions to run builds and tests for Linux,
Windows, and MacOS environments. We use these tools to run Linux builds and
tests for various less-common configurations, such as compiler versions that are
not available on LC systems. While we do builds for CUDA, HIP, and SYCL RAJA
GPU back-ends in the Azure and GitHub Actions Linux environments, RAJA tests
are only run for CPU-only pipelines.

We use Azure Pipelines to run builds and tests for Linux, Windows, and MacOS
environments. While we do builds for CUDA, HIP, and SYCL RAJA GPU back-ends
in the Azure Linux environment, RAJA tests are only run for CPU-only pipelines.
.. note:: Azure Pipelines and GitHub Actions CI test jobs are run on every
RAJA pull request, regardless of whether it was made from a branch in the
RAJA project repo or from a fork of the repo.

Azure Pipelines Testing Workflow
--------------------------------

The Azure Pipelines testing workflow for RAJA is much simpler than the GitLab
testing process described earlier.

The test jobs we run for each OS environment are specified in the
`RAJA/azure-pipelines.yml <https://github.com/LLNL/RAJA/blob/develop/azure-pipelines.yml>`_ file. This file defines the job steps, commands,
The jobs run in the Azure Pipelines testing workflow for RAJA are specified in
the `RAJA/azure-pipelines.yml <https://github.com/LLNL/RAJA/blob/develop/azure-pipelines.yml>`_ file. This file defines the job steps, commands,
compilers, etc. for each OS environment in the associated ``- job:`` section.
A summary of the configurations we build are:

* **Windows.** The ``- job: Windows`` Windows section contains information
for the Windows test builds. For example, we build and test RAJA as
a static and shared library. This is indicated in the Windows ``strategy``
section::
a static and/or shared library. This is indicated in the Windows
``strategy`` section::

strategy:
matrix:
Expand All @@ -340,7 +347,7 @@ A summary of the configurations we build are:
vmImage: 'windows-2019'

**MacOS.** The ``- job: Mac`` section contains information for Mac test
builds. For example, we build RAJA using the the MacOS/compiler
builds. For example, we build RAJA using the MacOS/compiler
image provided by the Azure application indicated in the ``pool`` section;
for example::

Expand All @@ -351,41 +358,81 @@ A summary of the configurations we build are:
test builds. We build and test RAJA using Docker container images generated
with recent versions of various compilers. The RAJA project shares these
images with other open-source LLNL RADIUSS projects and they are maintained
in the `RES-Ops Docker <https://github.com/rse-ops/docker-images>`_
in the `RADIUSS Docker <https://github.com/LLNL/radiuss-docker>`_
project on GitHub. The builds we do at any point in time are located in
the ``strategy`` block::

strategy:
matrix:
gccX:
docker_target: ...
...
clangY:
gcc11:
docker_target: ...
...
nvccZ:
clang14:
docker_target: ...

...

The Linux OS the docker images are run on is indicated in the ``pool`` section;
The Linux OS image used is indicated in the ``pool`` section;
for example::

pool:
vmImage: 'ubuntu-latest'

GitHub Actions Testing Workflow
--------------------------------

The jobs run in the GitHub Actions testing workflow for RAJA are specified in
the `RAJA/.github/workflows/build.yml <https://github.com/LLNL/RAJA/blob/develop/.github/workflows/build.yml>`_ file. This file defines the job steps, commands,
compilers, etc. for each OS environment in the associated ``jobs:`` section.
A summary of the configurations we build are:

* **Windows.** The ``build_windows:`` Windows section contains information
for the Windows test builds. For example, we build and test RAJA as
a static and shared library. This is indicated in the Windows ``strategy``
section::

strategy:
matrix:
shared:
- args:
BUILD_SHARED_LIBS=On
CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=On
- args: BUILD_SHARED_LIBS=Off

We use the Windows/compiler image provided by the GitHub Actions application
indicated by::

runs-on: windows-latest

**MacOS.** The ``build_mac:`` section contains information for Mac test
builds. We use the MacOS/compiler image provided by the GitHub Actions
application indicated by::

runs-on: macos-latest

**Linux.** The ``build_docker:`` section contains information for Linux
test builds. We build and test RAJA using Docker container images
maintained in the `RADIUSS Docker <https://github.com/LLNL/radiuss-docker>`_
project on GitHub. The builds we do at any point in time are located in
the ``strategy`` block, for example::

strategy:
matrix:
target: [gcc12_debug, gcc13, clang13, clang15, rocm5.6, rocm5.6_desul, intel2024, intel2024_debug, intel2024_sycl]
The Linux OS image used is indicated by::
runs-on: ubuntu-latest

Docker Builds
-------------

For each Linux/Docker pipeline, the base container images, CMake, build, and
test commands are located in `RAJA/Dockerfile <https://github.com/LLNL/RAJA/blob/develop/Dockerfile>`_.

The base container images are built and maintained through the
`RSE-Ops Docker <https://rse-ops.github.io/>`_ project. A table of the most
up-to-date containers can be found
`here <https://rse-ops.github.io/docker-images/>`_. These images are rebuilt
regularly ensuring that we have the most up to date builds of each
container and compiler.
The base container images are built and maintained in the
`RADIUSS Docker <https://github.com/LLNL/radiuss-docker>`_ project.
These images are rebuilt regularly ensuring that we have the most up to date
builds of each container and compiler.

.. note:: Please see :ref:`docker_local-label` for more information about
reproducing Docker builds locally for debugging purposes.
Expand Down
Loading

0 comments on commit 9de96a7

Please sign in to comment.