Help: Add documentation for target_sources(FILE_SET) and associated properties

10 files changed, 190 insertions, 10 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 1236f1d..abde6e0 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -132,7 +132,7 @@ Installing Targets
   install(TARGETS targets... [EXPORT <export-name>]
           [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
           [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
-            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
+            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>]
            [DESTINATION <dir>]
            [PERMISSIONS permissions...]
            [CONFIGURATIONS [Debug|Release|...]]
@@ -204,6 +204,13 @@ that may be installed:
   Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for
   ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details.
 
+``FILE_SET <set>``
+  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.
+
 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
 installation properties apply to all target types. If only one is given then
@@ -225,15 +232,16 @@ 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:
 
-================== =============================== ======================
-   Target Type         GNUInstallDirs Variable        Built-In Default
-================== =============================== ======================
-``RUNTIME``        ``${CMAKE_INSTALL_BINDIR}``     ``bin``
-``LIBRARY``        ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
-``ARCHIVE``        ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
-``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
-``PUBLIC_HEADER``  ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
-================== =============================== ======================
+=============================== =============================== ======================
+   Target Type                      GNUInstallDirs Variable        Built-In Default
+=============================== =============================== ======================
+``RUNTIME``                     ``${CMAKE_INSTALL_BINDIR}``     ``bin``
+``LIBRARY``                     ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
+``ARCHIVE``                     ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
+``PRIVATE_HEADER``              ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+``PUBLIC_HEADER``               ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+``FILE_SET`` (type ``HEADERS``) ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+=============================== =============================== ======================
 
 Projects wishing to follow the common practice of installing headers into a
 project-specific subdirectory will need to provide a destination rather than
@@ -338,6 +346,11 @@ top level:
   See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
   the name of the exported target.
 
+  If ``EXPORT`` is used and the targets include ``PUBLIC`` or ``INTERFACE``
+  file sets, all of them must be specified with ``FILE_SET`` arguments. All
+  ``PUBLIC`` or ``INTERFACE`` file sets associated with a target are included
+  in the export.
+
 ``INCLUDES DESTINATION``
   This option specifies a list of directories which will be added to the
   :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst
index 520614a..2fded5e 100644
--- a/Help/command/target_sources.rst
+++ b/Help/command/target_sources.rst
@@ -46,3 +46,105 @@ Arguments to ``target_sources`` may use "generator expressions"
 with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
+
+.. code-block:: cmake
+
+  target_sources(<target>
+    <INTERFACE|PUBLIC|PRIVATE> [FILE_SET set1] [TYPE type1] [BASE_DIRS dirs1...] [FILES files1...]
+    [<INTERFACE|PUBLIC|PRIVATE> [FILE_SET set2] [TYPE type2] [BASE_DIRS dirs2...] [FILES files2...])
+
+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. The only acceptable type is ``HEADERS``. The
+optional default file sets are named after their type.
+
+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.
+
+Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, or
+``PRIVATE`` and accepts the following arguments:
+
+``FILE_SET <set>``
+
+  A string representing the name of the file set to create or add to. This must
+  not start with a capital letter, unless its name is ``HEADERS``.
+
+``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``.
+
+``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
+  specified when the file set is first created, the value of
+  :variable:`CMAKE_CURRENT_SOURCE_DIR` is added.
+
+``FILES <files>``
+
+  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
+  :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.
+
+The following target properties are set by ``target_sources(FILE_SET)``:
+
+:prop_tgt:`HEADER_SETS`
+
+  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)>`.
+
+: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.
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 435b2c6..3d74a11 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -214,6 +214,11 @@ Properties on Targets
    /prop_tgt/GHS_NO_SOURCE_GROUP_FILE
    /prop_tgt/GNUtoMS
    /prop_tgt/HAS_CXX
+   /prop_tgt/HEADER_DIRS
+   /prop_tgt/HEADER_DIRS_NAME
+   /prop_tgt/HEADER_SET
+   /prop_tgt/HEADER_SET_NAME
+   /prop_tgt/HEADER_SETS
    /prop_tgt/HIP_ARCHITECTURES
    /prop_tgt/HIP_EXTENSIONS
    /prop_tgt/HIP_STANDARD
@@ -255,6 +260,7 @@ Properties on Targets
    /prop_tgt/INTERFACE_COMPILE_DEFINITIONS
    /prop_tgt/INTERFACE_COMPILE_FEATURES
    /prop_tgt/INTERFACE_COMPILE_OPTIONS
+   /prop_tgt/INTERFACE_HEADER_SETS
    /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES
    /prop_tgt/INTERFACE_LINK_DEPENDS
    /prop_tgt/INTERFACE_LINK_DIRECTORIES
diff --git a/Help/prop_tgt/HEADER_DIRS.rst b/Help/prop_tgt/HEADER_DIRS.rst
new file mode 100644
index 0000000..3495545
--- /dev/null
+++ b/Help/prop_tgt/HEADER_DIRS.rst
@@ -0,0 +1,6 @@
+HEADER_DIRS
+-----------
+
+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)>`.
diff --git a/Help/prop_tgt/HEADER_DIRS_NAME.rst b/Help/prop_tgt/HEADER_DIRS_NAME.rst
new file mode 100644
index 0000000..c2bbd0a
--- /dev/null
+++ b/Help/prop_tgt/HEADER_DIRS_NAME.rst
@@ -0,0 +1,6 @@
+HEADER_DIRS_<NAME>
+------------------
+
+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)>`.
diff --git a/Help/prop_tgt/HEADER_SET.rst b/Help/prop_tgt/HEADER_SET.rst
new file mode 100644
index 0000000..2b8b0d4
--- /dev/null
+++ b/Help/prop_tgt/HEADER_SET.rst
@@ -0,0 +1,8 @@
+HEADER_SET
+----------
+
+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.
diff --git a/Help/prop_tgt/HEADER_SETS.rst b/Help/prop_tgt/HEADER_SETS.rst
new file mode 100644
index 0000000..ed7c528
--- /dev/null
+++ b/Help/prop_tgt/HEADER_SETS.rst
@@ -0,0 +1,6 @@
+HEADER_SETS
+-----------
+
+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.
diff --git a/Help/prop_tgt/HEADER_SET_NAME.rst b/Help/prop_tgt/HEADER_SET_NAME.rst
new file mode 100644
index 0000000..25a5573
--- /dev/null
+++ b/Help/prop_tgt/HEADER_SET_NAME.rst
@@ -0,0 +1,8 @@
+HEADER_SET_<NAME>
+-----------------
+
+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.
diff --git a/Help/prop_tgt/INTERFACE_HEADER_SETS.rst b/Help/prop_tgt/INTERFACE_HEADER_SETS.rst
new file mode 100644
index 0000000..93ea9c5
--- /dev/null
+++ b/Help/prop_tgt/INTERFACE_HEADER_SETS.rst
@@ -0,0 +1,7 @@
+INTERFACE_HEADER_SETS
+---------------------
+
+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
+:command:`install(EXPORT)` and :command:`export`.
diff --git a/Help/release/dev/target-sources-file-set.rst b/Help/release/dev/target-sources-file-set.rst
new file mode 100644
index 0000000..bd28efa
--- /dev/null
+++ b/Help/release/dev/target-sources-file-set.rst
@@ -0,0 +1,18 @@
+target-headers
+--------------
+
+* The :command:`target_sources` command gained a new ``FILE_SET`` mode, which
+  can be used to add headers as header-only source files of a target.
+* New :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` properties
+  were added, which list the header file sets associated with a target.
+* New :prop_tgt:`HEADER_SET` and :prop_tgt:`HEADER_SET_<NAME>` properties were
+  added, which list the files in the associated header file set.
+* New :prop_tgt:`HEADER_DIRS` and :prop_tgt:`HEADER_DIRS_<NAME>` properties
+  were added, which specify the base directories of the associated header file
+  set.
+* The :command:`install(TARGETS)` command gained a new ``FILE_SET`` argument,
+  which can be used to install header file sets associated with a target.
+* The :manual:`File API <cmake-file-api(7)>` ``codemodel-v2`` minor version has
+  been bumped to ``4``.
+* The :manual:`File API <cmake-file-api(7)>` ``codemodel-v2`` ``directory``
+  object gained a new installer type of ``fileSet``.