CMakePackageConfigHelpers.cmake 13.1 KB
Newer Older
1 2 3 4
#.rst:
# CMakePackageConfigHelpers
# -------------------------
#
5 6
# Helpers functions for creating config files that can be included by other
# projects to find and use a package.
7
#
8 9
# Adds the :command:`configure_package_config_file()` and
# :command:`write_basic_package_version_file()` commands.
10
#
11 12
# Generating a Package Configuration File
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13
#
14
# .. command:: configure_package_config_file
15
#
16 17
#  Create a config file for a project::
#
18 19 20 21 22 23 24
#    configure_package_config_file(<input> <output>
#      INSTALL_DESTINATION <path>
#      [PATH_VARS <var1> <var2> ... <varN>]
#      [NO_SET_AND_CHECK_MACRO]
#      [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
#      [INSTALL_PREFIX <path>]
#      )
25
#
26 27 28 29 30
# ``configure_package_config_file()`` should be used instead of the plain
# :command:`configure_file()` command when creating the ``<Name>Config.cmake``
# or ``<Name>-config.cmake`` file for installing a project or library.  It helps
# making the resulting package relocatable by avoiding hardcoded paths in the
# installed ``Config.cmake`` file.
31
#
32 33
# In a ``FooConfig.cmake`` file there may be code like this to make the install
# destinations know to the using project:
34
#
35
# .. code-block:: cmake
36 37 38 39 40 41 42
#
#    set(FOO_INCLUDE_DIR   "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
#    set(FOO_DATA_DIR   "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
#    set(FOO_ICONS_DIR   "@CMAKE_INSTALL_PREFIX@/share/icons" )
#    ...logic to determine installedPrefix from the own location...
#    set(FOO_CONFIG_DIR  "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
#
43 44 45 46 47 48 49 50
# All 4 options shown above are not sufficient, since the first 3 hardcode the
# absolute directory locations, and the 4th case works only if the logic to
# determine the ``installedPrefix`` is correct, and if ``CONFIG_INSTALL_DIR``
# contains a relative path, which in general cannot be guaranteed.  This has the
# effect that the resulting ``FooConfig.cmake`` file would work poorly under
# Windows and OSX, where users are used to choose the install location of a
# binary package at install time, independent from how
# :variable:`CMAKE_INSTALL_PREFIX` was set at build/cmake time.
51
#
52 53
# Using ``configure_package_config_file`` helps.  If used correctly, it makes
# the resulting ``FooConfig.cmake`` file relocatable.  Usage:
54
#
55 56 57 58 59 60 61
# 1. write a ``FooConfig.cmake.in`` file as you are used to
# 2. insert a line containing only the string ``@PACKAGE_INIT@``
# 3. instead of ``set(FOO_DIR "@SOME_INSTALL_DIR@")``, use
#    ``set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@")`` (this must be after the
#    ``@PACKAGE_INIT@`` line)
# 4. instead of using the normal :command:`configure_file()`, use
#    ``configure_package_config_file()``
62 63 64
#
#
#
65 66
# The ``<input>`` and ``<output>`` arguments are the input and output file, the
# same way as in :command:`configure_file()`.
67
#
68
# The ``<path>`` given to ``INSTALL_DESTINATION`` must be the destination where
69 70
# the ``FooConfig.cmake`` file will be installed to.  This path can either be
# absolute, or relative to the ``INSTALL_PREFIX`` path.
71
#
72 73 74 75 76 77 78
# The variables ``<var1>`` to ``<varN>`` given as ``PATH_VARS`` are the
# variables which contain install destinations.  For each of them the macro will
# create a helper variable ``PACKAGE_<var...>``.  These helper variables must be
# used in the ``FooConfig.cmake.in`` file for setting the installed location.
# They are calculated by ``configure_package_config_file`` so that they are
# always relative to the installed location of the package.  This works both for
# relative and also for absolute locations.  For absolute locations it works
79 80 81 82 83 84 85 86 87
# only if the absolute location is a subdirectory of ``INSTALL_PREFIX``.
#
# If the ``INSTALL_PREFIX`` argument is passed, this is used as base path to
# calculate all the relative paths.  The ``<path>`` argument must be an absolute
# path.  If this argument is not passed, the :variable:`CMAKE_INSTALL_PREFIX`
# variable will be used instead.  The default value is good when generating a
# FooConfig.cmake file to use your package from the install tree.  When
# generating a FooConfig.cmake file to use your package from the build tree this
# option should be used.
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
#
# By default ``configure_package_config_file`` also generates two helper macros,
# ``set_and_check()`` and ``check_required_components()`` into the
# ``FooConfig.cmake`` file.
#
# ``set_and_check()`` should be used instead of the normal ``set()`` command for
# setting directories and file locations.  Additionally to setting the variable
# it also checks that the referenced file or directory actually exists and fails
# with a ``FATAL_ERROR`` otherwise.  This makes sure that the created
# ``FooConfig.cmake`` file does not contain wrong references.
# When using the ``NO_SET_AND_CHECK_MACRO``, this macro is not generated
# into the ``FooConfig.cmake`` file.
#
# ``check_required_components(<package_name>)`` should be called at the end of
# the ``FooConfig.cmake`` file if the package supports components.  This macro
# checks whether all requested, non-optional components have been found, and if
# this is not the case, sets the ``Foo_FOUND`` variable to ``FALSE``, so that
# the package is considered to be not found.  It does that by testing the
# ``Foo_<Component>_FOUND`` variables for all requested required components.
# When using the ``NO_CHECK_REQUIRED_COMPONENTS_MACRO`` option, this macro is
# not generated into the ``FooConfig.cmake`` file.
109 110
#
# For an example see below the documentation for
111 112 113 114 115 116 117 118 119
# :command:`write_basic_package_version_file()`.
#
# Generating a Package Version File
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#
# .. command:: write_basic_package_version_file
#
#  Create a version file for a project::
#
120 121 122
#    write_basic_package_version_file(<filename>
#      [VERSION <major.minor.patch>]
#      COMPATIBILITY <AnyNewerVersion|SameMajorVersion|ExactVersion> )
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
#
#
# Writes a file for use as ``<package>ConfigVersion.cmake`` file to
# ``<filename>``.  See the documentation of :command:`find_package()` for
# details on this.
#
# ``<filename>`` is the output filename, it should be in the build tree.
# ``<major.minor.patch>`` is the version number of the project to be installed.
#
# If no ``VERSION`` is given, the :variable:`PROJECT_VERSION` variable is used.
# If this hasn't been set, it errors out.
#
# The ``COMPATIBILITY`` mode ``AnyNewerVersion`` means that the installed
# package version will be considered compatible if it is newer or exactly the
# same as the requested version.  This mode should be used for packages which
# are fully backward compatible, also across major versions.
# If ``SameMajorVersion`` is used instead, then the behaviour differs from
# ``AnyNewerVersion`` in that the major version number must be the same as
# requested, e.g.  version 2.0 will not be considered compatible if 1.0 is
# requested.  This mode should be used for packages which guarantee backward
# compatibility within the same major version.
# If ``ExactVersion`` is used, then the package is only considered compatible if
# the requested version matches exactly its own version number (not considering
# the tweak version).  For example, version 1.2.3 of a package is only
# considered compatible to requested version 1.2.3.  This mode is for packages
# without compatibility guarantees.
# If your project has more elaborated version matching rules, you will need to
# write your own custom ``ConfigVersion.cmake`` file instead of using this
# macro.
#
# Internally, this macro executes :command:`configure_file()` to create the
# resulting version file.  Depending on the ``COMPATIBLITY``, either the file
# ``BasicConfigVersion-SameMajorVersion.cmake.in`` or
# ``BasicConfigVersion-AnyNewerVersion.cmake.in`` is used.  Please note that
157
# these two files are internal to CMake and you should not call
158 159
# :command:`configure_file()` on them yourself, but they can be used as starting
# point to create more sophisticted custom ``ConfigVersion.cmake`` files.
160
#
161 162
# Example Generating Package Files
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
163
#
164 165
# Example using both :command:`configure_package_config_file` and
# ``write_basic_package_version_file()``:
166
#
167
# ``CMakeLists.txt``:
168
#
169
# .. code-block:: cmake
170 171 172 173 174 175
#
#    set(INCLUDE_INSTALL_DIR include/ ... CACHE )
#    set(LIB_INSTALL_DIR lib/ ... CACHE )
#    set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
#    ...
#    include(CMakePackageConfigHelpers)
176 177 178 179 180 181 182 183 184 185
#    configure_package_config_file(FooConfig.cmake.in
#      ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
#      INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
#      PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
#    write_basic_package_version_file(
#      ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
#      VERSION 1.2.3
#      COMPATIBILITY SameMajorVersion )
#    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
#                  ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
186 187
#            DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
#
188
# ``FooConfig.cmake.in``:
189
#
190
# .. code-block:: cmake
191 192 193 194 195 196 197 198 199
#
#    set(FOO_VERSION x.y.z)
#    ...
#    @PACKAGE_INIT@
#    ...
#    set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
#    set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
#
#    check_required_components(Foo)
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216


#=============================================================================
# Copyright 2012 Alexander Neundorf <neundorf@kde.org>
#
# Distributed under the OSI-approved BSD License (the "License");
# see accompanying file Copyright.txt for details.
#
# This software is distributed WITHOUT ANY WARRANTY; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the License for more information.
#=============================================================================
# (To distribute this file outside of CMake, substitute the full
#  License text for the above reference.)

include(CMakeParseArguments)

217 218 219 220 221 222
include(WriteBasicConfigVersionFile)

macro(WRITE_BASIC_PACKAGE_VERSION_FILE)
  write_basic_config_version_file(${ARGN})
endmacro()

223
function(CONFIGURE_PACKAGE_CONFIG_FILE _inputFile _outputFile)
224
  set(options NO_SET_AND_CHECK_MACRO NO_CHECK_REQUIRED_COMPONENTS_MACRO)
225
  set(oneValueArgs INSTALL_DESTINATION INSTALL_PREFIX)
226 227 228 229 230 231 232 233 234 235 236 237
  set(multiValueArgs PATH_VARS )

  cmake_parse_arguments(CCF "${options}" "${oneValueArgs}" "${multiValueArgs}"  ${ARGN})

  if(CCF_UNPARSED_ARGUMENTS)
    message(FATAL_ERROR "Unknown keywords given to CONFIGURE_PACKAGE_CONFIG_FILE(): \"${CCF_UNPARSED_ARGUMENTS}\"")
  endif()

  if(NOT CCF_INSTALL_DESTINATION)
    message(FATAL_ERROR "No INSTALL_DESTINATION given to CONFIGURE_PACKAGE_CONFIG_FILE()")
  endif()

238 239 240 241 242 243 244 245 246 247
  if(DEFINED CCF_INSTALL_PREFIX)
    if(IS_ABSOLUTE "${CCF_INSTALL_PREFIX}")
      set(installPrefix "${CCF_INSTALL_PREFIX}")
    else()
      message(FATAL_ERROR "INSTALL_PREFIX must be an absolute path")
    endif()
  else()
    set(installPrefix "${CMAKE_INSTALL_PREFIX}")
  endif()

248 249 250
  if(IS_ABSOLUTE "${CCF_INSTALL_DESTINATION}")
    set(absInstallDir "${CCF_INSTALL_DESTINATION}")
  else()
251
    set(absInstallDir "${installPrefix}/${CCF_INSTALL_DESTINATION}")
252
  endif()
253

254
  file(RELATIVE_PATH PACKAGE_RELATIVE_PATH "${absInstallDir}" "${installPrefix}" )
255 256 257 258 259

  foreach(var ${CCF_PATH_VARS})
    if(NOT DEFINED ${var})
      message(FATAL_ERROR "Variable ${var} does not exist")
    else()
260
      if(IS_ABSOLUTE "${${var}}")
261
        string(REPLACE "${installPrefix}" "\${PACKAGE_PREFIX_DIR}"
262
                        PACKAGE_${var} "${${var}}")
263
      else()
264
        set(PACKAGE_${var} "\${PACKAGE_PREFIX_DIR}/${${var}}")
265
      endif()
266 267 268
    endif()
  endforeach()

269 270
  get_filename_component(inputFileName "${_inputFile}" NAME)

271 272
  set(PACKAGE_INIT "
####### Expanded from @PACKAGE_INIT@ by configure_package_config_file() #######
273 274 275
####### Any changes to this file will be overwritten by the next CMake run ####
####### The input file was ${inputFileName}                            ########

276 277 278
get_filename_component(PACKAGE_PREFIX_DIR \"\${CMAKE_CURRENT_LIST_DIR}/${PACKAGE_RELATIVE_PATH}\" ABSOLUTE)
")

279 280 281 282 283 284 285 286
  if("${absInstallDir}" MATCHES "^(/usr)?/lib(64)?/.+")
    # Handle "/usr move" symlinks created by some Linux distros.
    set(PACKAGE_INIT "${PACKAGE_INIT}
# Use original install prefix when loaded through a \"/usr move\"
# cross-prefix symbolic link such as /lib -> /usr/lib.
get_filename_component(_realCurr \"\${CMAKE_CURRENT_LIST_DIR}\" REALPATH)
get_filename_component(_realOrig \"${absInstallDir}\" REALPATH)
if(_realCurr STREQUAL _realOrig)
287
  set(PACKAGE_PREFIX_DIR \"${installPrefix}\")
288 289 290 291 292 293
endif()
unset(_realOrig)
unset(_realCurr)
")
  endif()

294 295 296 297 298 299 300 301 302 303 304
  if(NOT CCF_NO_SET_AND_CHECK_MACRO)
    set(PACKAGE_INIT "${PACKAGE_INIT}
macro(set_and_check _var _file)
  set(\${_var} \"\${_file}\")
  if(NOT EXISTS \"\${_file}\")
    message(FATAL_ERROR \"File or directory \${_file} referenced by variable \${_var} does not exist !\")
  endif()
endmacro()
")
  endif()

305 306 307 308 309 310 311 312 313 314

  if(NOT CCF_NO_CHECK_REQUIRED_COMPONENTS_MACRO)
    set(PACKAGE_INIT "${PACKAGE_INIT}
macro(check_required_components _NAME)
  foreach(comp \${\${_NAME}_FIND_COMPONENTS})
    if(NOT \${_NAME}_\${comp}_FOUND)
      if(\${_NAME}_FIND_REQUIRED_\${comp})
        set(\${_NAME}_FOUND FALSE)
      endif()
    endif()
315
  endforeach()
316 317 318 319
endmacro()
")
  endif()

320 321 322 323 324 325
  set(PACKAGE_INIT "${PACKAGE_INIT}
####################################################################################")

  configure_file("${_inputFile}" "${_outputFile}" @ONLY)

endfunction()