From c707fde0f26cb8d15db22a1a5b707c4b8c1bb6cc Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Wed, 22 Jul 2026 12:02:40 -0400 Subject: [PATCH] Help: Move general FILE_SET info to cmake-buildsystem(7) 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 --- Help/command/install.rst | 16 ++-- Help/command/source_group.rst | 2 + Help/command/target_sources.rst | 101 ++------------------------ Help/manual/cmake-buildsystem.7.rst | 109 ++++++++++++++++++++++++++++ Help/manual/cmake-file-api.7.rst | 11 +-- 5 files changed, 134 insertions(+), 105 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index cb8db41cd2..801cd7fd0d 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -247,9 +247,9 @@ Signatures ``FILE_SET `` .. versionadded:: 3.23 - File sets are defined by the :command:`target_sources(FILE_SET)` command. - If the file set ```` 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 ```` 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: diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 60e3bf82e7..cc517bf646 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -88,6 +88,8 @@ Commands List of file sets. Files of these file sets will be placed in group ````. Arguments to ``FILE_SETS`` may use :manual:`generator expressions `. + See the :manual:`cmake-buildsystem(7)` manual for more details on + :ref:`File Sets`. ``TARGET `` .. versionadded:: 4.5 diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 528e660ad4..3ad25dcc72 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -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``, ```` will populate the - :prop_fs:`SOURCES` property of ````, which are used when building the - target itself. With the scope ``PUBLIC`` and ``INTERFACE``, ```` will - populate the :prop_fs:`INTERFACE_SOURCES` property of ````, 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 `` 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 `` 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 `` + arguments can be omitted. For all other file set names, ``TYPE`` is required. ``BASE_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_` -* :prop_tgt:`HEADER_DIRS` -* :prop_tgt:`HEADER_DIRS_` - -For file sets of type ``SOURCES``: - -* :prop_tgt:`SOURCE_SETS` -* :prop_tgt:`INTERFACE_SOURCE_SETS` -* :prop_tgt:`SOURCE_SET` -* :prop_tgt:`SOURCE_SET_` -* :prop_tgt:`SOURCE_DIRS` -* :prop_tgt:`SOURCE_DIRS_` - -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_` -* :prop_tgt:`CXX_MODULE_DIRS` -* :prop_tgt:`CXX_MODULE_DIRS_` - -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:`$` 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:`$` and appended to this property. - See Also ^^^^^^^^ diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 967c3e31ac..7b349d0a2a 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -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_` +* :prop_tgt:`HEADER_DIRS` +* :prop_tgt:`HEADER_DIRS_` + +For file sets of type ``SOURCES``: + +* :prop_tgt:`SOURCE_SETS` +* :prop_tgt:`INTERFACE_SOURCE_SETS` +* :prop_tgt:`SOURCE_SET` +* :prop_tgt:`SOURCE_SET_` +* :prop_tgt:`SOURCE_DIRS` +* :prop_tgt:`SOURCE_DIRS_` + +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_` +* :prop_tgt:`CXX_MODULE_DIRS` +* :prop_tgt:`CXX_MODULE_DIRS_` + +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:`$` 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:`$` 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 diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 64dd5bdc07..163c5f890f 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -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