From 9ffb03c9c694f3781672ac7d7bcbf7a856123b5c Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Wed, 28 Aug 2024 14:36:33 -0700 Subject: [PATCH 1/3] Updated Dev Guide to describe current CI workflows using Azure and GH Actions --- .../sphinx/dev_guide/build_configurations.rst | 38 ++- docs/sphinx/dev_guide/ci.rst | 121 +++++++--- docs/sphinx/dev_guide/ci_tasks.rst | 224 +++++++++++------- docs/sphinx/dev_guide/contributing.rst | 8 +- 4 files changed, 240 insertions(+), 151 deletions(-) diff --git a/docs/sphinx/dev_guide/build_configurations.rst b/docs/sphinx/dev_guide/build_configurations.rst index a71c047d33..4cf7761ec3 100644 --- a/docs/sphinx/dev_guide/build_configurations.rst +++ b/docs/sphinx/dev_guide/build_configurations.rst @@ -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, @@ -241,17 +241,15 @@ 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 --no-cache @@ -259,21 +257,17 @@ you have Docker installed. `RAJA 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/: /bin/bash + $ docker run -it ghcr.io/llnl/radiuss: /bin/bash - Here, ``:`` is the OS image and compiler image you - want (see the aforementioned Dockerfile). + Here, ```` 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. diff --git a/docs/sphinx/dev_guide/ci.rst b/docs/sphinx/dev_guide/ci.rst index 9466a76dd5..2643a83f20 100644 --- a/docs/sphinx/dev_guide/ci.rst +++ b/docs/sphinx/dev_guide/ci.rst @@ -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 `_. - 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 threes 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 `_. + 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 @@ -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 @@ -302,29 +305,33 @@ plus RAJA-specific specs defined in files in the `RAJA/.gitlab/jobs `_ 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 `_ 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: @@ -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:: @@ -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 `_ + in the `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 `_ 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 `_ + 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 `_. -The base container images are built and maintained through the -`RSE-Ops Docker `_ project. A table of the most -up-to-date containers can be found -`here `_. 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 `_ 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. diff --git a/docs/sphinx/dev_guide/ci_tasks.rst b/docs/sphinx/dev_guide/ci_tasks.rst index 5c63ecc9ad..75e7e9e578 100644 --- a/docs/sphinx/dev_guide/ci_tasks.rst +++ b/docs/sphinx/dev_guide/ci_tasks.rst @@ -12,8 +12,8 @@ Continuous Integration (CI) Testing Maintenance Tasks ***************************************************** -In :ref:`ci-label`, we described RAJA CI workflows. This section describes -how to perform common RAJA CI testing maintenance tasks. +In :ref:`ci-label`, we described RAJA CI testing workflows. This section +describes how to perform common RAJA CI testing maintenance tasks. .. _gitlab_ci_tasks-label: @@ -29,12 +29,18 @@ for a project, mirroring a GitHub to GitLab, etc. Please refer to `LC GitLab CI Changing build and test configurations -------------------------------------- -The build for each test we run is defined by a Spack spec in one of two places, -depending on whether it is *shared* with other projects or it is specific to -RAJA. The details are described in :ref:`gitlab_ci_pipelines-label`. +The configurations that are tested in RAJA are defined by a Spack spec in one +of two places, depending on whether it is *shared* with other projects or +it is specific to RAJA. The details are described +in :ref:`gitlab_ci_pipelines-label`. Each spec contains information (compiler +and version, build variants, etc.) that must be consistent with the +build specs defined in the `RADIUSS Spack Configs +`_ project, which also includes +the RAJA Spack package. The RADIUSS Spack Configs project is included as a +RAJA submodule in the ``RAJA/scripts`` directory. -Remove a configuration -^^^^^^^^^^^^^^^^^^^^^^ +Removing a configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^ To remove a RAJA-specific test configuration, simply delete the entry for it in the ``RAJA/.gitlab/jobs/.yml`` file where it is defined. Here, @@ -47,20 +53,25 @@ there, remove the job entry, and create a pull request. .. important:: The RADIUSS Spack Configs project is used by several other projects. When changing a shared configuration file, please make sure the - change is OK with those other projects. + change is OK with those other projects. Typically, shared configurations + are only changed when it makes sense to update compilers for all projects, + such as when system default compiler versions change. -Add a configuration -^^^^^^^^^^^^^^^^^^^ +Adding a configuration +^^^^^^^^^^^^^^^^^^^^^^^^ To add a RAJA-specific test configuration, add an entry for it to the ``RAJA/.gitlab/jobs/.yml`` file, where ``MACHINE`` is the name of the LC platform where it will be run. When adding a test configuration, it is important to note two items that must be specified properly: - * A unique **job label**, which identifies it in the machine configuration - file and also on a web page for a GitLab CI pipeline - * A build **Spack spec**, which identifies the compiler and version, - compiler flags, build options, etc. + * Each jobs must have a unique **job label**, which identifies it in the + machine configuration file and also on a web page for a GitLab CI pipeline + * The **Spack spec** name identifies the compiler and version, + compiler flags, build options, etc. must match an existing spec in + the `RADIUSS Spack Configs `_ + project. Also, the build options must be consistent with the variants + defined in the RAJA package in that project. For example, an entry for a build using the clang 12.0.1 compiler with CUDA 11.5.0 on the LC lassen machine would be something like this: @@ -82,7 +93,9 @@ there, add the job entry, and create a pull request. .. important:: The RADIUSS Spack Configs project is used by several other projects. When changing a shared configuration file, please make sure the - change is OK with those other projects. + change is OK with those other projects. Typically, shared configurations + are only changed when it makes sense to update compilers for all projects, + such as when system default compiler versions change. Modifying a configuration ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -90,7 +103,7 @@ Modifying a configuration To change an existing configuration, change the relevant information in the configuration in the appropriate ``RAJA/.gitlab/jobs/.yml`` file. Make sure to also modify the job label as needed, so it is descriptive of the -configuration (and remains unique!!). +configuration is unique with respect to the others that are being run. To modify a shared configuration, it must be changed in the appropriate ``gitlab/radiuss-jobs/.yml`` file in the `RADIUSS Spack Configs @@ -102,12 +115,12 @@ there, modify the job entry, and create a pull request. appropriate system type in the `RADIUSS Spack Configs `_ repo. - If the desired entry is not there, but exists in a newer version of the RADIUSS - Spack Configs project, update the RAJA submodule to use the newer version. If - the information does not exist in any version of the RADIUSS Spack Configs - project, create a branch there, add the needed spec info, and create a pull - request. Then, when that PR is merged, update the RAJA submodule for the - RADIUSS Spack Configs project to the new version. + If the desired entry is not there, but exists in a newer version of the + RADIUSS Spack Configs project, update the RAJA submodule to use the newer + version. If the information does not exist in any version of the RADIUSS + Spack Configs project, create a branch there, add the needed spec info, + and create a pull request. Then, when that PR is merged, update the RAJA + submodule for the RADIUSS Spack Configs project to the new version. Changing run parameters ^^^^^^^^^^^^^^^^^^^^^^^ @@ -150,21 +163,23 @@ annotate the job for this. For example: allow_failure: true .. important:: When a shared job needs to be modified for RAJA specifically, we - call that "overriding": The job label must be kept the same as in the - ``gitlab/radiuss-jobs/.yml`` file in the `RADIUSS Spack Configs - `_, and the RAJA-specific job - can be adapted. If you override a shared job, please add a comment to - describe the change in the ``RAJA/.gitlab/jobs/.yml`` file where - the job is overridden. + call that "overriding". The job label must be kept the same as for the + shared job in the ``gitlab/radiuss-jobs/.yml`` file in the + `RADIUSS Spack Configs `_, + and the RAJA-specific job can be adapted. If you override a shared job, + please add a comment to describe the change in the + ``RAJA/.gitlab/jobs/.yml`` file where the job is overridden. Building the Intel clang + SYCL HIP compiler for use in CI ---------------------------------------------------------- -The SYCL CI tests on corona rely on a custom Intel Clang SYCL compiler that we -build ourselves. This compiler lives in the ``/usr/workspace/raja-dev/`` folder so -that it can be accessed by the gitlab CI system. Since the intel compiler does -not do releases in the typical sense (they simply update their repo *every night*), +To run CI tests for the RAJA SYCL back-end on GitLab, we use the corona +system and a custom Intel Clang compiler that we build ourselves to support +SYCL for AMD GPUs. This compiler lives in the ``/usr/workspace/raja-dev/`` +folder so that it can be accessed by the service user account that we use to +run our GitLab CI. Since the Intel compiler does not +do releases in the typical sense (they simply update their repo *every night*), it may become necessary to periodically build a new version of the compiler to ensure that we are using the most up-to-date version available. The steps for building, installing, and running are shown here. @@ -172,32 +187,35 @@ building, installing, and running are shown here. Building the Compiler ^^^^^^^^^^^^^^^^^^^^^ -.. important:: Because intel updates their compiler repo daily, there is a nonzero possibility that the head of the sycl branch will fail to build. - In the event that it does not build, try checking out a different commit. On the intel/llvm GitHub page, one can see which of their - commits builds by checking the status badge next to each commit. Look for a commit that passes. +.. important:: Because Intel updates their compiler repo daily, it is possible + that the head of the SYCL branch will fail to build. In the event that it + does not build, try checking out an earlier commit. On the Intel/LLVM GitHub + page, one can see which of their commits builds by checking the status + badge next to each commit. Look for a commit that passes. - -#. Load the version of GCC that you want to use. In this case, we are using LC's gcc/10.3.1-magic installation:: +#. Load the module of the version of GCC headers that you want to use. For example, we typically use the system default, which on corona is gcc/10.3.1-magic:: module load gcc/10.3.1-magic -#. Load the version of rocm that you want to use. In this case, we are using 5.7.1:: +#. Load the module of the version of ROCm that you want to use. For example:: module load rocm/5.7.1 -#. Clone the "sycl" branch of intel's llvm compiler fork:: +#. Clone the SYCL branch of Intel's LLVM compiler:: git clone https://github.com/intel/llvm -b sycl -#. cd into that folder:: +#. cd into the LLVM folder:: cd llvm - In the event that the head of the sycl branch does not build, run ``git checkout `` to checkout a version that does build. + In the event that the head of the sycl branch does not build, run + ``git checkout `` to checkout a version that does build. #. Build the compiler. - Note that in this example, we are using rocm5.7.1, but one can change the version they wish to use simply by changing the paths in the configure step + Note that in this example, we are using rocm5.7.1, but one can change the + version they wish to use simply by changing the paths in the configure step a. Configure @@ -224,11 +242,11 @@ Building the Compiler #. Test the compiler - Follow the steps in the `Using the compiler`_ section to test this installation + Follow the steps in the `Using the compiler`_ section to test the installation #. Install - a. The build step will install the compiler to the folder ``buildrocm/install``. Simply copy this folder to the ``/usr/workspace/raja-dev/`` directory using the naming scheme ``clang_sycl__hip_gcc_rocm`` + a. The build step will install the compiler in the folder ``buildrocm/install``. Copy this folder to the ``/usr/workspace/raja-dev/`` directory using the naming scheme ``clang_sycl__hip_gcc_rocm`` #. Set the permissions of the folder, and everything in it to 750:: @@ -242,11 +260,11 @@ Building the Compiler Using the compiler ^^^^^^^^^^^^^^^^^^ -#. Load the version of rocm that you used when building the compiler:: +#. Load the version of rocm that you used when building the compiler, for example:: module load rocm/5.7.1 -#. Navigate to the root of your local checkout space of the RAJA repo:: +#. Navigate to the root of your local RAJA checkout space:: cd /path/to/raja @@ -256,32 +274,40 @@ Using the compiler Note that at the time of writing, the newest compiler we had built was at ``clang_sycl_2f03ef85fee5_hip_gcc10.3.1_rocm5.7.1`` -#. cd into the auto generated build directory:: +#. cd into the generated build directory:: cd {build directory} -#. Run the tests:: +#. Build the code and run the RAJA tests:: make -j + make test -============== -Azure CI Tasks -============== +============================================ +Azure Pipelines and GitHub Actions CI Tasks +============================================ -The tasks in this section apply to RAJA Azure Pipelines CI. +The tasks in this section apply to RAJA Azure Pipelines and GitHub Actions +CI testing that was described in :ref:`azure_ci-label` Changing Builds/Container Images -------------------------------- The builds we run in Azure are defined in the `RAJA/azure-pipelines.yml `_ file. + +The builds we run in GitHub Actions are defined in the `RAJA/.github/workflows/build.yml `_ file. Linux/Docker ^^^^^^^^^^^^ -To update or add a new compiler / job to Azure CI we need to edit both ``azure-pipelines.yml`` and ``Dockerfile``. +To update or add a new compiler / job to Azure Pipelines or GitHub Actions CI, +we need to edit either the ``RAJA/azure-pipelines.yml`` file or the +``RAJA/.github/workflows/build.yml`` file and the ``RAJA/Dockerfile``, if +changes are needed there. -If we want to add a new Azure pipeline to build with ``compilerX``, then in ``azure-pipelines.yml`` we can add the job like so:: +If we want to add a new Azure pipeline to build with ``compilerX``, then in the +``RAJA/azure-pipelines.yml`` file we can add the job like so:: -job: Docker ... @@ -291,78 +317,100 @@ If we want to add a new Azure pipeline to build with ``compilerX``, then in ``az compilerX: docker_target: compilerX -Here, ``compilerX:`` defines the name of a job in Azure. ``docker_target: compilerX`` defines a variable ``docker_target``, which is used to determine what part of the ``Dockerfile`` to run. +Here, ``compilerX`` defines the name of a job in Azure. ``docker_target: compilerX`` defines a variable ``docker_target``, which is used to determine which +entry in the ``Dockerfile`` file to use, where the name after ``docker_target`` +is the shorthand name of job in the ``Dockerfile`` file following the word +``AS``. + +Similarly, for GitHub Actions, we add the name of the job to the job list in +the ``RAJA/.github/workflows/build.yaml`` file:: -In the ``Dockerfile`` we will want to add our section that defines the commands for the ``compilerX`` job.:: + jobs: + build_docker: + strategy: + matrix: + target: [..., compilerX] - FROM ghcr.io/rse-ops/compilerX-ubuntu-20.04:compilerX-XXX AS compilerX +In the ``RAJA/Dockerfile`` file, we add a section that defines the commands for the ``compilerX`` job, such as:: + + FROM ghcr.io/llnl/radiuss:compilerX-ubuntu-22.04 AS compilerX ENV GTEST_COLOR=1 COPY . /home/raja/workspace WORKDIR /home/raja/workspace/build RUN cmake -DCMAKE_CXX_COMPILER=compilerX ... && \ make -j 6 && \ ctest -T test --output-on-failure && \ - cd .. && rm -rf build + make clean -Each of our docker builds is built up on a base image maintained by RSE-Ops, a table of available base containers can be found `here `_. We are also able to add target names to each build with ``AS ...``. This target name correlates to the ``docker_target: ...`` defined in ``azure-pipelines.yml``. +Each of our docker builds is built up on a base image maintained in the +`RADIUSS Docker Project `_. -The base containers are shared across multiple projects and are regularly rebuilt. If bugs are fixed in the base containers the changes will be automatically propagated to all projects using them in their Docker builds. +The base container images are shared by multiple projects and are rebuilt +regularly rebuilt. If bugs are fixed in the base images, the changes will be +automatically propagated to all projects using them in their Docker builds. -Check `here `_ for a list of all currently available RSE-Ops containers. Please see the `RSE-Ops Containers Project `_ on GitHub to get new containers built that aren't yet available. +Check `RADIUSS Docker Project `_ for a +list of currently available images. Windows / MacOS ^^^^^^^^^^^^^^^ -We run our Windows / MacOS builds directly on the Azure virtual machine instances. In order to update the Windows / MacOS instance we can change the ``pool`` under ``-job: Windows`` or ``-job: Mac``:: +We run our Windows and MacOS builds directly on the provided Azure machine +instances. To change the versions, change the ``pool`` under ``-job: Windows`` +or ``-job: Mac`` in the ``RAJA/azure-pipelines.yml`` file:: -job: Windows ... pool: vmImage: 'windows-2019' ... + -job: Mac ... pool: vmImage: 'macOS-latest' +Similarly, in GitHub Actions, we run our Windows and MacOS builds directly on +the provided machine instances. To change the versions, change the +appropriate lines in the ``RAJA/.github/workflows/build.yml`` file:: + + build_mac: + runs-on: macos-latest + ... + + build_windows: + runs-on: windows-latest + ... + + Changing Build/Run Parameters ----------------------------- Linux/Docker ^^^^^^^^^^^^ -We can edit the build and run configurations of each docker build, in the ``RUN`` command. Such as adding CMake options or changing the parallel build value of ``make -j N`` for adjusting throughput. - -Each base image is built using `spack `_. For the most part the container environments are set up to run our CMake and build commands out of the box. However, there are a few exceptions where we need to ``spack load`` specific modules into the path. - - * **Clang** requires us to load LLVM for OpenMP runtime libraries.:: - - . /opt/spack/share/spack/setup-env.sh && spack load llvm - - **CUDA** for the cuda runtime.:: +We can edit the build and run configurations of each Docker build, by editing +the appropriate line containing the ``RUN`` command in the ``RAJA/Dockerfile`` +file. For example, we can change CMake options or change the parallel build +value of ``make -j N`` for adjusting throughput. - . /opt/spack/share/spack/setup-env.sh && spack load cuda +Each base image is built using `spack `_. +For the most part the container environments are set up to run our CMake and +build commands out of the box. However, there are a few exceptions where we +may need to load compiler specific environment variables, such as for +the Intel LLVM compiler. For example, this may appear as:: - **HIP** for the hip runtime and llvm-amdgpu runtime libraries.:: + RUN /bin/bash -c "source /opt/intel/oneapi/setvars.sh 2>&1 > /dev/null && \ + cmake ..." - . /opt/spack/share/spack/setup-env.sh && spack load hip llvm-amdgpu - - **SYCL** requires us to run setupvars.sh:: - - source /opt/view/setvars.sh +In these cases, it is important to include the double quotes in the correct +locations. Windows / MacOS ^^^^^^^^^^^^^^^ -Windows and MacOS build / run parameters can be configured directly in ``azure-pipelines.yml``. CMake options can be configured with ``CMAKE_EXTRA_FLAGS`` for each job. The ``-j`` value can also be edited directly in the Azure ``script`` definitions for each job. - -The commands executed to configure, build, and test RAJA for each -pipeline in Azure are located in the `RAJA/Dockerfile `_ file. -Each pipeline section begins with a line that ends with ``AS ...`` -where the ellipses in the name of a build-test pipeline. The name label -matches an entry in the Docker test matrix in the -``RAJA/azure-pipelines.yml`` file mentioned above. - +Windows and MacOS build / run parameters can be configured directly in the +``RAJA/azure-pipelines.yml`` or ``RAJA/.github/workflows/build.yml`` file. CMake options can be configured with ``CMAKE_EXTRA_FLAGS`` for each job. The ``-j`` value can also be edited directly in these files for each job. .. _rajaperf_ci_tasks-label: @@ -395,6 +443,6 @@ the `RAJAPerf/.uberenv_config.json which point at the relevant RAJA submodule locations. That is the paths contain ``tpl/RAJA/...``. -Apart from this minor difference, all CI maintenance and development tasks for +Apart from these minor differences, all CI maintenance and development tasks for the RAJA Performance Suite follow the same pattern that is described in :ref:`ci_tasks-label`. diff --git a/docs/sphinx/dev_guide/contributing.rst b/docs/sphinx/dev_guide/contributing.rst index b8fc618bce..811a0f7f6a 100644 --- a/docs/sphinx/dev_guide/contributing.rst +++ b/docs/sphinx/dev_guide/contributing.rst @@ -71,10 +71,10 @@ of the contributor. The process involves four main steps: #. A RAJA contributor makes a PR on the RAJA GitHub project to merge a branch on which she has developed a contribution into another RAJA branch, typically, the develop branch. - #. When a PR is created, GitHub triggers Azure CI testing checks and - possibly GitLab CI checks if the branch is part of the RAJA GItHub repo. - Running and pass/fail status is reported back to GitHub where it can be - viewed and monitored. + #. When a PR is created, GitHub triggers Azure and GitHub Actions CI test + checks and GitLab CI checks if the branch is part of the RAJA GitHub repo. + Running and pass/fail status for all checks is reported back to the + corresponding GitHub pull request where it can be viewed and monitored. #. Meanwhile, RAJA team members and other contributors review the PR, suggesting changes and/or approving when they think it is ready to merge. #. When all checks pass and the PR is approved, the PR may be merged. From 490d2414a7d405cef71020fc3b7916c949defebf Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Wed, 4 Sep 2024 11:18:33 -0700 Subject: [PATCH 2/3] Fixes from reviewer comments. --- docs/sphinx/dev_guide/ci.rst | 2 +- docs/sphinx/dev_guide/ci_tasks.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/dev_guide/ci.rst b/docs/sphinx/dev_guide/ci.rst index 2643a83f20..1ad27561d3 100644 --- a/docs/sphinx/dev_guide/ci.rst +++ b/docs/sphinx/dev_guide/ci.rst @@ -22,7 +22,7 @@ The RAJA project uses threes 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 `_. - While we do some GPU builds on Azure and GitHub Actions, for CUDA, HIP, and + 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, diff --git a/docs/sphinx/dev_guide/ci_tasks.rst b/docs/sphinx/dev_guide/ci_tasks.rst index 75e7e9e578..8370a38f68 100644 --- a/docs/sphinx/dev_guide/ci_tasks.rst +++ b/docs/sphinx/dev_guide/ci_tasks.rst @@ -346,7 +346,7 @@ Each of our docker builds is built up on a base image maintained in the `RADIUSS Docker Project `_. The base container images are shared by multiple projects and are rebuilt -regularly rebuilt. If bugs are fixed in the base images, the changes will be +regularly. If bugs are fixed in the base images, the changes will be automatically propagated to all projects using them in their Docker builds. Check `RADIUSS Docker Project `_ for a From 31e9b1097dfda7468f491de32f5bba0ad5714784 Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Wed, 4 Sep 2024 15:04:40 -0700 Subject: [PATCH 3/3] Fix typo. --- docs/sphinx/dev_guide/ci.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/dev_guide/ci.rst b/docs/sphinx/dev_guide/ci.rst index 1ad27561d3..778ff47ff8 100644 --- a/docs/sphinx/dev_guide/ci.rst +++ b/docs/sphinx/dev_guide/ci.rst @@ -17,7 +17,7 @@ Continuous Integration (CI) Testing viewed by clicking the appropriate link in the **checks** section of a GitHub pull request. -The RAJA project uses threes CI tools to run tests: +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