summaryrefslogtreecommitdiff
path: root/Help/command/source_group.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Help/command/source_group.rst')
-rw-r--r--Help/command/source_group.rst58
1 files changed, 58 insertions, 0 deletions
diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst
new file mode 100644
index 000000000..938ca40f2
--- /dev/null
+++ b/Help/command/source_group.rst
@@ -0,0 +1,58 @@
+source_group
+------------
+
+Define a grouping for source files in IDE project generation.
+There are two different signatures to create source groups.
+
+::
+
+ source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
+ source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
+
+Defines a group into which sources will be placed in project files.
+This is intended to set up file tabs in Visual Studio.
+The options are:
+
+``TREE``
+ CMake will automatically detect, from ``<src>`` files paths, source groups
+ it needs to create, to keep structure of source groups analogically to the
+ actual files and directories structure in the project. Paths of ``<src>``
+ files will be cut to be relative to ``<root>``.
+
+``PREFIX``
+ Source group and files located directly in ``<root>`` path, will be placed
+ in ``<prefix>`` source groups.
+
+``FILES``
+ Any source file specified explicitly will be placed in group
+ ``<name>``. Relative paths are interpreted with respect to the
+ current source directory.
+
+``REGULAR_EXPRESSION``
+ Any source file whose name matches the regular expression will
+ be placed in group ``<name>``.
+
+If a source file matches multiple groups, the *last* group that
+explicitly lists the file with ``FILES`` will be favored, if any.
+If no group explicitly lists the file, the *last* group whose
+regular expression matches the file will be favored.
+
+The ``<name>`` of the group and ``<prefix>`` argument may contain backslashes
+to specify subgroups:
+
+.. code-block:: cmake
+
+ source_group(outer\\inner ...)
+ source_group(TREE <root> PREFIX sources\\inc ...)
+
+For backwards compatibility, the short-hand signature
+
+.. code-block:: cmake
+
+ source_group(<name> <regex>)
+
+is equivalent to
+
+.. code-block:: cmake
+
+ source_group(<name> REGULAR_EXPRESSION <regex>)