dev-manual, ref-manual: Updates for BBPATH.

Two things fixed:

1. A couple examples for setting up a layer.conf file were
   using the meta-yocto configuration file as an example.
   Turns out this is a bad example because the BBPATH variable
   is appended to the LAYERDIR when setting BBPATH rather
   than the other way around.  That is because meta-yocto
   is a distro layer.  BSP layers, however, are not distro
   layers and are the norm here.  So I switched up the way
   BBPATH was set and actually called out meta-yocto-bsp
   config file as a template.

2. Added a link for the BBPATH variable in the
   FILESYSTEM_PERMS_TABLES variable description in the
   glossary.  Just happened to notice this so I fixed it

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

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

2 files changed, 52 insertions, 25 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e7655ade9f..ff19fb716a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -102,37 +102,64 @@
                        layer folder, you need to create a <filename>conf/layer.conf</filename> file.
                        It is easiest to take an existing layer configuration file and copy that to your
                        layer's <filename>conf</filename> directory and then modify the file as needed.</para>
-                       <para>The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the
+                       <para>The <filename>meta-yocto-bsp/conf/layer.conf</filename> file demonstrates the
                        required syntax:
                        <literallayout class='monospaced'>
      # We have a conf and classes directory, add to BBPATH
-     BBPATH := "${LAYERDIR}:${BBPATH}"
+     BBPATH := "${BBPATH}:${LAYERDIR}"
 
-     # We have recipes-* directories, add to BBFILES
+     # We have a packages directory, add to BBFILES
      BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
                  ${LAYERDIR}/recipes-*/*/*.bbappend"
 
-     BBFILE_COLLECTIONS += "yocto"
-     BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
-     BBFILE_PRIORITY_yocto = "5"
+     BBFILE_COLLECTIONS += "yoctobsp"
+     BBFILE_PATTERN_yoctobsp := "^${LAYERDIR}/"
+     BBFILE_PRIORITY_yoctobsp = "5"
                         </literallayout></para>
-                        <para>In the previous example, the recipes for the layers are added to
-                        <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
-                        The
-                        <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
-                        variable is then appended with the layer name.
-                        The
-                        <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
-                        variable is set to a regular expression and is used to match files
-                        from <filename>BBFILES</filename> into a particular layer.
-                        In this case, immediate expansion of
-                        <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
-                        sets <filename>BBFILE_PATTERN</filename> to the layer's path.
-                        The
-                        <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
-                        variable then assigns a priority to the layer.
-                        Applying priorities is useful in situations where the same package might appear in multiple
-                        layers and allows you to choose what layer should take precedence.</para>
+                        <para>Here is an explanation of the example:
+                        <itemizedlist>
+                            <listitem><para>The configuration and
+                                classes directory is appended to
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
+                                <note>
+                                    All non-distro layers, which include all BSP
+                                    layers, are expected to append the layer
+                                    directory to the
+                                    <filename>BBPATH</filename>.
+                                    On the other hand, distro layers, such as
+                                    <filename>meta-yocto</filename>, can choose
+                                    to enforce their own precedence over
+                                    <filename>BBPATH</filename>.
+                                    For an example of that syntax, see the
+                                    <filename>layer.conf</filename> file for
+                                    the <filename>meta-yocto</filename> layer.
+                                </note></para></listitem>
+                            <listitem><para>The recipes for the layers are
+                                appended to
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
+                                </para></listitem>
+                            <listitem><para>The
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
+                                variable is then appended with the layer name.
+                                </para></listitem>
+                            <listitem><para>The
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
+                                variable is set to a regular expression and is
+                                used to match files from
+                                <filename>BBFILES</filename> into a particular
+                                layer.
+                                In this case, immediate expansion of
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
+                                sets <filename>BBFILE_PATTERN</filename> to the
+                                layer's path.</para></listitem>
+                            <listitem><para>The
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
+                                variable then assigns a priority to the layer.
+                                Applying priorities is useful in situations
+                                where the same package might appear in multiple
+                                layers and allows you to choose what layer
+                                should take precedence.</para></listitem>
+                        </itemizedlist></para>
                         <para>Note the use of the
                         <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
                         variable with the immediate expansion operator.
@@ -1769,7 +1796,7 @@
                         the <filename>layer.conf</filename> file as follows:
                         <literallayout class='monospaced'>
      # We have a conf and classes directory, add to BBPATH
-     BBPATH := "${LAYERDIR}:${BBPATH}"
+     BBPATH := "${BBPATH}:${LAYERDIR}"
 
      # We have a packages directory, add to BBFILES
      BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index ff9a227db1..dabf05989e 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1138,7 +1138,7 @@ Core layer for images cannot be removed
                     point to your custom <filename>fs-perms.txt</filename>.
                     You can specify more than a single file permissions setting table.
                     The paths you specify to these files must be defined within the
-                    <filename>BBPATH</filename> variable.
+                    <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
                 </para>
                 <para>
                     For guidance on how to create your own file permissions settings table file,