ref-manual, dev-manual: Updates to BBMASK variable.

Fixes YOCTO #3662

I added more information to the variable desription in the
glossary for BBMASK.  The information included a bit more
syntax information as well as some more complex examples.

I added more reference information to the "Excluding Recipes
From the Build" section to help better describe how the
BBMASK variable works.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
(From yocto-docs rev: f10f43a543e7b0892863e165d2902741a8823009)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 71 insertions, 25 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 2ae83810e1..e7655ade9f 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2321,27 +2321,38 @@
         <title>Excluding Recipes From the Build</title>
 
         <para>
-            You might find that there are groups of recipes you want to filter
-            out of the build process.
+            You might find that there are groups of recipes or append files
+            that you want to filter out of the build process.
             For example, recipes you know you will never use or want should not
             be part of the build.
-            Removing these recipes from parsing speeds up parts of the build.
+            Removing these files from parsing speeds up parts of the build.
         </para>
 
         <para>
             It is possible to filter or mask out <filename>.bb</filename> and
             <filename>.bbappend</filename> files.
             You can do this by providing an expression with the
-            <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'>BBMASK</ulink></filename>
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'><filename>BBMASK</filename></ulink>
             variable.
             Here is an example:
             <literallayout class='monospaced'>
-     BBMASK = ".*/meta-mymachine/recipes-maybe/"
+     BBMASK = "/meta-mymachine/recipes-maybe/"
             </literallayout>
-            Here, all <filename>.bb</filename> and <filename>.bbappend</filename> files
-            in the directory that match the expression are ignored during the build
-            process.
+            Here, all <filename>.bb</filename> and
+            <filename>.bbappend</filename> files in the directory that matches
+            the expression are ignored during the build process.
+            See the glossary entry for the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'><filename>BBMASK</filename></ulink>
+            variable for more information.
         </para>
+
+        <note>
+            The value you provide is passed to python's regular expression
+            compiler.
+            The expression is compared against the full paths to the files.
+            For complete syntax information, see python's documentation at
+            <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
+        </note>
     </section>
 
     <section id="platdev-appdev-srcrev">
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 0a29502544..ff9a227db1 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -342,26 +342,61 @@
 
         <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
             <glossdef>
-                <para>Prevents BitBake from processing recipes and recipe append files.
-                    You can use the <filename>BBMASK</filename> variable to "hide"
-                    these <filename>.bb</filename> and <filename>.bbappend</filename> files.
-                    BitBake ignores any recipe or recipe append files that match the expression.
+                <para>
+                    Prevents BitBake from processing recipes and recipe
+                    append files.
+                    Use the <filename>BBMASK</filename> variable from within the
+                    <filename>conf/local.conf</filename> file found
+                    in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                </para>
+
+                <para>
+                    You can use the <filename>BBMASK</filename> variable
+                    to "hide" these <filename>.bb</filename> and
+                    <filename>.bbappend</filename> files.
+                    BitBake ignores any recipe or recipe append files that
+                    match the expression.
                     It is as if BitBake does not see them at all.
-                    Consequently, matching files are not parsed or otherwise used by
-                    BitBake.</para>
-                <para>The value you provide is passed to python's regular expression compiler.
-                    For complete syntax information, see python's documentation at
+                    Consequently, matching files are not parsed or otherwise
+                    used by BitBake.</para>
+                <para>
+                    The value you provide is passed to python's regular
+                    expression compiler.
+                    The expression is compared against the full paths to
+                    the files.
+                    For complete syntax information, see python's
+                    documentation at
                     <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
-                    The expression is compared against the full paths to the files.
-                    For example, the following uses a complete regular expression to tell
-                    BitBake to ignore all recipe and recipe append files in the
-                    <filename>.*/meta-ti/recipes-misc/</filename> directory:
+                </para>
+
+                <para>
+                    The following example uses a complete regular expression
+                    to tell BitBake to ignore all recipe and recipe append
+                    files in the <filename>/meta-ti/recipes-misc/</filename>
+                    directory:
                     <literallayout class='monospaced'>
-     BBMASK = ".*/meta-ti/recipes-misc/"
-                    </literallayout></para>
-                <para>Use the <filename>BBMASK</filename> variable from within the
-                    <filename>conf/local.conf</filename> file found
-                    in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para>
+     BBMASK = "/meta-ti/recipes-misc/"
+                    </literallayout>
+                    If you want to mask out multiple directories or recipes,
+                    use the vertical bar to separate the regular expression
+                    fragments.
+                    This next example masks out multiple directories and
+                    individual recipes:
+                    <literallayout class='monospaced'>
+     BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
+     BBMASK .= "|.*meta-oe/recipes-support/"
+     BBMASK .= "|.*openldap"
+     BBMASK .= "|.*opencv"
+     BBMASK .= "|.*lzma"
+                    </literallayout>
+                    Notice how the vertical bar is used to append the fragments.
+                    <note>
+                        When specifying a directory name, use the trailing
+                        slash character to ensure you match just that directory
+                        name.
+                    </note>
+                </para>
             </glossdef>
         </glossentry>