documentation: More information about DL_DIR added.

The information surrounding the central download directory was
pretty scant.  Jim Abernathy pointed this out in an email sent to
me.  As a start, I have added quite a bit more information to
the glossary description for DL_DIR.  Part of that added information
is a pointer to the FAQ entry that describes exactly how the
build system gets source files.  Then, in the YP Development Manual
in the section that introduces the build process, I added several
references to various variables that are set in the local.conf
file prior to kicking off the build.

Reported-by: Jim Abernathy <jim.abernathy@intel.com>
(From yocto-docs rev: 4d7835a3bff5bd054301fa9ab6954c11c88dad58)

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

1 files changed, 36 insertions, 1 deletions

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 711a8a97ca..60bf034d19 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -344,7 +344,42 @@
 
         <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
             <glossdef>
-                <para>The directory where all fetched sources will be stored.</para>
+                <para>
+                    The central download directory used by the build process to store downloads.
+                    You can set this directory by defining the <filename>DL_DIR</filename>
+                    variable in the <filename>/conf/local.conf</filename> file.
+                    This directory is self-maintaining and you should not have
+                    to touch it. 
+                    By default, the directory is <filename>downloads</filename> in the 
+                    Yocto Project build directory.
+                    <literallayout class='monospaced'>
+     #DL_DIR ?= "${TOPDIR}/downloads"
+                    </literallayout>
+                    To specify a different download directory, simply uncomment the line
+                    and provide your directory.
+                </para>
+
+                <para>
+                    During a first build, the system downloads many different source code 
+                    tarballs from various upstream projects. 
+                    Downloading can take a while, particularly if your network
+                    connection is slow. 
+                    Tarballs are all stored in the directory defined by 
+                    <filename>DL_DIR</filename> and the build system looks there first 
+                    to find source tarballs. 
+                    <note>
+                        When wiping and rebuilding, you can preserve this directory to speed 
+                        up this part of subsequent builds. 
+                    </note>
+                </para>
+
+                <para>
+                    You can safely share this directory between multiple builds on the 
+                    same development machine.  
+                    For additional information on how the build process gets source files, see
+                    <link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>this entry</link> in
+                    The FAQ appendix of this manual.
+                </para>
             </glossdef>
 
         </glossentry>