Update rapids-cmake to have a set of examples showing common patterns

examples/README.md

@@ -0,0 +1,101 @@
+# rapids-cmake Examples
+
+This directory contains examples demonstrating key features of rapids-cmake.
+
+## Available Examples
+
+### [project-bootstrap](project-bootstrap/)
+Demonstrates the complete RAPIDS project initialization pattern used by ALL production RAPIDS projects:
+- `VERSION` file - Project version in YY.MM.PP format
+- `RAPIDS_BRANCH` file - rapids-cmake branch specification
+- `cmake/rapids_config.cmake` - Parse version files and set variables
+- `cmake/RAPIDS.cmake` - FetchContent-based rapids-cmake bootstrap
+
+Shows how RAPIDS C++ projects are for set up for rapids-cmake. This is the first example you should read if you are wondering "How do I start a RAPIDS C++ project?".
+
+### [conda-support](conda-support/)
+Demonstrates conda environment integration for proper builds within conda:
+- `rapids_cmake_support_conda_env()` - Create target with conda compile/link settings
+- `MODIFY_PREFIX_PATH` - Automatically configure CMAKE_PREFIX_PATH for conda
+
+Shows how to set up proper conda environment support including include directories, library paths, rpath-link, and build optimization overrides.
+
+### [cuda-features](cuda-features/)
+Demonstrates core CUDA-specific rapids-cmake features:
+- `rapids_cuda_init_architectures()` - Initialize CUDA architectures before project()
+- `rapids_cmake_build_type()` - Set default build type
+- `rapids_cuda_init_runtime()` - Configure CUDA runtime (static/shared)
+- `rapids_cuda_enable_fatbin_compression()` - Enable fatbin compression with proper TARGET usage
+
+### [export-feature](export-feature/)
+Demonstrates the rapids-cmake export system for creating reusable CMake packages:
+- `rapids_export()` - Generate BUILD and INSTALL exports
+- `rapids_find_package()` - Find dependencies and track in export sets
+- `rapids_cpm_find()` - Fetch dependencies via CPM and add to export sets
+- `rapids_cmake_install_lib_dir()` - conda-aware library installation directory
+
+Shows how to create a library that can be consumed by downstream projects via find_package().
+
+### [find-generate-module](find-generate-module/)
+Demonstrates generating and installing FindModule files for dependencies without CMake support:
+- `rapids_find_generate_module()` - Generate FindModule for packages lacking CMake config
+- Export FindModules with your package for downstream dependency resolution
+
+Shows how projects can generate a custom Find Module to locate a dependency. Shows how to install said Find Module, so that downstream packages that depend on non-CMake-aware libraries will not fail to configure.
+
+### [project-override](project-override/)
+Demonstrates conditional dependency version overrides using CMake presets:
+- `RAPIDS_CMAKE_CPM_OVERRIDE_VERSION_FILE` - CMake variable to specify override file
+- `override.json` - JSON file specifying custom dependency versions (e.g., CCCL)
+- `CMakePresets.json` - Presets with and without overrides enabled
+
+Shows how to conditionally enable dependency overrides based on the selected CMake preset. The `default` preset uses standard versions, while `with-override` applies custom versions from override.json.
+
+### [version-header](version-header/)
+Demonstrates generating C++ version headers from CMake project version:
+- `rapids_cmake_write_version_file()` - Generate version header with macros
+- Integration with project() VERSION command
+- Version information accessible at runtime in C++ code
+
+Shows how to make project version available to C++ code through generated headers. This pattern is used by ALL RAPIDS projects (RMM, cuDF, cuVS) to provide version information for runtime checks, logging, and compatibility verification.
+
+### [third-party-dependencies](third-party-dependencies/)
+Demonstrates the cmake/thirdparty/ organization pattern for managing dependencies at scale:
+- `cmake/thirdparty/get_fmt.cmake` - Simple dependency pattern (like cuVS's hnswlib)
+- `cmake/thirdparty/get_spdlog.cmake` - Dependency with custom PATCH_COMMAND
+- One file per dependency for organization and maintainability
+
+Shows how RAPIDS projects organize third-party dependencies. This pattern scales from small projects to large ones (cuDF manages 15+ dependencies this way). Critical for maintainability as projects grow.
+
+### [pin-dependencies](pin-dependencies/)
+Demonstrates dependency pinning for reproducible builds:
+- `rapids_cpm_init(GENERATE_PINNED_VERSIONS)` - Generate pinned versions file
+- `pins.json` - Lock dependency versions for reproducibility
+- CMakePresets.json - Presets with and without pinned dependencies
+- `update_pins.sh` - Script to regenerate pinned versions
+
+Shows how to generate and use pinned dependency versions for reproducible builds.
+
+## Building Examples
+
+Each example can be built independently:
+
+```bash
+cd <example-directory>
+cmake -S . -B build
+cmake --build build
+```
+
+Some examples provide CMake presets:
+
+```bash
+cd <example-directory>
+cmake --preset <preset-name>
+cmake --build --preset <preset-name>
+```
+
+## Requirements
+
+- CMake 3.30.4 or later
+- CUDA Toolkit
+- C++17 compatible compiler

examples/conda-support/CMakeLists.txt

@@ -0,0 +1,73 @@
+# =============================================================================
+# cmake-format: off
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+# SPDX-License-Identifier: Apache-2.0
+# cmake-format: on
+# =============================================================================
+
+cmake_minimum_required(VERSION 3.30.4 FATAL_ERROR)
+
+# When running under rapids-cmake testing infrastructure, rapids-cmake-dir is already set and we
+# should use the local version instead of downloading RAPIDS.cmake
+if(NOT DEFINED rapids-cmake-dir)
+  if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
+    file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/main/RAPIDS.cmake
+         ${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
+  endif()
+  set(rapids-cmake-branch main)
+  include(${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
+else()
+  # Test mode: Set up CMAKE_MODULE_PATH to use local rapids-cmake
+  if(NOT "${rapids-cmake-dir}" IN_LIST CMAKE_MODULE_PATH)
+    list(APPEND CMAKE_MODULE_PATH "${rapids-cmake-dir}")
+  endif()
+endif()
+
+include(rapids-cmake)
+include(rapids-cuda)
+
+rapids_cuda_init_architectures(conda_support_example)
+
+# rapids-pre-commit-hooks: disable-next-line[verify-hardcoded-version]
+project(conda_support_example VERSION 1.0 LANGUAGES CXX CUDA)
+
+rapids_cmake_build_type(Release)
+
+# cmake-format: off
+# Create conda environment support target This target provides:
+# - Conda include directories (as SYSTEM to match conda behavior)
+# - Conda library directories
+# - Proper rpath-link settings for conda environments
+# - Debug build optimization override (-O0 instead of conda's -O2)
+# - File prefix remapping for reproducible builds
+# cmake-format: on
+rapids_cmake_support_conda_env(conda_env MODIFY_PREFIX_PATH)
+
+# Create a simple CUDA library
+add_library(conda_support_lib SHARED lib.cu)
+
+set_target_properties(conda_support_lib
+                      PROPERTIES CXX_STANDARD 20
+                                 CXX_STANDARD_REQUIRED ON
+                                 CUDA_STANDARD 20
+                                 CUDA_STANDARD_REQUIRED ON
+                                 POSITION_INDEPENDENT_CODE ON)
+
+# Link to the conda environment target if it exists
+if(TARGET conda_env)
+  target_link_libraries(conda_support_lib PRIVATE conda_env)
+  message(STATUS "Conda environment support enabled")
+else()
+  message(STATUS "Not in conda environment - conda support target not created")
+endif()
+
+# Create an executable that uses the library
+add_executable(conda_support_example main.cu)
+target_link_libraries(conda_support_example PRIVATE conda_support_lib)
+
+set_target_properties(conda_support_example PROPERTIES CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON
+                                                       CUDA_STANDARD 20 CUDA_STANDARD_REQUIRED ON)
+
+if(TARGET conda_env)
+  target_link_libraries(conda_support_example PRIVATE conda_env)
+endif()

examples/conda-support/lib.cu

@@ -0,0 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <cstdio>
+
+void conda_support_function() { printf("conda-support example library\n"); }

examples/conda-support/main.cu

@@ -0,0 +1,15 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <cstdio>
+
+extern void conda_support_function();
+
+int main()
+{
+  printf("conda-support example\n");
+  conda_support_function();
+  return 0;
+}

examples/cuda-features/CMakeLists.txt

@@ -0,0 +1,51 @@
+# =============================================================================
+# cmake-format: off
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+# SPDX-License-Identifier: Apache-2.0
+# cmake-format: on
+# =============================================================================
+
+cmake_minimum_required(VERSION 3.30.4 FATAL_ERROR)
+
+# When running under rapids-cmake testing infrastructure, rapids-cmake-dir is already set and we
+# should use the local version instead of downloading RAPIDS.cmake
+if(NOT DEFINED rapids-cmake-dir)
+  if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
+    file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/main/RAPIDS.cmake
+         ${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
+  endif()
+  set(rapids-cmake-branch main)
+  include(${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
+else()
+  # Test mode: Set up CMAKE_MODULE_PATH to use local rapids-cmake
+  if(NOT "${rapids-cmake-dir}" IN_LIST CMAKE_MODULE_PATH)
+    list(APPEND CMAKE_MODULE_PATH "${rapids-cmake-dir}")
+  endif()
+endif()
+
+include(rapids-cmake)
+include(rapids-cuda)
+include(${rapids-cmake-dir}/cuda/enable_fatbin_compression.cmake)
+
+# Initialize CUDA architectures before project() call
+rapids_cuda_init_architectures(cuda_features_example)
+
+# rapids-pre-commit-hooks: disable-next-line[verify-hardcoded-version]
+project(cuda_features_example VERSION 1.0 LANGUAGES CXX CUDA)
+
+option(CUDA_STATIC_RUNTIME "Use CUDA static runtime" OFF)
+
+# Set a default build type if none was specified
+rapids_cmake_build_type(Release)
+
+# Set the CUDA runtime that CUDA targets will use
+rapids_cuda_init_runtime(USE_STATIC ${CUDA_STATIC_RUNTIME})
+
+# Create a simple CUDA executable
+add_executable(cuda_features_example main.cu)
+
+set_target_properties(cuda_features_example PROPERTIES CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON
+                                                       CUDA_STANDARD 20 CUDA_STANDARD_REQUIRED ON)
+
+# Enable fatbin compression on the target
+rapids_cuda_enable_fatbin_compression(TARGET cuda_features_example)