[jhbuild/feature/regex-based-include-searching: 3/4] docs: documenet c_include_glob

[Sebastian Geiger <segeiger src gnome org>]

commit 297ae4225b184ce5cbd0c0ba349f689f312ec5a3
Author: Sebastian Geiger <sbastig gmx net>
Date:   Sun May 16 12:35:05 2021 +0200

    docs: documenet c_include_glob

 doc/C/index.docbook | 74 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 62 insertions(+), 12 deletions(-)
---
diff --git a/doc/C/index.docbook b/doc/C/index.docbook
index 20fb5c47..b8951948 100644
--- a/doc/C/index.docbook
+++ b/doc/C/index.docbook
@@ -3270,25 +3270,43 @@ Optional packages: (JHBuild will build the missing packages)
 &lt;/systemmodule&gt;
 </programlisting>
 
-        <para>If the system module does not provide a pkg-config file,
+        <para>If the system module does not provide a pkg-config file, the
           <sgmltag class="element">systemdependencies</sgmltag> tag can be used
-          to identify the dependencies. Two values are supported by the
-          <sgmltag class="attribute">type</sgmltag> attribute of the
-          <sgmltag class="element">dep</sgmltag> tag:</para>
+          to identify the dependencies. A dependency is specified using the
+          <sgmltag class="element">dep</sgmltag> subelement which accepts both a
+          <sgmltag class="attribute">type</sgmltag> and a
+          <sgmltag class="attribute">name</sgmltag> attribute. A dependency
+          can either be an executable program or a C include file. The
+          <sgmltag class="attribute">type</sgmltag> attribute supports
+          three different types to specify dependencies:</para>
 
         <orderedlist>
           <listitem>
-            <simpara><sgmltag class="attvalue">path</sgmltag> value. The path
-              is searched for the matching program name.</simpara>
+            <simpara><sgmltag class="attvalue">path</sgmltag> value. The
+              <varname>PATH</varname> is searched for a matching executable
+              program specified via <sgmltag class="attribute">name</sgmltag>.
+              Additionally, <varname>/sbin</varname> and <varname>/usr/sbin</varname>
+              are searched if they are not contained in <varname>PATH</varname>.
+            </simpara>
           </listitem>
           <listitem>
             <simpara><sgmltag class="attvalue">c_include</sgmltag> value. The
-              C include path is searched for the matching header name.
+              C include paths known to JHBuild are searched for the matching header name.
               <sgmltag class="attribute">name</sgmltag> may include a
-              sub-directory. The C include search path can modified by setting
-              <varname>CPPFLAGS</varname> within the configuration variables
-              <varname>cflags</varname> or
-              <link linkend="cfg-module-autogenargs"><varname>module_autogenargs</varname></link>.
+              sub-directory. See below for ways to configure the include paths that JHBuild
+              will search.
+            </simpara>
+          </listitem>
+          <listitem>
+            <simpara><sgmltag class="attvalue">c_include_glob</sgmltag> value. Allows to specify
+              the include path location in the form of a shell glob that is evaluated by python's
+              glob module to find a matching include file.
+              <sgmltag class="attribute">name</sgmltag> may include a pathname that
+              contains shell-style wildcards (i.e., *, ? and []). If the pathname is
+              absolute it will be directly evaluated using python's glob.glob function,
+              otherwise it will be evaluated relative to the configured include paths.
+              See below for ways to configure the include paths that JHBuild
+              will search.
             </simpara>
           </listitem>
         </orderedlist>
@@ -3305,12 +3323,16 @@ Optional packages: (JHBuild will build the missing packages)
   &lt;branch repo="<replaceable>system</replaceable>" version="<replaceable>version</replaceable>" /&gt;
   &lt;systemdependencies&gt;
     &lt;dep type="c_include" name="<replaceable>header-name</replaceable>" /&gt;
+    &lt;altdep type="c_include_glob"
+            name="<replaceable>/absolute/*/alternative-header-name-3</replaceable>" /&gt;
+    &lt;altdep type="c_include_glob"
+            name="<replaceable>relative/*/alternative-header-name-4</replaceable>" /&gt;
   &lt;/systemdependencies&gt;
 &lt;/systemmodule&gt;
 </programlisting>
 
         <para>If the system module may be installed in different locations
-          or installed with different names by different distributions,
+          or installed with different names by different distributions, the
           <sgmltag class="element">altdep</sgmltag> tag can be used as
           subelements of <sgmltag class="element">dep</sgmltag> tag to
           specify alternative locations or names.
@@ -3335,11 +3357,39 @@ Optional packages: (JHBuild will build the missing packages)
     &lt;dep type="c_include" name="<replaceable>header-name</replaceable>"&gt;
       &lt;altdep type="c_include" name="<replaceable>alternative-header-name-1</replaceable>" /&gt;
       &lt;altdep type="c_include" name="<replaceable>alternative-header-name-2</replaceable>" /&gt;
+      &lt;altdep type="c_include_glob"
+              name="<replaceable>/absolute/*/alternative-header-name-3</replaceable>" /&gt;
+      &lt;altdep type="c_include_glob"
+              name="<replaceable>relative/*/alternative-header-name-4</replaceable>" /&gt;
       ...
     &lt;dep&gt;
   &lt;/systemdependencies&gt;
 &lt;/systemmodule&gt;
 </programlisting>
+
+        <para>
+          The C include search paths used by JHBuild can modified
+          in several ways:
+        </para>
+
+        <orderedlist>
+          <listitem>
+            JHBuild detects and extracts additional include paths specified in
+            the <varname>CPPFLAGS</varname>, <varname>CFLAGS</varname> and
+            <varname>CXXFLAGS</varname> environment variables.
+          </listitem>
+          <listitem>
+            Within the configuration variables:
+            <link linkend="cfg-makeargs"><varname>makeargs</varname></link>,
+            <link linkend="cfg-module-makeargs"><varname>module_makeargs</varname></link> and
+            <link linkend="cfg-module-autogenargs"><varname>module_autogenargs</varname></link>.
+          </listitem>
+          <listitem>
+            Finally, from paths specified in the the environment variables
+            <varname>C_INCLUDE_PATH</varname> and <varname>CPLUS_INCLUDE_PATH</varname>.
+          </listitem>
+        </orderedlist>
+
       </section>
 
       <section id="moduleset-syntax-defs-waf">