Skip to content

Commit eb2a6c0

Browse files
robertmaynardrobertmaynard
committed
Update to add even more examples
1 parent 71a0083 commit eb2a6c0

35 files changed

Lines changed: 998 additions & 10 deletions

File tree

‎examples/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,22 @@ This directory contains examples demonstrating key features of rapids-cmake.
44

55
## Available Examples
66

7+
### [project-bootstrap](project-bootstrap/)
8+
Demonstrates the complete RAPIDS project initialization pattern used by ALL production RAPIDS projects:
9+
- `VERSION` file - Project version in YY.MM.PP format
10+
- `RAPIDS_BRANCH` file - rapids-cmake branch specification
11+
- `cmake/rapids_config.cmake` - Parse version files and set variables
12+
- `cmake/RAPIDS.cmake` - FetchContent-based rapids-cmake bootstrap
13+
14+
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?".
15+
16+
### [conda-support](conda-support/)
17+
Demonstrates conda environment integration for proper builds within conda:
18+
- `rapids_cmake_support_conda_env()` - Create target with conda compile/link settings
19+
- `MODIFY_PREFIX_PATH` - Automatically configure CMAKE_PREFIX_PATH for conda
20+
21+
Shows how to set up proper conda environment support including include directories, library paths, rpath-link, and build optimization overrides.
22+
723
### [cuda-features](cuda-features/)
824
Demonstrates core CUDA-specific rapids-cmake features:
925
- `rapids_cuda_init_architectures()` - Initialize CUDA architectures before project()
@@ -16,9 +32,17 @@ Demonstrates the rapids-cmake export system for creating reusable CMake packages
1632
- `rapids_export()` - Generate BUILD and INSTALL exports
1733
- `rapids_find_package()` - Find dependencies and track in export sets
1834
- `rapids_cpm_find()` - Fetch dependencies via CPM and add to export sets
35+
- `rapids_cmake_install_lib_dir()` - CONDA-aware library installation directory
1936

2037
Shows how to create a library that can be consumed by downstream projects via find_package().
2138

39+
### [find-generate-module](find-generate-module/)
40+
Demonstrates generating and installing FindModule files for dependencies without CMake support:
41+
- `rapids_find_generate_module()` - Generate FindModule for packages lacking CMake config
42+
- Export FindModules with your package for downstream dependency resolution
43+
44+
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.
45+
2246
### [project-override](project-override/)
2347
Demonstrates conditional dependency version overrides using CMake presets:
2448
- `RAPIDS_CMAKE_CPM_OVERRIDE_VERSION_FILE` - CMake variable to specify override file
@@ -27,6 +51,22 @@ Demonstrates conditional dependency version overrides using CMake presets:
2751

2852
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.
2953

54+
### [version-header](version-header/)
55+
Demonstrates generating C++ version headers from CMake project version:
56+
- `rapids_cmake_write_version_file()` - Generate version header with macros
57+
- Integration with project() VERSION command
58+
- Version information accessible at runtime in C++ code
59+
60+
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.
61+
62+
### [third-party-dependencies](third-party-dependencies/)
63+
Demonstrates the cmake/thirdparty/ organization pattern for managing dependencies at scale:
64+
- `cmake/thirdparty/get_fmt.cmake` - Simple dependency pattern (like cuVS's hnswlib)
65+
- `cmake/thirdparty/get_spdlog.cmake` - Dependency with custom PATCH_COMMAND
66+
- One file per dependency for organization and maintainability
67+
68+
Shows the professional dependency organization pattern used by ALL RAPIDS projects. This pattern scales from small projects to large ones (cuDF manages 15+ dependencies this way). Critical for maintainability as projects grow.
69+
3070
### [pin-dependencies](pin-dependencies/)
3171
Demonstrates dependency pinning for reproducible builds:
3272
- `rapids_cpm_init(GENERATE_PINNED_VERSIONS)` - Generate pinned versions file

‎examples/conda-support/CMakeLists.txt‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# =============================================================================
2+
# cmake-format: off
3+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
4+
# SPDX-License-Identifier: Apache-2.0
5+
# cmake-format: on
6+
# =============================================================================
7+
8+
cmake_minimum_required(VERSION 3.30.4 FATAL_ERROR)
9+
10+
# When running under rapids-cmake testing infrastructure, rapids-cmake-dir is already set and we
11+
# should use the local version instead of downloading RAPIDS.cmake
12+
if(NOT DEFINED rapids-cmake-dir)
13+
if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
14+
file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/main/RAPIDS.cmake
15+
${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
16+
endif()
17+
set(rapids-cmake-branch main)
18+
include(${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
19+
else()
20+
# Test mode: Set up CMAKE_MODULE_PATH to use local rapids-cmake
21+
if(NOT "${rapids-cmake-dir}" IN_LIST CMAKE_MODULE_PATH)
22+
list(APPEND CMAKE_MODULE_PATH "${rapids-cmake-dir}")
23+
endif()
24+
endif()
25+
26+
include(rapids-cmake)
27+
include(rapids-cuda)
28+
29+
rapids_cuda_init_architectures(conda_support_example)
30+
31+
project(conda_support_example VERSION 1.0 LANGUAGES CXX CUDA)
32+
33+
rapids_cmake_build_type(Release)
34+
35+
# Create conda environment support target This target provides: - Conda include directories (as
36+
# SYSTEM to match conda behavior) - Conda library directories - Proper rpath-link settings for conda
37+
# environments - Debug build optimization override (-O0 instead of conda's -O2) - File prefix
38+
# remapping for reproducible builds
39+
rapids_cmake_support_conda_env(conda_env MODIFY_PREFIX_PATH)
40+
41+
# Create a simple CUDA library
42+
add_library(conda_support_lib SHARED lib.cu)
43+
44+
set_target_properties(conda_support_lib
45+
PROPERTIES CXX_STANDARD 17
46+
CXX_STANDARD_REQUIRED ON
47+
CUDA_STANDARD 17
48+
CUDA_STANDARD_REQUIRED ON
49+
POSITION_INDEPENDENT_CODE ON)
50+
51+
# Link the conda environment target if it exists The target is only created when running in a conda
52+
# environment
53+
if(TARGET conda_env)
54+
target_link_libraries(conda_support_lib PRIVATE conda_env)
55+
message(STATUS "Conda environment support enabled")
56+
else()
57+
message(STATUS "Not in conda environment - conda support target not created")
58+
endif()
59+
60+
# Create an executable that uses the library
61+
add_executable(conda_support_example main.cu)
62+
target_link_libraries(conda_support_example PRIVATE conda_support_lib)
63+
64+
set_target_properties(conda_support_example PROPERTIES CXX_STANDARD 17 CXX_STANDARD_REQUIRED ON
65+
CUDA_STANDARD 17 CUDA_STANDARD_REQUIRED ON)
66+
67+
if(TARGET conda_env)
68+
target_link_libraries(conda_support_example PRIVATE conda_env)
69+
endif()

‎examples/conda-support/lib.cu‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
// =============================================================================
2+
// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
3+
// SPDX-License-Identifier: Apache-2.0
4+
// =============================================================================
5+
6+
#include <cstdio>
7+
8+
void conda_support_function() { printf("conda-support example library\n"); }

‎examples/conda-support/main.cu‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// =============================================================================
2+
// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
3+
// SPDX-License-Identifier: Apache-2.0
4+
// =============================================================================
5+
6+
#include <cstdio>
7+
8+
extern void conda_support_function();
9+
10+
int main()
11+
{
12+
printf("conda-support example\n");
13+
conda_support_function();
14+
return 0;
15+
}

‎examples/cuda-features/CMakeLists.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# =============================================================================
22
# cmake-format: off
3-
# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
3+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
44
# SPDX-License-Identifier: Apache-2.0
55
# cmake-format: on
66
# =============================================================================

‎examples/cuda-features/main.cu‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION. All rights reserved.
2+
* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION. All rights reserved.
33
* SPDX-License-Identifier: Apache-2.0
44
*/
55

‎examples/export-feature/CMakeLists.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# =============================================================================
22
# cmake-format: off
3-
# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
3+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
44
# SPDX-License-Identifier: Apache-2.0
55
# cmake-format: on
66
# =============================================================================
@@ -66,8 +66,8 @@ set_target_properties(export_example
6666
# Link dependencies
6767
target_link_libraries(export_example PUBLIC CUDA::cudart PRIVATE fmt::fmt)
6868

69-
# Installation rules
70-
include(GNUInstallDirs)
69+
# Installation rules - use rapids_cmake_install_lib_dir for CONDA-aware lib directory
70+
rapids_cmake_install_lib_dir(lib_dir MODIFY_INSTALL_LIBDIR)
7171
install(TARGETS export_example
7272
EXPORT export_example_targets
7373
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}

‎examples/export-feature/lib.cu‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION. All rights reserved.
2+
* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION. All rights reserved.
33
* SPDX-License-Identifier: Apache-2.0
44
*/
55

‎examples/find-generate-module/CMakeLists.txt‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# =============================================================================
2+
# cmake-format: off
3+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
4+
# SPDX-License-Identifier: Apache-2.0
5+
# cmake-format: on
6+
# =============================================================================
7+
8+
cmake_minimum_required(VERSION 3.30.4 FATAL_ERROR)
9+
10+
# When running under rapids-cmake testing infrastructure, rapids-cmake-dir is already set and we
11+
# should use the local version instead of downloading RAPIDS.cmake
12+
if(NOT DEFINED rapids-cmake-dir)
13+
if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
14+
file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/main/RAPIDS.cmake
15+
${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
16+
endif()
17+
set(rapids-cmake-branch main)
18+
include(${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
19+
else()
20+
# Test mode: Set up CMAKE_MODULE_PATH to use local rapids-cmake
21+
if(NOT "${rapids-cmake-dir}" IN_LIST CMAKE_MODULE_PATH)
22+
list(APPEND CMAKE_MODULE_PATH "${rapids-cmake-dir}")
23+
endif()
24+
endif()
25+
26+
include(rapids-cmake)
27+
include(rapids-export)
28+
include(rapids-find)
29+
30+
project(find_generate_module_example VERSION 1.0 LANGUAGES CXX)
31+
32+
rapids_cmake_build_type(Release)
33+
34+
# ##################################################################################################
35+
# WHY use rapids_find_generate_module?
36+
# ##################################################################################################
37+
#
38+
# Problem: Your library depends on a third-party package (e.g., "SimpleLib") that: 1. Doesn't
39+
# provide a CMake config file (simplelib-config.cmake) 2. Doesn't have a standard
40+
# FindSimpleLib.cmake module
41+
#
42+
# Solution: Generate a FindSimpleLib.cmake module that: 1. Searches for the package's headers and
43+
# libraries 2. Creates proper CMake targets 3. Is INSTALLED with your package so downstream users
44+
# can find SimpleLib too
45+
#
46+
# why: - Without this, downstream projects can't use find_package(YourPackage) because they can't
47+
# find SimpleLib - The generated FindModule is included in your package's export sets - Downstream
48+
# projects automatically get the FindModule when they find_package(YourPackage)
49+
#
50+
# ##################################################################################################
51+
52+
# For this example, we'll use ZLIB which DOES have a FindModule, but we'll pretend it doesn't to
53+
# demonstrate the pattern.
54+
55+
# STEP 1: Generate the FindModule
56+
# ================================
57+
# This creates FindMyZLIB.cmake and adds it to export sets
58+
rapids_find_generate_module(MyZLIB
59+
HEADER_NAMES zlib.h # Required: headers to search for
60+
LIBRARY_NAMES z # Optional: libraries to search for
61+
INCLUDE_SUFFIXES include # Optional: extra search paths
62+
BUILD_EXPORT_SET example_exports # Add to build export
63+
INSTALL_EXPORT_SET example_exports # Add to install export
64+
)
65+
66+
# STEP 2: Find the package using the generated module
67+
# ====================================================
68+
# This uses the FindMyZLIB.cmake we just generated
69+
rapids_find_package(MyZLIB REQUIRED BUILD_EXPORT_SET example_exports
70+
INSTALL_EXPORT_SET example_exports)
71+
72+
# STEP 3: Create your library that uses the dependency
73+
# =====================================================
74+
add_library(example_lib lib.cpp)
75+
76+
set_target_properties(example_lib
77+
PROPERTIES CXX_STANDARD 17
78+
CXX_STANDARD_REQUIRED ON
79+
POSITION_INDEPENDENT_CODE ON
80+
VERSION ${PROJECT_VERSION}
81+
SOVERSION ${PROJECT_VERSION_MAJOR})
82+
83+
# Link against the found package
84+
target_link_libraries(example_lib PUBLIC MyZLIB::MyZLIB)
85+
86+
# STEP 4: Install the library and headers
87+
# ========================================
88+
include(GNUInstallDirs)
89+
90+
install(TARGETS example_lib EXPORT example_exports LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
91+
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
92+
93+
# STEP 5: Export the package (FindMyZLIB.cmake is automatically included!)
94+
# =========================================================================
95+
set(doc_string
96+
[=[
97+
Provide targets for the find_generate_module_example library.
98+
99+
This example demonstrates why rapids_find_generate_module is important:
100+
101+
The example_lib library depends on MyZLIB. When downstream projects call:
102+
find_package(find_generate_module_example)
103+
104+
They automatically get:
105+
1. The FindMyZLIB.cmake module (installed with this package)
106+
2. Ability to find MyZLIB using the generated module
107+
3. Proper transitive dependencies set up
108+
109+
WITHOUT rapids_find_generate_module:
110+
- Downstream projects would fail to configure
111+
- They couldn't find MyZLIB dependency
112+
- No way to use example_lib
113+
114+
WITH rapids_find_generate_module:
115+
- FindMyZLIB.cmake is installed alongside your package config
116+
- Downstream projects automatically find MyZLIB
117+
- Everything "just works"
118+
]=])
119+
120+
# Create install export (FindMyZLIB.cmake is included in export set)
121+
rapids_export(INSTALL find_generate_module_example
122+
EXPORT_SET example_exports
123+
GLOBAL_TARGETS example_lib
124+
NAMESPACE example::
125+
DOCUMENTATION doc_string)
126+
127+
# Create build export
128+
rapids_export(BUILD find_generate_module_example EXPORT_SET example_exports
129+
GLOBAL_TARGETS example_lib NAMESPACE example::)

‎examples/find-generate-module/lib.cpp‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// =============================================================================
2+
// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
3+
// SPDX-License-Identifier: Apache-2.0
4+
// =============================================================================
5+
6+
#include <cstdio>
7+
#include <zlib.h>
8+
9+
void find_generate_module_function()
10+
{
11+
printf("find-generate-module example\n");
12+
printf("zlib version: %s\n", zlibVersion());
13+
}

0 commit comments

Comments
 (0)