diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml | 253 |
1 files changed, 44 insertions, 209 deletions
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml index 9b2701cc31..4bddc59965 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml @@ -7,16 +7,19 @@ <title>Source Directory Structure</title> <para> - The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components. - Understanding them and knowing where they are located is key to using the Yocto Project well. - This chapter describes the Source Directory and gives information about the various - files and directories. + The <link linkend='source-directory'>Source Directory</link> + consists of several components. + Understanding them and knowing where they are located is key to using the + Yocto Project well. + This chapter describes the Source Directory and gives information about + the various files and directories. </para> <para> - For information on how to establish a local Source Directory on your development system, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>" - section in the Yocto Project Development Manual. + For information on how to establish a local Source Directory on your + development system, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>" + section in the Yocto Project Development Tasks Manual. </para> <note> @@ -31,7 +34,7 @@ <para> This section describes the top-level components of the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + <link linkend='source-directory'>Source Directory</link>. </para> <section id='structure-core-bitbake'> @@ -42,7 +45,7 @@ The copy usually matches the current stable BitBake release from the BitBake project. BitBake, a - <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + <link linkend='metadata'>Metadata</link> interpreter, reads the Yocto Project Metadata and runs the tasks defined by that data. Failures are usually from the Metadata and not from BitBake itself. @@ -53,10 +56,8 @@ When you run the <filename>bitbake</filename> command, the main BitBake executable, which resides in the <filename>bitbake/bin/</filename> directory, starts. - Sourcing an environment setup script (e.g. - <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>) + Sourcing the environment setup script (i.e. + <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>) places the <filename>scripts</filename> and <filename>bitbake/bin</filename> directories (in that order) into the shell's <filename>PATH</filename> environment variable. @@ -75,27 +76,24 @@ This directory contains user configuration files and the output generated by the OpenEmbedded build system in its standard configuration where the source tree is combined with the output. - The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + The + <link linkend='build-directory'>Build Directory</link> is created initially when you <filename>source</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>). + <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). </para> <para> It is also possible to place output and configuration files in a directory separate from the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + <link linkend='source-directory'>Source Directory</link> by providing a directory name when you <filename>source</filename> 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> - and - "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>" - sections. + "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>" + section. </para> </section> @@ -175,9 +173,7 @@ 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> - and - <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link> - scripts append this directory to the shell's + script appends this directory to the shell's <filename>PATH</filename> environment variable. </para> @@ -192,14 +188,7 @@ <title><filename>&OE_INIT_FILE;</filename></title> <para> - 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> + This script sets up the OpenEmbedded build environment. 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. @@ -212,7 +201,7 @@ <para> When you run this script, your Yocto Project environment is set up, a - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + <link linkend='build-directory'>Build Directory</link> is created, your working directory becomes the Build Directory, and you are presented with a list of common BitBake targets. Here is an example: @@ -234,19 +223,19 @@ The script gets its default list of common targets from the <filename>conf-notes.txt</filename> file, which is found in the <filename>meta-poky</filename> directory within the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + <link linkend='source-directory'>Source Directory</link>. Should you have custom distributions, it is very easy to modify this configuration file to include your targets for your distribution. See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" - section in the Yocto Project Development Manual for more + section in the Yocto Project Development Tasks Manual for more information. </para> <para> By default, running this script without a - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + <link linkend='build-directory'>Build Directory</link> argument creates the <filename>build</filename> directory in your current working directory. If you provide a Build Directory argument when you @@ -254,17 +243,17 @@ 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 - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: + <link linkend='source-directory'>Source Directory</link>: <literallayout class='monospaced'> $ source &OE_INIT_FILE; ~/mybuilds </literallayout> The OpenEmbedded build system uses the template configuration files, which are found by default in the <filename>meta-poky/conf</filename> directory in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + Source Directory. See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" - section in the Yocto Project Development Manual for more + section in the Yocto Project Development Tasks Manual for more information. <note> The OpenEmbedded build system does not support file or directory names that @@ -278,157 +267,6 @@ </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. - Aside from setting up the environment, this script starts a - memory-resident BitBake server. - 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 using BitBake - commands. - Following is the script syntax: - <literallayout class='monospaced'> - $ source oe-init-build-env-memres <replaceable>port_number</replaceable> <replaceable>build_dir</replaceable> - </literallayout> - Following are some considerations when sourcing this script: - <itemizedlist> - <listitem><para> - The script uses other scripts within the - <filename>scripts</filename> directory to do the bulk of - the work. - </para></listitem> - <listitem><para> - If you do not provide a port number with the script, the - BitBake server starts at a randomly selected port. - </para></listitem> - <listitem><para> - The script's parameters are positionally dependent. - Consequently, you cannot run the script and provide a - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - name without also providing a port number. - In other words, the following syntax is illegal: - <literallayout class='monospaced'> - $ source oe-initbuild-env-memres <replaceable>build_dir</replaceable> - </literallayout> - <note> - The previous restriction might be resolved in the - future. - See - <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=7555'>Bug 7555</ulink> - for more information. - </note> - </para></listitem> - </itemizedlist> - </para> - - <para> - When you run this script, your Yocto Project environment is set - up, a Build Directory is created, your working directory becomes - the Build Directory, and you are presented with a list of common - BitBake targets. - Here is an example: - <literallayout class='monospaced'> - $ source oe-init-build-env-memres - No port specified, using dynamically selected port - - ### Shell environment set up for builds. ### - - You can now run 'bitbake <target>' - - Common targets are: - core-image-minimal - core-image-sato - meta-toolchain - meta-ide-support - - You can also run generated qemu images with a command like 'runqemu qemux86' - Bitbake server address: 127.0.0.1, server port: 53995 - Bitbake server started on demand as needed, use bitbake -m to shut it down - </literallayout> - The script gets its default list of common targets from the - <filename>conf-notes.txt</filename> file, which is found in the - <filename>meta-poky</filename> directory within the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - Should you have custom distributions, it is very easy to modify - this configuration file to include your targets for your - distribution. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" - section in the Yocto Project Development Manual for more - information. - </para> - - <para> - By default, running this script without a - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - argument creates a build directory named - <filename>build</filename>. - If you provide a Build Directory argument and port number when you - <filename>source</filename> the script, the Build Directory is - created using that name. - For example, the following command starts the BitBake server using - port 53995 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 53995 ~/mybuilds - </literallayout> - The <filename>oe-init-build-env-memres</filename> script starts a - memory resident BitBake server. - This BitBake instance uses the - <filename>bitbake-cookerdaemon.log</filename> file, which is - located in the Build Directory. - </para> - - <para> - The OpenEmbedded build system uses the template configuration - files, which are found by default in the - <filename>meta-poky/conf</filename> directory in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" - section in the Yocto Project Development Manual for more - information. - <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> @@ -443,11 +281,9 @@ <para> The OpenEmbedded build system creates the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - when you run one of the build environment setup scripts (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>). + <link linkend='build-directory'>Build Directory</link> + when you run the build environment setup scripts (i.e. + <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). </para> <para> @@ -505,9 +341,7 @@ <filename>local.conf.sample</filename> when you <filename>source</filename> the top-level 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>). + <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). </para> <para> @@ -533,7 +367,7 @@ You can see how the <filename>TEMPLATECONF</filename> variable is used by looking at the <filename>scripts/oe-setup-builddir</filename> script in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + <link linkend='source-directory'>Source Directory</link>. You can find the Yocto Project version of the <filename>local.conf.sample</filename> file in the <filename>meta-poky/conf</filename> directory. @@ -559,9 +393,7 @@ <filename>bblayers.conf.sample</filename> when you <filename>source</filename> the top-level 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>). + <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). </para> <para> @@ -585,7 +417,7 @@ <note> You can see how the <filename>TEMPLATECONF</filename> variable <filename>scripts/oe-setup-builddir</filename> script in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + <link linkend='source-directory'>Source Directory</link>. You can find the Yocto Project version of the <filename>bblayers.conf.sample</filename> file in the <filename>meta-poky/conf</filename> directory. @@ -733,7 +565,7 @@ contain appropriate <filename>COPYING</filename> license files with other licensing information. For information on licensing, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" - section. + section in the Yocto Project Development Tasks Manual. </para> </section> @@ -777,7 +609,8 @@ sysroot that matches your target hardware. You can find out more about these installers in the "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" - section in the Yocto Project Software Development Kit (SDK) Developer's Guide. + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. </para> </section> @@ -808,7 +641,8 @@ recipe listed in <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. Population of this directory is handled through shared state, while - the path is specified by the <filename>COMPONENTS_DIR</filename> + the path is specified by the + <link linkend='var-COMPONENTS_DIR'><filename>COMPONENTS_DIR</filename></link> variable. Apart from a few unusual circumstances, handling of the <filename>sysroots-components</filename> directory should be automatic, and recipes should not directly reference @@ -907,7 +741,8 @@ <filename>linux-qemux86-standard-build</filename> and then patched by Quilt. (See the "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using Quilt in Your Workflow</ulink>" - section in the Yocto Project Development Manual for more information.) + section in the Yocto Project Development Tasks Manual for more + information.) Within the <filename>linux-qemux86-standard-build</filename> directory, standard Quilt directories <filename>linux-3.0/patches</filename> and <filename>linux-3.0/.pc</filename> are created, @@ -1041,7 +876,7 @@ <para> As mentioned previously, - <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> is the core + <link linkend='metadata'>Metadata</link> is the core of the Yocto Project. Metadata has several important subdivisions: </para> |