From 759440d9ffd8e7971fdce5ac40d2968f15bd88c3 Mon Sep 17 00:00:00 2001 From: Robert Maynard Date: Wed, 5 May 2021 14:23:34 -0400 Subject: [PATCH] Add support for building sphinx based documentation for the project --- .gitignore | 1 + README.md | 16 +- docs/Makefile | 20 +++ docs/api.rst | 87 ++++++++++ docs/basics.rst | 33 ++++ docs/command/rapids_cmake_build_type.rst | 1 + docs/command/rapids_cmake_make_global.rst | 1 + .../rapids_cmake_support_conda_env.rst | 1 + docs/command/rapids_cpm_find.rst | 1 + docs/command/rapids_cpm_init.rst | 1 + .../rapids_cuda_init_architectures.rst | 1 + docs/command/rapids_cuda_init_runtime.rst | 1 + .../command/rapids_cuda_set_architectures.rst | 1 + docs/command/rapids_export.rst | 1 + docs/command/rapids_export_cpm.rst | 1 + .../rapids_export_find_package_file.rst | 1 + docs/command/rapids_export_package.rst | 1 + .../rapids_export_write_dependencies.rst | 1 + docs/command/rapids_export_write_language.rst | 1 + docs/command/rapids_find_generate_module.rst | 1 + docs/command/rapids_find_package.rst | 1 + docs/conf.py | 133 +++++++++++++++ docs/index.rst | 19 +++ rapids-cmake/cmake/build_type.cmake | 18 +-- rapids-cmake/cmake/make_global.cmake | 30 ++-- rapids-cmake/cmake/support_conda_env.cmake | 31 ++-- rapids-cmake/cpm/find.cmake | 80 +++++----- rapids-cmake/cpm/init.cmake | 20 ++- rapids-cmake/cuda/init_architectures.cmake | 58 ++++--- rapids-cmake/cuda/init_runtime.cmake | 2 +- rapids-cmake/cuda/set_architectures.cmake | 38 ++--- rapids-cmake/export/cpm.cmake | 30 ++-- rapids-cmake/export/export.cmake | 127 ++++++++++----- rapids-cmake/export/find_package_file.cmake | 18 +-- rapids-cmake/export/package.cmake | 23 +-- rapids-cmake/export/write_dependencies.cmake | 24 ++- rapids-cmake/export/write_language.cmake | 25 +-- rapids-cmake/find/generate_module.cmake | 151 +++++++++--------- rapids-cmake/find/package.cmake | 65 ++++---- testing/utils/cmake_test.cmake | 2 +- 40 files changed, 744 insertions(+), 323 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/api.rst create mode 100644 docs/basics.rst create mode 100644 docs/command/rapids_cmake_build_type.rst create mode 100644 docs/command/rapids_cmake_make_global.rst create mode 100644 docs/command/rapids_cmake_support_conda_env.rst create mode 100644 docs/command/rapids_cpm_find.rst create mode 100644 docs/command/rapids_cpm_init.rst create mode 100644 docs/command/rapids_cuda_init_architectures.rst create mode 100644 docs/command/rapids_cuda_init_runtime.rst create mode 100644 docs/command/rapids_cuda_set_architectures.rst create mode 100644 docs/command/rapids_export.rst create mode 100644 docs/command/rapids_export_cpm.rst create mode 100644 docs/command/rapids_export_find_package_file.rst create mode 100644 docs/command/rapids_export_package.rst create mode 100644 docs/command/rapids_export_write_dependencies.rst create mode 100644 docs/command/rapids_export_write_language.rst create mode 100644 docs/command/rapids_find_generate_module.rst create mode 100644 docs/command/rapids_find_package.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/.gitignore b/.gitignore index a33518f0..e01e6ca3 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ ## C++ test build directory build/ example/build/ +docs/_build ## Eclipse IDE .project diff --git a/README.md b/README.md index ff258ae1..f13b5c07 100644 --- a/README.md +++ b/README.md @@ -83,22 +83,14 @@ The most commonly used function are: The `rapids-export` module contains core functionality to allow projects to easily record and write out build and install dependencies, that come from `find_package` or `cpm` -- `rapids_export_package( )` Explicitly record a `find_package` call for `install` - or `build` exporting. Used by `rapids_export` to generate a correct config module. -- `rapids_export_cpm( )` Explicitly record a `cpm` call for `install` or `build` - exporting. Used by `rapids_export` to generate a correct config module. -- `rapids_export_find_package_file( )` Explicitly record a custom `Find.cmake` - file that is required for the `install` or `build` export set. Used by `rapids_export` to correctly install - custom FindModules. -- `rapids_export( EXPORT_SET )` write out all the require components of a projects config - module so that the `install` or `build` directory can be imported via `find_package`. See `rapids_export` - documentation for full documentation +- `rapids_export( EXPORT_SET )` write out all the require components of a + projects config module so that the `install` or `build` directory can be imported via `find_package`. See `rapids_export` documentation for full documentation ### find -The `rapids-find` module contains core functionality to allow projects to easily generate FindModule or export -`find_package` calls: +The `rapids-find` module contains core functionality to allow projects to easily generate FindModule +or export `find_package` calls: The most commonly used function are: diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 00000000..623f8beb --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,87 @@ +API Reference +############# + + +Common +****** + +The `rapids_cmake` functions provide common CMake logic that numerous projects +require. + +.. toctree:: + :titlesonly: + + /command/rapids_cmake_build_type + /command/rapids_cmake_make_global + /command/rapids_cmake_support_conda_env + +CPM +*** + +The `rapids_cpm` functions allow projects to find or build dependencies with built-in +tracking of these dependencies for correct export support. + +.. toctree:: + :titlesonly: + + /command/rapids_cpm_init + /command/rapids_cpm_find + +Find +**** + +The `rapids_find` functions allow projects to find system dependencies with built-in +tracking of these dependencies for correct export support. + +.. toctree:: + :titlesonly: + + /command/rapids_find_generate_module + /command/rapids_find_package + +CUDA +**** + +The `rapids_cuda` functions provide common CMake CUDA logic that numerous projects +require. + +.. toctree:: + :titlesonly: + + rapids_cuda_init_architectures + rapids_cuda_init_runtime + rapids_cuda_set_architectures [Advanced] + + +Export Set Generation +********************* + +These `rapids_export` functions allow projects to generate correct build and install tree `Project-Config.cmake` modules including required dependencies. + +For the vast majority of projects :cmake:command:`rapids_export` should be sufficient. But when +not projects may use commands such as :cmake:command:`rapids_write_dependencies` and +cmake:command:`rapids_write_language` to create a custom `Project-Config.cmake`. + + +.. toctree:: + :maxdepth: 1 + + rapids_export + rapids_export_write_dependencies [Advanced] + rapids_export_write_language [Advanced] + +Export Set Tracking +******************* + +These `rapids_export` functions allow projects to track track dependencies for +correct export generation. These should only be used when :cmake:command:`rapids_find_package`, +:cmake:command:`rapids_cpm_find`, or :cmake:command:`rapids_find_generate_module` are insufficient. + + +.. toctree:: + :titlesonly: + + rapids_export_cpm [Advanced] + rapids_export_find_package_file [Advanced] + rapids_export_package [Advanced] + diff --git a/docs/basics.rst b/docs/basics.rst new file mode 100644 index 00000000..a5a18074 --- /dev/null +++ b/docs/basics.rst @@ -0,0 +1,33 @@ +rapids-cmake +############ + +This is a collection of CMake modules that are useful for all CUDA RAPIDS +projects. By sharing the code in a single place it makes rolling out CMake +fixes easier. + + +Installation +************ + +The ``rapids-cmake`` module is designed to be acquired via CMake's `Fetch +Content `_ into your project. + +.. code-block:: cmake + + cmake_minimum_required(...) + + include(FetchContent) + FetchContent_Declare( + rapids-cmake + GIT_REPOSITORY https://github.com/rapidsai/rapids-cmake.git + GIT_TAG branch-. + ) + FetchContent_MakeAvailable(rapids-cmake) + include(rapids-cmake) + include(rapids-cpm) + include(rapids-cuda) + include(rapids-export) + include(rapids-find) + + project(...) + diff --git a/docs/command/rapids_cmake_build_type.rst b/docs/command/rapids_cmake_build_type.rst new file mode 100644 index 00000000..0215b412 --- /dev/null +++ b/docs/command/rapids_cmake_build_type.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/cmake/build_type.cmake diff --git a/docs/command/rapids_cmake_make_global.rst b/docs/command/rapids_cmake_make_global.rst new file mode 100644 index 00000000..f3c04273 --- /dev/null +++ b/docs/command/rapids_cmake_make_global.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/cmake/make_global.cmake diff --git a/docs/command/rapids_cmake_support_conda_env.rst b/docs/command/rapids_cmake_support_conda_env.rst new file mode 100644 index 00000000..1f039318 --- /dev/null +++ b/docs/command/rapids_cmake_support_conda_env.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/cmake/support_conda_env.cmake diff --git a/docs/command/rapids_cpm_find.rst b/docs/command/rapids_cpm_find.rst new file mode 100644 index 00000000..316d8d84 --- /dev/null +++ b/docs/command/rapids_cpm_find.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/cpm/find.cmake diff --git a/docs/command/rapids_cpm_init.rst b/docs/command/rapids_cpm_init.rst new file mode 100644 index 00000000..3833e304 --- /dev/null +++ b/docs/command/rapids_cpm_init.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/cpm/init.cmake diff --git a/docs/command/rapids_cuda_init_architectures.rst b/docs/command/rapids_cuda_init_architectures.rst new file mode 100644 index 00000000..77eabdbd --- /dev/null +++ b/docs/command/rapids_cuda_init_architectures.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/cuda/init_architectures.cmake diff --git a/docs/command/rapids_cuda_init_runtime.rst b/docs/command/rapids_cuda_init_runtime.rst new file mode 100644 index 00000000..77eabdbd --- /dev/null +++ b/docs/command/rapids_cuda_init_runtime.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/cuda/init_architectures.cmake diff --git a/docs/command/rapids_cuda_set_architectures.rst b/docs/command/rapids_cuda_set_architectures.rst new file mode 100644 index 00000000..cad95074 --- /dev/null +++ b/docs/command/rapids_cuda_set_architectures.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/cuda/set_architectures.cmake diff --git a/docs/command/rapids_export.rst b/docs/command/rapids_export.rst new file mode 100644 index 00000000..37620658 --- /dev/null +++ b/docs/command/rapids_export.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/export/export.cmake diff --git a/docs/command/rapids_export_cpm.rst b/docs/command/rapids_export_cpm.rst new file mode 100644 index 00000000..55f8e2cd --- /dev/null +++ b/docs/command/rapids_export_cpm.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/export/cpm.cmake diff --git a/docs/command/rapids_export_find_package_file.rst b/docs/command/rapids_export_find_package_file.rst new file mode 100644 index 00000000..d352babd --- /dev/null +++ b/docs/command/rapids_export_find_package_file.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/export/find_package_file.cmake diff --git a/docs/command/rapids_export_package.rst b/docs/command/rapids_export_package.rst new file mode 100644 index 00000000..f7edd13f --- /dev/null +++ b/docs/command/rapids_export_package.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/export/package.cmake diff --git a/docs/command/rapids_export_write_dependencies.rst b/docs/command/rapids_export_write_dependencies.rst new file mode 100644 index 00000000..199203c1 --- /dev/null +++ b/docs/command/rapids_export_write_dependencies.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/export/write_dependencies.cmake diff --git a/docs/command/rapids_export_write_language.rst b/docs/command/rapids_export_write_language.rst new file mode 100644 index 00000000..161ea4e1 --- /dev/null +++ b/docs/command/rapids_export_write_language.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/export/write_language.cmake diff --git a/docs/command/rapids_find_generate_module.rst b/docs/command/rapids_find_generate_module.rst new file mode 100644 index 00000000..5209dd8c --- /dev/null +++ b/docs/command/rapids_find_generate_module.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/find/generate_module.cmake diff --git a/docs/command/rapids_find_package.rst b/docs/command/rapids_find_package.rst new file mode 100644 index 00000000..1b82e923 --- /dev/null +++ b/docs/command/rapids_find_package.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../rapids-cmake/find/package.cmake diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..60e0e041 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,133 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os + +# -- Project information ----------------------------------------------------- + +project = "rapids-cmake" +copyright = "2021, NVIDIA" +author = "NVIDIA" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = "0.20" +# The full version, including alpha/beta/rc tags. +release = "0.20.0" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + +extensions = [ + "sphinx.ext.intersphinx", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx_copybutton", + "sphinxcontrib.moderncmakedomain" +] + + +copybutton_prompt_text = ">>> " + +ipython_mplbackend = "str" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst'] +source_suffix = {".rst": "restructuredtext"} + +# The master toctree document. +master_doc = "index" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# + +html_theme = "sphinx_pydata_theme" + +# on_rtd is whether we are on readthedocs.org +on_rtd = os.environ.get("READTHEDOCS", None) == "True" + +if not on_rtd: + # only import and set the theme if we're building docs locally + # otherwise, readthedocs.org uses their theme by default, + # so no need to specify it + import sphinx_rtd_theme + + html_theme = "sphinx_rtd_theme" + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = "rapidscmakedoc" + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {"https://docs.python.org/": None} + +# Config numpydoc +numpydoc_show_inherited_class_members = True +numpydoc_class_members_toctree = False + +autoclass_content = "init" + + +def setup(app): + app.add_js_file("copybutton_pydocs.js") + app.add_css_file("params.css") + app.add_css_file("https://docs.rapids.ai/assets/css/custom.css") diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..4d90e83a --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,19 @@ +.. rapids-cmake documentation file + +Welcome to rapids-cmake's documentation! +=============================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + basics.rst + api.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/rapids-cmake/cmake/build_type.cmake b/rapids-cmake/cmake/build_type.cmake index d9ba196a..dbf661d6 100644 --- a/rapids-cmake/cmake/build_type.cmake +++ b/rapids-cmake/cmake/build_type.cmake @@ -20,26 +20,24 @@ include_guard(GLOBAL) rapids_cmake_build_type ----------------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -Establish the :variable:`CMAKE_BUILD_TYPE` default value for the project if the user -hasn't specified one and the generator is either Ninja or Makefile. - -.. command:: rapids_cmake_build_type +Establish the :cmake:variable:`CMAKE_BUILD_TYPE` default value. .. code-block:: cmake rapids_cmake_build_type(default_type) - If the generator is `Ninja` or `Makefile` the :variable:`CMAKE_BUILD_TYPE` - variable will be established if it doesn't already exist. +If the generator is `Ninja` or `Makefile` the :cmake:variable:`CMAKE_BUILD_TYPE` +variable will be established if not explicitly set by the user. This removes +situations where the `No-Config` / `Empty` build type is used. - ``default_type`` - The default build type to use if one doesn't already exist +``default_type`` + The default build type to use if one doesn't already exist Result Variables ^^^^^^^^^^^^^^^^ - CMAKE_BUILD_TYPE will be set to ``default_type`` if not already set + :cmake:variable:`CMAKE_BUILD_TYPE` will be set to ``default_type`` if not already set #]=======================================================================] function(rapids_cmake_build_type default_type) diff --git a/rapids-cmake/cmake/make_global.cmake b/rapids-cmake/cmake/make_global.cmake index 7d934fd3..bd644aea 100644 --- a/rapids-cmake/cmake/make_global.cmake +++ b/rapids-cmake/cmake/make_global.cmake @@ -18,22 +18,32 @@ include_guard(GLOBAL) #[=======================================================================[.rst: rapids_cmake_make_global ------------------------ +------------------------ -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 - If a target is imported via `find_package` or `CPM` make it global so - everything can reference it no-matter where it was imported +Make sure all provided targets have global visibility no matter how they +are constructed. -.. command:: rapids_cmake_make_global - - .. code-block:: cmake +.. code-block:: cmake rapids_cmake_make_global(target_var) - ``target_var`` - Holds the variable that lists all targets that should be promoted to - GLOBAL scope + +CMake targets have visibility or scope where they can be referenced by name. +Any built-in target such as those created by :cmake:command:`add_library` have +global visibility. Targets created with :cmake:command:`add_library(IMPORTED)` by +default have directory visibility. This causes problems when trying to reason +about targets created by `CPM`, as they could be either of the above. + +This function promotes the set of targets provided to have global visibility. +This makes it easier for users to reason about when/where they can reference +the targets. + + +``target_var`` + Holds the variable that lists all targets that should be promoted to + GLOBAL scope #]=======================================================================] function(rapids_cmake_make_global target_var) diff --git a/rapids-cmake/cmake/support_conda_env.cmake b/rapids-cmake/cmake/support_conda_env.cmake index f8a169f8..63a24f0d 100644 --- a/rapids-cmake/cmake/support_conda_env.cmake +++ b/rapids-cmake/cmake/support_conda_env.cmake @@ -20,37 +20,36 @@ include_guard(GLOBAL) rapids_cmake_support_conda_env ------------------------------ -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -Establish a target that holds the CONDA enviornment include and link directories. - -.. command:: rapids_cmake_support_conda_env +Establish a target that holds the CONDA include and link directories. .. code-block:: cmake rapids_cmake_support_conda_env( [MODIFY_PREFIX_PATH] ) - Creates a global interface target called `target_name` that holds - the CONDA include and link directories, when executed +Creates a global interface target called `target_name` that holds +the CONDA include and link directories, when executed - Also offers the ability to modify :variable:`CMAKE_PREFIX_PATH` to - include the paths in enviornment variables `BUILD_PREFIX`, `PREFIX`, - and `CONDA_PREFIX` based on the current CONDA enviornment. +Also offers the ability to modify :cmake:variable:`CMAKE_PREFIX_PATH` to +include the paths in enviornment variables `BUILD_PREFIX`, `PREFIX`, +and `CONDA_PREFIX` based on the current CONDA enviornment. - ``MODIFY_PREFIX_PATH`` - When in a conda build enviornment the contents of `$ENV{BUILD_PREFIX}` and `$ENV{PREFIX}` - will be inserted to the front of :variable:`CMAKE_PREFIX_PATH`. +``MODIFY_PREFIX_PATH`` + When in a conda build enviornment the contents of `$ENV{BUILD_PREFIX}` and `$ENV{PREFIX}` + will be inserted to the front of :cmake:variable:`CMAKE_PREFIX_PATH`. - When in a conda enviornment the contents of `$ENV{CONDA_PREFIX}` will be inserted to - th front of :variable:`CMAKE_PREFIX_PATH`. + When in a conda enviornment the contents of `$ENV{CONDA_PREFIX}` will be inserted to + th front of :cmake:variable:`CMAKE_PREFIX_PATH`. Result Variables ^^^^^^^^^^^^^^^^ - CMAKE_PREFIX_PATH will be modifed when `MODIFY_PREFIX_PATH` is provided + :cmake:variable:`CMAKE_PREFIX_PATH` will be modifed when `MODIFY_PREFIX_PATH` is provided + and called from a conda enviornment Result Targets ^^^^^^^^^^^^^^^^ - Will be created only if called from a conda enviornment + `target_name` target will be created only if called from a conda enviornment #]=======================================================================] function(rapids_cmake_support_conda_env target) diff --git a/rapids-cmake/cpm/find.cmake b/rapids-cmake/cpm/find.cmake index e2a982bf..2df447f4 100644 --- a/rapids-cmake/cpm/find.cmake +++ b/rapids-cmake/cpm/find.cmake @@ -19,54 +19,62 @@ include_guard(GLOBAL) rapids_cpm_find --------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -.. command:: rapids_cpm_find +Allow projects to find or build a dependency via `CPM` with built-in +tracking of these dependencies for correct export support. - .. code-block:: cmake +.. code-block:: cmake - rapids_cpm_find( - [GLOBAL_TARGETS ] - [BUILD_EXPORT_SET ] - [INSTALL_EXPORT_SET ] - - all normal CPM options - ) + rapids_cpm_find( + [GLOBAL_TARGETS ] + [BUILD_EXPORT_SET ] + [INSTALL_EXPORT_SET ] + + all normal CPM options + ) - Generate a CPMFindPackage call and associate relevant information - to the provided build and install exports. +Generate a CPM FindPackage call and associate this with the listed +build and install export set for correct export generation. - Note: - Adding an export set to `rapids_cpm_find` has different behavior - for build and install. Build exports a respective CPM call, since - we presume other CPM packages don't generate a correct build directory - config module. While install exports a `find_dependency` call as - we expect projects to have a valid install setup. +Since the visibility of CMake's targets differ between targets built locally and those +imported, :cmake:command:`rapids_cpm_find` promotes imported targets to be global so users have +consistency. List all targets used by your project in `GLOBAL_TARGET`. - If you need different behavior you will need to use `rapids_export_package()` - or `rapids_export_cpm()`. +.. note:: + Requires :cmake:command:`rapids_cpm_init` to be called before usage - ``PackageName`` - Name of the package to find. +.. note:: + Adding an export set to :cmake:command:`rapids_cpm_find` has different behavior + for build and install. Build exports a respective CPM call, since + we presume other CPM packages don't generate a correct build directory + config module. While install exports a `find_dependency` call as + we expect projects to have a valid install setup. - ``version`` - Version of the package you would like CPM to find. + If you need different behavior you will need to use :cmake:command:`rapids_export_package()` + or :cmake:command:`rapids_export_cpm()`. - ``GLOBAL_TARGETS`` - Which targets from this package should be made global. This information - will be propagated to any associated export set. +``PackageName`` + Name of the package to find. - ``BUILD_EXPORT_SET`` - Record that a `CPMFindPackage( ...) call needs to occur as part of - our build directory export set. +``version`` + Version of the package you would like CPM to find. - ``INSTALL_EXPORT_SET`` - Record a `find_dependency( ...) call needs to occur as part of - our build directory export set. +``GLOBAL_TARGETS`` + Which targets from this package should be made global. This information + will be propagated to any associated export set. - ``CPM_ARGS`` - Required placeholder to be provied before any extra arguments that need to - be passed down to `CPMFindPackage`. +``BUILD_EXPORT_SET`` + Record that a :cmake:command:`CPMFindPackage( ...)` call needs to occur as part of + our build directory export set. + +``INSTALL_EXPORT_SET`` + Record a :cmake:command:`find_dependency( ...)` call needs to occur as part of + our build directory export set. + +``CPM_ARGS`` + Required placeholder to be provied before any extra arguments that need to + be passed down to :cmake:command:`CPMFindPackage`. #]=======================================================================] diff --git a/rapids-cmake/cpm/init.cmake b/rapids-cmake/cpm/init.cmake index 8d680cb6..bc9ded6c 100644 --- a/rapids-cmake/cpm/init.cmake +++ b/rapids-cmake/cpm/init.cmake @@ -20,23 +20,21 @@ include_guard(GLOBAL) rapids_cpm_init ------------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 Establish the `CPM` infrastructure for the project. -.. command:: rapids_cpm_init +.. code-block:: cmake - .. code-block:: cmake + rapids_cpm_init() - rapids_cpm_init(default_type) +The CPM module will be downloaded based on the state of :cmake:variable:`CPM_SOURCE_CACHE` and +:cmake:variable:`ENV{CPM_SOURCE_CACHE}`. This allows multiple nested projects to share the +same download of CPM. If those variables aren't set the file will be cached +in the build tree of the calling project - Establish the `CPM` module for the project. Must be called before - any invocation of `rapids_cpm_`. - - The CPM module will be downloaded based on the state of `CPM_SOURCE_CACHE` and - `ENV{CPM_SOURCE_CACHE}`. This allows multiple nested projects to share the - same download of CPM. If those variables aren't set the file will be cached - in the build tree of the calling project +.. note:: + Must be called before any invocation of :cmake:command:`rapids_cpm_find`. #]=======================================================================] function(rapids_cpm_init ) diff --git a/rapids-cmake/cuda/init_architectures.cmake b/rapids-cmake/cuda/init_architectures.cmake index fa501311..160a2718 100644 --- a/rapids-cmake/cuda/init_architectures.cmake +++ b/rapids-cmake/cuda/init_architectures.cmake @@ -20,34 +20,56 @@ include_guard(GLOBAL) rapids_cuda_init_architectures ------------------------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -Sets up RAPIDS special handling of :variable:`CMAKE_CUDA_ARCHITECTURES` and -establishes CUDA architecture compilation for all CUDA targets - -Note: Required to be called before `project()` -Note: Will automatically call `rapids_cuda_set_architectures()` - -.. command:: rapids_cuda_init_architectures +Extends :cmake:variable:`CMAKE_CUDA_ARCHITECTURES` to include support +for `ALL` and `NATIVE` to make CUDA architecture compilation easier. .. code-block:: cmake rapids_cuda_init_architectures() - Establishes what CUDA architectures that will be compiled for. Parses the :variable:`CMAKE_CUDA_ARCHITECTURES` - for special values "ALL", "NATIVE", and "". +Establishes what CUDA architectures that will be compiled for. +Parses the :cmake:variable:`CMAKE_CUDA_ARCHITECTURES` for special +values `ALL`, `NATIVE` and `""`. + +.. note:: + Required to be called before :cmake:command:`project()` + + Will automatically call :cmake:command:`rapids_cuda_set_architectures` immediately + after :cmake:command:`project()` establishing the correct values for + :cmake:variable:`CMAKE_CUDA_ARCHITECTURES`. + +``project_name`` + Name of the project + +``NATIVE`` or ``""``: + When passed will compile for all GPU architectures present on the current machine + +``ALL``: + When passed will compile for all supported RAPIDS GPU architectures + + +Example on how to properly use :cmake:command:`rapids_cuda_init_architectures`: + +.. code-block:: cmake + + cmake_minimum_required(...) + + include(FetchContent) + FetchContent_Declare( + rapids-cmake + GIT_REPOSITORY https://github.com/rapidsai/rapids-cmake.git + GIT_TAG branch-. + ) + FetchContent_MakeAvailable(rapids-cmake) + include(rapids-cuda) - ``NATIVE`` or ``""``: - When passed will compile for all GPU architectures present on the current machine + rapids_cuda_init_architectures(ExampleProject) + project(ExampleProject ...) - ``ALL``: - When passed will compile for all supported RAPIDS GPU architectures - Note: Required to be called before `project()` - Note: Will automatically call `rapids_cuda_set_architectures()` - ``project_name`` - Name of the project #]=======================================================================] function(rapids_cuda_init_architectures project_name) diff --git a/rapids-cmake/cuda/init_runtime.cmake b/rapids-cmake/cuda/init_runtime.cmake index eaf090ac..7687e565 100644 --- a/rapids-cmake/cuda/init_runtime.cmake +++ b/rapids-cmake/cuda/init_runtime.cmake @@ -20,7 +20,7 @@ include_guard(GLOBAL) rapids_cuda_init_runtime ------------------------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 Establish what CUDA runtime library should be propagated diff --git a/rapids-cmake/cuda/set_architectures.cmake b/rapids-cmake/cuda/set_architectures.cmake index 8e054dac..0ad58897 100644 --- a/rapids-cmake/cuda/set_architectures.cmake +++ b/rapids-cmake/cuda/set_architectures.cmake @@ -20,37 +20,39 @@ include_guard(GLOBAL) rapids_cuda_set_architectures ------------------------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -Finishes setting up :variable:`CMAKE_CUDA_ARCHITECTURES` based on the output -state of `rapids_cuda_init_architectures`. +Sets up :cmake:variable:`CMAKE_CUDA_ARCHITECTURES` based on the requested mode -Note: Is automatically called by `rapids_cuda_init_architectures` +.. code-block:: cmake -.. command:: rapids_cuda_set_architectures + rapids_cuda_set_architectures( (NATIVE|ALL) ) - .. code-block:: cmake +Establishes what CUDA architectures that will be compiled for, overriding +any existing :cmake:variable:`CMAKE_CUDA_ARCHITECTURES` value. - rapids_cuda_set_architectures( (NATIVE|ALL) ) +This function should rarely be used, as :cmake:command:`rapids_cuda_init_architectures` +allows for the expected workflow of using :cmake:variable:`CMAKE_CUDA_ARCHITECTURES` +when configuring a project. If for some reason your project can't use +:cmake:command:`rapids_cuda_init_architectures` than you can use :cmake:command:`rapids_cuda_set_architectures` +directly. - Establishes what CUDA architectures that will be compiled for. +.. note:: + This is automatically called by :cmake:command:`rapids_cuda_init_architectures` - Note: Is automatically called by `rapids_cuda_init_architectures` - - ``NATIVE``: - When passed NATIVE as the first parameter will compile for all - GPU architectures present on the current machine. Requires that - the CUDA language be enabled for the current CMake project. - - ``ALL``: - When passed ALL will compile for all supported RAPIDS GPU architectures +``NATIVE``: + When passed NATIVE as the first parameter will compile for all + GPU architectures present on the current machine. Requires that + the CUDA language be enabled for the current CMake project. +``ALL``: + When passed ALL will compile for all supported RAPIDS GPU architectures Result Variables ^^^^^^^^^^^^^^^^ ``CMAKE_CUDA_ARCHITECTURES`` will exist and set to the list of architectures - that should be compiled for + that should be compiled for. Will overwrite any existing values. #]=======================================================================] function(rapids_cuda_set_architectures mode) diff --git a/rapids-cmake/export/cpm.cmake b/rapids-cmake/export/cpm.cmake index f2417b67..2897ec4e 100644 --- a/rapids-cmake/export/cpm.cmake +++ b/rapids-cmake/export/cpm.cmake @@ -18,21 +18,33 @@ rapids_export_cpm ----------------- +.. versionadded:: v21.06.00 + Record a given found by `CPMFindPackage` is required for a given export set -.. versionadded:: 0.20 +.. code-block:: cmake + + rapids_export_cpm( (build|install) + + + CPM_ARGS + [GLOBAL_TARGETS ] + ) + -.. command:: rapids_export_cpm +Records a given found by `CPMFindPackage` is required for a +given export set. - .. code-block:: cmake +This means that when :cmake:command:`rapids_export` or +`:cmake:command:`rapids_export_write_dependencies` is called the `CPMFindPackage` +call will be replicated for consumers. - rapids_export_cpm( (build|install) - - - CPM_ARGS - [GLOBAL_TARGETS ] - ) +.. note:: + It is an anti-pattern to use this command with `INSTALL` as most CMake + based projects should be installed, and :cmake:command:`rapids_export_package(INSTALL` used + to find it. Only use :cmake:command:`rapids_export_cpm(INSTALL` when the above pattern + doesn't work for some reason. #]=======================================================================] function(rapids_export_cpm type name export_set) diff --git a/rapids-cmake/export/export.cmake b/rapids-cmake/export/export.cmake index 8f0455ef..d5de65f9 100644 --- a/rapids-cmake/export/export.cmake +++ b/rapids-cmake/export/export.cmake @@ -19,63 +19,108 @@ include_guard(GLOBAL) rapids_export --------------------- +.. versionadded:: v21.06.00 + Generate a projects -Config.cmake module and all related information -.. versionadded:: 0.20 +.. code-block:: cmake -.. command:: rapids_export_language + rapids_export( (build|install) + EXPORT_SET + [ GLOBAL_TARGETS ] + [ LANGUAGES ] + [ NAMESPACE ] + [ DOCUMENTATION ] + [ FINAL_CODE_BLOCK ] + ) - .. code-block:: cmake +The :cmake:command:`rapids_export` function allow projects to easily generate a fully +correct build and install tree `Project-Config.cmake` module including any necessary +calls to :cmake:command:`find_dependency`, or :cmake:command:`CPMFindPackage`. - rapids_export_language( (build|install) - EXPORT_SET - [GLOBAL_TARGETS ] - [ LANGUAGES ] - [ NAMESPACE ] - [ DOCUMENTATION ] - [ FINAL_CODE_BLOCK ] - ) +.. note: + The files generated by :cmake:command:`rapids_export` are completly standalone + and don't require the consuming package to use `rapids-cmake` - Generate a projects -Config.cmake module and all related information - ... +``project_name`` + Name of the project, to be used by consumers when using `find_package` + +``GLOBAL_TARGETS`` + Explicitly list what targets should be made globally visibile to + the consuming project. + +``LANGUAGES`` + Non default languages, such as CUDA that are required by consumers + of your package. This makes sure all consumers properly setup these + languages correctly. - ``project_name`` - Name of the project, to be used by consumers when using `find_package` + This is required as CMake's :cmake:command:`enable_language` only supports + enabling languages for the current directory scope, and doesn't support + being called from within functions. Marking languages here overcomes + these limitations and makes it possible for packages included via + `CPM` to enable languages. - ``GLOBAL_TARGETS`` - Explicitly list what targets should be made globally visibile to - the consuming project. +``NAMESPACE`` + Optional value to specify what namespace all targets from the + EXPORT_SET will be placed into. When provided must match the pattern + of `::`. + If not provided all targets will be placed in the `::` + namespace - ``LANGUAGES`` - Non C or C++ languages, such as CUDA that are required by consumers - of your package. This makes sure all consumers properly setup these - languages correctly, critically important when consuming packages - via `CPM`. + Note: When exporting with `BUILD` type, only `GLOBAL_TARGETS` will + be placed in the namespace. - ``NAMESPACE`` - Optional value to specify what namespace all targets from the - EXPORT_SET will be placed into. When provided must match the pattern - of `::`. - If not provided all targets will be placed in the `::` - namespace +``DOCUMENTATION`` + Optional value of the variable that holds the documentation + for this config file. - Note: When exporting with `BUILD` type, only `GLOBAL_TARGETS` will - be placed in the namespace. + Note: This requires the documentation variable instead of the contents + so we can handle having CMake code inside the documentation - ``DOCUMENTATION`` - Optional value of the variable that holds the documentation - for this config file. +``FINAL_CODE_BLOCK`` + Optional value of the variable that holds a string of code that will + be executed at the last step of this config file. - Note: This requires the documentation variable instead of the contents - so we can handle having CMake code inside the documentation + Note: This requires the code block variable instead of the contents + so that we can properly insert CMake code - ``FINAL_CODE_BLOCK`` - Optional value of the variable that holds a string of code that will - be executed at the last step of this config file. - Note: This requires the code block variable instead of the contents - so that we can properly insert CMake code +Example on how to properly use :cmake:command:`rapids_export`: + +.. code-block:: cmake + + ... + add_library(example STATIC source.cu) + target_compile_features(example PUBLIC $) + + install(TARGETS example + DESTINATION lib + EXPORT example-targets + ) + + set(doc_string [=[Provide targets for the example library.]=]) + + set(code_string [=[ message(STATUS "hi from example-config")]=]) + + rapids_export(INSTALL example + EXPORT_SET example-targets + GLOBAL_TARGETS example # Need to list all targets from `install(TARGETS` + NAMESPACE example:: + DOCUMENTATION doc_string + FINAL_CODE_BLOCK code_string + ) + + rapids_export(BUILD example + EXPORT_SET example-targets + GLOBAL_TARGETS example # Need to list all targets from `install(TARGETS` + # CUDA language support is a build detail only, as target_compile_features + # guards the language behind `BUILD_INTERFACE` generator expression + LANGUAGES CUDA + NAMESPACE example:: + DOCUMENTATION doc_string + FINAL_CODE_BLOCK code_string + ) #]=======================================================================] diff --git a/rapids-cmake/export/find_package_file.cmake b/rapids-cmake/export/find_package_file.cmake index 0f932b7d..fded45b2 100644 --- a/rapids-cmake/export/find_package_file.cmake +++ b/rapids-cmake/export/find_package_file.cmake @@ -18,19 +18,17 @@ rapids_export_cpm ----------------- -Record a given found by `CPMFindPackage` is required for a -given export set - -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -.. command:: rapids_export_find_package_file +Record a given found by :cmake:command:`CPMFindPackage` is required for a +given export set - .. code-block:: cmake +.. code-block:: cmake - rapids_export_find_package_file( (build|install) - - - ) + rapids_export_find_package_file( (build|install) + + + ) #]=======================================================================] function(rapids_export_find_package_file type file_path export_set) diff --git a/rapids-cmake/export/package.cmake b/rapids-cmake/export/package.cmake index ee6cf9ec..7791cd7d 100644 --- a/rapids-cmake/export/package.cmake +++ b/rapids-cmake/export/package.cmake @@ -18,20 +18,25 @@ rapids_export_package --------------------- -Record a given found by `find_package` is required for a +.. versionadded:: v21.06.00 + +Record a given found by :cmake:command:`find_package` is required for a given export set -.. versionadded:: 0.20 +.. code-block:: cmake -.. command:: rapids_export_package + rapids_export_package( (build|install) + + + [GLOBAL_TARGETS ] + ) - .. code-block:: cmake +Records a given found by :cmake:command:`find_package` is required for a +given export set. - rapids_export_package( (build|install) - - - [GLOBAL_TARGETS ] - ) +This means that when :cmake:command:`rapids_export` or +`:cmake:command:`rapids_export_write_dependencies` is called a +:cmake:command:`find_dependency` call will be replicated for consumers. #]=======================================================================] function(rapids_export_package type name export_set) diff --git a/rapids-cmake/export/write_dependencies.cmake b/rapids-cmake/export/write_dependencies.cmake index 428fea51..c23740ad 100644 --- a/rapids-cmake/export/write_dependencies.cmake +++ b/rapids-cmake/export/write_dependencies.cmake @@ -16,15 +16,29 @@ #[=======================================================================[.rst: rapids_export_write_dependencies ---------------------- +-------------------------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -.. command:: rapids_export_write_dependencies +.. code-block:: cmake - .. code-block:: cmake +Creates a self-containted file that searches for all dependencies for a given +export set. - rapids_export_write_dependencies( (BUILD|INSTALL) ) + rapids_export_write_dependencies( (BUILD|INSTALL) ) + +Generates a self-contained file that will search for all dependencies of +a given export_set for the requested mode. + +``BUILD`` + Will generate calls for all build directory export set + +``INSTALL`` + Will generate calls for all install directory export set + +.. note:: + It is better to use :cmake:command:`rapids_export` as it generates a complete + CMake config module. #]=======================================================================] function(rapids_export_write_dependencies type export_set file_path) diff --git a/rapids-cmake/export/write_language.cmake b/rapids-cmake/export/write_language.cmake index 77dbd15c..2825d172 100644 --- a/rapids-cmake/export/write_language.cmake +++ b/rapids-cmake/export/write_language.cmake @@ -16,26 +16,33 @@ #[=======================================================================[.rst: rapids_export_write_language ---------------------- +---------------------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -.. command:: rapids_export_write_language +Creates a self-containted file that makes sure the requested language is enabled +globally. - .. code-block:: cmake +.. code-block:: cmake - rapids_export_write_language( (build|install) (CXX|CUDA|...) ) + rapids_export_write_language( (build|install) (CXX|CUDA|...) ) - Creates the logic required to make sure that a language is enabled - by consuming projects. - Since CMake requires `enable_language` to be executed in the root directory, - but when projects are imported via `CPM` or in a subdirectory this won't occur +The contents of `` will be a self-contained file that when called +via :cmake:command:`include` will make sure the requested language is enabled +globally. +This is required as CMake's :cmake:command:`enable_language` only supports +enabling languages for the current directory scope, and doesn't support +being called from within functions. These limitations make it impossible +for packages included via `CPM` to enable extra languages. + +.. note:: This uses some serious CMake black magic to make sure that `enable_language` occurs both at the call site, and up the entire `add_subdirectory` stack so the language is enabled globally. + #]=======================================================================] function(rapids_export_write_language type lang file_path) list(APPEND CMAKE_MESSAGE_CONTEXT "rapids.export.write_language") diff --git a/rapids-cmake/find/generate_module.cmake b/rapids-cmake/find/generate_module.cmake index 2cda1226..d1444fa0 100644 --- a/rapids-cmake/find/generate_module.cmake +++ b/rapids-cmake/find/generate_module.cmake @@ -22,88 +22,85 @@ cmake_policy(VERSION 3.20) rapids_find_generate_module -------------- -Generate a Find*.cmake module for the requested package - -.. versionadded:: 0.20 - -.. command:: rapids_find_generate_module - - .. code-block:: cmake - - rapids_find_generate_module( - HEADER_NAMES - [LIBRARY_NAMES ] - [INCLUDE_SUFFIXES ] - [VERSION ] - [NO_CONFIG] - [BUILD_EXPORT_SET ] - [INSTALL_EXPORT_SET ] - ) - - Generates a custom Find module for the requested package. Makes - it easier for projects to look for packages that don't have - an exisiting FindModule or don't provide a CONFIG module - when installed. - - Note: - If you are using this for a module that is part of - your BUILD or INSTALL export set, it is highly likely - that this needs to be part of the same export sets. - - +.. versionadded:: v21.06.00 - ``HEADER_NAMES`` - Header names that should be provided to `find_path` to - determine the include directory of the package. If provided - a list of names only one needs to be found for a directory - to be considered a match - - ``LIBRARY_NAMES`` - library names that should be provided to `find_library` to - determine the include directory of the package. If provided - a list of names only one needs to be found for a directory - to be considered a match - - Note: - Every entry that doesn't start with `lib` will also be - searched for as `lib` - - ``INCLUDE_SUFFIXES`` - Extra relative sub-directories to use while searching for `HEADER_NAMES`. - - ``VERSION`` - Will append extra entries of the library to search for based on the - content of `LIBRARY_NAMES`: - - - - . - - lib - - lib. - - :Note - This ordering is done explicitly to follow CMake recommendations - for searching for versioned libraries: - - "We recommend specifying the unversioned name first so that locally-built packages - can be found before those provided by distributions." - - ``NO_CONFIG`` - When provied will stop the generated Find Module from - first searching for the projects shipped Find Config. - - ``BUILD_EXPORT_SET`` - Record that this custom FindPackage module needs to be part - of our build directory export set. This means that it will be - usable by the calling package if it needs to search for - again. +Generate a Find*.cmake module for the requested package - ``INSTALL_EXPORT_SET`` - Record that this custom FindPackage module needs to be part - of our install export set. This means that it will be installed as - part of our packages CMake infrastructure +.. code-block:: cmake + + rapids_find_generate_module( + HEADER_NAMES + [LIBRARY_NAMES ] + [INCLUDE_SUFFIXES ] + [VERSION ] + [NO_CONFIG] + [BUILD_EXPORT_SET ] + [INSTALL_EXPORT_SET ] + ) + +Generates a custom Find module for the requested package. Makes +it easier for projects to look for packages that don't have +an exisiting FindModule or don't provide a CONFIG module +when installed. + +.. note:: + If you are using this for a module that is part of + your BUILD or INSTALL export set, it is highly likely + that this needs to be part of the same export sets. + + +``HEADER_NAMES`` + Header names that should be provided to :cmake:command:`find_path` to + determine the include directory of the package. If provided + a list of names only one needs to be found for a directory + to be considered a match + +``LIBRARY_NAMES`` + library names that should be provided to :cmake:command:`find_library` to + determine the include directory of the package. If provided + a list of names only one needs to be found for a directory + to be considered a match + + .. note:: + Every entry that doesn't start with `lib` will also be + searched for as `lib` + +``INCLUDE_SUFFIXES`` + Extra relative sub-directories to use while searching for `HEADER_NAMES`. + +``VERSION`` + Will append extra entries of the library to search for based on the + content of `LIBRARY_NAMES`: + - + - . + - lib + - lib. + + This ordering is done explicitly to follow CMake recommendations + for searching for versioned libraries: + + "We recommend specifying the unversioned name first so that locally-built packages + can be found before those provided by distributions." + +``NO_CONFIG`` + When provied will stop the generated Find Module from + first searching for the projects shipped Find Config. + +``BUILD_EXPORT_SET`` + Record that this custom FindPackage module needs to be part + of our build directory export set. This means that it will be + usable by the calling package if it needs to search for + again. + +``INSTALL_EXPORT_SET`` + Record that this custom FindPackage module needs to be part + of our install export set. This means that it will be installed as + part of our packages CMake export set infrastructure Result Variables ^^^^^^^^^^^^^^^^ - CMAKE_BUILD_TYPE will be set to ``default_type`` if not already set + :cmake:variable:`CMAKE_MODULE_PATH` will be modifed to include the + folder where `Find.cmake` is located. #]=======================================================================] function(rapids_find_generate_module name) diff --git a/rapids-cmake/find/package.cmake b/rapids-cmake/find/package.cmake index 22bc4ada..0744d215 100644 --- a/rapids-cmake/find/package.cmake +++ b/rapids-cmake/find/package.cmake @@ -19,46 +19,51 @@ include_guard(GLOBAL) rapids_find_package -------------- -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 -.. command:: rapids_find_package +Allow projects to find dependencies via `find_package` with built-in +tracking of these dependencies for correct export support. - .. code-block:: cmake +.. code-block:: cmake - rapids_find_package( - [REQUIRED] - [GLOBAL_TARGETS ] - [BUILD_EXPORT_SET ] - [INSTALL_EXPORT_SET ] - [ - all normal find_package options ] - ) + rapids_find_package( + [REQUIRED] + [GLOBAL_TARGETS ] + [BUILD_EXPORT_SET ] + [INSTALL_EXPORT_SET ] + [ + all normal find_package options ] + ) - Generate a `find_package` call and associate relevant information - to the provided build and install exports. +Generate a :cmake:command:`find_package` call and associate this with the listed +build and install export set for correct export generation. - Note: - If the project/package you are looking for doesn't have an existing - CMake Find module, please look at using `rapids_find_generate_module`. +Since the visibility of CMake's targets differ between targets built locally and those +imported, :cmake:command:`rapids_find_package` promotes imported targets to be global +so users have consistency. List all targets used by your project in `GLOBAL_TARGET`. - ``PackageName`` - Name of the package to find. +.. note:: + If the project/package you are looking for doesn't have an existing + CMake Find module, please look at using :cmake:command:`rapids_find_generate_module`. - ``GLOBAL_TARGETS`` - Which targets from this package should be made global. This information - will be propagated to any associated export set. +``PackageName`` + Name of the package to find. - ``BUILD_EXPORT_SET`` - Record that a `find_dependency() call needs to occur as part of - our build directory export set. +``GLOBAL_TARGETS`` + Which targets from this package should be made global. This information + will be propagated to any associated export set. - ``INSTALL_EXPORT_SET`` - Record that a `find_dependency() call needs to occur as part of - our build directory export set. +``BUILD_EXPORT_SET`` + Record that a :cmake:command:`find_dependency()` call needs to occur + as part of our build directory export set. - ``FIND_ARGS`` - Required placeholder to be provied before any extra arguments that need to - be passed down to `find_pacakge` +``INSTALL_EXPORT_SET`` + Record that a :cmake:command:`find_dependency()` call needs to occur + as part of our build directory export set. + +``FIND_ARGS`` + Required placeholder to be provied before any extra arguments that need to + be passed down to cmake:command:`find_pacakge` #]=======================================================================] diff --git a/testing/utils/cmake_test.cmake b/testing/utils/cmake_test.cmake index 85e4ae47..989ae549 100644 --- a/testing/utils/cmake_test.cmake +++ b/testing/utils/cmake_test.cmake @@ -21,7 +21,7 @@ add_cmake_build_test generate a CMake tests given either a single CMake file or a directory. -.. versionadded:: 0.20 +.. versionadded:: v21.06.00 .. command:: add_cmake_build_test