Difference between revisions of "CMake/Tutorials/Packaging"

From KitwarePublic
Jump to navigationJump to search
(Replace content with link to new CMake community wiki)
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
__TOC__
{{CMake/Template/Moved}}


This page documents creation and use of packages that help projects locate each other.
This page has moved [https://gitlab.kitware.com/cmake/community/wikis/doc/tutorials/Packaging here].
These features are distinct from CPack which is meant for creating source and binary distributions and installers.
 
The <code>find_package</code> command has been enhanced with features to help find packages without the use of "find" modules (FindXXX.cmake files).
Projects that are aware of CMake may provide a "package configuration file" inside their installation trees.
Naming the file correctly and installing it in a suitable location will allow the <code>find_package</code> command to find it easily.
 
See also the CMake [[CMake/Tutorials/Package_Registry|Package Registry]] to help <code>find_package</code> find packages in arbitrary locations.
 
=Package Configuration Files=
 
Consider a project "Foo" that installs the following files:
 
  <prefix>/include/foo-1.2/foo.h
  <prefix>/lib/foo-1.2/libfoo.a
 
It may also provide a CMake package configuration file
 
  <prefix>/lib/foo-1.2/foo-config.cmake
 
with content such as
 
  # ...
  # (compute PREFIX relative to file location)
  # ...
  set(foo_INCLUDE_DIRS ${PREFIX}/include/foo-1.2)
  set(foo_LIBRARY ${PREFIX}/lib/foo-1.2/libfoo.a)
 
If another project wishes to use Foo it need only to locate the <code>foo-config.cmake</code> file and load it to get all the information it needs about package content locations.
Since the package configuration file is provided by the package installation it already knows all the file locations.
 
The <code>find_package</code> command may be used to search for the configuration file:
 
  find_package(Foo)
 
This command (assuming no <code>FindFoo.cmake</code> module exists) constructs a set of installation prefixes and searches under each prefix in several locations.
Given the name "Foo", it looks for a file called "<code>FooConfig.cmake</code>" or "<code>foo-config.cmake</code>".
The full set of locations is specified in the <code>find_package</code> command documentation, but one place it looks is
 
  <prefix>/lib/Foo*/
 
where "<code>Foo*</code>" is a case-insensitive globbing expression.
In our example the globbing expression will match "<code><prefix>/lib/foo-1.2</code>" and the configuration file will be found.
 
'''Note:''' If your project does not already have a <code><prefix>/lib/Foo*/</code> directory you may prefer to put the package file in <code><prefix>/lib/cmake/Foo*/</code> to keep the <code>lib</code> directory clean.  However, CMake 2.6.2 and lower do not search there.  CMake 2.6.3 and above do.
 
Once found, a package configuration file is immediately loaded.  It contains all the information the project needs to use the package.
 
==Packaging and Exporting==
 
Package configuration files may also work in conjunction with [[CMake/Tutorials/Exporting_and_Importing_Targets|Exporting and Importing Targets]].
For example, a project might write
 
  add_library(mylib STATIC mylib.c mylib.h)
  install(FILES mylib.h DESTINATION include/myproj)
  install(TARGETS mylib EXPORT mylib-targets DESTINATION lib/myproj)
  install(EXPORT mylib-targets DESTINATION lib/myproj)
  install(FILES myproj-config.cmake DESTINATION lib/myproj)
 
where <code>myproj-config.cmake</code> contains something like
 
  get_filename_component(SELF_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH)
  include(${SELF_DIR}/mylib-targets.cmake)
  get_filename_component(myproj_INCLUDE_DIRS "${SELF_DIR}/../../include/myproj" ABSOLUTE)
 
After the project is built and installed, an outside project may use it by writing
 
  find_package(myproj REQUIRED)
  include_directories(${myproj_INCLUDE_DIRS})
  add_executable(myexe myexe.c)
  target_link_libraries(myexe mylib)
 
=Package Version Files=
 
The <code>find_package</code> command offers a version request argument.  One might write
 
  find_package(Foo 1.2)
  find_package(Bar 4.2 EXACT)
 
in order to get a version of package <code>Foo</code> that is compatible with version 1.2 and exactly package <code>Bar</code> version 4.2.
CMake does not attempt to define any convention for the compatibility or exactness of version numbers for a package.
It also does not try to map the version number to a directory or file name.
Instead packages must provide "version" files next to their package configuration files.
This allows maximum flexibility for project authors and package maintainers.
 
A package version file is placed next to the package configuration file.
Its name matches that of the configuration file but has either "<code>-version</code>" or "<code>Version</code>" appended to the name before the "<code>.cmake</code>" extension.
For example, the files
 
  <prefix>/lib/foo-1.3/foo-config.cmake
  <prefix>/lib/foo-1.3/foo-config-version.cmake
 
and
 
  <prefix>/lib/bar-4.2/BarConfig.cmake
  <prefix>/lib/bar-4.2/BarConfigVersion.cmake
 
are each pairs of package configuration files and corresponding version files.
When the <code>find_package</code> command finds a candidate package configuration file it looks next to it for a version file.
The version file is loaded to test whether the package version is an acceptable match for the version requested.
If the version file claims compatibility the configuration file is accepted.  Otherwise it is ignored.
 
When the <code>find_package</code> command loads a version file it first sets the following variables:
 
{| border=1
! CMake 2.6.2 and Above !! CMake 2.6.0 and 2.6.1
|-valign="top"
|<pre>
PACKAGE_FIND_NAME          = the <package> name
PACKAGE_FIND_VERSION      = full requested version string
PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
</pre>
||<pre>
PACKAGE_FIND_NAME          = the <package> name
PACKAGE_FIND_VERSION      = full requested version string
PACKAGE_FIND_VERSION_MAJOR = requested major version, if any
PACKAGE_FIND_VERSION_MINOR = requested minor version, if any
PACKAGE_FIND_VERSION_PATCH = requested patch version, if any
</pre>
|}
 
The version file must use these variables to check whether it is compatible or an exact match for the requested version.
It sets the following variables with results:
 
  PACKAGE_VERSION            = full provided version string
  PACKAGE_VERSION_EXACT      = true if version is exact match
  PACKAGE_VERSION_COMPATIBLE = true if version is compatible
  PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version (CMake >= 2.6.3)
 
For example, <code>foo-config-version.cmake</code> might contain
 
  set(PACKAGE_VERSION 1.3)
  if("${PACKAGE_FIND_VERSION_MAJOR}" EQUAL 1)
    set(PACKAGE_VERSION_COMPATIBLE 1) # compatible with any version 1.x
    if("${PACKAGE_FIND_VERSION_MINOR}" EQUAL 3)
      set(PACKAGE_VERSION_EXACT 1)    # exact match for version 1.3
    endif("${PACKAGE_FIND_VERSION_MINOR}" EQUAL 3)
  endif("${PACKAGE_FIND_VERSION_MAJOR}" EQUAL 1)
 
if it is compatible with all "<code>1.x</code>" versions of Foo and exactly matches version "<code>1.3</code>".
Note that the input variable names all start in "<code>PACKAGE_FIND_</code>" and the output variable names all start in "<code>PACKAGE_</code>".
The names are fixed and do not vary with the package name.
 
Version files are loaded in a nested scope so they are free to set any variables they wish as part of their computation.
The <code>find_package</code> command wipes out the scope when the version file has completed and it has checked the output variables.
When the version file claims to be an acceptable match for the requested version the <code>find_package</code> command sets the following variables for use by the project:
 
{| border=1
! CMake 2.6.2 and Above !! CMake 2.6.0 and 2.6.1
|-valign="top"
|<pre>
<package>_VERSION      = full provided version string
<package>_VERSION_MAJOR = major version if provided, else 0
<package>_VERSION_MINOR = minor version if provided, else 0
<package>_VERSION_PATCH = patch version if provided, else 0
<package>_VERSION_TWEAK = tweak version if provided, else 0
<package>_VERSION_COUNT = number of version components, 0 to 4
</pre>
||<pre>
<package>_VERSION      = package version (major[.minor[.patch]])
<package>_VERSION_MAJOR = major from major[.minor[.patch]], if any
<package>_VERSION_MINOR = minor from major[.minor[.patch]], if any
<package>_VERSION_PATCH = patch from major[.minor[.patch]], if any
</pre>
|}
 
The variables report the version of the package that was actually found.
The "<code><package></code>" part of their name matches the argument given to the <code>find_package</code> command.

Latest revision as of 15:40, 30 April 2018


The CMake community Wiki has moved to the Kitware GitLab Instance.

This page has moved here.