Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ jobs:
- name: Run target type tests
run: cmake -P tests/setup/test_target_type.cmake

- name: Run install directory tests
run: cmake -P tests/setup/test_install_dirs.cmake

- name: Run custom executable runtime deployment tests
run: cmake -P tests/setup/test_runtime_dlls.cmake

Expand All @@ -50,6 +53,9 @@ jobs:
- name: Run target type tests
run: cmake -P tests/setup/test_target_type.cmake

- name: Run install directory tests
run: cmake -P tests/setup/test_install_dirs.cmake

- name: Run custom executable runtime deployment tests
run: cmake -P tests/setup/test_runtime_dlls.cmake

Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,7 +366,7 @@ cpp_library_setup(
[DOCS_EXCLUDE_SYMBOLS symbols] # Symbols to exclude from docs
[DOCS_INPUTS input_list] # Additional documentation files/directories
[DOCS_OPTIONS setting_list] # Additive single-line Doxygen assignments
[REQUIRES_CPP_VERSION 17|20|23] # C++ version (default: 17)
[REQUIRES_CPP_VERSION 17|20|23] # C++ version (default: 20)
[INSTALL_OPTION option_name] # Independent installation control (default: uppercase NAMESPACE_INSTALL)
)
```
Expand All @@ -378,6 +378,12 @@ cpp_library_setup(
- Version is automatically detected from git tags (see [Version Management](#version-management) for overrides).
- Installation is controlled by `INSTALL_OPTION`, or the uppercase `${NAMESPACE}_INSTALL` option
when omitted. Options default to `PROJECT_IS_TOP_LEVEL`.
- `cpp_library_setup()` makes the effective `GNUInstallDirs` directory variables
available to subsequent caller install rules, including when installation is disabled.
- `REQUIRES_CPP_VERSION` sets the minimum C++ standard. Compiled library, test,
and example targets default to `CXX_EXTENSIONS OFF` unless
`CMAKE_CXX_EXTENSIONS` is set by the caller. This does not impose a dialect on
consumers or enable pedantic diagnostics.

### Documentation configuration

Expand Down
3 changes: 3 additions & 0 deletions cmake/cpp-library-setup.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,9 @@ function(_cpp_library_setup_core)
if(ARG_SOURCES)
# Respect the consumer's BUILD_SHARED_LIBS setting.
add_library(${ARG_NAME} ${ARG_SOURCES})
if(NOT DEFINED CMAKE_CXX_EXTENSIONS)
set_target_properties(${ARG_NAME} PROPERTIES CXX_EXTENSIONS OFF)
endif()
add_library(${ARG_NAMESPACE}::${ARG_CLEAN_NAME} ALIAS ${ARG_NAME})
target_include_directories(${ARG_NAME} PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
Expand Down
14 changes: 12 additions & 2 deletions cpp-library.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,9 @@ function(_cpp_library_setup_executables)
)
endif()
endif()
if(NOT DEFINED CMAKE_CXX_EXTENSIONS)
set_target_properties(${executable_base} PROPERTIES CXX_EXTENSIONS OFF)
endif()
else()
message(WARNING "${ARG_TYPE} file ${source_dir}/${executable} not found")
endif()
Expand All @@ -166,7 +169,7 @@ function(cpp_library_setup)
set(oneValueArgs
DESCRIPTION # Description string
NAMESPACE # Namespace (e.g., "stlab")
REQUIRES_CPP_VERSION # C++ version (default: 17)
REQUIRES_CPP_VERSION # C++ version (default: 20)
INSTALL_OPTION # Custom installation option name
)
set(multiValueArgs
Expand Down Expand Up @@ -235,6 +238,13 @@ function(cpp_library_setup)
# Include installation module that requires project() to be called first
# (GNUInstallDirs needs language/architecture information)
include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-install.cmake")
include(GNUInstallDirs)
foreach(dir IN ITEMS BINDIR SBINDIR LIBEXECDIR SYSCONFDIR SHAREDSTATEDIR
LOCALSTATEDIR RUNSTATEDIR LIBDIR INCLUDEDIR OLDINCLUDEDIR
DATAROOTDIR DATADIR INFODIR LOCALEDIR MANDIR DOCDIR)
set(CMAKE_INSTALL_${dir} "${CMAKE_INSTALL_${dir}}" PARENT_SCOPE)
set(CMAKE_INSTALL_FULL_${dir} "${CMAKE_INSTALL_FULL_${dir}}" PARENT_SCOPE)
endforeach()

# Calculate clean name (without namespace prefix) for target alias
# If PROJECT_NAME starts with NAMESPACE-, strip it; otherwise use PROJECT_NAME as-is
Expand All @@ -251,7 +261,7 @@ function(cpp_library_setup)

# Set defaults
if(NOT ARG_REQUIRES_CPP_VERSION)
set(ARG_REQUIRES_CPP_VERSION 17)
set(ARG_REQUIRES_CPP_VERSION 20)
endif()

# Get version from git tags and update project version variables
Expand Down
105 changes: 105 additions & 0 deletions docs/installation-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Installation design

This document records the installation policy and the recommendation for
[#37](https://github.com/stlab/cpp-library/issues/37). It is for maintainers
evaluating installation changes, not a guide to distributing a complete
application or dependency bundle.

## Goals and boundaries

- Strongly discourage installation workflows. Use CPM to consume and build
dependencies from source unless a package manager or another specific
requirement calls for installation.
- Installing a component does not install its dependencies. CMake cannot
generally provide that guarantee across arbitrary dependencies and build
systems. The client or package manager is responsible for making those
dependencies available.
- Provide component install rules and dependency information for package
managers and other explicit installation workflows. Do not treat the
resulting artifacts as self-contained, distributable packages with their
dependencies included.
- Minimize installation-specific requirements in client `CMakeLists.txt`
files. Most clients following the recommended CPM workflow should not need
additional installation configuration.

These are design goals, not a claim that every existing example or API already
meets them. In particular, the README describes installation as optional but
does not yet state this policy as strongly.

## Existing behavior

`cpp_library_setup()` creates install rules when its selected installation
option is enabled. The option is `INSTALL_OPTION`, if specified, or the
uppercase namespace followed by `_INSTALL`. Its default is
`PROJECT_IS_TOP_LEVEL`; an existing option value is preserved. These rules
do not execute during an ordinary build.

An explicit install can produce headers, library artifacts, and CMake package
configuration and target exports. The generated configuration contains
`find_dependency()` calls for detected public dependencies; those calls locate
dependencies and do not install them. Tracking and mapping have limits, and
untracked dependencies can prevent installation. See the
[installation module](../cmake/cpp-library-install.cmake) and
[dependency handling documentation](../README.md#dependency-handling-in-installed-packages).

Install options select which toolkit packages contribute rules to a build.
If several packages share an enabled namespace option, an install of that build
can execute rules for more than one package. That is not a general mechanism
for installing a component's dependency closure: other dependencies may use
different options, come from installed packages, or have unrelated install
behavior. `INSTALL_OPTION` permits independently controlled packages in the
same namespace.

## Issue #37

The shared namespace option is initialized when each package calls
`cpp_library_setup()`, not when the top-level project begins. If a
same-namespace dependency is configured first, it can create the shared option
with a subproject default of `OFF`. The top-level package then preserves that
value, so its install rules are disabled even though its own default would
otherwise be `ON`. An existing cache value also persists across configurations.
This affects installation-rule selection, not normal source consumption.

An installation user can set the shared option explicitly at configuration
time, for example `-DCEL_INSTALL=ON`. This can also enable rules for other
packages using that option; it does not ensure their dependencies are
available. A project that needs to establish the default before loading
dependencies can declare the option after `project()` and before those
dependencies. A package that requires independent control can use a distinct
`INSTALL_OPTION`. These are existing mechanisms, not a requirement for every
CPM client.

## Recommendation

**Defer #37 without changing the implementation or adding an initializer.**
The gap was discovered during review, and no client has reported it as a
problem. An early initializer would replace a manual option declaration with
another installation-specific call and ordering requirement; it would not
meaningfully reduce client CMake. Moving `cpp_library_setup()` before
dependencies might avoid the specific ordering problem in some projects, but
requires clients to change their setup order and has not been established as a
general replacement. Changing shared-option defaults or overriding cached
values would risk existing builds and explicit choices.

Leave #37 open as a known limitation. Revisit it if a client reports a
concrete problem, or if a design can remove the ordering hazard without
adding installation-specific client boilerplate or breaking existing choices.
Any proposed change should cover shared options, independent
`INSTALL_OPTION` values, explicit cache overrides, and both standalone and
nested builds.

## History and compatibility

Installation support was restored in commit `3ab13f2`. Commit `fba98d9`
introduced dependency-provider tracking to generate dependency information
for installed CMake configurations. Commit `0e6c594` and
[#22](https://github.com/stlab/cpp-library/pull/22) introduced namespace
installation control so embedded projects can opt in, including for package
manager workflows.

[#27](https://github.com/stlab/cpp-library/pull/27) added independent options,
target-scoped deferred installation metadata, and transitive linkage for
separately installed nested packages. Its stated motivation includes the
standalone extraction of `stlab-execution` and its use by STLab. Preserve these
capabilities unless a separate change reviews their users, history, and
compatibility consequences. This recommendation removes no install feature.
7 changes: 7 additions & 0 deletions tests/install/fixtures/consumer/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,13 @@ project(consumer LANGUAGES CXX)
include(CTest)
include("${TOOLKIT_SOURCE}/cpp-library.cmake")
find_package(stlab-parent 1.0.0 REQUIRED)
add_executable(ordinary-consumer tests/consumer.cpp)
set_target_properties(ordinary-consumer PROPERTIES CXX_EXTENSIONS ON)
target_link_libraries(ordinary-consumer PRIVATE stlab::parent)
get_target_property(consumer_extensions ordinary-consumer CXX_EXTENSIONS)
if(NOT consumer_extensions)
message(FATAL_ERROR "Installed library changed consumer dialect")
endif()
get_target_property(imported stlab::leaf IMPORTED)
get_target_property(leaf_type stlab::leaf TYPE)
if(NOT imported OR NOT leaf_type STREQUAL EXPECTED_LEAF_TYPE)
Expand Down
64 changes: 63 additions & 1 deletion tests/setup/fixtures/target_type/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,82 @@ include("${TOOLKIT_SOURCE}/cpp-library.cmake")
cpp_library_enable_dependency_tracking()
project(sample LANGUAGES CXX)
set(CPP_LIBRARY_VERSION 1.0.0)
set(FIXTURE_INSTALL OFF CACHE BOOL "" FORCE)
if(DEFINED FIXTURE_NORMAL_DATADIR)
set(CMAKE_INSTALL_DATADIR "${FIXTURE_NORMAL_DATADIR}")
endif()
if(NOT CHECK_INSTALL_DIRS)
set(FIXTURE_INSTALL OFF CACHE BOOL "" FORCE)
endif()
if(CHECK_DIALECT)
include(CTest)
add_library(doctest::doctest INTERFACE IMPORTED)
add_library(unrelated INTERFACE)
get_target_property(unrelated_extensions unrelated CXX_EXTENSIONS)
set(unrelated_before "${unrelated_extensions}")
set(test_args TESTS dialect_test.cpp compile_fail.cpp EXAMPLES dialect_example.cpp)
file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/compiler-id.txt" "${CMAKE_CXX_COMPILER_ID}")
endif()
set(source_args SOURCES sample.cpp)
if(OMIT_SOURCES)
set(source_args)
endif()
if(DEFINED FIXTURE_CPP_VERSION)
set(version_args REQUIRES_CPP_VERSION "${FIXTURE_CPP_VERSION}")
endif()
cpp_library_setup(
DESCRIPTION "Consumer-selected target type fixture"
NAMESPACE fixture
HEADERS sample.hpp
${version_args}
${test_args}
${source_args})
if(CHECK_INSTALL_DIRS)
if(NOT CMAKE_INSTALL_DATADIR STREQUAL EXPECTED_DATADIR)
message(FATAL_ERROR "Expected DATADIR ${EXPECTED_DATADIR}, got '${CMAKE_INSTALL_DATADIR}'")
endif()
if(NOT CMAKE_INSTALL_FULL_DATADIR STREQUAL "${CMAKE_INSTALL_PREFIX}/${EXPECTED_DATADIR}")
message(FATAL_ERROR "Unexpected full DATADIR '${CMAKE_INSTALL_FULL_DATADIR}'")
endif()
if(NOT CMAKE_INSTALL_FULL_BINDIR STREQUAL "${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_BINDIR}")
message(FATAL_ERROR "Unexpected full BINDIR '${CMAKE_INSTALL_FULL_BINDIR}'")
endif()
if(FIXTURE_INSTALL)
install(FILES include/fixture/sample.hpp
DESTINATION "${CMAKE_INSTALL_DATADIR}/licenses/fixture-sample")
endif()
endif()
get_target_property(actual sample TYPE)
if(NOT actual STREQUAL EXPECTED_TYPE)
message(FATAL_ERROR "Expected ${EXPECTED_TYPE}, got ${actual}")
endif()
if(DEFINED EXPECTED_CPP_VERSION)
get_target_property(features sample INTERFACE_COMPILE_FEATURES)
if(NOT "cxx_std_${EXPECTED_CPP_VERSION}" IN_LIST features)
message(FATAL_ERROR "Expected C++${EXPECTED_CPP_VERSION} requirement, got '${features}'")
endif()
endif()
if(NOT BUILD_SHARED_LIBS STREQUAL EXPECTED_BUILD_SHARED_LIBS)
message(FATAL_ERROR "Setup changed parent BUILD_SHARED_LIBS")
endif()
if(CHECK_DIALECT)
set(checked_targets dialect_test compile_fail dialect_example)
if(NOT OMIT_SOURCES)
list(APPEND checked_targets sample)
endif()
foreach(target IN LISTS checked_targets)
get_target_property(extensions ${target} CXX_EXTENSIONS)
if(NOT "${extensions}" STREQUAL "${EXPECTED_EXTENSIONS}")
message(FATAL_ERROR "${target} CXX_EXTENSIONS: expected ${EXPECTED_EXTENSIONS}, got ${extensions}")
endif()
endforeach()
get_target_property(unrelated_extensions unrelated CXX_EXTENSIONS)
if(NOT "${unrelated_before}" STREQUAL "${unrelated_extensions}")
message(FATAL_ERROR "Setup changed unrelated target dialect")
endif()
if(NOT DEFINED EXPECTED_CALLER_EXTENSIONS AND DEFINED CMAKE_CXX_EXTENSIONS)
message(FATAL_ERROR "Setup changed caller CMAKE_CXX_EXTENSIONS")
elseif(DEFINED EXPECTED_CALLER_EXTENSIONS AND
NOT "${CMAKE_CXX_EXTENSIONS}" STREQUAL "${EXPECTED_CALLER_EXTENSIONS}")
message(FATAL_ERROR "Setup changed caller CMAKE_CXX_EXTENSIONS")
endif()
endif()
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
int main() { return 0; }
1 change: 1 addition & 0 deletions tests/setup/fixtures/target_type/tests/compile_fail.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
#error This test must fail to compile.
1 change: 1 addition & 0 deletions tests/setup/fixtures/target_type/tests/dialect_test.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
int main() { return 0; }
67 changes: 67 additions & 0 deletions tests/setup/test_install_dirs.cmake
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# SPDX-License-Identifier: BSL-1.0
#
# Run as: cmake -P tests/setup/test_install_dirs.cmake
cmake_minimum_required(VERSION 3.24)

get_filename_component(toolkit_source "${CMAKE_CURRENT_LIST_DIR}/../.." ABSOLUTE)
string(RANDOM LENGTH 16 ALPHABET 0123456789abcdef test_id)
set(test_root "${toolkit_source}/build/install-dirs-${test_id}")

function(run_command)
execute_process(COMMAND ${ARGN} RESULT_VARIABLE result OUTPUT_VARIABLE out ERROR_VARIABLE err)
if(NOT result EQUAL 0)
message(FATAL_ERROR "Command failed (${result}): ${ARGN}\n${out}\n${err}")
endif()
endfunction()

function(run_case name expected_data enabled)
set(source "${test_root}/${name}/source")
set(binary "${test_root}/${name}/build")
set(prefix "${test_root}/${name}/prefix")
file(MAKE_DIRECTORY "${source}")
file(COPY "${CMAKE_CURRENT_LIST_DIR}/fixtures/target_type/" DESTINATION "${source}")
run_command("${CMAKE_COMMAND}" -S "${source}" -B "${binary}" -G Ninja
"-DTOOLKIT_SOURCE=${toolkit_source}" -DOMIT_SOURCES=ON
-DEXPECTED_TYPE=INTERFACE_LIBRARY -DBUILD_SHARED_LIBS=OFF
-DEXPECTED_BUILD_SHARED_LIBS=OFF -DCHECK_INSTALL_DIRS=ON
"-DFIXTURE_INSTALL=${enabled}" "-DEXPECTED_DATADIR=${expected_data}"
"-DCMAKE_INSTALL_PREFIX=${prefix}" ${ARGN})
if(enabled)
run_command("${CMAKE_COMMAND}" --install "${binary}")
if(NOT EXISTS "${prefix}/${expected_data}/licenses/fixture-sample/sample.hpp")
message(FATAL_ERROR "${name}: license install destination missing")
endif()
set(next_prefix "${test_root}/${name}/next-prefix")
run_command("${CMAKE_COMMAND}" -S "${source}" -B "${binary}"
"-DCMAKE_INSTALL_PREFIX=${next_prefix}")
else()
file(READ "${binary}/cmake_install.cmake" install_script)
if(install_script MATCHES "fixture-sample")
message(FATAL_ERROR "${name}: installation disabled but rules were generated")
endif()
endif()
message(STATUS "PASS ${name}")
endfunction()

run_case(default share ON)
run_case(datadir custom-data ON -DCMAKE_INSTALL_DATADIR=custom-data)
run_case(normal_datadir normal-data ON -DFIXTURE_NORMAL_DATADIR=normal-data)
run_case(dataroot custom-root ON -DCMAKE_INSTALL_DATAROOTDIR=custom-root)
run_case(disabled share OFF)

set(source "${test_root}/subproject/source")
set(binary "${test_root}/subproject/build")
file(MAKE_DIRECTORY "${source}/component")
file(COPY "${CMAKE_CURRENT_LIST_DIR}/fixtures/target_type/" DESTINATION "${source}/component")
file(WRITE "${source}/CMakeLists.txt"
"cmake_minimum_required(VERSION 3.24)\nproject(wrapper LANGUAGES CXX)\nadd_subdirectory(component)\n")
run_command("${CMAKE_COMMAND}" -S "${source}" -B "${binary}" -G Ninja
"-DTOOLKIT_SOURCE=${toolkit_source}" -DOMIT_SOURCES=ON
-DEXPECTED_TYPE=INTERFACE_LIBRARY -DBUILD_SHARED_LIBS=OFF
-DEXPECTED_BUILD_SHARED_LIBS=OFF -DCHECK_INSTALL_DIRS=ON
-DFIXTURE_INSTALL=OFF -DEXPECTED_DATADIR=share
"-DCMAKE_INSTALL_PREFIX=${test_root}/subproject/prefix")
message(STATUS "PASS subproject")

file(REMOVE_RECURSE "${test_root}")
message(STATUS "All install directory cases passed!")
Loading
Loading