GHI #18 CMake fixes and introduction of package_name

- introduce `package_name` and `target_name` variables and use these where appropriate (i.e. without confusing reviewers about what values some variables hold) - replace `InstallConfig.cmake` with `in/patomic-config.cmake.in` - only include targets file in config file if target isn't already defined - add summary table in `OptionVariables.cmake` - change PATH cache variables to STRING so that there aren't issues if they're set on the command line - changed installed CMake names to kebab-case
doodspav · Oct 21, 2023 · de41e2e · de41e2e
1 parent ae97acb
commit de41e2e
Show file tree

Hide file tree

Showing 5 changed files with 110 additions and 50 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -2,8 +2,15 @@ cmake_minimum_required(VERSION 3.14)
 
 include(cmake/PreventInSourceBuilds.cmake)
 
+
+# ---- Initialize Project ----
+
+# used to support find_package
+set(package_name "patomic")
+
+# create base project
 project(
-    patomic
+    ${package_name}
     VERSION 0.5.1
     DESCRIPTION "Portable C90 Atomics Library"
     HOMEPAGE_URL "https://github.com/doodspav/patomic"
@@ -17,61 +24,68 @@ include(cmake/OptionVariables.cmake)
 
 # ---- Declare Library ----
 
-add_library(
-    patomic_patomic
-    ${build_type}
+# target that we can modify (can't modify ALIAS targets)
+# target name should not be the same as ${PROJECT_NAME}, causes add_subdirectory issues
+set(target_name "patomic_patomic")
+add_library(${target_name} ${build_type})
+
+# alias to cause error at configuration time instead of link time if target is missing
+add_library(patomic::patomic ALIAS ${target_name})
+
+# add sources to target
+target_sources(
+    ${target_name} PRIVATE
     # include
     include/patomic/patomic.h
     # src
     src/patomic.c
 )
 
-# alias to cause error at configuration time instead of link time if target is missing
-add_library(patomic::patomic ALIAS patomic_patomic)
-
 
 # ---- Generate Build Info Headers ----
 
 # used in export header generated below
 if(NOT PATOMIC_BUILD_SHARED)
-    target_compile_definitions(patomic_patomic PUBLIC PATOMIC_STATIC_DEFINE)
+    target_compile_definitions(${target_name} PUBLIC PATOMIC_STATIC_DEFINE)
 endif()
 
+# generate header file with export macros prefixed with BASE_NAME
 include(GenerateExportHeader)
 generate_export_header(
-    patomic_patomic
+    ${target_name}
     BASE_NAME patomic
     EXPORT_FILE_NAME include/patomic/patomic_export.h
 )
 
 
 # ---- Library Properties ----
 
+# hide all symbols by default
+# use SameMajorVersion versioning for shared library lookup
 set_target_properties(
-    patomic_patomic PROPERTIES
+    ${target_name} PROPERTIES
     C_VISIBILITY_PRESET hidden
     VISIBILITY_INLINES_HIDDEN YES
     VERSION "${PROJECT_VERSION}"
     SOVERSION "${PROJECT_VERSION_MAJOR}"
-    EXPORT_NAME patomic
-    OUTPUT_NAME patomic
+    EXPORT_NAME "patomic"
+    OUTPUT_NAME "patomic"
 )
 
 # header files generated by CMake
 target_include_directories(
-    patomic_patomic SYSTEM
-    PUBLIC
+    ${target_name} SYSTEM PUBLIC
     "$<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/include>"
 )
 
 # header files from /include
 target_include_directories(
-    patomic_patomic ${warning_guard}
-    PUBLIC
+    ${target_name} ${warning_guard} PUBLIC
     "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>"
 )
 
-target_compile_features(patomic_patomic PUBLIC c_std_90)
+# require C90 compiler support
+target_compile_features(${target_name} PUBLIC c_std_90)
 
 
 # ---- Install Rules ----

diff --git a/cmake/InstallConfig.cmake b/cmake/InstallConfig.cmake
diff --git a/cmake/InstallRules.cmake b/cmake/InstallRules.cmake
@@ -1,60 +1,63 @@
 include(CMakePackageConfigHelpers)
-include(GNUInstallDirs)
-
-# find_package(<package>) call for consumers to find this project
-set(package patomic)
 
 # copy header files to CMAKE_INSTALL_INCLUDEDIR
 install(
     DIRECTORY
-    "../include"
-    "${PROJECT_BINARY_DIR}/include/"
+    "${PROJECT_SOURCE_DIR}/include"  # our header files
+    "${PROJECT_BINARY_DIR}/include"  # generated header files
     DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-    COMPONENT patomic_Development
+    COMPONENT ${package_name}-development
 )
 
 # copy target build output artifacts to OS dependent locations
+# (except includes)
 install(
-    TARGETS patomic_patomic
-    EXPORT patomicTargets
+    TARGETS ${target_name}
+    EXPORT ${package_name}-targets
     RUNTIME #
-    COMPONENT patomic_Runtime
+    COMPONENT ${package_name}-runtime
     LIBRARY #
-    COMPONENT patomic_Runtime
-    NAMELINK_COMPONENT patomic_Development
+    COMPONENT ${package_name}-runtime
+    NAMELINK_COMPONENT ${package_name}-development
     ARCHIVE #
-    COMPONENT patomic_Development
+    COMPONENT ${package_name}-development
     INCLUDES #
     DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
 )
 
+# create config file that points to targets file
+configure_file(
+    "${PROJECT_SOURCE_DIR}/cmake/in/patomic-config.cmake.in"
+    "${PROJECT_BINARY_DIR}/cmake/${package_name}-config.cmake"
+    @ONLY
+)
+
 # copy config file for find_package to find
 install(
-    FILES "InstallConfig.cmake"
+    FILES "${PROJECT_BINARY_DIR}/cmake/${package_name}-config.cmake"
     DESTINATION "${PATOMIC_INSTALL_CMAKEDIR}"
-    RENAME "${package}Config.cmake"
-    COMPONENT patomic_Development
+    COMPONENT ${package_name}-development
 )
 
 # create version file for consumer to check version in CMake
 write_basic_package_version_file(
-    "${package}ConfigVersion.cmake"
-    COMPATIBILITY SameMajorVersion
+    "${package_name}-config-version.cmake"
+    COMPATIBILITY SameMajorVersion  # a.k.a. SemVer
 )
 
-# copy version file for find_package to find
+# copy version file for find_package to find for version check
 install(
-    FILES "${PROJECT_BINARY_DIR}/${package}ConfigVersion.cmake"
+    FILES "${PROJECT_BINARY_DIR}/${package_name}-config-version.cmake"
     DESTINATION "${PATOMIC_INSTALL_CMAKEDIR}"
-    COMPONENT patomic_Development
+    COMPONENT ${package_name}-development
 )
 
-# create core configuration file detailing targets for consumer
+# create targets file included by config file with targets for consumers
 install(
-    EXPORT patomicTargets
+    EXPORT ${package_name}-targets
     NAMESPACE patomic::
     DESTINATION "${PATOMIC_INSTALL_CMAKEDIR}"
-    COMPONENT patomic_Development
+    COMPONENT ${package_name}-development
 )
 
 # support packaging library

diff --git a/cmake/OptionVariables.cmake b/cmake/OptionVariables.cmake
@@ -1,3 +1,22 @@
+include(GNUInstallDirs)
+
+
+# ---- Options Summary ----
+
+# ------------------------------------------------------------------------------------------------
+# | Option                       | Availability  | Default                                       |
+# |==============================|===============|===============================================|
+# | BUILD_SHARED_LIBS            | Top-Level     | OFF                                           |
+# | BUILD_TESTING                | Top-Level     | OFF                                           |
+# | CMAKE_INSTALL_INCLUDEDIR     | Top-Level     | include/${package_name}-${PROJECT_VERSION}    |
+# |------------------------------|---------------|-----------------------------------------------|
+# | PATOMIC_BUILD_SHARED         | Always        | ${BUILD_SHARED_LIBS}                          |
+# | PATOMIC_BUILD_TESTING        | Always        | ${BUILD_TESTING}                              |
+# | PATOMIC_INCLUDES_WITH_SYSTEM | Not Top-Level | ON                                            |
+# | PATOMIC_INSTALL_CMAKEDIR     | Always        | ${CMAKE_INSTALL_LIBDIR}/cmake/${package_name} |
+# ------------------------------------------------------------------------------------------------
+
+
 # ---- Build Shared ----
 
 # Sometimes it's useful to be able to single out a dependency to be built as
@@ -7,7 +26,7 @@ if(PROJECT_IS_TOP_LEVEL)
 endif()
 option(
     PATOMIC_BUILD_SHARED
-    "Override BUILD_SHARED_LIBS for patomic library"
+    "Override BUILD_SHARED_LIBS for ${package_name} library"
     ${BUILD_SHARED_LIBS}
 )
 mark_as_advanced(PATOMIC_BUILD_SHARED)
@@ -27,7 +46,7 @@ set(warning_guard "")
 if(NOT PROJECT_IS_TOP_LEVEL)
     option(
         PATOMIC_INCLUDES_WITH_SYSTEM
-        "Use SYSTEM modifier for patomic's includes, disabling warnings"
+        "Use SYSTEM modifier for ${package_name}'s includes, disabling warnings"
         ON
     )
     mark_as_advanced(PATOMIC_INCLUDES_WITH_SYSTEM)
@@ -48,7 +67,7 @@ if(PROJECT_IS_TOP_LEVEL)
 endif()
 option(
     PATOMIC_BUILD_TESTING
-    "Override BUILD_TESTING for patomic library"
+    "Override BUILD_TESTING for ${package_name} library"
     ${BUILD_TESTING}
 )
 mark_as_advanced(PATOMIC_BUILD_TESTING)
@@ -57,22 +76,35 @@ mark_as_advanced(PATOMIC_BUILD_TESTING)
 # ---- Install Include Directory ----
 
 # Adds an extra directory to the include path by default, so that when you link
-# against the target, you get `<prefix>/include/patomic-X.Y.Z` added to your
+# against the target, you get `<prefix>/include/<package>-X.Y.Z` added to your
 # include paths rather than `<prefix/include`.
+# This doesn't affect include paths used by consumers of this project.
+# The variable type is STRING rather than PATH, because otherwise passing
+# -DCMAKE_INSTALL_INCLUDEDIR=include on the command line would expand to an
+# absolute path with the base being the current CMake directory, leading to
+# unexpected errors.
 if(PROJECT_IS_TOP_LEVEL)
     set(
-        CMAKE_INSTALL_INCLUDEDIR "include/patomic-${PROJECT_VERSION}"
-        CACHE PATH ""
+        CMAKE_INSTALL_INCLUDEDIR "include/${package_name}-${PROJECT_VERSION}"
+        CACHE STRING ""
     )
+    # marked as advanced in GNUInstallDirs version, so we follow their lead
+    mark_as_advanced(CMAKE_INSTALL_INCLUDEDIR)
 endif()
 
 
 # ---- Install CMake Directory ----
 
 # This allows package maintainers to freely override the installation path for
 # the CMake configs.
+# This doesn't affect include paths used by consumers of this project.
+# The variable type is STRING rather than PATH, because otherwise passing
+# -DPATOMIC_INSTALL_CMAKEDIR=lib/cmake on the command line would expand to an
+# absolute path with the base being the current CMake directory, leading to
+# unexpected errors.
 set(
-    PATOMIC_INSTALL_CMAKEDIR "${CMAKE_INSTALL_LIBDIR}/cmake/${package}"
-    CACHE PATH "CMake package config location relative to the install prefix"
+    PATOMIC_INSTALL_CMAKEDIR "${CMAKE_INSTALL_LIBDIR}/cmake/${package_name}"
+    CACHE STRING "CMake package config location relative to the install prefix"
 )
+# depends on CMAKE_INSTALL_LIBDIR which is marked as advanced in GNUInstallDirs
 mark_as_advanced(PATOMIC_INSTALL_CMAKEDIR)
diff --git a/cmake/in/patomic-config.cmake.in b/cmake/in/patomic-config.cmake.in
@@ -0,0 +1,12 @@
+# init @ variables before doing anything else
+@PACKAGE_INIT@
+
+# no dependencies or special setup
+
+# we cannot modify an existing IMPORT target
+if(NOT TARGET patomic::patomic)
+
+    # import targets
+    include("${CMAKE_CURRENT_LIST_DIR}/@[email protected]")
+
+endif()