Add example cmake project

.github/workflows/pr.yml

@@ -37,6 +37,7 @@ jobs:
     name: Compute NVCC matrix
     runs-on: ubuntu-latest
     outputs:
+      FULL_MATRIX: ${{ steps.set-outputs.outputs.FULL_MATRIX }}
       CUDA_VERSIONS: ${{ steps.set-outputs.outputs.CUDA_VERSIONS }}
       HOST_COMPILERS: ${{ steps.set-outputs.outputs.HOST_COMPILERS }}
       PER_CUDA_COMPILER_MATRIX: ${{ steps.set-outputs.outputs.PER_CUDA_COMPILER_MATRIX }}
@@ -53,6 +54,7 @@ jobs:
         id: set-outputs
         run: |
           FULL_MATRIX='${{steps.compute-nvcc-matrix.outputs.matrix}}'
+          echo "FULL_MATRIX=$FULL_MATRIX" | tee -a "$GITHUB_OUTPUT"
           CUDA_VERSIONS=$(echo $FULL_MATRIX | jq -c '[.[] | .cuda] | unique')
           echo "CUDA_VERSIONS=$CUDA_VERSIONS" | tee -a "$GITHUB_OUTPUT"
           HOST_COMPILERS=$(echo $FULL_MATRIX | jq -c '[.[] | .compiler.name] | unique')
@@ -104,6 +106,24 @@ jobs:
       build_script: "./ci/build_libcudacxx.sh"
       test_script: "./ci/test_libcudacxx.sh" 
       devcontainer_version: ${{ needs.get-devcontainer-version.outputs.DEVCONTAINER_VERSION }}
+
+  examples:
+    name: CCCL Examples
+    needs: [compute-nvcc-matrix, get-devcontainer-version]
+    strategy:
+      fail-fast: false
+      matrix: 
+        include: ${{ fromJSON(needs.compute-nvcc-matrix.outputs.FULL_MATRIX) }}
+    uses: ./.github/workflows/run-as-coder.yml
+    with:
+      name: CCCL Examples CUDA${{matrix.cuda}} ${{matrix.compiler.name}}${{matrix.compiler.version}}
+      runner: linux-${{matrix.cpu}}-gpu-v100-latest-1
+      image: rapidsai/devcontainers:${{needs.get-devcontainer-version.outputs.DEVCONTAINER_VERSION}}-cpp-${{matrix.compiler.name}}${{matrix.compiler.version}}-cuda${{matrix.cuda}}-${{matrix.os}}
+      command: |
+        cd examples/example_project
+        cmake -S . -B build -DCCCL_TAG="$GITHUB_SHA" 
+        cmake --build build/
+        ctest --test-dir build/ --output-on-failure
 
   # This job is the final job that runs after all other jobs and is used for branch protection status checks.
   # See: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks
@@ -114,5 +134,6 @@ jobs:
       - libcudacxx
       - cub
       - thrust
+      - examples
     steps:
       - run: echo "CI success"

.github/workflows/run-as-coder.yml

@@ -40,6 +40,7 @@ jobs:
       - name: Run command
         shell: su coder {0}
         run: | 
+            set -exo pipefail
             cd ~/cccl
             eval "${{inputs.command}}" || exit_code=$?
             if [ ! -z "$exit_code" ]; then

CMakeLists.txt

@@ -29,10 +29,13 @@ option(CCCL_ENABLE_LIBCUDACXX "Enable the libcu++ developer build." ON)
 option(CCCL_ENABLE_CUB "Enable the CUB developer build." ON)
 option(CCCL_ENABLE_THRUST "Enable the Thrust developer build." ON)
 option(CCCL_ENABLE_TESTING "Enable CUDA C++ Core Library tests." ON)
+option(CCCL_ENABLE_EXAMPLES "Enable CUDA C++ Core Library examples." ON)
 
 include(CTest)
 enable_testing()
 
+include(cmake/CCCLUtilities.cmake)
+
 if (CCCL_ENABLE_LIBCUDACXX)
   set(LIBCUDACXX_TOPLEVEL_PROJECT ON)
 endif()
@@ -52,3 +55,7 @@ add_subdirectory(thrust)
 if (CCCL_ENABLE_TESTING)
   add_subdirectory(test)
 endif()
+
+if (CCCL_ENABLE_EXAMPLES)
+  add_subdirectory(examples)
+endif()

cmake/CCCLUtilities.cmake

@@ -0,0 +1,20 @@
+# Add a build-and-test CTest.
+# - full_test_name_var will be set to the full name of the test.
+# - subdir is the relative path to the test project directory.
+# - test_id is used to generate a unique name for this test, allowing the
+#   subdir to be reused.
+# - Any additional args will be passed to the project configure step.
+function(cccl_add_compile_test full_test_name_var subdir test_id)
+  set(test_name cccl.test.cmake.${subdir}.${test_id})
+  set(src_dir "${CMAKE_CURRENT_SOURCE_DIR}/${subdir}")
+  set(build_dir "${CMAKE_CURRENT_BINARY_DIR}/${subdir}/${test_id}")
+  add_test(NAME ${test_name}
+    COMMAND "${CMAKE_CTEST_COMMAND}"
+      --build-and-test "${src_dir}" "${build_dir}"
+      --build-generator "${CMAKE_GENERATOR}"
+      --build-options
+        ${ARGN}
+      --test-command "${CMAKE_CTEST_COMMAND}" --output-on-failure
+  )
+  set(${full_test_name_var} ${test_name} PARENT_SCOPE)
+endfunction()

examples/CMakeLists.txt

@@ -0,0 +1,17 @@
+
+include(../cmake/CCCLUtilities.cmake)
+
+set(cmake_opts
+  -D "CMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}"
+  -D "CMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}"
+  -D "CMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}"
+  -D "CMAKE_CUDA_COMPILER=${CMAKE_CUDA_COMPILER}"
+  -D "CMAKE_CUDA_HOST_COMPILER=${CMAKE_CUDA_HOST_COMPILER}"
+  -D "CMAKE_CUDA_ARCHITECTURES=${CMAKE_CUDA_ARCHITECTURES}"
+)
+
+cccl_add_compile_test(test_name
+  example_project
+  "default"
+  ${cmake_opts}
+)

examples/README.md

@@ -0,0 +1,12 @@
+
+This directory contains examples of how to use CCCL in your project.
+
+See the `README.md` in each subdirectory for more information.
+
+To build and run only the examples, run the following commands from the root directory of the repository:
+
+```bash
+cmake -S . -B build -DCCCL_ENABLE_EXAMPLES=ON -DCCCL_ENABLE_THRUST=OFF -DCCCL_ENABLE_CUB=OFF -DCCCL_ENABLE_LIBCUDACXX=OFF -DCCCL_ENABLE_TESTING=OFF
+cmake --build build
+ctest --test-dir build --output-on-failure
+```

examples/example_project/CMakeLists.txt

@@ -0,0 +1,37 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+
+project(CCCLDemo CUDA)
+
+# This example uses the CMake Package Manager (CPM) to simplify fetching CCCL from GitHub
+# For more information, see https://github.com/cpm-cmake/CPM.cmake
+include(cmake/CPM.cmake)
+
+
+# We define these as variables so they can be overriden in CI to pull from a PR instead of CCCL `main`
+# In your project, these variables are unncessary and you can just use the values directly 
+set(CCCL_REPOSITORY "nvidia/cccl" CACHE STRING "GitHub repository to fetch CCCL from")
+set(CCCL_TAG "main" CACHE STRING "Git tag/branch to fetch from CCCL repository")
+
+# This will automatically clone CCCL from GitHub and make the exported cmake targets available
+CPMAddPackage(
+    NAME CCCL
+    GITHUB_REPOSITORY ${CCCL_REPOSITORY}
+    GIT_TAG ${CCCL_TAG}
+)
+
+# Default to building for the GPU on the current system
+if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+  set(CMAKE_CUDA_ARCHITECTURES native)
+endif()
+
+# Creates a cmake executable target for the main program
+add_executable(example_project example.cu)
+
+# "Links" the CCCL Cmake target to the `example_project` executable. This configures everything needed to use
+# CCCL headers, including setting up include paths, compiler flags, etc.
+target_link_libraries(example_project PRIVATE CCCL::CCCL)
+
+# This is only relevant for internal testing and not needed by end users. 
+include(CTest)
+enable_testing()
+add_test(NAME example_project COMMAND example_project)

examples/example_project/README.md

@@ -0,0 +1,143 @@
+
+# Example Project Using CCCL From GitHub
+
+Many CUDA C++ users are accustomed to using CCCL headers (Thrust, CUB, libcu++) provided with the [NVIDIA CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit) or [NVIDIA HPC SDK](https://developer.nvidia.com/hpc-sdk).
+
+In addition, we also support using CCCL directly from GitHub. 
+The primary benefit is that this allows users to use the latest version of CCCL without having to wait for a new release of the CUDA Toolkit or HPC SDK.
+
+This example demonstrates how to use CCCL from GitHub in a CMake project.
+
+## Overview
+
+This is a standalone example of how to use [CCCL](https://github.com/nvidia/cccl) in a CMake project. 
+
+This example demonstrates fetching CCCL from GitHub and linking it with a simple example CUDA program ([`example.cu`](example.cu)) that utilizes the headers from CCCL.
+
+This is intended to be a starting point for users who want to use CCCL in their own projects.
+
+## How to Adapt This Example to Your Project
+
+This example is intended to be a starting point for users who want to use CCCL in their own projects. 
+In order to adapt this example to your project, you will need to do the following:
+1. Download `CPM.cmake` into your project's `cmake/` directory ([see below for instructions](#downloading-cpm)).
+2. Add the following lines to your project's `CMakeLists.txt` file:
+   ```cmake
+   include(cmake/CPM.cmake)
+
+   # This will automatically clone CCCL from GitHub and make the exported cmake targets available
+   CPMAddPackage(
+       NAME CCCL
+       GITHUB_REPOSITORY nvidia/cccl
+       GIT_TAG main # Fetches the latest commit on the main branch
+   )
+
+   # If you're building an executable
+   add_executable(your_executable your_file.cu)
+   target_link_libraries(your_executable PRIVATE CCCL::CCCL)
+
+   # Alternatively, if you're building a library
+   add_library(your_library your_file.cu)
+   target_link_libraries(your_library PRIVATE CCCL::CCCL)
+   ```
+   See the [CMakeLists.txt](CMakeLists.txt) file in this directory for a complete example.
+3. Configure and build your project as normal and verify that it builds successfully.
+
+For more information on using CPM, see [below](#using-cmake-package-manager).
+
+## Using CMake Package Manager
+
+This example uses the CMake Package Manager (CPM) to fetch CCCL from GitHub. 
+
+See the [CMakeLists.txt](CMakeLists.txt) file in this directory for the complete example.
+
+If you are not familiar with CPM, you can find more information [here](https://github.com/cpm-cmake/CPM.cmake). 
+In short, CPM is a CMake module that simplifies dependency management for CMake projects. 
+It automatically downloads and integrates dependencies into your CMake project.
+
+### Downloading CPM
+
+In order to get the latest version of CPM.cmake, you can run the following command in the root directory of your project:
+
+```bash
+mkdir -p cmake
+wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake
+```
+
+This will download and create the file `cmake/CPM.cmake` in your project directory. 
+Most projects will want to commit this file to their source control system.
+You can then use `include(cmake/CPM.cmake)` in your project's `CMakeLists.txt` file to include CPM in your project.
+
+Alternatively, you can add the following logic to your `CMakeLists.txt` to download CPM if it is not already present in your project directory.
+
+```cmake
+set(CPM_DOWNLOAD_VERSION 0.34.0)
+
+if(CPM_SOURCE_CACHE)
+  set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+elseif(DEFINED ENV{CPM_SOURCE_CACHE})
+  set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+else()
+  set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+endif()
+
+if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
+  message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
+  file(DOWNLOAD
+       https://github.com/TheLartians/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
+       ${CPM_DOWNLOAD_LOCATION}
+  )
+endif()
+
+include(${CPM_DOWNLOAD_LOCATION})
+```
+
+## Building and Running the Example
+
+Most people will want to adapt this example to their own project as described [above](#how-to-adapt-this-example-to-your-project). If you would like to build and run this example as-is, you will need to follow the instructions below.
+
+### Prerequisites
+
+If you would like to build and run this example as-is, you will need:
+
+- A CUDA-capable GPU
+- NVIDIA CUDA Toolkit (11.1 or later)
+- CMake (3.14 or later)
+- A C++14 standard-compliant compiler
+- git
+
+### Instructions
+
+1. Clone this repository to your local machine.
+   ```bash
+   git clone https://github.com/NVIDIA/cccl.git
+   ```
+
+2. Enter the directory of the cloned repository.
+   ```bash
+   cd cccl/examples/example_project 
+   ```
+
+3. Run the CMake configure step
+   ```bash
+   cmake -S . -B build
+   ```
+   Alternatively,
+   ```bash
+   mkdir -p build
+   cd build
+   cmake ..
+   ```
+4. Run the CMake build step.
+   ```bash
+   cmake --build .
+   ```
+
+6. Run the executable.
+   ```bash
+   ./build/example_project
+   ```
+
+If everything is configured correctly, the program will execute and print the sum of an array of integers, demonstrating the use of cccl.
+
+

examples/example_project/cmake/CPM.cmake

@@ -0,0 +1,33 @@
+set(CPM_DOWNLOAD_VERSION 0.38.1)
+
+if(CPM_SOURCE_CACHE)
+  set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+elseif(DEFINED ENV{CPM_SOURCE_CACHE})
+  set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+else()
+  set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+endif()
+
+# Expand relative path. This is important if the provided path contains a tilde (~)
+get_filename_component(CPM_DOWNLOAD_LOCATION ${CPM_DOWNLOAD_LOCATION} ABSOLUTE)
+
+function(download_cpm)
+  message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
+  file(DOWNLOAD
+       https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
+       ${CPM_DOWNLOAD_LOCATION}
+  )
+endfunction()
+
+if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
+  download_cpm()
+else()
+  # resume download if it previously failed
+  file(READ ${CPM_DOWNLOAD_LOCATION} check)
+  if("${check}" STREQUAL "")
+    download_cpm()
+  endif()
+  unset(check)
+endif()
+
+include(${CPM_DOWNLOAD_LOCATION})