Merge topic 'target-sources-file-set'

a7c71b9f03 Tests: Add tests for target_sources(FILE_SET) and associated functionality
4b0ee4e338 Help: Add documentation for target_sources(FILE_SET) and associated properties
3c3698b0e4 FileAPI: Add information on file set installers
8a09723bff cmGeneratorTarget: Integrate file sets into calculated sources
2a78d47b16 install(EXPORT): Install file sets
9b479124cc install(TARGETS): Add FILE_SET mode
d8af2d954f target_sources(): Add FILE_SET mode
f2bd022468 cmTargetSources: Refactor to add enum class parameters
...

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Merge-request: !6653

11 files changed, 235 insertions, 11 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-file-api.7.rst b/Help/manual/cmake-file-api.7.rst
index 5e22ea9..4b8ac65 100644
--- a/Help/manual/cmake-file-api.7.rst
+++ b/Help/manual/cmake-file-api.7.rst
@@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from
 
   {
     "kind": "codemodel",
-    "version": { "major": 2, "minor": 2 },
+    "version": { "major": 2, "minor": 4 },
     "paths": {
       "source": "/path/to/top-level-source-dir",
       "build": "/path/to/top-level-build-dir"
@@ -758,6 +758,15 @@ with members:
       ``destination`` member is populated. This type has additional members
       ``runtimeDependencySetName`` and ``runtimeDependencySetType``.
 
+    ``fileSet``
+      An :command:`install(TARGETS)` call with ``FILE_SET``.
+      The ``destination`` and ``paths`` members are populated.
+      The ``isOptional`` member may exist.
+      This type has additional members ``fileSetName``, ``fileSetType``,
+      ``fileSetDirectories``, and ``fileSetTarget``.
+
+      This type was added in codemodel version 2.4.
+
   ``isExcludeFromAll``
     Optional member that is present with boolean value ``true`` when
     :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option.
@@ -835,6 +844,41 @@ with members:
       Indicates that this installer installs dependencies that are macOS
       frameworks.
 
+  ``fileSetName``
+    Optional member that is present when ``type`` is ``fileSet``. The value is
+    a string with the name of the file set.
+
+    This field was added in codemodel version 2.4.
+
+  ``fileSetType``
+    Optional member that is present when ``type`` is ``fileSet``. The value is
+    a string with the type of the file set.
+
+    This field was added in codemodel version 2.4.
+
+  ``fileSetDirectories``
+    Optional member that is present when ``type`` is ``fileSet``. The value
+    is a list of strings with the file set's base directories (determined by
+    genex-evaluation of :prop_tgt:`HEADER_DIRS` or
+    :prop_tgt:`HEADER_DIRS_<NAME>`).
+
+    This field was added in codemodel version 2.4.
+
+  ``fileSetTarget``
+    Optional member that is present when ``type`` is ``fileSet``. The value
+    is a JSON object with members:
+
+    ``id``
+      A string uniquely identifying the target.  This matches
+      the ``id`` member of the target in the main "codemodel"
+      object's ``targets`` array.
+
+    ``index``
+      An unsigned integer 0-based index into the main "codemodel"
+      object's ``targets`` array for the target.
+
+    This field was added in codemodel version 2.4.
+
   ``scriptFile``
     Optional member that is present when ``type`` is ``script``.
     The value is a string specifying the path to the script file on disk,
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``.