documentation: Added the memory-resident BitBake feature

The main changes are captured in a new section devoted to the oe-init-build-env-memres script within the ref-structure.xml file and in the variables.xml file in a BBSERVER variable entry in the glossary. All other changes were necessary to integrate the new functionality into areas where running the setup script are discussed. Before this feature, there was a single setup script (oe-init-build-env). Consequently, wordings and such were designed exclusively for this single method. With the introduction of a second possible method to initialize the build environment, tweaks to many sections were needed. Beside the wording tweaks, appropriate cross-referencing was also needed. All these changes cover the integration of the new feature. Reported-by: Richard Purdie <richard.purdie@linuxfoundation.org> (From yocto-docs rev: c55c9a53c9b4cd1e06e6e81e32d56f9bbf5fe98c) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2013-09-10 12:13:25 -07:00 · 2013-09-10 12:13:25 -07:00 · a266619317
parent cc2626727c
commit a266619317
11 changed files with 168 additions and 25 deletions
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@ -91,7 +91,9 @@
            <para>
                If you use BitBake to generate the ADT Installer tarball, you must
                <filename>source</filename> the environment setup script
-                (<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>)
+                (<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                or 
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
                located in the Source Directory before running the
                BitBake command that creates the tarball.
            </para>
@ -549,8 +551,12 @@

    <para>
         Remember, before using any <filename>bitbake</filename> command, you
-         must source the <filename>&OE_INIT_PATH;</filename> script located in
-         the Source Directory and you must make sure your
+         must source the build environment setup script 
+         (i.e.
+         <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+         or
+         <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
+         located in the Source Directory and you must make sure your
         <filename>conf/local.conf</filename> variables are correct.
         In particular, you need to be sure the
         <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@ -1812,6 +1812,8 @@
                environment, you must build the tool using BitBake.
                Thus, the environment must be set up using the
                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                or
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
                script found in the
                <link linkend='build-directory'>Build Directory</link>.
                The following commands build and invoke <filename>menuconfig</filename> assuming the
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@ -509,7 +509,9 @@
                This term refers to the area used by the OpenEmbedded build system for builds.
                The area is created when you <filename>source</filename> the setup
                environment script that is found in the Source Directory
-                (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
+                (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                or
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
                The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
                variable points to the Build Directory.</para>

--- a/documentation/mega-manual/figures/user-configuration.png
+++ b/documentation/mega-manual/figures/user-configuration.png
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@ -106,7 +106,11 @@
            configuration files.
            These example files are used as a basis for creating actual
            configuration files when you source the build environment
-            script <filename>oe-init-build-env</filename>.
+            script 
+            (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
        </para>

        <para>
@ -119,14 +123,15 @@
            and <filename>bblayers.conf</filename> configuration files.
            These default configuration files are created only if versions
            do not already exist in the Build Directory at the time you
-            source the <filename>oe-init-build-env</filename> script.
+            source the build environment setup script.
        </para>

        <para>
            Because the Poky repository is fundamentally an aggregation of
            existing repositories, some users might be familiar with running
-            the <filename>oe-init-build-env</filename> script in the context of
-            separate OpenEmbedded-Core and BitBake repositories rather than a
+            the <filename>&OE_INIT_FILE;</filename> or 
+            <filename>oe-init-build-env-memres</filename> script in the context 
+            of separate OpenEmbedded-Core and BitBake repositories rather than a
            single Poky repository.
            This discussion assumes the script is executed from within a cloned
            or unpacked version of Poky.
--- a/documentation/ref-manual/faq.xml
+++ b/documentation/ref-manual/faq.xml
@ -682,9 +682,11 @@
            <para>
                Yes - you can easily do this.
                When you use BitBake to build an image, all the build output
-                goes into the directory created when you source the
+                goes into the directory created when you run the 
+                build environment setup script (i.e.
                <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
-                setup script.
+                or
+                <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
                By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
                is named <filename>build</filename> but can be named
                anything you want.
--- a/documentation/ref-manual/figures/user-configuration.png
+++ b/documentation/ref-manual/figures/user-configuration.png
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@ -74,7 +74,11 @@
            the source tree is combined with the output.
            The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
            is created initially when you <filename>source</filename>
-            the OpenEmbedded build environment setup script <filename>&OE_INIT_FILE;</filename>.
+            the OpenEmbedded build environment setup script 
+            (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
        </para>

        <para>
@ -85,8 +89,10 @@
            the setup script.
            For information on separating output from your local
            Source Directory files, see the
-            "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
-            section.
+            "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            and
+            "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
+            sections.
        </para>
    </section>

@ -143,7 +149,7 @@
            which is a Yocto Project build user interface.
            For more information on the Hob, see the
            <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project</ulink>
-            webpage.
+            web page.
        </para>
    </section>

@ -162,7 +168,9 @@
            This directory contains various integration scripts that implement
            extra functionality in the Yocto Project environment (e.g. QEMU scripts).
            The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
-            script appends this directory to the shell's
+            and
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
+            scripts append this directory to the shell's
            <filename>PATH</filename> environment variable.
        </para>

@ -177,11 +185,19 @@
        <title><filename>&OE_INIT_FILE;</filename></title>

        <para>
-            This script sets up the OpenEmbedded build environment.
+            This script is one of two scripts that set up the OpenEmbedded build 
+            environment.
+            For information on the other script, see the 
+            "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
+            section.
+        </para>
+
+        <para>
            Running this script with the <filename>source</filename> command in
            a shell makes changes to <filename>PATH</filename> and sets other
            core BitBake variables based on the current working directory.
-            You need to run this script before running BitBake commands.
+            You need to run an environment setup script before running BitBake 
+            commands.
            The script uses other scripts within the
            <filename>scripts</filename> directory to do the bulk of the work.
        </para>
@ -191,7 +207,7 @@
            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
            argument creates the <filename>build</filename> directory.
            If you provide a Build Directory argument when you
-            <filename>source</filename> the script, you direct OpenEmbedded
+            <filename>source</filename> the script, you direct the OpenEmbedded
            build system to create a Build Directory of your choice.
            For example, the following command creates a Build Directory named
            <filename>mybuilds</filename> that is outside of the
@ -211,6 +227,81 @@
        </para>
    </section>

+    <section id='structure-memres-core-script'>
+        <title><filename>oe-init-build-env-memres</filename></title>
+
+        <para>
+            This script is one of two scripts that set up the OpenEmbedded build 
+            environment.
+            Setting up the environment with this script uses a 
+            memory-resident BitBake.
+            For information on the other setup script, see the 
+            "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
+            section.
+        </para>
+
+        <para>
+            Memory-resident BitBake resides in memory until you specifically
+            remove it using the following BitBake command:
+            <literallayout class='monospaced'>
+     $ bitbake -m
+            </literallayout>
+        </para>
+
+        <para>
+            Running this script with the <filename>source</filename> command in
+            a shell makes changes to <filename>PATH</filename> and sets other
+            core BitBake variables based on the current working directory.
+            One of these variables is the 
+            <link linkend='var-BBSERVER'><filename>BBSERVER</filename></link>
+            variable, which allows the OpenEmbedded build system to locate 
+            the server that is running BitBake.
+        </para>
+
+        <para>
+            You need to run an environment setup script before running BitBake 
+            commands.
+            Following is the script syntax:
+            <literallayout class='monospaced'>
+     $ source oe-init-build-env-memres &lt;port_number&gt; &lt;build_dir&gt;
+            </literallayout>
+            The script uses other scripts within the
+            <filename>scripts</filename> directory to do the bulk of the work.
+        </para>
+
+        <para>
+            If you do not provide a port number with the script, the default
+            port "12345" is used.
+        </para>
+
+        <para>
+            By default, running this script without a
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            argument creates the <filename>build</filename> directory.
+            If you provide a Build Directory argument when you
+            <filename>source</filename> the script, you direct the OpenEmbedded
+            build system to create a Build Directory of your choice.
+            For example, the following command uses the default port number
+            "12345" and creates a Build Directory named
+            <filename>mybuilds</filename> that is outside of the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
+            <literallayout class='monospaced'>
+     $ source oe-init-build-env-memres ~/mybuilds
+            </literallayout>
+            <note>
+                The OpenEmbedded build system does not support file or 
+                directory names that contain spaces.
+                If you attempt to run the 
+                <filename>oe-init-build-env-memres</filename> script
+                from a Source Directory that contains spaces in either the 
+                filenames or directory names, the script returns an error 
+                indicating no such file or directory.
+                Be sure to use a Source Directory free of names containing 
+                spaces.
+            </note>
+        </para>
+    </section>
+
    <section id='structure-basic-top-level'>
        <title><filename>LICENSE, README, and README.hardware</filename></title>

--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@ -710,6 +710,28 @@ Core layer for images cannot be removed
            </glossdef>
        </glossentry>

+        <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
+            <glossdef>
+                <para>
+                    Points to the server that runs memory-resident BitBake.
+                    This variable is set by the 
+                    <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
+                    setup script and should not be hand-edited.
+                    The variable is only used when you employ memory-resident
+                    BitBake.
+                    The setup script exports the value as follows:
+                    <literallayout class='monospaced'>
+     export BBSERVER=localhost:$port
+                    </literallayout>
+                    For more information on how the 
+                    <filename>BBSERVER</filename> is used, see the 
+                    <filename>oe-init-build-env-memres</filename> script, which
+                    is located in the 
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+            </glossdef>
+        </glossentry>
+
        <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
            <glossdef>
                <para>
@ -762,13 +784,16 @@ Core layer for images cannot be removed

        <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
            <glossdef>
-                <para>Points to the location of the
+                <para>
+                    Points to the location of the
                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
                    You can define this directory indirectly through the
                    <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
-                    script by passing in a Build Directory path when you run the
-                    script.
-                    If you run the script and do not provide a Build Directory
+                    and 
+                    <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
+                    scripts by passing in a Build Directory path when you run 
+                    the scripts.
+                    If you run the scripts and do not provide a Build Directory
                    path, the <filename>BUILDDIR</filename> defaults to
                    <filename>build</filename> in the current directory.
                </para>
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@ -27,8 +27,13 @@
        <title>Build Overview</title>

        <para>
-            The first thing you need to do is set up the OpenEmbedded build environment by sourcing
-            the <link linkend='structure-core-script'>environment setup script</link> as follows:
+            The first thing you need to do is set up the OpenEmbedded build 
+            environment by sourcing an environment setup script
+            (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+            Here is an example:
            <literallayout class='monospaced'>
     $ source &OE_INIT_FILE; [&lt;build_dir&gt;]
            </literallayout>
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@ -464,7 +464,12 @@
                 to the Build Directory.
                 Later, when the build completes, the Build Directory contains all the files
                 created during the build.
-                 </para></listitem>
+                 <note>
+                     For information on running a memory-resident BitBake, see
+                     the
+                     <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
+                     setup script.
+                 </note></para></listitem>
         </itemizedlist>
         <para>
             Take some time to examine your <filename>local.conf</filename> file