mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-02-16 12:11:04 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Fix CMakePackageConfigHelpers typos, grammar and formatting

Browse Source
This commit is contained in:
Craig Scott
2024-04-19 17:20:28 +10:00
parent f1cacaa830
commit b7fcc44be9
1 changed files with 56 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
Modules/CMakePackageConfigHelpers.cmake
View File

@@ -5,7 +5,7 @@
CMakePackageConfigHelpers
-------------------------
Helpers functions for creating config files that can be included by other
Helper functions for creating config files that can be included by other
projects to find and use a package.
Generating a Package Configuration File
@@ -26,11 +26,11 @@ Generating a Package Configuration File
``configure_package_config_file()`` should be used instead of the plain
:command:`configure_file()` command when creating the ``<PackageName>Config.cmake``
or ``<PackageName>-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.
It helps make the resulting package relocatable by avoiding hardcoded paths
in the installed ``<PackageName>Config.cmake`` file.
In a ``FooConfig.cmake`` file there may be code like this to make the install
destinations know to the using project:
destinations known to the using project:
.. code-block:: cmake
@@ -40,27 +40,25 @@ destinations know to the using project:
#...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
All four options shown above are not sufficient The first three hardcode the
absolute directory locations. The fourth 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
Windows and macOS, where users are used to choosing the install location of a
binary package at install time, independent from how
:variable:`CMAKE_INSTALL_PREFIX` was set at build/cmake time.
Using ``configure_package_config_file`` helps. If used correctly, it makes
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
1. Write a ``FooConfig.cmake.in`` file as you are used to.
2. Insert a line at the top 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()``
``@PACKAGE_INIT@`` line).
4. Instead of using the normal :command:`configure_file()` command, use
``configure_package_config_file()``.
The ``<input>`` and ``<output>`` arguments are the input and output file, the
same way as in :command:`configure_file()`.
@@ -70,48 +68,47 @@ the ``FooConfig.cmake`` file will be installed to. This path can either be
absolute, or relative to the ``INSTALL_PREFIX`` path.
The variables ``<var1>`` to ``<varN>`` given as ``PATH_VARS`` are the
variables which contain install destinations. For each of them the macro will
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
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
relative and also for absolute locations. For absolute locations, it works
only if the absolute location is a subdirectory of ``INSTALL_PREFIX``.
.. versionadded:: 3.1
If the ``INSTALL_PREFIX`` argument is passed, this is used as base path to
If the ``INSTALL_PREFIX`` argument is passed, this is used as the 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.
``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.
By default ``configure_package_config_file`` also generates two helper macros,
``set_and_check()`` and ``check_required_components()`` into the
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
``set_and_check()`` should be used instead of the normal :command:`set` command
for setting directories and file locations. In addition to setting the
variable, it also checks that the referenced file or directory actually exists
and fails with a fatal error if it doesn't. This ensures that the generated
``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.
Add the ``NO_SET_AND_CHECK_MACRO`` option to prevent the generation of the
``set_and_check()`` macro in the ``FooConfig.cmake`` file.
``check_required_components(<PackageName>)`` should be called at the end of
the ``FooConfig.cmake`` file. 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
non-optional components have been found, and if this is not the case, it 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. This macro should be
called even if the package doesn't provide any components to make sure
users are not specifying components erroneously. When using the
``NO_CHECK_REQUIRED_COMPONENTS_MACRO`` option, this macro is not generated
into the ``FooConfig.cmake`` file.
users are not specifying components erroneously. Add the
``NO_CHECK_REQUIRED_COMPONENTS_MACRO`` option to prevent the generation of the
``check_required_components()`` macro in the ``FooConfig.cmake`` file.
For an example see below the documentation for
:command:`write_basic_package_version_file()`.
See also :ref:`CMakePackageConfigHelpers Examples`.
Generating a Package Version File
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -126,11 +123,11 @@ Generating a Package Version File
[ARCH_INDEPENDENT] )
Writes a file for use as ``<PackageName>ConfigVersion.cmake`` file to
Writes a file for use as a ``<PackageName>ConfigVersion.cmake`` file to
``<filename>``. See the documentation of :command:`find_package()` for
details on this.
details on such files.
``<filename>`` is the output filename, it should be in the build tree.
``<filename>`` is the output filename, which 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.
@@ -153,9 +150,9 @@ 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.
If your project has more elaborate version matching rules, you will need to
write your own custom ``<PackageName>ConfigVersion.cmake`` file instead of
using this macro.
.. versionadded:: 3.11
The ``SameMinorVersion`` compatibility mode.
@@ -170,13 +167,13 @@ macro.
unless ``ARCH_INDEPENDENT`` is given, in which case the package is considered
compatible on any architecture.
.. note:: ``ARCH_INDEPENDENT`` is intended for header-only libraries or similar
packages with no binaries.
.. note:: ``ARCH_INDEPENDENT`` is intended for header-only libraries or
similar packages with no binaries.
.. versionadded:: 3.19
The version file generated by ``AnyNewerVersion``, ``SameMajorVersion`` and
``SameMinorVersion`` arguments of ``COMPATIBILITY`` handle the version range
if any is specified (see :command:`find_package` command for the details).
``SameMinorVersion`` arguments of ``COMPATIBILITY`` handle the version range,
if one is specified (see :command:`find_package` command for the details).
``ExactVersion`` mode is incompatible with version ranges and will display an
author warning if one is specified.
@@ -184,8 +181,9 @@ Internally, this macro executes :command:`configure_file()` to create the
resulting version file. Depending on the ``COMPATIBILITY``, the corresponding
``BasicConfigVersion-<COMPATIBILITY>.cmake.in`` file is used.
Please note that these files are internal to CMake and you should not call
:command:`configure_file()` on them yourself, but they can be used as starting
point to create more sophisticated custom ``ConfigVersion.cmake`` files.
:command:`configure_file()` on them yourself, but they can be used as a starting
point to create more sophisticated custom ``<PackageName>ConfigVersion.cmake``
files.
Generating an Apple Platform Selection File
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -328,15 +326,16 @@ Generating an Apple Platform Selection File
information to pretend the package was not found. If this option
is not given, the default behavior is to issue a fatal error.
.. _`CMakePackageConfigHelpers Examples`:
Example Generating Package Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Example using both :command:`configure_package_config_file` and
``write_basic_package_version_file()``:
``CMakeLists.txt``:
Example using both the :command:`configure_package_config_file` and
:command:`write_basic_package_version_file()` commands:
.. code-block:: cmake
:caption: ``CMakeLists.txt``
include(GNUInstallDirs)
set(INCLUDE_INSTALL_DIR ${CMAKE_INSTALL_INCLUDEDIR}/Foo
@@ -357,9 +356,9 @@ Example using both :command:`configure_package_config_file` and
${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo )
``FooConfig.cmake.in``:
::
.. code-block:: cmake
:caption: ``FooConfig.cmake.in``
:force:
set(FOO_VERSION x.y.z)
...