Add example cmake project

.github/workflows/pr.yml

@@ -1,3 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
 
 # This is the main workflow that runs on every PR and push to main
 name: pr
@@ -37,6 +51,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 +68,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 +120,22 @@ 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: |
+        cmake -S . --preset=examples -DCCCL_EXAMPLE_CPM_TAG=${GITHUB_SHA} -DCMAKE_CUDA_COMPILER=nvcc
+        ctest --preset=examples
 
   # 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 +146,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()

CMakePresets.json

@@ -0,0 +1,57 @@
+{
+  "version": 3,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 21,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "base",
+      "hidden": true,
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/build/${presetName}",
+      "cacheVariables": {
+        "CCCL_ENABLE_LIBCUDACXX": false,
+        "CCCL_ENABLE_CUB": false,
+        "CCCL_ENABLE_THRUST": false,
+        "CCCL_ENABLE_TESTING": false,
+        "CCCL_ENABLE_EXAMPLES": false
+      }
+    },
+    {
+      "name": "examples",
+      "displayName": "CCCL Examples",
+      "description": "Configure, build, and run the CCCL Examples",
+      "inherits": "base",
+      "cacheVariables": {
+        "CMAKE_CUDA_ARCHITECTURES": "70",
+        "CCCL_ENABLE_EXAMPLES": true
+      }
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "base",
+      "hidden": true,
+      "output": {
+        "outputOnFailure": true
+      },
+      "execution": {
+        "noTestsAction": "error",
+        "stopOnFailure": false
+      }
+    },
+    {
+      "name": "examples",
+      "configurePreset": "examples",
+      "inherits": "base",
+      "filter":{
+        "include": {
+          "name": "^cccl\\.example\\."
+        }
+      }
+    }
+  ]
+}
+

README.md

@@ -6,4 +6,4 @@ Stay tuned.
 
 ## CI Pipeline Overview
 
-For a detailed overview of the CI pipeline, see [ci-overview.md](ci-overview.md).
+For a detailed overview of the CI pipeline, see [ci-overview.md](ci-overview.md).

cmake/CCCLUtilities.cmake

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+
+# Add a build-and-test CTest.
+# - full_test_name_var will be set to the full name of the test.
+# - name_prefix is the prefix of the test's name (e.g. `cccl.test.cmake`)
+# - 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 name_prefix subdir test_id)
+  set(test_name ${name_prefix}.${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,39 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+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}"
+)
+
+set(CCCL_EXAMPLE_CPM_REPOSITORY "nvidia/cccl" CACHE STRING "GitHub repository used for CPM examples.")
+set(CCCL_EXAMPLE_CPM_TAG "main" CACHE STRING "Git tag/branch used for CPM examples.")
+
+set(cmake_cpm_opts
+  -D "CCCL_REPOSITORY=${CCCL_EXAMPLE_CPM_REPOSITORY}"
+  -D "CCCL_TAG=${CCCL_EXAMPLE_CPM_TAG}"
+)
+
+cccl_add_compile_test(test_name
+  cccl.example
+  example_project
+  "default"
+  ${cmake_opts}
+  ${cmake_cpm_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,52 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+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)