CMakePackageConfigHelpers.cmake 12.6 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
#.rst:
# CMakePackageConfigHelpers
# -------------------------
#
# CONFIGURE_PACKAGE_CONFIG_FILE(), WRITE_BASIC_PACKAGE_VERSION_FILE()
#
#
#
# ::
#
#     CONFIGURE_PACKAGE_CONFIG_FILE(<input> <output> INSTALL_DESTINATION <path>
#                                                    [PATH_VARS <var1> <var2> ... <varN>]
#                                                    [NO_SET_AND_CHECK_MACRO]
#                                                    [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
#                                                    [NO_FIND_DEPENDENCY_MACRO])
#
17
18
19
#
#
# CONFIGURE_PACKAGE_CONFIG_FILE() should be used instead of the plain
20
21
22
23
# 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.
24
25
26
#
# In a FooConfig.cmake file there may be code like this to make the
# install destinations know to the using project:
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
#
# ::
#
#    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@" )
#
# 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 CMAKE_INSTALL_PREFIX was set at build/cmake time.
#
# Using CONFIGURE_PACKAGE_CONFIG_FILE() helps.  If used correctly, it
# makes the resulting FooConfig.cmake file relocatable.  Usage:
#
# ::
#
#    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 configure_file(), use CONFIGURE_PACKAGE_CONFIG_FILE()
#
#
#
# The <input> and <output> arguments are the input and output file, the
# same way as in configure_file().
#
# The <path> given to INSTALL_DESTINATION must be the destination where
# the FooConfig.cmake file will be installed to.  This can either be a
# relative or absolute path, both work.
#
# 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 only if the absolute
# location is a subdirectory of CMAKE_INSTALL_PREFIX.
#
# By default configure_package_config_file() also generates two helper
# macros, set_and_check() and check_required_components() into the
77
78
# FooConfig.cmake file.
#
79
80
81
82
83
84
# 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
85
86
# into the FooConfig.cmake file.
#
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
# 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
# option, this macro is not generated into the FooConfig.cmake file.
#
# For an example see below the documentation for
# WRITE_BASIC_PACKAGE_VERSION_FILE().
#
#
#
# ::
#
#   WRITE_BASIC_PACKAGE_VERSION_FILE( filename VERSION major.minor.patch COMPATIBILITY (AnyNewerVersion|SameMajorVersion|ExactVersion) )
#
#
#
# Writes a file for use as <package>ConfigVersion.cmake file to
# <filename>.  See the documentation of 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
#
# 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 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
# these two files are internal to CMake and you should not call
# configure_file() on them yourself, but they can be used as starting
140
141
142
# point to create more sophisticted custom ConfigVersion.cmake files.
#
#
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
#
# Example using both configure_package_config_file() and
# write_basic_package_version_file(): CMakeLists.txt:
#
# ::
#
#    set(INCLUDE_INSTALL_DIR include/ ... CACHE )
#    set(LIB_INSTALL_DIR lib/ ... CACHE )
#    set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
#    ...
#    include(CMakePackageConfigHelpers)
#    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
#            DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
#
#
164
#
165
# With a FooConfig.cmake.in:
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
#
# ::
#
#    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)
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197


#=============================================================================
# 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)

198
199
200
201
202
203
include(WriteBasicConfigVersionFile)

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

204
205

function(CONFIGURE_PACKAGE_CONFIG_FILE _inputFile _outputFile)
206
  set(options NO_SET_AND_CHECK_MACRO NO_CHECK_REQUIRED_COMPONENTS_MACRO NO_FIND_DEPENDENCY_MACRO)
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
  set(oneValueArgs INSTALL_DESTINATION )
  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()

  if(IS_ABSOLUTE "${CCF_INSTALL_DESTINATION}")
    set(absInstallDir "${CCF_INSTALL_DESTINATION}")
  else()
    set(absInstallDir "${CMAKE_INSTALL_PREFIX}/${CCF_INSTALL_DESTINATION}")
  endif()
225

226
227
228
229
230
231
  file(RELATIVE_PATH PACKAGE_RELATIVE_PATH "${absInstallDir}" "${CMAKE_INSTALL_PREFIX}" )

  foreach(var ${CCF_PATH_VARS})
    if(NOT DEFINED ${var})
      message(FATAL_ERROR "Variable ${var} does not exist")
    else()
232
233
234
      if(IS_ABSOLUTE "${${var}}")
        string(REPLACE "${CMAKE_INSTALL_PREFIX}" "\${PACKAGE_PREFIX_DIR}"
                        PACKAGE_${var} "${${var}}")
235
      else()
236
        set(PACKAGE_${var} "\${PACKAGE_PREFIX_DIR}/${${var}}")
237
      endif()
238
239
240
    endif()
  endforeach()

241
242
  get_filename_component(inputFileName "${_inputFile}" NAME)

243
244
  set(PACKAGE_INIT "
####### Expanded from @PACKAGE_INIT@ by configure_package_config_file() #######
245
246
247
####### Any changes to this file will be overwritten by the next CMake run ####
####### The input file was ${inputFileName}                            ########

248
249
250
get_filename_component(PACKAGE_PREFIX_DIR \"\${CMAKE_CURRENT_LIST_DIR}/${PACKAGE_RELATIVE_PATH}\" ABSOLUTE)
")

251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
  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)
  set(PACKAGE_PREFIX_DIR \"${CMAKE_INSTALL_PREFIX}\")
endif()
unset(_realOrig)
unset(_realCurr)
")
  endif()

266
267
268
269
270
271
272
273
274
275
276
  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()

277
278
279
280
281
282
283
284
285
286

  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()
287
  endforeach()
288
289
290
291
endmacro()
")
  endif()

292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
  if(NOT CCF_NO_FIND_DEPENDENCY_MACRO)
    set(PACKAGE_INIT "${PACKAGE_INIT}
macro(find_dependency dep)
  if (NOT \${dep}_FOUND)
    if (\${ARGV1})
      set(version \${ARGV1})
    endif()
    set(exact_arg)
    if(\${CMAKE_FIND_PACKAGE_NAME}_FIND_VERSION_EXACT)
      set(exact_arg EXACT)
    endif()
    set(quiet_arg)
    if(\${CMAKE_FIND_PACKAGE_NAME}_FIND_QUIETLY)
      set(quiet_arg QUIET)
    endif()
    set(required_arg)
    if(\${CMAKE_FIND_PACKAGE_NAME}_FIND_REQUIRED)
      set(required_arg REQUIRED)
    endif()

    find_package(\${dep} \${version} \${exact_arg} \${quiet_arg} \${required_arg})
    if (NOT \${dep}_FOUND)
      set(\${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE \"\${CMAKE_FIND_PACKAGE_NAME} could not be found because dependency \${dep} could not be found.\")
      set(\${CMAKE_FIND_PACKAGE_NAME}_FOUND False)
      return()
    endif()
    set(required_arg)
    set(quiet_arg)
    set(exact_arg)
  endif()
endmacro()
")
  endif()

326
327
328
329
330
331
  set(PACKAGE_INIT "${PACKAGE_INIT}
####################################################################################")

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

endfunction()