ref-manual, yocto-project-qs: Explanations for Git tarballs

Fixes [YOCTO #5035]

By default, the DL_DIR does not get files from Git repositories
that are suitable for mirroring.  There is a work-around by
using the BB_GENERATE_MIRROR_TARBALLS variable, which, when
set, causes the build system to generate tarballs for the
Git repositories and place them in the DL_DIR.

To address this, I added a new variable description for the
BB_GENERATE_MIRROR_TARBALLS varible, updated the DL_DIR
variable to indicate that "out-of-the-box" the YP puts suitable
mirror files into the DL_DIR for everthing except Git
repositories.

Some other sections were updated where discussion revolved around
pulling down source files.  The QS had a spot where the
BB_GENERATE_MIRROR_TARBALLS variable was actually used in an
example.  And, the expanded discussion on the BitBake process
had a couple spots that deserved a mention.

(From yocto-docs rev: 1539ff13222449ba60bfaaaac4fe1e8a795b0039)

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

3 files changed, 46 insertions, 14 deletions

diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index eccf97698a..c8f2fae94e 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -491,6 +491,14 @@
             <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
             variable.
             This area is a cache that can hold previously downloaded source.
+            You can also instruct the OpenEmbedded build system to create
+            tarballs from Git repositories, which is not the default behavior,
+            and store them in the <filename>DL_DIR</filename> by using the
+            <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
+            variable.
+        </para>
+
+        <para>
             Judicious use of a <filename>DL_DIR</filename> directory can
             save the build system a trip across the Internet when looking
             for files.
@@ -566,6 +574,15 @@
                 fetcher module.
             </para>
 
+            <note>
+                For information on how to have the OpenEmbedded build system
+                generate tarballs for Git repositories and place them in the
+                <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+                directory, see the
+                <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
+                variable.
+            </note>
+
             <para>
                 When fetching a repository, BitBake uses the
                 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index fe1c100794..5d0d257e23 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -502,6 +502,12 @@
                     For performance reasons, creating and placing tarballs of
                     the Git repositories is not the default action by the
                     OpenEmbedded build system.
+                    <literallayout class='monospaced'>
+     BB_Generate_MIRROR_TARBALLS = "1"
+                    </literallayout>
+                    Set this variable in your <filename>local.conf</filename>
+                    file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
                 </para>
             </glossdef>
         </glossentry>
@@ -1272,6 +1278,15 @@ Core layer for images cannot be removed
                 <para>
                     The central download directory used by the build process to
                     store downloads.
+                    By default, <filename>DL_DIR</filename> gets files
+                    suitable for mirroring for everything except Git
+                    repositories.
+                    If you want tarballs of Git repositories, use the
+                    <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
+                    variable.
+                </para>
+
+                <para>
                     You can set this directory by defining the
                     <filename>DL_DIR</filename> variable in the
                     <filename>/conf/local.conf</filename> file.
@@ -1296,20 +1311,9 @@ Core layer for images cannot be removed
                     <filename>DL_DIR</filename> and the build system looks there
                     first to find source tarballs.
                     <note>
-                        <para>
-                            When wiping and rebuilding, you can preserve this
-                            directory to speed up this part of subsequent
-                            builds.
-                        </para>
-
-                        <para>
-                            Also, by default, the <filename>DL_DIR</filename>
-                            does not contain tarballs of Git directories.
-                            However, you can instruct the build process to save
-                            these tarballs to the directory by using the
-                            <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
-                            variable.
-                        </para>
+                        When wiping and rebuilding, you can preserve this
+                        directory to speed up this part of subsequent
+                        builds.
                     </note>
                 </para>
 
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index f212437f07..e33e4a6e4c 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -911,6 +911,17 @@
         </para>
 
         <para>
+            In the previous example, the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
+            variable causes the OpenEmbedded build system to generate tarballs
+            of the Git repositories and store them in the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+            directory.
+            Due to performance reasons, generating and storing these tarballs
+            is not the build system's default behavior.
+        </para>
+
+        <para>
             You can also use the
             <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
             variable.