Add Thrust CMake example with flexible device system, update docs (NVIDIA#4500)

alliepiper · web-flow · commit 436cde63123f · 2025-04-18T19:00:46.000-04:00
* Bump minimum cmake in examples to match CCCL reqs.
* Use local repo / HEAD by default when building CCCL examples.
* Actually build the cudastf example.
* Add new CCCL+CMake+CPM example that demonstrates how to change device backend.
* Update existing Thrust CMake documentation to clarify intended-audience and cross-ref user docs.
diff --git a/docs/thrust/cmake_options.rst b/docs/thrust/cmake_options.rst
@@ -1,5 +1,18 @@
 .. _cmake-options:
 
+Notice
+------
+
+This document details the CMake options used for **developer builds**
+of the Thrust tests and examples included in the CCCL repository.
+The options presented here are not available when using Thrust as an
+end-user via our installed CMake packages, or when using
+``add_subdirectory`` / CPM to add CCCL/Thrust to your project's build system.
+For details and examples of using Thrust as an end-user, please refer
+to the following resources:
+
+- `Thrust + CMake example <https://github.com/NVIDIA/cccl/tree/main/examples/thrust_flexible_device_system>`__
+
 CMake Options
 =============
 
diff --git a/docs/thrust/developer_build.rst b/docs/thrust/developer_build.rst
@@ -1,6 +1,6 @@
 .. _thrust-module-setup:
 
-Setup
+Developer Build
 ==================================================
 
 .. toctree::
diff --git a/docs/thrust/index.rst b/docs/thrust/index.rst
@@ -8,9 +8,9 @@ Thrust: The C++ Parallel Algorithms Library
    :maxdepth: 2
 
    :ref:`Overview <thrust-module>`
-   setup
    releases
    release_process
+   developer_build
    api
    ${repo_docs_api_path}/thrust_api
 
@@ -29,6 +29,17 @@ Examples
 
 Thrust is best learned through examples.
 
+-------------
+CMake Example
+-------------
+
+A complete, standalone example project showing how to write a CMake build system that uses Thrust with any supported
+device system is available in the CCCL repository `here <https://github.com/NVIDIA/cccl/tree/main/examples/thrust_flexible_device_system>`__.
+
+------------------
+Thrust API Example
+------------------
+
 The following example generates random numbers serially and then transfers them
   to a parallel device where they are sorted.
 
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -24,8 +24,8 @@ set(cmake_opts
   -D "CMAKE_CUDA_ARCHITECTURES=${arches_escaped}"
 )
 
-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(CCCL_EXAMPLE_CPM_REPOSITORY "${CCCL_SOURCE_DIR}" CACHE STRING "Git repository used for CPM examples.")
+set(CCCL_EXAMPLE_CPM_TAG "HEAD" CACHE STRING "Git tag/branch used for CPM examples.")
 
 set(cmake_cpm_opts
   -D "CCCL_REPOSITORY=${CCCL_EXAMPLE_CPM_REPOSITORY}"
@@ -50,4 +50,23 @@ if (CUDAToolkit_VERSION_MAJOR VERSION_GREATER_EQUAL 12)
     ${cmake_opts}
     ${cmake_cpm_opts}
   )
-endif()
+
+  cccl_add_compile_test(test_name
+    cccl.example
+    cudax_stf
+    "default"
+    ${cmake_opts}
+    ${cmake_cpm_opts}
+  )
+endif() # CTK > 12.0
+
+foreach (DEVICE_SYSTEM IN ITEMS CUDA OMP TBB CPP)
+  cccl_add_compile_test(test_name
+    cccl.example
+    thrust_flexible_device_system
+    "${DEVICE_SYSTEM}"
+    -D "CCCL_THRUST_DEVICE_SYSTEM=${DEVICE_SYSTEM}"
+    ${cmake_opts}
+    ${cmake_cpm_opts}
+  )
+endforeach()
diff --git a/examples/basic/CMakeLists.txt b/examples/basic/CMakeLists.txt
@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
 
 project(CCCLDemo CUDA)
 
@@ -24,13 +24,13 @@ include(cmake/CPM.cmake)
 
 # We define these as variables so they can be overridden in CI to pull from a PR instead of CCCL `main`
 # In your project, these variables are unnecessary and you can just use the values directly
-set(CCCL_REPOSITORY "nvidia/cccl" CACHE STRING "GitHub repository to fetch CCCL from")
+set(CCCL_REPOSITORY "https://github.com/NVIDIA/cccl" CACHE STRING "Git 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_REPOSITORY "${CCCL_REPOSITORY}"
     GIT_TAG ${CCCL_TAG}
 )
 
diff --git a/examples/cudax/CMakeLists.txt b/examples/cudax/CMakeLists.txt
@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
 
 project(CUDAX_SAMPLES CUDA CXX)
 
@@ -23,13 +23,13 @@ include(cmake/CPM.cmake)
 
 # We define these as variables so they can be overridden in CI to pull from a PR instead of CCCL `main`
 # In your project, these variables are unnecessary and you can just use the values directly
-set(CCCL_REPOSITORY "nvidia/cccl" CACHE STRING "GitHub repository to fetch CCCL from")
+set(CCCL_REPOSITORY "https://github.com/NVIDIA/cccl" CACHE STRING "Git 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_REPOSITORY "${CCCL_REPOSITORY}"
   GIT_TAG ${CCCL_TAG}
   GIT_SHALLOW ON
   # The following is required to make the `CCCL::cudax` target available:
diff --git a/examples/cudax_stf/CMakeLists.txt b/examples/cudax_stf/CMakeLists.txt
@@ -13,19 +13,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
 
 project(CUDAX_SAMPLES CUDA CXX)
 
 # 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 overridden in CI to pull from a PR instead of CCCL `main`
+# In your project, these variables are unnecessary and you can just use the values directly
+set(CCCL_REPOSITORY "https://github.com/NVIDIA/cccl" CACHE STRING "Git 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 "nvidia/cccl"
-  GIT_TAG "main"
+  GIT_REPOSITORY "${CCCL_REPOSITORY}"
+  GIT_TAG ${CCCL_TAG}
   # The following is required to make the `CCCL::cudax` target available:
   OPTIONS "CCCL_ENABLE_UNSTABLE ON"
 )
diff --git a/examples/thrust_flexible_device_system/CMakeLists.txt b/examples/thrust_flexible_device_system/CMakeLists.txt
@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 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 demo provides an example of how to configure a project to use Thrust while selecting
+# the device system as a configuration option. The device system is selected by setting the
+# CMake option `CCCL_THRUST_DEVICE_SYSTEM={CUDA, OMP, TBB, CPP}` for CUDA, OpenMP, Intel Threading
+# Building Blocks (TBB), and serial C++, respectively. If no option is provided, the default is `CUDA`.
+#
+# See the accompanying README.md for more information and build instructions.
+
+cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
+
+project(ThrustFlexibleDeviceSystemDemo CXX)
+
+# 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 overridden in CI to pull from a PR instead of CCCL `main`
+# In your project, these variables are unnecessary and you can just use the values directly
+set(CCCL_REPOSITORY "https://github.com/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.
+# The default `CCCL::Thrust` target will be configured to use the system device defined by
+# `CCCL_THRUST_DEVICE_SYSTEM`.
+CPMAddPackage(
+    NAME CCCL
+    GIT_REPOSITORY "${CCCL_REPOSITORY}"
+    GIT_TAG ${CCCL_TAG}
+)
+
+# CUDA specific setup
+if (CCCL_THRUST_DEVICE_SYSTEM STREQUAL "CUDA")
+  # Need to explicitly enable the CUDA language for the project.
+  # Note that the project(...) command earlier only enables CXX by default.
+  enable_language(CUDA)
+
+  # Compile for the native CUDA arch if not specified:
+  if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+    set(CMAKE_CUDA_ARCHITECTURES native)
+  endif()
+endif()
+
+# Creates a cmake executable target for the main program
+add_executable(example_program example.cpp)
+ # Thrust requires at least C++17:
+target_compile_features(example_program PUBLIC cuda_std_17 cxx_std_17)
+
+# By default, CMake inspects the source file extension to determine whether to use C++ or CUDA
+# compilers. We can override this behavior by using source file properties. Here, we tell CMake
+# to compile this C++ (.cpp) file with the CUDA compiler when using the CUDA device system:
+if (CCCL_THRUST_DEVICE_SYSTEM STREQUAL "CUDA")
+  set_source_files_properties(example.cpp PROPERTIES LANGUAGE CUDA)
+endif()
+
+# "Links" the CCCL Cmake target to the `example_program` executable. This configures everything needed to use
+# CCCL headers, including setting up include paths, compiler flags, Thrust host/device configuration, etc.
+target_link_libraries(example_program PRIVATE CCCL::CCCL)
+
+# This is only relevant for internal testing and not needed by end users.
+include(CTest)
+enable_testing()
+add_test(NAME example_program COMMAND example_program)
+set_tests_properties(example_program PROPERTIES
+  PASS_REGULAR_EXPRESSION "Detected device system: ${CCCL_THRUST_DEVICE_SYSTEM}"
+)
diff --git a/examples/thrust_flexible_device_system/README.md b/examples/thrust_flexible_device_system/README.md
@@ -0,0 +1,45 @@
+# Thrust Flexible Device System Example
+
+This example illustrates best practices for writing generic CMake that supports user-configuration of the Thrust device system via the `CCCL_THRUST_DEVICE_SYSTEM` CMake option.
+
+Valid values for this option are:
+
+- `CUDA`
+- `OMP` (OpenMP)
+- `TBB` (Intel Thread Building Blocks)
+- `CPP` (Serial C++ backend)
+
+The CMakeLists.txt file for this example is annotated to show how to achieve a generic build system that supports any of device system.
+
+## How To Use This Example
+
+Configure and build this example as follows:
+
+```
+# Checkout example and prepare build directory:
+git clone https://github.com/NVIDIA/cccl.git
+cd cccl/thrust_flexible_device_system
+mkdir build
+cd build
+
+# Configure:
+cmake .. -DCCCL_THRUST_DEVICE_SYSTEM=CUDA # or TBB, OMP, CPP
+
+# Build:
+cmake --build .
+
+# Run:
+ctest -V
+```
+
+## Advanced Thrust Usecases
+
+For more control over the Thrust configuration, see the Thrust CMake package's [README.md](../../lib/cmake/thrust/README.md).
+This details how to use the `thrust_create_target` function to generate Thrust interface targets in CMake.
+
+If using `thrust_create_target` directly, you may also want to set the CMake option `CCCL_ENABLE_DEFAULT_THRUST_TARGET=OFF` to prevent the default `CCCL::Thrust` target from being initialized.
+This will avoid checking for any dependencies required for the default target that may be unnecessary for your project.
+
+## Further Reading About CCCL + CMake
+
+The `basic` example's [README.md](../basic/README.md) has additional information that you may find useful for using CCCL with CPM and CMake.
diff --git a/examples/thrust_flexible_device_system/cmake/CPM.cmake b/examples/thrust_flexible_device_system/cmake/CPM.cmake
diff --git a/examples/thrust_flexible_device_system/example.cpp b/examples/thrust_flexible_device_system/example.cpp
diff --git a/lib/cmake/thrust/README.md b/lib/cmake/thrust/README.md
