handbook: document the LAYERDIR variable

LAYERDIR is one of the few variables which requires immediate expansion and is
worth documenting explicitly.

Signed-off-by: Joshua Lock <josh@linux.intel.com>

diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index b437c77fa331d2107cf3fbe1f3c8743f9882e3ec..936a74480eb34a4749c1bc0e8d27770d89cc1822 100644 (file)
--- a/handbook/extendpoky.xml
+++ b/handbook/extendpoky.xml
@@ -582,12 +582,17 @@ require conf/distro/include/poky-extras-src-revisions.inc
                 As can be seen, the layers recipes are added to BBFILES. The
                 BBFILE_COLLECTIONS variable is then appended to with the
                 layer name. The BBFILE_PATTERN variable is immediately expanded
-                with a regular expression used to match files from BBFILES into a
-                particular layer, in this case by using the base pathname.
+                with a regular expression used to match files from BBFILES into
+                a particular layer, in this case by using the base pathname.
                 The BBFILE_PRIORITY variable then assigns different
                 priorities to the files in different layers. This is useful
                 in situations where the same package might appear in multiple
                 layers and allows you to choose which layer should 'win'.
+                Note the use of LAYERDIR with the immediate expansion operator.
+                LAYERDIR expands to the directory of the current layer and
+                requires use of the immediate expansion operator so that Bitbake
+                does not lazily expand the variable when it's parsing a
+                different directory.
             </para>
 
             <para>

diff --git a/handbook/ref-variables.xml b/handbook/ref-variables.xml
index 7bbcdb81f0d1d6340d251d573a4678e2b719414f..e4523bfdc1c658b44f671efd6aaceee1818da31c 100644 (file)
--- a/handbook/ref-variables.xml
+++ b/handbook/ref-variables.xml
@@ -403,6 +403,15 @@
 
     <glossdiv id='var-glossary-l'><title>L</title>
 
+        <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
+            <glossdef>
+                <para>When used inside a layer.conf gives the path of the
+                current layer. This variable requires immediate expansion
+                (see the Bitbake manual) as lazy expansion can result in
+                the expansion happening in the wrong directory and therefore
+                giving the wrong value.</para>
+            </glossdef>
+        </glossentry>
         <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
             <glossdef>
                 <para>List of package source licenses.</para>