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

1 files changed, 102 insertions, 0 deletions

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.