Merge topic 'help-add_custom_command-DEPFILE-format'

8a3aac990e Help: add_custom_command: describes depfile format

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

Help/command/add_custom_command.rst

@@ -271,9 +271,48 @@ The options are:
 ``DEPFILE``
   .. versionadded:: 3.7
 
-  Specify a ``.d`` depfile which holds dependencies for the custom command.
-  It is usually emitted by the custom command itself.  This keyword may only
-  be used if the generator supports it, as detailed below.
+  Specify a depfile which holds dependencies for the custom command. It is
+  usually emitted by the custom command itself.  This keyword may only be used
+  if the generator supports it, as detailed below.
+
+  The expected format, compatible with what is generated by ``gcc`` with the
+  option ``-M``, is independent of the generator or platform.
+
+  The formal syntax, as specified using
+  `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
+  the regular extensions, is the following:
+
+  .. raw:: latex
+
+    \begin{small}
+
+  .. productionlist:: depfile
+    depfile: `rule`*
+    rule: `targets` (`colon` `dependencies`?)? `eol`
+    colon: `separator`* ':' space `separator`*
+    targets: `target` (`separator` `target`)*
+    target: `pathname`
+    dependencies: `dependency` (`separator` `dependency`)*
+    dependency: `pathname`
+    separator: (space | line_continue)+
+    line_continue: '\' `eol`
+    space: ' ' | '\t'
+    pathname: `character`+
+    character: `std_character` | `dollar` | `hash` | `whitespace`
+    std_character: <any character except '$', '#' or ' '>
+    dollar: '$$'
+    hash: '\#'
+    whitespace: '\ '
+    eol: '\r'? '\n'
+
+  .. raw:: latex
+
+    \end{small}
+
+  .. note::
+
+    As part of ``pathname``, any slash and backslash is interpreted as
+    a directory separator.
 
   .. versionadded:: 3.7
     The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword