Skip to content

Commit

Permalink
rapids_export version support expanded to handle more use-cases
Browse files Browse the repository at this point in the history
The rapids_export command now supports the following features:

Explicit version argument option. This allows projects to specify a
version when calling `rapids_export` instead of having it inferred
from the `project()` call.

Disabling of version exporting by passing `VERSION OFF`. This
removes the generation of any version related information to allow
for projects that don't have API/ABI version matching requirements

Projects that only have a MAJOR version number now don't try
to match on the exact Major.Minor value but instead on Major only
  • Loading branch information
robertmaynard committed Jul 19, 2021
1 parent e76246d commit 457cd90
Show file tree
Hide file tree
Showing 9 changed files with 393 additions and 42 deletions.
1 change: 1 addition & 0 deletions cmake-format-rapids-cmake.json
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@
"NAMESPACE": 1,
"DOCUMENTATION": 1,
"FINAL_CODE_BLOCK": 1,
"VERSION": 1,
"GLOBAL_TARGETS": "+",
"LANGUAGES": "+"
}
Expand Down
125 changes: 89 additions & 36 deletions rapids-cmake/export/export.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -28,17 +28,18 @@ Generate a projects -Config.cmake module and all related information
rapids_export( (BUILD|INSTALL) <project_name>
EXPORT_SET <export_set>
[ GLOBAL_TARGETS <targets...> ]
[ LANGUAGES <langs...> ]
[ VERSION <X.Y.Z> ]
[ NAMESPACE <name_space> ]
[ DOCUMENTATION <doc_variable> ]
[ FINAL_CODE_BLOCK <code_block_variable> ]
[ LANGUAGES <langs...> ]
)

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`.

.. note:
.. note::
The files generated by :cmake:command:`rapids_export` are completly standalone
and don't require the consuming package to use `rapids-cmake`

Expand All @@ -49,16 +50,31 @@ calls to :cmake:command:`find_dependency`, or :cmake:command:`CPMFindPackage`.
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.

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.
``VERSION``
Explicitly list the version of the package being exported. By
default :cmake:command:`rapids_export` uses the version specified by the
root level :cmake:command:`project` call. If no version has been specified
either way or `OFF` is provided as the `VERSION` value, no version compatibility
checks will be generated.

Depending on the version string different compatibility modes will be used.

+------------------+---------------------+
| Version String | Compatiblity Type |
+==================+=====================+
| None | No checks perfomed |
+------------------+---------------------+
| X | SameMajorVersion |
+------------------+---------------------+
| X.Y | SameMinorVersion |
+------------------+---------------------+
| X.Y.Z | SameMinorVersion |
+------------------+---------------------+

.. note::
It can be useful to explicitly specify a version string when generating
export rules for a sub-component of alarger project, or an external
project that doesn't have export rules.

``NAMESPACE``
Optional value to specify what namespace all targets from the
Expand All @@ -84,6 +100,17 @@ calls to :cmake:command:`find_dependency`, or :cmake:command:`CPMFindPackage`.
Note: This requires the code block variable instead of the contents
so that we can properly insert CMake code

``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.

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.


Example on how to properly use :cmake:command:`rapids_export`:

Expand Down Expand Up @@ -124,7 +151,7 @@ Example on how to properly use :cmake:command:`rapids_export`:


#]=======================================================================]
# cmake-lint: disable=R0915,W0105
# cmake-lint: disable=R0912,R0915,W0105
function(rapids_export type project_name)
include(GNUInstallDirs)
include(CMakePackageConfigHelpers)
Expand All @@ -133,14 +160,54 @@ function(rapids_export type project_name)
string(TOLOWER ${type} type)

set(options "")
set(one_value EXPORT_SET NAMESPACE DOCUMENTATION FINAL_CODE_BLOCK)
set(one_value EXPORT_SET VERSION NAMESPACE DOCUMENTATION FINAL_CODE_BLOCK)
set(multi_value GLOBAL_TARGETS LANGUAGES)
cmake_parse_arguments(RAPIDS "${options}" "${one_value}" "${multi_value}" ${ARGN})

if(NOT DEFINED RAPIDS_NAMESPACE)
set(RAPIDS_NAMESPACE "${project_name}::")
endif()

set(rapids_version_set ON)
if(DEFINED RAPIDS_VERSION AND NOT RAPIDS_VERSION)
# We need to capture `VERSION OFF` so we need to make sure it has an off value, and not just
# undefined
set(rapids_version_set OFF)
unset(RAPIDS_VERSION) # unset this so we don't export a version value of `OFF`
elseif(NOT DEFINED RAPIDS_VERSION AND NOT DEFINED PROJECT_VERSION)
set(rapids_version_set OFF)
elseif(DEFINED PROJECT_VERSION AND NOT DEFINED RAPIDS_VERSION)
# Choose the project version when an explicit version isn't provided
set(RAPIDS_VERSION "${PROJECT_VERSION}")
endif()

if(rapids_version_set)
include("${rapids-cmake-dir}/cmake/parse_version.cmake")
rapids_cmake_parse_version(MAJOR "${RAPIDS_VERSION}" rapdis_orig_major_version)
rapids_cmake_parse_version(MINOR "${RAPIDS_VERSION}" rapdis_orig_minor_version)
rapids_cmake_parse_version(PATCH "${RAPIDS_VERSION}" rapdis_orig_patch_version)

# Generate an explicit VERSION string without zeroes to work around:
# https://gitlab.kitware.com/cmake/cmake/-/issues/22207
set(rapids_version_compat SameMajorVersion)
if(rapdis_orig_major_version)
math(EXPR rapdis_major_version "${rapdis_orig_major_version} + 0" OUTPUT_FORMAT DECIMAL)
string(APPEND rapdis_project_version "${rapdis_major_version}")
endif()

if(rapdis_orig_minor_version)
math(EXPR rapdis_minor_version "${rapdis_orig_minor_version} + 0" OUTPUT_FORMAT DECIMAL)
string(APPEND rapdis_project_version ".${rapdis_minor_version}")
set(rapids_version_compat SameMinorVersion)
endif()

if(rapdis_orig_patch_version)
math(EXPR rapdis_patch_version "${rapdis_orig_patch_version} + 0" OUTPUT_FORMAT DECIMAL)
string(APPEND rapdis_project_version ".${rapdis_patch_version}")
set(rapids_version_compat SameMinorVersion)
endif()
endif()

set(RAPIDS_PROJECT_DOCUMENTATION "Generated ${project_name}-config module")
if(DEFINED RAPIDS_DOCUMENTATION)
set(RAPIDS_PROJECT_DOCUMENTATION "${${RAPIDS_DOCUMENTATION}}")
Expand All @@ -161,18 +228,11 @@ function(rapids_export type project_name)
"${scratch_dir}/${project_name}-config.cmake"
INSTALL_DESTINATION "${install_location}")

# Use explicit VERSION string without patch version to work around issue:
# https://gitlab.kitware.com/cmake/cmake/-/issues/22207 To do this we trim any leading zeroes
# from our major && minor version values as patch isn't used for compatibility.
string(REGEX REPLACE "^0+" "" version_minor "${PROJECT_VERSION_MINOR}")
string(REGEX REPLACE "^0+" "" version_major "${PROJECT_VERSION_MAJOR}")
set(rapdis_project_version "${version_major}.${version_minor}")
if(PROJECT_VERSION_PATCH)
string(APPEND rapdis_project_version ".${PROJECT_VERSION_PATCH}")
if(rapids_version_set)
write_basic_package_version_file(
"${scratch_dir}/${project_name}-config-version.cmake" VERSION ${rapdis_project_version}
COMPATIBILITY ${rapids_version_compat})
endif()
write_basic_package_version_file(
"${scratch_dir}/${project_name}-config-version.cmake" VERSION ${rapdis_project_version}
COMPATIBILITY SameMinorVersion)

install(EXPORT ${RAPIDS_EXPORT_SET} FILE ${project_name}-targets.cmake
NAMESPACE ${RAPIDS_NAMESPACE} DESTINATION "${install_location}")
Expand Down Expand Up @@ -200,18 +260,11 @@ function(rapids_export type project_name)
"${install_location}/${project_name}-config.cmake"
INSTALL_DESTINATION "${install_location}")

# Use explicit VERSION string without patch version to work around issue:
# https://gitlab.kitware.com/cmake/cmake/-/issues/22207 To do this we trim any leading zeroes
# from our major && minor version values as patch isn't used for compatibility.
string(REGEX REPLACE "^0+" "" version_minor "${PROJECT_VERSION_MINOR}")
string(REGEX REPLACE "^0+" "" version_major "${PROJECT_VERSION_MAJOR}")
set(rapdis_project_version "${version_major}.${version_minor}")
if(PROJECT_VERSION_PATCH)
string(APPEND rapdis_project_version ".${PROJECT_VERSION_PATCH}")
if(rapids_version_set)
write_basic_package_version_file(
"${install_location}/${project_name}-config-version.cmake" VERSION ${rapdis_project_version}
COMPATIBILITY ${rapids_version_compat})
endif()
write_basic_package_version_file(
"${install_location}/${project_name}-config-version.cmake" VERSION ${rapdis_project_version}
COMPATIBILITY SameMinorVersion)

export(EXPORT ${RAPIDS_EXPORT_SET} NAMESPACE ${RAPIDS_NAMESPACE}
FILE "${install_location}/${project_name}-targets.cmake")
Expand Down
12 changes: 7 additions & 5 deletions rapids-cmake/export/template/config.cmake.in
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,15 @@ if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/@[email protected]")
include("${CMAKE_CURRENT_LIST_DIR}/@[email protected]")
endif()

include("${CMAKE_CURRENT_LIST_DIR}/@[email protected]")
if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/@[email protected]")
include("${CMAKE_CURRENT_LIST_DIR}/@[email protected]")
endif()

# Set our version variables
set(@project_name_uppercase@_VERSION_MAJOR @PROJECT_VERSION_MAJOR@)
set(@project_name_uppercase@_VERSION_MINOR @PROJECT_VERSION_MINOR@)
set(@project_name_uppercase@_VERSION_PATCH @PROJECT_VERSION_PATCH@)
set(@project_name_uppercase@_VERSION @PROJECT_VERSION@)
set(@project_name_uppercase@_VERSION_MAJOR @rapdis_orig_major_version@)
set(@project_name_uppercase@_VERSION_MINOR @rapdis_orig_minor_version@)
set(@project_name_uppercase@_VERSION_PATCH @rapdis_orig_patch_version@)
set(@project_name_uppercase@_VERSION @RAPIDS_VERSION@)


set(rapids_global_targets @RAPIDS_GLOBAL_TARGETS@)
Expand Down
8 changes: 7 additions & 1 deletion testing/export/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,14 @@ add_cmake_config_test( export_cpm-options-escaped.cmake )
add_cmake_build_test( export-verify-build-namespaces )
add_cmake_build_test( export-verify-code-block )
add_cmake_build_test( export-verify-doc-string )
add_cmake_config_test( export-verify-calendar-version-matching.cmake )
add_cmake_config_test( export-verify-file-names.cmake )

add_cmake_config_test( export-verify-calendar-version-matching.cmake )
add_cmake_config_test( export-verify-explicit-disabled-version.cmake )
add_cmake_config_test( export-verify-explicit-major-version-only-matching.cmake )
add_cmake_config_test( export-verify-explicit-version-value.cmake )
add_cmake_config_test( export-verify-implicit-disabled-version.cmake )
add_cmake_config_test( export-verify-implicit-major-version-only-matching.cmake )
add_cmake_config_test( export-verify-version.cmake )

add_cmake_config_test( export_package-build.cmake )
Expand Down
58 changes: 58 additions & 0 deletions testing/export/export-verify-explicit-disabled-version.cmake
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
#=============================================================================
# Copyright (c) 2018-2021, NVIDIA CORPORATION.
#
# 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.
#=============================================================================
include(${rapids-cmake-dir}/export/cpm.cmake)
include(${rapids-cmake-dir}/export/export.cmake)

project(test LANGUAGES CXX VERSION 1.2)

add_library(fakeLib INTERFACE)
install(TARGETS fakeLib EXPORT fake_set)

rapids_export(BUILD test
VERSION OFF
EXPORT_SET fake_set
LANGUAGES CXX
)

# Verify that build files have correct names
if(NOT EXISTS "${CMAKE_BINARY_DIR}/test-config.cmake")
message(FATAL_ERROR "rapids_export failed to generate correct config file name")
endif()

# Verify that the version.cmake file doesn't exist as we don't have a
# version value
if(EXISTS "${CMAKE_BINARY_DIR}/test-config-version.cmake")
message(FATAL_ERROR "rapids_export incorrectly generated a version file")
endif()

set(CMAKE_PREFIX_PATH ${CMAKE_BINARY_DIR})
find_package(test REQUIRED)

if(DEFINED TEST_VERSION)
message(FATAL_ERROR "rapids_export incorrectly generated a version variable")
endif()

if(DEFINED TEST_VERSION_MAJOR)
message(FATAL_ERROR "rapids_export incorrectly generated a major version value")
endif()

if(DEFINED TEST_VERSION_MINOR)
message(FATAL_ERROR "rapids_export incorrectly generated a minor version value")
endif()

if(DEFINED TEST_VERSION_PATCH)
message(FATAL_ERROR "rapids_export incorrectly generated a patch version value")
endif()
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
#=============================================================================
# Copyright (c) 2018-2021, NVIDIA CORPORATION.
#
# 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.
#=============================================================================
include(${rapids-cmake-dir}/export/cpm.cmake)
include(${rapids-cmake-dir}/export/export.cmake)

project(test LANGUAGES CXX VERSION 4.2.1)

add_library(fakeLib INTERFACE)
install(TARGETS fakeLib EXPORT fake_set)

rapids_export(BUILD test
VERSION 4
EXPORT_SET fake_set
LANGUAGES CXX
)

# Verify that build files have correct names
if(NOT EXISTS "${CMAKE_BINARY_DIR}/test-config.cmake")
message(FATAL_ERROR "rapids_export failed to generate correct config file name")
endif()

# Verify that the version.cmake file exists with an explicit version arg
if(NOT EXISTS "${CMAKE_BINARY_DIR}/test-config-version.cmake")
message(FATAL_ERROR "rapids_export failed to generate a version file")
endif()

set(CMAKE_PREFIX_PATH ${CMAKE_BINARY_DIR})
find_package(test 4.0 REQUIRED)

if(NOT TEST_VERSION STREQUAL "4")
message(FATAL_ERROR "rapids_export failed to export version information")
endif()

if(NOT TEST_VERSION_MAJOR STREQUAL "4")
message(FATAL_ERROR "rapids_export failed to export major version value")
endif()

if(DEFINED TEST_VERSION_MINOR)
message(FATAL_ERROR "rapids_export incorrectly generated a minor version value")
endif()

if(DEFINED TEST_VERSION_PATCH)
message(FATAL_ERROR "rapids_export incorrectly generated a patch version value")
endif()
Loading

0 comments on commit 457cd90

Please sign in to comment.