Creating packages that work well with package managers

To prevent ambiguities with similarly named headers, a subdirectory of include named like the package can be used.

I recommend still only adding -I ${PREFIX}/include to compilations rather than -I ${PREFIX}/include/${PACKAGE_NAME}. If we are using this technique to prevent ambiguities with names, then we would also not want code to be ambiguous. The include #include <${PACKAGE_NAME}/ambiguous_name.h> is less ambiguous than #include <ambiguous_name.h>

When doing find_package(${PACKAGE_NAME}), CMake will look in $X/lib/cmake for a file named ${PACKAGE_NAME}Config.cmake for each X in CMAKE_PREFIX_PATH.

This is one of many choices. The file can also be named ${PACKAGE_NAME@u}-config.cmake and can also be placed in a dozen other locations relative to directories X in CMAKE_INSTALL_PREFIX.

See section Build/CMake/Config Files for more details.

This directory contains manpages.

The manpages can be made available to the user in various ways.

The way I suggest is to simply add ${PREFIX}/bin to PATH.

Put files in here that define completions for a command or shell function. The name of the file should be _ls, _ls.bash, ls, or ls.bash for definding the completion of a command named ls.

A file defining completion functions for many commands can be reused by placing symbolic links for each other command whose completion is provided by this file.

Other static files used by the package should go in this directory (technically what should go in here is more precise than "everything else" but if you don't know where to put something, put it here.

For packages to coexist, if the package provides more that one file, all those files should go in a subdirectory of share named like the package.

This might seem redundant if you install packages each in their own PREFIX. For example, I might install the package named repos in the prefix $HOME/my-packages/repos and it will contain the directory $HOME/my-packages/repos/share/repos. It might seem weird to have the name of the package twice but this important for the package to be able to coexist with other packages.

It is also good to do it this way because then we follow FHS guidelines.

The initialization of lmod and the other one adds /usr/share/modulefiles to MODULE_PATH therefore it makes sense to put module files for things in our package in this directory.

Tools may choose to do run cmake SRC_DIR -DCMAKE_INSTALL_PREFIX=... followed by make install or cmake -S SRC_DIR -B BUILD_DIR followed by cmake --install BUILD_DIR --prefix ${PREFIX}.

It is essential that both be supported if using cpack (make package) because it works by using cmake --install BUILD_DIR --prefix STAGING_AREA and making a tarball of STAGING_AREA.

Both should be supported. This means that evaluation of CMAKE_INSTALL_PREFIX should be deferred to the moment of installation.

The following evaluates CMAKE_INSTALL_PREFIX at configure time and does not support cmake --install BUILD_DIR --prefix ${PREFIX}:

# Doesn't work
install(CODE "message(STATUS \"installing into ${CMAKE_INSTALL_PREFIX}\")")

This is because CMake works by creating cmake_install.cmake at configuration time that is then run as a CMake script at install time. The evaluation at configure time causes the value of CMAKE_INSTALL_PREFIX from configure time to become hardcoded into this script:

# cmake_install.cmake
message(STATUS "installing into \usr\local"

The fix is very simple: just defer the evaluation until install time. This version (with a \ in front of the dollar sign:

# Works
install(CODE "message(STATUS \"installing into \${CMAKE_INSTALL_PREFIX}\")")

works because it the evaluation of ${CMAKE_INSTALL_PREFIX} will happen when cmake_install.cmake is run (instead of happening during its creation):

# cmake_install.cmake
message(STATUS "installing into ${CMAKE_INSTALL_PREFIX}")

In other install() commands, the value of CMAKE_INSTALL_PREFIX should not be used. Let CMake handle that. The following:

# don't do this
install(TARGETS my_exec DESTINATION ${CMAKE_INSTALL_PREFIX}/bin)
install(FILES something DESTINATION ${CMAKE_INSTALL_PREFIX}/share/${PACKAGE_NAME}/something)

is redundant because when the argument of DESTINATION is a relative path, it is interepreted relative to the installation directory.

It also breaks cpack, and prevents users and package managers from using cmake --install BUILD --prefix ${PREFIX}.

We should do this instead:

# do this
install(TARGETS my_exec DESTINATION bin)
install(FILES something DESTINATION share/${PACKAGE_NAME}/something)

Starting with ${PROJECT_NAME}Config.cmake.in containing

<<TODO>>

and list_of_targets containing a list of some or all of the project's targets, the code below define a name ${export_set_name} for a set of installed targets and the calls to configure_package_config_file and write_basic_package_version_file create $PREFIX/cmake/${PACKAGE_NAME}Config.cmake and $PREFIX/cmake/${PACKAGE_NAME}ConfigVersion.cmake

include(GNUInstallDirs) # Defines CONFIG_INSTALL_DIR as lib/cmake
include(CMakePackageConfigHelpers)

# Add `EXPORT ${export_set_name}` to `install(TARGETS` command
# to define ${export_set_name} and associate it with these targets.
install(TARGETS ${list_of_targets} EXPORT ${export_set_name})
# An `install(EXPORT ${export_set_name} ...)` tells CMake to generate files
# containing all the information on the targets in the previously created "export
# set" for client # projects built with CMake to consume.
install(
    EXPORT ${export_set_name}
    NAMESPACE ${PROJECT_NAME}::
    DESTINATION ${CONFIG_INSTALL_DIR}
)

# This creates =${PACKAGE_NAME}Config.cmake= which is the entry point from a
# =find_package= call.
configure_package_config_file(
    "${PROJECT_NAME}Config.cmake.in"
    "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
    INSTALL_DESTINATION "${CONFIG_INSTALL_DIR}"
    PATH_VARS CMAKE_INSTALL_INCLUDEDIR CMAKE_INSTALL_LIBDIR
)
# Creates =${PACKAGE_NAME}ConfigVersion.cmake=
write_basic_package_version_file(
    "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake"
    COMPATIBILITY SameMajorVersion
)

Note that CMAKE_INSTALL_PREFIX should not be used in the argument to INSTALL_DESTINATION. This is for reasons described in the previous section about deferring evaluation of CMAKE_INSTALL_PREFIX until install time.