ref-manual: Updates to describe wildcarding support

Added specific wildcarding support descriptions for all related
variables and file panthnames.

(From yocto-docs rev: 543e398c4ae1bce38517a88cd91c957a583a2892)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 144 insertions, 53 deletions

diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml
index e25a147549..c573a521a7 100644
--- a/documentation/ref-manual/ref-terms.xml
+++ b/documentation/ref-manual/ref-terms.xml
@@ -29,11 +29,31 @@
                 information in the similarly-named recipe file.
                 For an example of an append file in use, see the
                 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
-                section in the Yocto Project Development Tasks Manual.
-                <note>
-                    Append files can also use wildcard patterns in their
-                    version numbers so they can be applied to more than one
-                    version of the underlying recipe file.
+                section in the Yocto Project Development Tasks Manual.</para>
+
+                <para>When you name an append file, you can use the
+                "<filename>%</filename>" wildcard character to allow for
+                matching recipe names.
+                For example, suppose you have an append file named as follows:
+                <literallayout class='monospaced'>
+     busybox_1.21.%.bbappend
+                </literallayout>
+                That append file would match any
+                <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename>
+                version of the recipe.
+                So, the append file would match the following recipe names:
+                <literallayout class='monospaced'>
+     busybox_1.21.1.bb
+     busybox_1.21.2.bb
+     busybox_1.21.3.bb
+                </literallayout>
+                <note><title>Important</title>
+                    The use of the "<filename>%</filename>" character
+                    is limited in that it only works directly in front of the
+                    <filename>.bbappend</filename> portion of the append file's
+                    name.
+                    You cannot use the wildcard character in any other
+                    location of the name.
                 </note>
                 </para></listitem>
             <listitem><para id='bitbake-term'>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 1bc6e2b77d..1774ba24c0 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -679,6 +679,13 @@
                             <literallayout class='monospaced'>
      BB_ALLOWED_NETWORKS = "*.gnu.org"
                             </literallayout>
+                            <note><title>Important</title>
+                                The use of the "<filename>*</filename>"
+                                character only works at the beginning of
+                                a host name.
+                                You cannot use the wildcard character in any
+                                other location of the name.
+                            </note>
                             </para></listitem>
                         <listitem><para>
                             Mirrors not in the host list are skipped and
@@ -1133,12 +1140,22 @@
 
         <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
             <info>
-                BBFILES[doc] = "List of recipe files used by BitBake to build software."
+                BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software."
             </info>
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
-                    List of recipe files used by BitBake to build software.
+                    A space-separated list of recipe files BitBake uses to
+                    build software.
+                </para>
+
+                <para>
+                    When specifying recipe files, you can pattern match using
+                    Python's
+                    <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
+                    syntax.
+                    For details on the syntax, see the documentation by
+                    following the previous link.
                 </para>
             </glossdef>
         </glossentry>
@@ -1267,15 +1284,19 @@
                     match any of the expressions.
                     It is as if BitBake does not see them at all.
                     Consequently, matching files are not parsed or otherwise
-                    used by BitBake.</para>
+                    used by BitBake.
+                </para>
+
                 <para>
                     The values you provide are passed to Python's regular
                     expression compiler.
+                    Consequently, the syntax follows Python's Regular
+                    Expression (re) syntax.
                     The expressions are compared against the full paths to
                     the files.
                     For complete syntax information, see Python's
-                    documentation for the appropriate release at
-                    <ulink url='http://docs.python.org/release/'></ulink>.
+                    documentation at
+                    <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
                 </para>
 
                 <para>
@@ -1443,6 +1464,17 @@
                     set up during compilation so that they are correct for
                     use when installed into the sysroot and called by the
                     build processes of other recipes.
+                    <note>
+                        The <filename>BINCONFIG_GLOB</filename> variable
+                        uses
+                        <ulink url='http://tldp.org/LDP/abs/html/globbingref.html'>shell globbing</ulink>,
+                        which is recognition and expansion of wildcards during
+                        pattern matching.
+                        Shell globbing is very similar to
+                        <ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
+                        and
+                        <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>.
+                    </note>
                 </para>
 
                 <para>
@@ -2366,6 +2398,14 @@
                     Defines wildcards to match when installing a list of
                     complementary packages for all the packages explicitly
                     (or implicitly) installed in an image.
+                    <note>
+                        The <filename>COMPLEMENTARY_GLOB</filename> variable
+                        uses Unix filename pattern matching
+                        (<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>),
+                        which is similar to the Unix style pathname pattern
+                        expansion
+                        (<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>).
+                    </note>
                     The resulting list of complementary packages is associated
                     with an item that can be added to
                     <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
@@ -4782,23 +4822,38 @@
                     <literallayout class='monospaced'>
      FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
                     </literallayout>
+                    <note><title>Notes</title>
+                        <itemizedlist>
+                            <listitem><para>
+                                When specifying files or paths, you can pattern
+                                match using Python's
+                                <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
+                                syntax.
+                                For details on the syntax, see the
+                                documentation by following the previous link.
+                                </para></listitem>
+                            <listitem><para>
+                                When specifying paths as part of the
+                                <filename>FILES</filename> variable, it is
+                                good practice to use appropriate path
+                                variables.
+                                For example, use <filename>${sysconfdir}</filename>
+                                rather than <filename>/etc</filename>, or
+                                <filename>${bindir}</filename> rather than
+                                <filename>/usr/bin</filename>.
+                                You can find a list of these variables at the
+                                top of the
+                                <filename>meta/conf/bitbake.conf</filename>
+                                file in the
+                                <link linkend='source-directory'>Source Directory</link>.
+                                You will also find the default values of the
+                                various <filename>FILES_*</filename> variables
+                                in this file.
+                                </para></listitem>
+                        </itemizedlist>
+                    </note>
                 </para>
 
-                <note>
-                    When specifying paths as part of the
-                    <filename>FILES</filename> variable, it is good practice
-                    to use appropriate path variables.
-                    For example, use <filename>${sysconfdir}</filename> rather
-                    than <filename>/etc</filename>, or
-                    <filename>${bindir}</filename> rather than
-                    <filename>/usr/bin</filename>.
-                    You can find a list of these variables at the top of the
-                    <filename>meta/conf/bitbake.conf</filename> file in the
-                    <link linkend='source-directory'>Source Directory</link>.
-                    You will also find the default values of the various
-                    <filename>FILES_*</filename> variables in this file.
-                </note>
-
                 <para>
                     If some of the files you provide with the
                     <filename>FILES</filename> variable are editable and you
@@ -10935,47 +10990,63 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
-                    If there are multiple versions of recipes available, this
-                    variable determines which recipe should be given preference.
+                    If multiple versions of recipes exist, this
+                    variable determines which version is given preference.
                     You must always suffix the variable with the
                     <link linkend='var-PN'><filename>PN</filename></link>
                     you want to select, and you should set the
                     <link linkend='var-PV'><filename>PV</filename></link>
                     accordingly for precedence.
-                    You can use the "<filename>%</filename>" character as a
-                    wildcard to match any number of characters, which can be
-                    useful when specifying versions that contain long revision
-                    numbers that could potentially change.
+                </para>
+
+                <para>
+                    The <filename>PREFERRED_VERSION</filename> variable
+                    supports limited wildcard use through the
+                    "<filename>%</filename>" character.
+                    You can use the character to match any number of
+                    characters, which can be useful when specifying versions
+                    that contain long revision numbers that potentially change.
                     Here are two examples:
                     <literallayout class='monospaced'>
      PREFERRED_VERSION_python = "3.4.0"
      PREFERRED_VERSION_linux-yocto = "4.12%"
                     </literallayout>
-                    <note>
-                        The specified version is matched against
-                        <link linkend='var-PV'><filename>PV</filename></link>,
-                        which does not necessarily match the version part of
-                        the recipe's filename.
-                        For example, consider two recipes
-                        <filename>foo_1.2.bb</filename> and
-                        <filename>foo_git.bb</filename> where
-                        <filename>foo_git.bb</filename> contains the following
-                        assignment:
-                        <literallayout class='monospaced'>
+                    <note><title>Important</title>
+                        The use of the "<filename>%</filename>" character
+                        is limited in that it only works at the end of the
+                        string.
+                        You cannot use the wildcard character in any other
+                        location of the string.
+                    </note>
+                </para>
+
+                <para>
+                    The specified version is matched against
+                    <link linkend='var-PV'><filename>PV</filename></link>,
+                    which does not necessarily match the version part of
+                    the recipe's filename.
+                    For example, consider two recipes
+                    <filename>foo_1.2.bb</filename> and
+                    <filename>foo_git.bb</filename> where
+                    <filename>foo_git.bb</filename> contains the following
+                    assignment:
+                    <literallayout class='monospaced'>
      PV = "1.1+git${SRCPV}"
-                        </literallayout>
-                        In this case, the correct way to select
-                        <filename>foo_git.bb</filename> is by using an
-                        assignment such as the following:
-                        <literallayout class='monospaced'>
+                    </literallayout>
+                    In this case, the correct way to select
+                    <filename>foo_git.bb</filename> is by using an
+                    assignment such as the following:
+                    <literallayout class='monospaced'>
      PREFERRED_VERSION_foo = "1.1+git%"
-                        </literallayout>
-                        Compare that previous example against the following
-                        incorrect example, which does not work:
-                        <literallayout class='monospaced'>
+                    </literallayout>
+                    Compare that previous example against the following
+                    incorrect example, which does not work:
+                    <literallayout class='monospaced'>
      PREFERRED_VERSION_foo = "git"
-                        </literallayout>
-                    </note>
+                    </literallayout>
+                </para>
+
+                <para>
                     Sometimes the <filename>PREFERRED_VERSION</filename>
                     variable can be set by configuration files in a way that
                     is hard to change.