mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-03-07 23:28:36 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'doc-file-sets'

Browse Source 
4286b72240 Help: Update install() docs to better reflect preference for file sets
ab1b573f41 Help: Reorganise FILE_SETS and related properties

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7031
This commit is contained in:
Brad King
2022-03-09 17:07:42 +00:00
committed by Kitware Robot
parent 8c852e4cd0 4286b72240
commit 363a0d6010
8 changed files with 137 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
Help/command/install.rst
View File

@@ -207,11 +207,13 @@ that may be installed:
``FILE_SET <set>``
.. versionadded:: 3.23
File sets are defined by the :command:`target_sources(FILE_SET)` command.
If the file set ``<set>`` exists and is ``PUBLIC`` or ``INTERFACE``, any
files added to the file set ``<set>`` created by
:command:`target_sources(FILE_SET)` are installed in the specified
destination, preserving their directory structure relative to the file set's
base directories.
files in the set are installed under the destination (see below).
The directory structure relative to the file set's base directories is
preserved. For example, a file added to the file set as
``/blah/include/myproj/here.h`` with a base directory ``/blah/include``
would be installed to ``myproj/here.h`` below the destination.
For each of these arguments given, the arguments following them only apply
to the target or file type specified in the argument. If none is given, the
@@ -223,13 +225,13 @@ For regular executables, static libraries and shared libraries, the
``DESTINATION`` argument is not required. For these target types, when
``DESTINATION`` is omitted, a default destination will be taken from the
appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
default value if that variable is not defined. The same is true for the
public and private headers associated with the installed targets through the
:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties.
A destination must always be provided for module libraries, Apple bundles and
frameworks. A destination can be omitted for interface and object libraries,
but they are handled differently (see the discussion of this topic toward the
end of this section).
default value if that variable is not defined. The same is true for file
sets, and the public and private headers associated with the installed
targets through the :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER`
target properties. A destination must always be provided for module libraries,
Apple bundles and frameworks. A destination can be omitted for interface and
object libraries, but they are handled differently (see the discussion of this
topic toward the end of this section).
The following table shows the target types with their associated variables and
built-in defaults that apply when no destination is given:
@@ -246,8 +248,9 @@ built-in defaults that apply when no destination is given:
=============================== =============================== ======================
Projects wishing to follow the common practice of installing headers into a
project-specific subdirectory will need to provide a destination rather than
rely on the above.
project-specific subdirectory may prefer using file sets with appropriate
paths and base directories. Otherwise, they must provide a ``DESTINATION``
instead of being able to rely on the above (see next example below).
To make packages compliant with distribution filesystem layout policies, if
projects must specify a ``DESTINATION``, it is recommended that they use a
@@ -256,7 +259,7 @@ This allows package maintainers to control the install destination by setting
the appropriate cache variables. The following example shows a static library
being installed to the default destination provided by
:module:`GNUInstallDirs`, but with its headers installed to a project-specific
subdirectory that follows the above recommendation:
subdirectory without using file sets:
.. code-block:: cmake
@@ -493,6 +496,12 @@ Installing Files
.. _FILES:
.. _PROGRAMS:
.. note::
If installing header files, consider using file sets defined by
:command:`target_sources(FILE_SET)` instead. File sets associate
headers with a target and they install as part of the target.
.. code-block:: cmake
install(<FILES|PROGRAMS> files...
@@ -549,7 +558,8 @@ file type if they wish to explicitly define the install destination.
Projects wishing to follow the common practice of installing headers into a
project-specific subdirectory will need to provide a destination rather than
rely on the above.
rely on the above. Using file sets for headers instead of ``install(FILES)``
would be even better (see :command:`target_sources(FILE_SET)`).
Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
@@ -562,13 +572,14 @@ projects must specify a ``DESTINATION``, it is recommended that they use a
path that begins with the appropriate :module:`GNUInstallDirs` variable.
This allows package maintainers to control the install destination by setting
the appropriate cache variables. The following example shows how to follow
this advice while installing headers to a project-specific subdirectory:
this advice while installing an image to a project-specific documentation
subdirectory:
.. code-block:: cmake
include(GNUInstallDirs)
install(FILES mylib.h
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
install(FILES logo.png
DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
)
.. versionadded:: 3.4
@@ -587,6 +598,13 @@ Installing Directories
.. _`install(DIRECTORY)`:
.. _DIRECTORY:
.. note::
To install a directory sub-tree of headers, consider using file sets
defined by :command:`target_sources(FILE_SET)` instead. File sets not only
preserve directory structure, they also associate headers with a target
and install as part of the target.
.. code-block:: cmake
install(DIRECTORY dirs...
@@ -638,10 +656,10 @@ any expression. For example, the code
.. code-block:: cmake
install(DIRECTORY src/ DESTINATION include/myproj
FILES_MATCHING PATTERN "*.h")
install(DIRECTORY src/ DESTINATION doc/myproj
FILES_MATCHING PATTERN "*.png")
will extract and install header files from a source tree.
will extract and install images from a source tree.
Some options may follow a ``PATTERN`` or ``REGEX`` expression as described
under :ref:`string(REGEX) <Regex Specification>` and are applied

94
Help/command/target_sources.rst
View File

@@ -91,72 +91,58 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o
``FILE_SET <set>``
A string representing the name of the file set to create or add to. This must
contain only numbers, letters, and underscores, and must not start with a
capital letter or underscore, unless its name is ``HEADERS``.
The name of the file set to create or add to. It must contain only letters,
numbers and underscores. Names starting with a capital letter are reserved
for built-in file sets predefined by CMake. The only predefined set name is
``HEADERS``. All other set names must not start with a capital letter or
underscore.
``TYPE <type>``
A string representing the type of the file set. The only acceptable value is
``HEADERS``. This may be omitted if the name of the file set is ``HEADERS``.
Every file set is associated with a particular type of file. ``HEADERS``
is currently the only defined type and it is an error to specify anything
else. As a special case, if the name of the file set is ``HEADERS``, the
type does not need to be specified and the ``TYPE <type>`` arguments can be
omitted. For all other file set names, ``TYPE`` is required.
``BASE_DIRS <dirs>``
``BASE_DIRS <dirs>...``
An optional list of strings representing the base directories of the file
set. This argument supports
:manual:`generator expressions <cmake-generator-expressions(7)>`. No two
``BASE_DIRS`` may be sub-directories of each other. If no ``BASE_DIRS`` are
An optional list of base directories of the file set. Any relative path
is treated as relative to the current source directory
(i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). If no ``BASE_DIRS`` are
specified when the file set is first created, the value of
:variable:`CMAKE_CURRENT_SOURCE_DIR` is added.
:variable:`CMAKE_CURRENT_SOURCE_DIR` is added. This argument supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``FILES <files>``
No two base directories for a file set may be sub-directories of each other.
This requirement must be met across all base directories added to a file set,
not just those within a single call to ``target_sources()``.
An optional list of strings representing files in the file set. Each file
must be in one of the ``BASE_DIRS``. This argument supports
:manual:`generator expressions <cmake-generator-expressions(7)>`. If relative
paths are specified, they are considered relative to
``FILES <files>...``
An optional list of files to add to the file set. Each file must be in
one of the base directories, or a subdirectory of one of the base
directories. This argument supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
If relative paths are specified, they are considered relative to
:variable:`CMAKE_CURRENT_SOURCE_DIR` at the time ``target_sources()`` is
called, unless they start with ``$<``, in which case they are computed
relative to the target's source directory after genex evaluation.
called. An exception to this is a path starting with ``$<``. Such paths
are treated as relative to the target's source directory after evaluation
of generator expressions.
The following target properties are set by ``target_sources(FILE_SET)``:
The following target properties are set by ``target_sources(FILE_SET)``,
but they should not generally be manipulated directly:
:prop_tgt:`HEADER_SETS`
* :prop_tgt:`HEADER_SETS`
* :prop_tgt:`INTERFACE_HEADER_SETS`
* :prop_tgt:`HEADER_SET`
* :prop_tgt:`HEADER_SET_<NAME>`
* :prop_tgt:`HEADER_DIRS`
* :prop_tgt:`HEADER_DIRS_<NAME>`
List of ``PRIVATE`` and ``PUBLIC`` header sets associated with a target.
Headers listed in these header sets are treated as source files for the
purposes of IDE integration, and have their :prop_sf:`HEADER_FILE_ONLY`
property set to ``TRUE``.
:prop_tgt:`INTERFACE_HEADER_SETS`
List of ``INTERFACE`` and ``PUBLIC`` header sets associated with a target.
Headers listed in these header sets can be installed with
:command:`install(TARGETS)` and exported with :command:`install(EXPORT)` and
:command:`export`.
:prop_tgt:`HEADER_SET`
Headers in the default header set associated with a target. This property
supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
:prop_tgt:`HEADER_SET_<NAME>`
Headers in the named header set ``<NAME>`` associated with a target. This
property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
:prop_tgt:`HEADER_DIRS`
Base directories of the default header set associated with a target. This
property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
:prop_tgt:`HEADER_DIRS_<NAME>`
Base directories of the header set ``<NAME>`` associated with a target. This
property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Target properties related to include directories are also modified by
``target_sources(FILE_SET)`` as follows:
:prop_tgt:`INCLUDE_DIRECTORIES`

12
Help/prop_tgt/HEADER_DIRS.rst
View File

@@ -3,6 +3,12 @@ HEADER_DIRS
.. versionadded:: 3.23
Semicolon-separated list of base directories of the default header set created
by :command:`target_sources(FILE_SET)`. This property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Semicolon-separated list of base directories of the target's default
header set (i.e. the file set with name and type ``HEADERS``). The property
supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See :prop_tgt:`HEADER_DIRS_<NAME>` for the list of base directories in
other header sets.

13
Help/prop_tgt/HEADER_DIRS_NAME.rst
View File

@@ -3,6 +3,13 @@ HEADER_DIRS_<NAME>
.. versionadded:: 3.23
Semicolon-separated list of base directories of the header set with name
``<NAME>`` created by :command:`target_sources(FILE_SET)`. This property
supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
Semicolon-separated list of base directories of the target's ``<NAME>``
header set, which has the set type ``HEADERS``. The property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See :prop_tgt:`HEADER_DIRS` for the list of base directories in the
default header set. See :prop_tgt:`HEADER_SETS` for the file set names of all
header sets.

15
Help/prop_tgt/HEADER_SET.rst
View File

@@ -3,8 +3,13 @@ HEADER_SET
.. versionadded:: 3.23
Semicolon-separated list of headers in the default header set created by
:command:`target_sources(FILE_SET)`. This property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`. If any of the
headers are relative paths, they are computed relative to the target's source
directory.
Semicolon-separated list of files in the target's default header set,
(i.e. the file set with name and type ``HEADERS``). If any of the paths
are relative, they are computed relative to the target's source directory.
The property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See :prop_tgt:`HEADER_SET_<NAME>` for the list of files in other header sets.

14
Help/prop_tgt/HEADER_SETS.rst
View File

@@ -3,6 +3,14 @@ HEADER_SETS
.. versionadded:: 3.23
List of ``PRIVATE`` and ``PUBLIC`` header sets added by
:command:`target_sources(FILE_SET)`. Headers listed in these header sets are
treated as source files for the purposes of IDE integration.
List of the target's ``PRIVATE`` and ``PUBLIC`` header sets (i.e. all
file sets with the type ``HEADERS``). Files listed in these file sets
are treated as source files for the purpose of IDE integration.
The files also have their :prop_sf:`HEADER_FILE_ONLY` property set to
``TRUE``.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See also :prop_tgt:`HEADER_SET_<NAME>`, :prop_tgt:`HEADER_SET` and
:prop_tgt:`INTERFACE_HEADER_SETS`.

15
Help/prop_tgt/HEADER_SET_NAME.rst
View File

@@ -3,8 +3,13 @@ HEADER_SET_<NAME>
.. versionadded:: 3.23
Semicolon-separated list of headers in the named header set ``<NAME>`` created
by :command:`target_sources(FILE_SET)`. This property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`. If any of the
headers are relative paths, they are computed relative to the target's source
directory.
Semicolon-separated list of files in the target's ``<NAME>`` header set,
which has the set type ``HEADERS``. If any of the paths are relative,
they are computed relative to the target's source directory. The property
supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See :prop_tgt:`HEADER_SET` for the list of files in the default header set.
See :prop_tgt:`HEADER_SETS` for the file set names of all header sets.

11
Help/prop_tgt/INTERFACE_HEADER_SETS.rst
View File

@@ -3,7 +3,12 @@ INTERFACE_HEADER_SETS
.. versionadded:: 3.23
List of ``INTERFACE`` and ``PUBLIC`` header sets added by
:command:`target_sources(FILE_SET)`. Headers listed in these header sets can be
installed with :command:`install(TARGETS)` and exported with
List of the target's ``INTERFACE`` and ``PUBLIC`` header sets (i.e. all
file sets with the type ``HEADERS``). Files listed in these header sets
can be installed with :command:`install(TARGETS)` and exported with
:command:`install(EXPORT)` and :command:`export`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See also :prop_tgt:`HEADER_SETS`.