dilim/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-08-03 14:20:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Help: Move general FILE_SET info to cmake-buildsystem(7)

Browse Source 
File sets have evolved to be more ubiquitous throughout a CMake build,
outside the scope of simply the target_sources command. Move general
information to the `cmake-buildsystem(7)` manual and keep only
reference information specific to the syntax of target_sources in its
command page. Sprinkle some more cross-references to the new location.

Fixes: #27900

Suggested-By: Marc Chevrier <marc.chevrier@gmail.com>
This commit is contained in:
Tyler Yankee
2026-07-22 12:02:40 -04:00
parent 41b071e482
commit c707fde0f2
5 changed files with 134 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
Help/command/install.rst
View File

@@ -247,9 +247,9 @@ Signatures
``FILE_SET <set-name>``
.. versionadded:: 3.23
File sets are defined by the :command:`target_sources(FILE_SET)` command.
If the file set ``<set-name>`` exists and is ``PUBLIC`` or ``INTERFACE``,
any files in the set of type ``HEADERS`` are installed under
:ref:`File sets` are defined by the :command:`target_sources(FILE_SET)`
command. If the file set ``<set-name>`` exists and is ``PUBLIC`` or
``INTERFACE``, any files in the set of type ``HEADERS`` are installed under
the destination (see below). Other types do not have any default
destination, so ``DESTINATION`` option must be specified for each
``FILE_SET``.
@@ -534,9 +534,10 @@ Signatures
.. note::
If installing header files, consider using file sets defined by
If installing header files, consider using :ref:`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.
headers with a target and they install as part of the target. See the
:manual:`cmake-buildsystem(7)` manual for more details.
Install files or programs:
@@ -643,10 +644,11 @@ Signatures
.. note::
To install a directory sub-tree of headers, consider using file sets
To install a directory sub-tree of headers, consider using :ref:`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.
and install as part of the target. See the :manual:`cmake-buildsystem(7)`
manual for more details.
Install the contents of one or more directories:

2
Help/command/source_group.rst
View File

@@ -88,6 +88,8 @@ Commands
List of file sets. Files of these file sets will be placed in group
``<group>``. Arguments to ``FILE_SETS`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
See the :manual:`cmake-buildsystem(7)` manual for more details on
:ref:`File Sets`.
``TARGET <target>``
.. versionadded:: 4.5

101
Help/command/target_sources.rst
View File

@@ -63,8 +63,6 @@ expressions to ensure the sources are correctly assigned to the target.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
.. _`File Sets`:
File Sets
^^^^^^^^^
@@ -78,49 +76,11 @@ File Sets
]...)
Adds a file set to a target, or adds files to an existing file set. Targets
have zero or more named file sets. Each file set has a name, a type, a scope of
``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and
files within those directories.
have zero or more named file sets.
.. versionchanged:: 4.4
A file may belong to at most one non-``HEADERS`` file set in a target.
See policy :policy:`CMP0211`.
The acceptable types include:
``HEADERS``
Sources intended to be used via a language's ``#include`` mechanism.
``SOURCES``
.. versionadded:: 4.4
Specifies sources to use when building a target and/or its dependents.
With the scope ``PRIVATE`` and ``PUBLIC``, ``<files>`` will populate the
:prop_fs:`SOURCES` property of ``<set>``, which are used when building the
target itself. With the scope ``PUBLIC`` and ``INTERFACE``, ``<files>`` will
populate the :prop_fs:`INTERFACE_SOURCES` property of ``<set>``, which are
used when building dependents. The sources specified by the
:prop_fs:`INTERFACE_SOURCES` property are propagated, transitively, to all
the dependents.
``CXX_MODULES``
.. versionadded:: 3.28
Sources which contain C++ interface module or partition units (i.e., those
using the ``export`` keyword). This file set type may not have an
``INTERFACE`` scope except on ``IMPORTED`` targets.
The optional default file sets are named after their type. The target may not
be a custom target or, for ``HEADERS`` and ``CXX_MODULES`` types, a
:prop_tgt:`FRAMEWORK` target.
Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets
have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. Files in an
``INTERFACE`` or ``PUBLIC`` file set can be installed with the
:command:`install(TARGETS)` command, and exported with the
:command:`install(EXPORT)` and :command:`export` commands.
See the :manual:`cmake-buildsystem(7)` manual for more on :ref:`File Sets`,
including their types and scope semantics, properties, and installation/export
behavior.
Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``,
or ``PRIVATE`` and accepts the following arguments:
@@ -137,10 +97,10 @@ or ``PRIVATE`` and accepts the following arguments:
``TYPE <type>``
Every file set is associated with a particular type of file. Only types
specified above may be used and it is an error to specify anything else. As
a special case, if the name of the file set is one of the types, 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.
listed under :ref:`File Sets` may be used and it is an error to specify
anything else. As a special case, if the name of the file set is one of these
types, 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>...``
@@ -168,51 +128,6 @@ or ``PRIVATE`` and accepts the following arguments:
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)``,
but they should not generally be manipulated directly:
For file sets of type ``HEADERS``:
* :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>`
For file sets of type ``SOURCES``:
* :prop_tgt:`SOURCE_SETS`
* :prop_tgt:`INTERFACE_SOURCE_SETS`
* :prop_tgt:`SOURCE_SET`
* :prop_tgt:`SOURCE_SET_<NAME>`
* :prop_tgt:`SOURCE_DIRS`
* :prop_tgt:`SOURCE_DIRS_<NAME>`
For file sets of type ``CXX_MODULES``:
* :prop_tgt:`CXX_MODULE_SETS`
* :prop_tgt:`INTERFACE_CXX_MODULE_SETS`
* :prop_tgt:`CXX_MODULE_SET`
* :prop_tgt:`CXX_MODULE_SET_<NAME>`
* :prop_tgt:`CXX_MODULE_DIRS`
* :prop_tgt:`CXX_MODULE_DIRS_<NAME>`
Target properties related to include directories are also modified by
``target_sources(FILE_SET)`` as follows:
:prop_tgt:`INCLUDE_DIRECTORIES`
If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE``
or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in
:genex:`$<BUILD_INTERFACE>` and appended to this property.
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
If the ``TYPE`` is ``HEADERS``, and the scope of the file set is
``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are
wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property.
See Also
^^^^^^^^

109
Help/manual/cmake-buildsystem.7.rst
View File

@@ -378,6 +378,115 @@ The commands are:
Populates the :prop_tgt:`LINK_OPTIONS` build specification and
:prop_tgt:`INTERFACE_LINK_OPTIONS` usage requirement properties.
.. _`File Sets`:
File Sets
^^^^^^^^^
.. versionadded:: 3.23
File sets associate files with a target as structured groups. A target has
zero or more named file sets. Each file set has:
* a name
* a type
* a scope of ``INTERFACE``, ``PUBLIC``, or ``PRIVATE``
* one or more base directories
* files within those directories
File sets are added to targets with :command:`target_sources` using the
``FILE_SET`` signature. See :command:`target_sources` for argument syntax and
validation details.
.. versionchanged:: 4.4
A file may belong to at most one non-``HEADERS`` file set in a target.
See policy :policy:`CMP0211`.
Acceptable file set types are:
``HEADERS``
Sources intended to be used via a language's ``#include`` mechanism.
``SOURCES``
.. versionadded:: 4.4
Specifies sources to use when building a target and/or its dependents.
With the scope ``PRIVATE`` and ``PUBLIC``, items populate the
:prop_fs:`SOURCES` property of the file set, which is used when building the
target itself. With the scope ``PUBLIC`` and ``INTERFACE``, items populate
the :prop_fs:`INTERFACE_SOURCES` property of the file set, which is used
when building dependents. Sources specified by
:prop_fs:`INTERFACE_SOURCES` propagate transitively to dependents.
``CXX_MODULES``
.. versionadded:: 3.28
Sources which contain C++ interface module or partition units (i.e., those
using the ``export`` keyword). This file set type may not have an
``INTERFACE`` scope except on ``IMPORTED`` targets.
The optional default file sets are named after their type. The target may not
be a custom target or, for ``HEADERS`` and ``CXX_MODULES`` types, a
:prop_tgt:`FRAMEWORK` target.
Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
IDE integration. Additionally, files in ``HEADERS`` file sets have their
:prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``.
Files in an ``INTERFACE`` or ``PUBLIC`` file set can be installed by
:command:`install(TARGETS)` and exported by :command:`install(EXPORT)` and
:command:`export`.
The following target properties are set by file sets and should not generally
be manipulated directly:
For file sets of type ``HEADERS``:
* :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>`
For file sets of type ``SOURCES``:
* :prop_tgt:`SOURCE_SETS`
* :prop_tgt:`INTERFACE_SOURCE_SETS`
* :prop_tgt:`SOURCE_SET`
* :prop_tgt:`SOURCE_SET_<NAME>`
* :prop_tgt:`SOURCE_DIRS`
* :prop_tgt:`SOURCE_DIRS_<NAME>`
For file sets of type ``CXX_MODULES``:
* :prop_tgt:`CXX_MODULE_SETS`
* :prop_tgt:`INTERFACE_CXX_MODULE_SETS`
* :prop_tgt:`CXX_MODULE_SET`
* :prop_tgt:`CXX_MODULE_SET_<NAME>`
* :prop_tgt:`CXX_MODULE_DIRS`
* :prop_tgt:`CXX_MODULE_DIRS_<NAME>`
Target properties related to include directories are also modified by file
sets as follows:
:prop_tgt:`INCLUDE_DIRECTORIES`
If the type is ``HEADERS``, and the scope of the file set is ``PRIVATE`` or
``PUBLIC``, all ``BASE_DIRS`` of the file set are wrapped in
:genex:`$<BUILD_INTERFACE>` and appended to this property.
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
If the type is ``HEADERS``, and the scope of the file set is ``INTERFACE``
or ``PUBLIC``, all ``BASE_DIRS`` of the file set are wrapped in
:genex:`$<BUILD_INTERFACE>` and appended to this property.
File sets do not populate the :prop_tgt:`SOURCES` or
:prop_tgt:`INTERFACE_SOURCES` target properties. They are represented by
their own file set and type-specific properties.
.. _`Target Build Specification`:
Target Build Specification

11
Help/manual/cmake-file-api.7.rst
View File

@@ -1581,15 +1581,16 @@ with members:
.. codemodel-versionadded:: 2.5
An optional member that is present when a target defines one or more
file sets. The value is a JSON array of entries corresponding to the
:ref:`File Sets`. The value is a JSON array of entries corresponding to the
target's file sets. Each entry is a JSON object with members:
``name``
A string specifying the name of the file set.
``type``
A string specifying the type of the file set. See
:command:`target_sources` supported file set types.
A string specifying the type of the file set. See the
:manual:`cmake-buildsystem(7)` manual for the list of supported file set
types.
``visibility``
A string specifying the visibility of the file set; one of ``PUBLIC``,
@@ -1642,7 +1643,7 @@ with members:
Optional member that is present when the source is part of at least one
file set; see also policy :policy:`CMP0211`. The value is
an array of unsigned integer 0-based indexes inte the ``fileSets`` array.
an array of unsigned integer 0-based indexes into the ``fileSets`` array.
``backtrace``
.. deprecated:: 4.4
@@ -1709,7 +1710,7 @@ with members:
Optional member that is present when the source is part of at least one
file set; see also policy :policy:`CMP0211`. The value is
an array of unsigned integer 0-based indexes inte the ``fileSets`` array.
an array of unsigned integer 0-based indexes into the ``fileSets`` array.
``sourceGroups``
Optional member that is present when sources are grouped together by