documentation/poky-ref-manual/ref-variables.xml: Edits to WORKDIR glossary

The edits add much more information to the WORKDIR variable in the
glossary.  There are some examples and it now shows how the
actual working directory is derived.

(From yocto-docs rev: 8b3e671f6088a2fb2d6f496cee979567cf0f222e)

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

1 files changed, 56 insertions, 2 deletions

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index c8c6a669c9..e9bc81fe7b 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1774,8 +1774,62 @@
 
         <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
             <glossdef>
-                <para>The path to directory in <filename>tmp/work/</filename> where 
-                    the package is built.</para>
+                <para>
+                    The pathname of the working directory in which the Yocto Project build system  
+                    builds packages.
+                    This directory is located within the
+                    <link linkend='var-TMPDIR'>TMPDIR</link> directory structure and changes
+                    as different packages are built.
+                </para>
+
+                <para>
+                    The actual <filename>WORKDIR</filename> directory depends on several things:
+                    <itemizedlist>
+                        <listitem>The temporary directory - <link linkend='var-TMPDIR'>TMPDIR</link></listitem>
+                        <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></listitem>
+                        <listitem>The target machine - <link linkend='var-MACHINE'>MACHINE</link></listitem>
+                        <listitem>The target operating system - <link linkend='var-TARGET_OS'>TARGET_OS</link></listitem>
+                        <listitem>The package name - <link linkend='var-PN'>PN</link></listitem>
+                        <listitem>The package version - <link linkend='var-PV'>PV</link></listitem>
+                        <listitem>The package revision - <link linkend='var-PR'>PR</link></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    For packages that are not dependent on a particular machine, 
+                    <filename>WORKDIR</filename> is defined as follows:
+                    <literallayout class='monospaced'>
+ ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+                    </literallayout>
+                    As an example, assume a 
+                    <ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#yocto-project-files'>
+                    Yocto Project Files</ulink> top-level directory named <filename>poky</filename> 
+                    and a default 
+                    <ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#yocto-project-build-directory'>
+                    Yocto Project Build Birectory</ulink> of <filename>poky/build</filename>.
+                    In this case, the working directory the build system uses to build 
+                    the <filename>v86d</filename> package is the following:
+                    <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0
+                    </literallayout>
+                </para>
+
+                <para>
+                    For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
+                    is defined slightly different:
+                    <literallayout class='monospaced'>
+ ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+                    </literallayout>
+                    As an example, again assume a Yocto Project Files top-level directory 
+                    named <filename>poky</filename> and a default Yocto Project build directory 
+                    of <filename>poky/build</filename>.
+                    In this case, the working directory the build system uses to build
+                    the <filename>acl</filename> package, which is dependent on a 
+                    MIPS-based device, is the following:
+                    <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
+                    </literallayout>
+                </para>
             </glossdef>
         </glossentry>