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>

2 files changed, 16 insertions, 2 deletions

diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index b437c77fa3..936a74480e 100644
--- 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 7bbcdb81f0..e4523bfdc1 100644
--- 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>