diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 4236 |
1 files changed, 2972 insertions, 1264 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 11a7065c4e3..9745c1308b4 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -24,8 +24,8 @@ each other. For introductory information on the Yocto Project Layer Model, see the - "<ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" - section in the Getting Started With Yocto Project Manual. + "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" + section in the Yocto Project Overview and Concepts Manual. </para> <section id='creating-your-own-layer'> @@ -56,7 +56,7 @@ has not already created a layer containing the Metadata you need. You can see the - <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink> + <ulink url='http://layers.openembedded.org/layerindex/layers/'>OpenEmbedded Metadata Index</ulink> for a list of layers from the OpenEmbedded community that can be used in the Yocto Project. You could find a layer that is identical or close to @@ -65,8 +65,15 @@ <listitem><para> <emphasis>Create a Directory:</emphasis> Create the directory for your layer. - While not strictly required, prepend the name of the - directory with the string "meta-". + When you create the layer, be sure to create the + directory in an area not associated with the + Yocto Project + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (e.g. the cloned <filename>poky</filename> repository). + </para> + + <para>While not strictly required, prepend the name of + the directory with the string "meta-". For example: <literallayout class='monospaced'> meta-mylayer @@ -86,24 +93,24 @@ the "meta-" string are appended to several variables used in the configuration. </para></listitem> - <listitem><para> - <emphasis>Create a Layer Configuration - File:</emphasis> - Inside your new layer folder, you need to create a - <filename>conf/layer.conf</filename> file. - It is easiest to take an existing layer configuration - file and copy that to your layer's - <filename>conf</filename> directory and then modify the - file as needed.</para> - - <para>The - <filename>meta-yocto-bsp/conf/layer.conf</filename> file - in the Yocto Project - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf'>Source Repositories</ulink> - demonstrates the required syntax. - For your layer, you need to replace "yoctobsp" with the - root name of your layer: - <literallayout class='monospaced'> + <listitem><para id='dev-layer-config-file-description'> + <emphasis>Create a Layer Configuration File:</emphasis> + Inside your new layer folder, you need to create a + <filename>conf/layer.conf</filename> file. + It is easiest to take an existing layer configuration + file and copy that to your layer's + <filename>conf</filename> directory and then modify the + file as needed.</para> + + <para>The + <filename>meta-yocto-bsp/conf/layer.conf</filename> file + in the Yocto Project + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf'>Source Repositories</ulink> + demonstrates the required syntax. + For your layer, you need to replace "yoctobsp" with + a unique identifier for your layer (e.g. "machinexyz" + for a layer named "meta-machinexyz"): + <literallayout class='monospaced'> # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" @@ -116,87 +123,76 @@ BBFILE_PRIORITY_yoctobsp = "5" LAYERVERSION_yoctobsp = "4" LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;" - </literallayout></para> - - <para>Here is an explanation of the example: + </literallayout> + Following is an explanation of the layer configuration + file: <itemizedlist> <listitem><para> - The configuration and classes directory is - appended to - <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>. - <note> - All non-distro layers are expected to - append the layer directory to - <filename>BBPATH</filename>. - On the other hand, distro layers, such as - <filename>meta-poky</filename>, can choose - to enforce their own precedence over - <filename>BBPATH</filename>. - For an example of that syntax, see the - <filename>meta-poky/conf/layer.conf</filename> - file for in the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf'>Source Repositories</ulink>. - </note> + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>: + Adds the layer's root directory to BitBake's + search path. + Through the use of the + <filename>BBPATH</filename> variable, BitBake + locates class files + (<filename>.bbclass</filename>), + configuration files, and files that are + included with <filename>include</filename> and + <filename>require</filename> statements. + For these cases, BitBake uses the first file + that matches the name found in + <filename>BBPATH</filename>. + This is similar to the way the + <filename>PATH</filename> variable is used for + binaries. + It is recommended, therefore, that you use + unique class and configuration filenames in + your custom layer. </para></listitem> <listitem><para> - The recipes for the layers are appended to - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>. + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>: + Defines the location for all recipes in the + layer. </para></listitem> <listitem><para> - The - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename> - variable is appended with the layer's root name, - which is "yoctobsp" in this example. + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></ulink>: + Establishes the current layer through a + unique identifier that is used throughout the + OpenEmbedded build system to refer to the layer. + In this example, the identifier "yoctobsp" is + the representation for the container layer + named "meta-yocto-bsp". </para></listitem> <listitem><para> - The - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename> - variable is set to a regular expression and is - used to match files from - <filename>BBFILES</filename> into a particular - layer. - In this case, - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> - is used to make - <filename>BBFILE_PATTERN</filename> match - within the layer's path. + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></ulink>: + Expands immediately during parsing to + provide the directory of the layer. </para></listitem> <listitem><para> - The - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename> - variable assigns a priority to the layer. - Applying priorities is useful in situations - where the same recipe might appear in multiple + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>: + Establishes a priority to use for + recipes in the layer when the OpenEmbedded build + finds recipes of the same name in different layers. - A priority allows you to choose the layer - that takes precedence. </para></listitem> <listitem><para> - The - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename> - variable optionally specifies the version of a - layer as a single number. + <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'><filename>LAYERVERSION</filename></ulink>: + Establishes a version number for the layer. + You can use this version number to specify this + exact version of the layer as a dependency when + using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></ulink> + variable. </para></listitem> <listitem><para> - The - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> - variable expands to the directory of the - current layer + <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERSERIES_COMPAT'><filename>LAYERSERIES_COMPAT</filename></ulink>: + Lists the + <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Yocto Project</ulink> + releases for which the current version is + compatible. + This variable is a good way to indicate how + up-to-date your particular layer is. </para></listitem> - </itemizedlist></para> - - <para>Through the use of the <filename>BBPATH</filename> - variable, BitBake locates class files - (<filename>.bbclass</filename>), - configuration files, and files that are included - with <filename>include</filename> and - <filename>require</filename> statements. - For these cases, BitBake uses the first file that - matches the name found in <filename>BBPATH</filename>. - This is similar to the way the <filename>PATH</filename> - variable is used for binaries. - It is recommended, therefore, that you use unique - class and configuration filenames in your custom layer. + </itemizedlist> </para></listitem> <listitem><para> <emphasis>Add Content:</emphasis> @@ -471,7 +467,7 @@ acceptable explanation for any questions answered "No". </para></listitem> <listitem><para> - You need to be a Yocto Project Member Organization. + Be a Yocto Project Member Organization. </para></listitem> </itemizedlist> </para> @@ -541,7 +537,7 @@ </para> <para> - The script divides tests into three areas: COMMON, BSD, + The script divides tests into three areas: COMMON, BSP, and DISTRO. For example, given a distribution layer (DISTRO), the layer must pass both the COMMON and DISTRO related tests. @@ -625,16 +621,18 @@ The following example shows how to enable a layer named <filename>meta-mylayer</filename>: <literallayout class='monospaced'> - LCONF_VERSION = "6" + # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf + # changes incompatibly + POKY_BBLAYERS_CONF_VERSION = "2" BBPATH = "${TOPDIR}" BBFILES ?= "" BBLAYERS ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-poky \ - $HOME/poky/meta-yocto-bsp \ - $HOME/poky/meta-mylayer \ + /home/<replaceable>user</replaceable>/poky/meta \ + /home/<replaceable>user</replaceable>/poky/meta-poky \ + /home/<replaceable>user</replaceable>/poky/meta-yocto-bsp \ + /home/<replaceable>user</replaceable>/poky/meta-mylayer \ " </literallayout> </para> @@ -1076,9 +1074,10 @@ <literallayout class='monospaced'> $ bitbake-layers create-layer <replaceable>your_layer_name</replaceable> </literallayout> - As an example, the following command adds a layer named - <filename>meta-scottrif</filename>: + As an example, the following command creates a layer named + <filename>meta-scottrif</filename> in your home directory: <literallayout class='monospaced'> + $ cd /usr/home $ bitbake-layers create-layer meta-scottrif NOTE: Starting bitbake server... Add your new layer with 'bitbake-layers add-layer meta-scottrif' @@ -1272,8 +1271,8 @@ To understand how these features work, the best reference is <filename>meta/classes/core-image.bbclass</filename>. This class lists out the available - <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> - of which most map to package groups while some, such as + <filename>IMAGE_FEATURES</filename> of which most map to + package groups while some, such as <filename>debug-tweaks</filename> and <filename>read-only-rootfs</filename>, resolve as general configuration settings. @@ -1693,7 +1692,7 @@ The Yocto Project and OpenEmbedded communities maintain many recipes that might be candidates for what you are doing. You can find a good central index of these recipes in the - <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>. + <ulink url='http://layers.openembedded.org'>OpenEmbedded Layer Index</ulink>. </para> <para> @@ -1858,8 +1857,8 @@ <para> You can find more information about the build process in - "<ulink url='&YOCTO_DOCS_GS_URL;#overview-development-environment'>The Yocto Project Development Environment</ulink>" - chapter of the Getting Started With Yocto Project Manual. + "<ulink url='&YOCTO_DOCS_OM_URL;#overview-development-environment'>The Yocto Project Development Environment</ulink>" + chapter of the Yocto Project Overview and Concepts Manual. </para> </section> @@ -1875,8 +1874,8 @@ Your recipe must have a <filename>SRC_URI</filename> variable that points to where the source is located. For a graphical representation of source locations, see the - "<ulink url='&YOCTO_DOCS_CM_URL;#sources-dev-environment'>Sources</ulink>" - section in the Yocto Project Concepts Manual. + "<ulink url='&YOCTO_DOCS_OM_URL;#sources-dev-environment'>Sources</ulink>" + section in the Yocto Project Overview and Concepts Manual. </para> <para> @@ -2188,8 +2187,9 @@ containing the current checksum. For more explanation and examples of how to set the <filename>LIC_FILES_CHKSUM</filename> variable, see the - "<ulink url='&YOCTO_DOCS_CM_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" - section in the Yocto Project Concepts Manual.</para> + "<link link='usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</link>" + section.</para> + <para>To determine the correct checksum string, you can list the appropriate files in the <filename>LIC_FILES_CHKSUM</filename> variable with @@ -2335,8 +2335,9 @@ automatically add a runtime dependency to "mypackage" on "example"). See the - "<ulink url='&YOCTO_DOCS_CM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" - in the Yocto Project Concepts Manual for further details. + "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" + section in the Yocto Project Overview and Concepts Manual for + further details. </para> </section> @@ -3398,9 +3399,10 @@ The variable <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename> is used to track source license changes as described in the - "<ulink url='&YOCTO_DOCS_CM_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" - section in the Yocto Project Concepts Manual. - You can quickly create Autotool-based recipes in a manner similar to the previous example. + "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</link>" + section in the Yocto Project Overview and Concepts Manual. + You can quickly create Autotool-based recipes in a manner + similar to the previous example. </para> </section> @@ -3605,9 +3607,9 @@ allows runtime dependencies between packages to be added automatically. See the - "<ulink url='&YOCTO_DOCS_CM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" - section in the Yocto Project Concepts Manual - for more information. + "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" + section in the Yocto Project Overview and + Concepts Manual for more information. </para></listitem> </itemizedlist> </note> @@ -4262,8 +4264,8 @@ You need to be sure that your development host is set up to use the Yocto Project. For information on how to set up your host, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>" - section in the Yocto Project Development Tasks Manual. + "<link linkend='dev-preparing-the-build-host'>Preparing the Build Host</link>" + section. </para></listitem> <listitem><para> <emphasis>Make Sure Git is Configured:</emphasis> @@ -4944,8 +4946,8 @@ Modifications will also disappear if you use the <filename>rm_work</filename> feature as described in the - "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" - section of the Yocto Project Quick Start. + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-saving-memory-during-a-build'>Conserving Disk Space During Builds</ulink>" + section. </note> </para></listitem> <listitem><para> @@ -5161,103 +5163,1336 @@ </para> </section> - <section id='platdev-building-targets-with-multiple-configurations'> - <title>Building Targets with Multiple Configurations</title> + <section id='dev-building'> + <title>Building</title> <para> - Bitbake also has functionality that allows you to build - multiple targets at the same time, where each target uses - a different configuration. + This section describes various build procedures. + For example, the steps needed for a simple build, a target that + uses multiple configurations, building an image for more than + one machine, and so forth. </para> - <para> - In order to accomplish this, you setup each of the configurations - you need to use in parallel by placing the configuration files in - your current build directory alongside the usual - <filename>local.conf</filename> file. - </para> + <section id='dev-building-a-simple-image'> + <title>Building a Simple Image</title> - <para> - Follow these guidelines to create an environment that supports - multiple configurations: - <itemizedlist> - <listitem><para> - <emphasis>Create Configuration Files</emphasis>: - You need to create a single configuration file for each - configuration for which you want to add support. - These files would contain lines such as the following: + <para> + In the development environment, you need to build an image + whenever you change hardware support, add or change system + libraries, or add or change services that have dependencies. + Several methods exist that allow you to build an image within + the Yocto Project. + This section presents the basic steps you need to build a + simple image using BitBake from a build host running Linux. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + For information on how to build an image using + <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>, + see the + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>. + </para></listitem> + <listitem><para> + For information on how to use + <filename>devtool</filename> to build images, see + the + "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>" + section in the Yocto Project Application + Development and the Extensible Software Development + Kit (eSDK) manual. + </para></listitem> + <listitem><para> + For a quick example on how to build an image using + the OpenEmbedded build system, see the + <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink> + document. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + The build process creates an entire Linux distribution from + source and places it in your + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + under <filename>tmp/deploy/images</filename>. + For detailed information on the build process using BitBake, + see the + "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>" + section in the Yocto Project Overview and Concepts Manual. + </para> + + <para> + The following figure and list overviews the build process: + <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" /> + <orderedlist> + <listitem><para> + <emphasis>Set up Your Host Development System to Support + Development Using the Yocto Project</emphasis>: + See the + "<link linkend='dev-manual-start'>Setting Up to Use the Yocto Project</link>" + section for options on how to get a build host ready to + use the Yocto Project. + </para></listitem> + <listitem><para> + <emphasis>Initialize the Build Environment:</emphasis> + Initialize the build environment by sourcing the build + environment script (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>): + <literallayout class='monospaced'> + $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>] + </literallayout></para> + + <para>When you use the initialization script, the + OpenEmbedded build system uses + <filename>build</filename> as the default Build + Directory in your current work directory. + You can use a <replaceable>build_dir</replaceable> + argument with the script to specify a different build + directory. + <note><title>Tip</title> + A common practice is to use a different Build + Directory for different targets. + For example, <filename>~/build/x86</filename> for a + <filename>qemux86</filename> target, and + <filename>~/build/arm</filename> for a + <filename>qemuarm</filename> target. + </note> + </para></listitem> + <listitem><para> + <emphasis>Make Sure Your <filename>local.conf</filename> + File is Correct:</emphasis> + Ensure the <filename>conf/local.conf</filename> + configuration file, which is found in the Build + Directory, is set up how you want it. + This file defines many aspects of the build environment + including the target machine architecture through the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, + the packaging format used during the build + (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>), + and a centralized tarball download directory through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable. + </para></listitem> + <listitem><para> + <emphasis>Build the Image:</emphasis> + Build the image using the <filename>bitbake</filename> + command: + <literallayout class='monospaced'> + $ bitbake <replaceable>target</replaceable> + </literallayout> + <note> + For information on BitBake, see the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </note> + The <replaceable>target</replaceable> is the name of the + recipe you want to build. + Common targets are the images in + <filename>meta/recipes-core/images</filename>, + <filename>meta/recipes-sato/images</filename>, and so + forth all found in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + Or, the target can be the name of a recipe for a + specific piece of software such as BusyBox. + For more details about the images the OpenEmbedded build + system supports, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" + chapter in the Yocto Project Reference Manual.</para> + + <para>As an example, the following command builds the + <filename>core-image-minimal</filename> image: + <literallayout class='monospaced'> + $ bitbake core-image-minimal + </literallayout> + Once an image has been built, it often needs to be + installed. + The images and kernels built by the OpenEmbedded + build system are placed in the Build Directory in + <filename class="directory">tmp/deploy/images</filename>. + For information on how to run pre-built images such as + <filename>qemux86</filename> and <filename>qemuarm</filename>, + see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> + manual. + For information about how to install these images, + see the documentation for your particular board or + machine. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='dev-building-images-for-multiple-targets-using-multiple-configurations'> + <title>Building Images for Multiple Targets Using Multiple Configurations</title> + + <para> + You can use a single <filename>bitbake</filename> command + to build multiple images or packages for different targets + where each image or package requires a different configuration + (multiple configuration builds). + The builds, in this scenario, are sometimes referred to as + "multiconfigs", and this section uses that term throughout. + </para> + + <para> + This section describes how to set up for multiple + configuration builds and how to account for cross-build + dependencies between the multiconfigs. + </para> + + <section id='dev-setting-up-and-running-a-multiple-configuration-build'> + <title>Setting Up and Running a Multiple Configuration Build</title> + + <para> + To accomplish a multiple configuration build, you must + define each target's configuration separately using + a parallel configuration file in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, + and you must follow a required file hierarchy. + Additionally, you must enable the multiple configuration + builds in your <filename>local.conf</filename> file. + </para> + + <para> + Follow these steps to set up and execute multiple + configuration builds: + <itemizedlist> + <listitem><para> + <emphasis>Create Separate Configuration Files</emphasis>: + You need to create a single configuration file for + each build target (each multiconfig). + Minimally, each configuration file must define the + machine and the temporary directory BitBake uses + for the build. + Suggested practice dictates that you do not + overlap the temporary directories + used during the builds. + However, it is possible that you can share the + temporary directory + (<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>). + For example, consider a scenario with two + different multiconfigs for the same + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>: "qemux86" built for + two distributions such as "poky" and "poky-lsb". + In this case, you might want to use the same + <filename>TMPDIR</filename>.</para> + + <para>Here is an example showing the minimal + statements needed in a configuration file for + a "qemux86" target whose temporary build directory + is <filename>tmpmultix86</filename>: + <literallayout class='monospaced'> + MACHINE="qemux86" + TMPDIR="${TOPDIR}/tmpmultix86" + </literallayout></para> + + <para>The location for these multiconfig + configuration files is specific. + They must reside in the current build directory in + a sub-directory of <filename>conf</filename> named + <filename>multiconfig</filename>. + Following is an example that defines two + configuration files for the "x86" and "arm" + multiconfigs: + <imagedata fileref="figures/multiconfig_files.png" align="center" width="4in" depth="3in" /> + </para> + + <para>The reason for this required file hierarchy + is because the <filename>BBPATH</filename> variable + is not constructed until the layers are parsed. + Consequently, using the configuration file as a + pre-configuration file is not possible unless it is + located in the current working directory. + </para></listitem> + <listitem><para> + <emphasis>Add the BitBake Multi-configuration Variable to the Local Configuration File</emphasis>: + Use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></ulink> + variable in your + <filename>conf/local.conf</filename> configuration + file to specify each multiconfig. + Continuing with the example from the previous + figure, the <filename>BBMULTICONFIG</filename> + variable needs to enable two multiconfigs: "x86" + and "arm" by specifying each configuration file: + <literallayout class='monospaced'> + BBMULTICONFIG = "x86 arm" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Launch BitBake</emphasis>: + Use the following BitBake command form to launch the + multiple configuration build: + <literallayout class='monospaced'> + $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ] + </literallayout> + For the example in this section, the following + command applies: + <literallayout class='monospaced'> + $ bitbake multiconfig:x86:core-image-minimal multiconfig:arm:core-image-sato + </literallayout> + The previous BitBake command builds a + <filename>core-image-minimal</filename> image that + is configured through the + <filename>x86.conf</filename> configuration file + and builds a <filename>core-image-sato</filename> + image that is configured through the + <filename>arm.conf</filename> configuration file. + </para></listitem> + </itemizedlist> + <note> + Support for multiple configuration builds in the + Yocto Project &DISTRO; (&DISTRO_NAME;) Release does + not include Shared State (sstate) optimizations. + Consequently, if a build uses the same object twice + in, for example, two different + <filename>TMPDIR</filename> directories, the build + either loads from an existing sstate cache for that + build at the start or builds the object fresh. + </note> + </para> + </section> + + <section id='dev-enabling-multiple-configuration-build-dependencies'> + <title>Enabling Multiple Configuration Build Dependencies</title> + + <para> + Sometimes dependencies can exist between targets + (multiconfigs) in a multiple configuration build. + For example, suppose that in order to build a + <filename>core-image-sato</filename> image for an "x86" + multiconfig, the root filesystem of an "arm" + multiconfig must exist. + This dependency is essentially that the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink> + task in the <filename>core-image-sato</filename> recipe + depends on the completion of the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink> + task of the <filename>core-image-minimal</filename> + recipe. + </para> + + <para> + To enable dependencies in a multiple configuration + build, you must declare the dependencies in the recipe + using the following statement form: + <literallayout class='monospaced'> + <replaceable>task_or_package</replaceable>[mcdepends] = "multiconfig:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>" + </literallayout> + To better show how to use this statement, consider the + example scenario from the first paragraph of this section. + The following statement needs to be added to the recipe + that builds the <filename>core-image-sato</filename> + image: <literallayout class='monospaced'> - MACHINE = "A" + do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_rootfs" </literallayout> - The files would contain any other variables that can - be set and built in the same directory. + In this example, the + <replaceable>from_multiconfig</replaceable> is "x86". + The <replaceable>to_multiconfig</replaceable> is "arm". + The task on which the <filename>do_image</filename> task + in the recipe depends is the <filename>do_rootfs</filename> + task from the <filename>core-image-minimal</filename> + recipe associated with the "arm" multiconfig. + </para> + + <para> + Once you set up this dependency, you can build the + "x86" multiconfig using a BitBake command as follows: + <literallayout class='monospaced'> + $ bitbake multiconfig:x86:core-image-sato + </literallayout> + This command executes all the tasks needed to create + the <filename>core-image-sato</filename> image for the + "x86" multiconfig. + Because of the dependency, BitBake also executes through + the <filename>do_rootfs</filename> task for the "arm" + multiconfig build. + </para> + + <para> + Having a recipe depend on the root filesystem of another + build might not seem that useful. + Consider this change to the statement in the + <filename>core-image-sato</filename> recipe: + <literallayout class='monospaced'> + do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_image" + </literallayout> + In this case, BitBake must create the + <filename>core-image-minimal</filename> image for the + "arm" build since the "x86" build depends on it. + </para> + + <para> + Because "x86" and "arm" are enabled for multiple + configuration builds and have separate configuration + files, BitBake places the artifacts for each build in the + respective temporary build directories (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>). + </para> + </section> + </section> + + <section id='building-an-initramfs-image'> + <title>Building an Initial RAM Filesystem (initramfs) Image</title> + + <para> + An initial RAM filesystem (initramfs) image provides a temporary + root filesystem used for early system initialization (e.g. + loading of modules needed to locate and mount the "real" root + filesystem). + <note> + The initramfs image is the successor of initial RAM disk + (initrd). + It is a "copy in and out" (cpio) archive of the initial + filesystem that gets loaded into memory during the Linux + startup process. + Because Linux uses the contents of the archive during + initialization, the initramfs image needs to contain all of the + device drivers and tools needed to mount the final root + filesystem. + </note> + </para> + + <para> + Follow these steps to create an initramfs image: + <orderedlist> + <listitem><para> + <emphasis>Create the initramfs Image Recipe:</emphasis> + You can reference the + <filename>core-image-minimal-initramfs.bb</filename> + recipe found in the <filename>meta/recipes-core</filename> + directory of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + as an example from which to work. + </para></listitem> + <listitem><para> + <emphasis>Decide if You Need to Bundle the initramfs Image + Into the Kernel Image:</emphasis> + If you want the initramfs image that is built to be + bundled in with the kernel image, set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink> + variable to "1" in your <filename>local.conf</filename> + configuration file and set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink> + variable in the recipe that builds the kernel image. + <note><title>Tip</title> + It is recommended that you do bundle the initramfs + image with the kernel image to avoid circular + dependencies between the kernel recipe and the + initramfs recipe should the initramfs image + include kernel modules. + </note> + Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename> + flag causes the initramfs image to be unpacked + into the <filename>${B}/usr/</filename> directory. + The unpacked initramfs image is then passed to the kernel's + <filename>Makefile</filename> using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink> + variable, allowing the initramfs image to be built into + the kernel normally. + <note> + If you choose to not bundle the initramfs image with + the kernel image, you are essentially using an + <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>. + Creating an initrd is handled primarily through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>, + <filename>INITRD_LIVE</filename>, and + <filename>INITRD_IMAGE_LIVE</filename> variables. + For more information, see the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink> + file. + </note> + </para></listitem> + <listitem><para> + <emphasis>Optionally Add Items to the initramfs Image + Through the initramfs Image Recipe:</emphasis> + If you add items to the initramfs image by way of its + recipe, you should use + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink> + rather than + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>. + <filename>PACKAGE_INSTALL</filename> gives more direct + control of what is added to the image as compared to + the defaults you might not necessarily want that are + set by the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink> + classes. + </para></listitem> + <listitem><para> + <emphasis>Build the Kernel Image and the initramfs + Image:</emphasis> + Build your kernel image using BitBake. + Because the initramfs image recipe is a dependency of the + kernel image, the initramfs image is built as well and + bundled with the kernel image if you used the + <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink> + variable described earlier. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='building-a-tiny-system'> + <title>Building a Tiny System</title> + + <para> + Very small distributions have some significant advantages such + as requiring less on-die or in-package memory (cheaper), better + performance through efficient cache usage, lower power requirements + due to less memory, faster boot times, and reduced development + overhead. + Some real-world examples where a very small distribution gives + you distinct advantages are digital cameras, medical devices, + and small headless systems. + </para> + + <para> + This section presents information that shows you how you can + trim your distribution to even smaller sizes than the + <filename>poky-tiny</filename> distribution, which is around + 5 Mbytes, that can be built out-of-the-box using the Yocto Project. + </para> + + <section id='tiny-system-overview'> + <title>Overview</title> + + <para> + The following list presents the overall steps you need to + consider and perform to create distributions with smaller + root filesystems, achieve faster boot times, maintain your critical + functionality, and avoid initial RAM disks: + <itemizedlist> + <listitem><para> + <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link> + </para></listitem> + <listitem><para> + <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link> + </para></listitem> + <listitem><para> + <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link> + </para></listitem> + <listitem><para> + <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link> + </para></listitem> + <listitem><para> + <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link> + </para></listitem> + <listitem><para> + <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link> + </para></listitem> + <listitem><para> + <link linkend='iterate-on-the-process'>Iterate on the process.</link> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='goals-and-guiding-principles'> + <title>Goals and Guiding Principles</title> + + <para> + Before you can reach your destination, you need to know + where you are going. + Here is an example list that you can use as a guide when + creating very small distributions: + <itemizedlist> + <listitem><para>Determine how much space you need + (e.g. a kernel that is 1 Mbyte or less and + a root filesystem that is 3 Mbytes or less). + </para></listitem> + <listitem><para>Find the areas that are currently + taking 90% of the space and concentrate on reducing + those areas. + </para></listitem> + <listitem><para>Do not create any difficult "hacks" + to achieve your goals.</para></listitem> + <listitem><para>Leverage the device-specific + options.</para></listitem> + <listitem><para>Work in a separate layer so that you + keep changes isolated. + For information on how to create layers, see + the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='understand-what-gives-your-image-size'> + <title>Understand What Contributes to Your Image Size</title> + + <para> + It is easiest to have something to start with when creating + your own distribution. + You can use the Yocto Project out-of-the-box to create the + <filename>poky-tiny</filename> distribution. + Ultimately, you will want to make changes in your own + distribution that are likely modeled after + <filename>poky-tiny</filename>. <note> - You can change the - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> - to not conflict. - </note></para> + To use <filename>poky-tiny</filename> in your build, + set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> + variable in your + <filename>local.conf</filename> file to "poky-tiny" + as described in the + "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>" + section. + </note> + </para> - <para> - Furthermore, the configuration file must be located in the - current build directory in a directory named - <filename>multiconfig</filename> under the build's - <filename>conf</filename> directory where - <filename>local.conf</filename> resides. - The reason for this restriction is because the - <filename>BBPATH</filename> variable is not constructed - until the layers are parsed. - Consequently, using the configuration file as a - pre-configuration file is not possible unless it is - located in the current working directory. - </para></listitem> - <listitem><para> - <emphasis>Add the BitBake Multi-Config Variable to you Local Configuration File</emphasis>: - Use the - <filename>BBMULTICONFIG</filename> - variable in your <filename>conf/local.conf</filename> - configuration file to specify each separate configuration. - For example, the following line tells BitBake it should load - <filename>conf/multiconfig/configA.conf</filename>, - <filename>conf/multiconfig/configB.conf</filename>, and - <filename>conf/multiconfig/configC.conf</filename>. + <para> + Understanding some memory concepts will help you reduce the + system size. + Memory consists of static, dynamic, and temporary memory. + Static memory is the TEXT (code), DATA (initialized data + in the code), and BSS (uninitialized data) sections. + Dynamic memory represents memory that is allocated at runtime: + stacks, hash tables, and so forth. + Temporary memory is recovered after the boot process. + This memory consists of memory used for decompressing + the kernel and for the <filename>__init__</filename> + functions. + </para> + + <para> + To help you see where you currently are with kernel and root + filesystem sizes, you can use two tools found in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> in + the <filename>scripts/tiny/</filename> directory: + <itemizedlist> + <listitem><para><filename>ksize.py</filename>: Reports + component sizes for the kernel build objects. + </para></listitem> + <listitem><para><filename>dirsize.py</filename>: Reports + component sizes for the root filesystem.</para></listitem> + </itemizedlist> + This next tool and command help you organize configuration + fragments and view file dependencies in a human-readable form: + <itemizedlist> + <listitem><para><filename>merge_config.sh</filename>: + Helps you manage configuration files and fragments + within the kernel. + With this tool, you can merge individual configuration + fragments together. + The tool allows you to make overrides and warns you + of any missing configuration options. + The tool is ideal for allowing you to iterate on + configurations, create minimal configurations, and + create configuration files for different machines + without having to duplicate your process.</para> + <para>The <filename>merge_config.sh</filename> script is + part of the Linux Yocto kernel Git repositories + (i.e. <filename>linux-yocto-3.14</filename>, + <filename>linux-yocto-3.10</filename>, + <filename>linux-yocto-3.8</filename>, and so forth) + in the + <filename>scripts/kconfig</filename> directory.</para> + <para>For more information on configuration fragments, + see the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>" + section in the Yocto Project Linux Kernel Development + Manual. + </para></listitem> + <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>: + Using the BitBake command with these options brings up + a Dependency Explorer from which you can view file + dependencies. + Understanding these dependencies allows you to make + informed decisions when cutting out various pieces of the + kernel and root filesystem.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='trim-the-root-filesystem'> + <title>Trim the Root Filesystem</title> + + <para> + The root filesystem is made up of packages for booting, + libraries, and applications. + To change things, you can configure how the packaging happens, + which changes the way you build them. + You can also modify the filesystem itself or select a different + filesystem. + </para> + + <para> + First, find out what is hogging your root filesystem by running the + <filename>dirsize.py</filename> script from your root directory: <literallayout class='monospaced'> - BBMULTICONFIG = "configA configB configC" + $ cd <replaceable>root-directory-of-image</replaceable> + $ dirsize.py 100000 > dirsize-100k.log + $ cat dirsize-100k.log </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Launch BitBake</emphasis>: - Use the following BitBake command form to launch the - build: + You can apply a filter to the script to ignore files under + a certain size. + The previous example filters out any files below 100 Kbytes. + The sizes reported by the tool are uncompressed, and thus + will be smaller by a relatively constant factor in a + compressed root filesystem. + When you examine your log file, you can focus on areas of the + root filesystem that take up large amounts of memory. + </para> + + <para> + You need to be sure that what you eliminate does not cripple + the functionality you need. + One way to see how packages relate to each other is by using + the Dependency Explorer UI with the BitBake command: <literallayout class='monospaced'> - $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ] + $ cd <replaceable>image-directory</replaceable> + $ bitbake -u taskexp -g <replaceable>image</replaceable> + </literallayout> + Use the interface to select potential packages you wish to + eliminate and see their dependency relationships. + </para> + + <para> + When deciding how to reduce the size, get rid of packages that + result in minimal impact on the feature set. + For example, you might not need a VGA display. + Or, you might be able to get by with <filename>devtmpfs</filename> + and <filename>mdev</filename> instead of + <filename>udev</filename>. + </para> + + <para> + Use your <filename>local.conf</filename> file to make changes. + For example, to eliminate <filename>udev</filename> and + <filename>glib</filename>, set the following in the + local configuration file: + <literallayout class='monospaced'> + VIRTUAL-RUNTIME_dev_manager = "" + </literallayout> + </para> + + <para> + Finally, you should consider exactly the type of root + filesystem you need to meet your needs while also reducing + its size. + For example, consider <filename>cramfs</filename>, + <filename>squashfs</filename>, <filename>ubifs</filename>, + <filename>ext2</filename>, or an <filename>initramfs</filename> + using <filename>initramfs</filename>. + Be aware that <filename>ext3</filename> requires a 1 Mbyte + journal. + If you are okay with running read-only, you do not need this + journal. + </para> + + <note> + After each round of elimination, you need to rebuild your + system and then use the tools to see the effects of your + reductions. + </note> + </section> + + <section id='trim-the-kernel'> + <title>Trim the Kernel</title> + + <para> + The kernel is built by including policies for hardware-independent + aspects. + What subsystems do you enable? + For what architecture are you building? + Which drivers do you build by default? + <note>You can modify the kernel source if you want to help + with boot time. + </note> + </para> + + <para> + Run the <filename>ksize.py</filename> script from the top-level + Linux build directory to get an idea of what is making up + the kernel: + <literallayout class='monospaced'> + $ cd <replaceable>top-level-linux-build-directory</replaceable> + $ ksize.py > ksize.log + $ cat ksize.log </literallayout> - Following is an example that supports building a minimal - image for configuration A alongside a standard - <filename>core-image-sato</filename>, which takes its - configuration from <filename>local.conf</filename>: + When you examine the log, you will see how much space is + taken up with the built-in <filename>.o</filename> files for + drivers, networking, core kernel files, filesystem, sound, + and so forth. + The sizes reported by the tool are uncompressed, and thus + will be smaller by a relatively constant factor in a compressed + kernel image. + Look to reduce the areas that are large and taking up around + the "90% rule." + </para> + + <para> + To examine, or drill down, into any particular area, use the + <filename>-d</filename> option with the script: <literallayout class='monospaced'> - $ bitbake multiconfig:configA:core-image-minimal core-image-sato + $ ksize.py -d > ksize.log </literallayout> + Using this option breaks out the individual file information + for each area of the kernel (e.g. drivers, networking, and + so forth). + </para> + + <para> + Use your log file to see what you can eliminate from the kernel + based on features you can let go. + For example, if you are not going to need sound, you do not + need any drivers that support sound. + </para> + + <para> + After figuring out what to eliminate, you need to reconfigure + the kernel to reflect those changes during the next build. + You could run <filename>menuconfig</filename> and make all your + changes at once. + However, that makes it difficult to see the effects of your + individual eliminations and also makes it difficult to replicate + the changes for perhaps another target device. + A better method is to start with no configurations using + <filename>allnoconfig</filename>, create configuration + fragments for individual changes, and then manage the + fragments into a single configuration file using + <filename>merge_config.sh</filename>. + The tool makes it easy for you to iterate using the + configuration change and build cycle. + </para> + + <para> + Each time you make configuration changes, you need to rebuild + the kernel and check to see what impact your changes had on + the overall size. + </para> + </section> + + <section id='remove-package-management-requirements'> + <title>Remove Package Management Requirements</title> + + <para> + Packaging requirements add size to the image. + One way to reduce the size of the image is to remove all the + packaging requirements from the image. + This reduction includes both removing the package manager + and its unique dependencies as well as removing the package + management data itself. + </para> + + <para> + To eliminate all the packaging requirements for an image, + be sure that "package-management" is not part of your + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> + statement for the image. + When you remove this feature, you are removing the package + manager as well as its dependencies from the root filesystem. + </para> + </section> + + <section id='look-for-other-ways-to-minimize-size'> + <title>Look for Other Ways to Minimize Size</title> + + <para> + Depending on your particular circumstances, other areas that you + can trim likely exist. + The key to finding these areas is through tools and methods + described here combined with experimentation and iteration. + Here are a couple of areas to experiment with: + <itemizedlist> + <listitem><para><filename>glibc</filename>: + In general, follow this process: + <orderedlist> + <listitem><para>Remove <filename>glibc</filename> + features from + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> + that you think you do not need.</para></listitem> + <listitem><para>Build your distribution. + </para></listitem> + <listitem><para>If the build fails due to missing + symbols in a package, determine if you can + reconfigure the package to not need those + features. + For example, change the configuration to not + support wide character support as is done for + <filename>ncurses</filename>. + Or, if support for those characters is needed, + determine what <filename>glibc</filename> + features provide the support and restore the + configuration. + </para></listitem> + <listitem><para>Rebuild and repeat the process. + </para></listitem> + </orderedlist></para></listitem> + <listitem><para><filename>busybox</filename>: + For BusyBox, use a process similar as described for + <filename>glibc</filename>. + A difference is you will need to boot the resulting + system to see if you are able to do everything you + expect from the running system. + You need to be sure to integrate configuration fragments + into Busybox because BusyBox handles its own core + features and then allows you to add configuration + fragments on top. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='iterate-on-the-process'> + <title>Iterate on the Process</title> + + <para> + If you have not reached your goals on system size, you need + to iterate on the process. + The process is the same. + Use the tools and see just what is taking up 90% of the root + filesystem and the kernel. + Decide what you can eliminate without limiting your device + beyond what you need. + </para> + + <para> + Depending on your system, a good place to look might be + Busybox, which provides a stripped down + version of Unix tools in a single, executable file. + You might be able to drop virtual terminal services or perhaps + ipv6. + </para> + </section> + </section> + + <section id='building-images-for-more-than-one-machine'> + <title>Building Images for More than One Machine</title> + + <para> + A common scenario developers face is creating images for several + different machines that use the same software environment. + In this situation, it is tempting to set the + tunings and optimization flags for each build specifically for + the targeted hardware (i.e. "maxing out" the tunings). + Doing so can considerably add to build times and package feed + maintenance collectively for the machines. + For example, selecting tunes that are extremely specific to a + CPU core used in a system might enable some micro optimizations + in GCC for that particular system but would otherwise not gain + you much of a performance difference across the other systems + as compared to using a more general tuning across all the builds + (e.g. setting + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink> + specifically for each machine's build). + Rather than "max out" each build's tunings, you can take steps that + cause the OpenEmbedded build system to reuse software across the + various machines where it makes sense. + </para> + + <para> + If build speed and package feed maintenance are considerations, + you should consider the points in this section that can help you + optimize your tunings to best consider build times and package + feed maintenance. + <itemizedlist> + <listitem><para> + <emphasis>Share the Build Directory:</emphasis> + If at all possible, share the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> + across builds. + The Yocto Project supports switching between different + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + values in the same <filename>TMPDIR</filename>. + This practice is well supported and regularly used by + developers when building for multiple machines. + When you use the same <filename>TMPDIR</filename> for + multiple machine builds, the OpenEmbedded build system can + reuse the existing native and often cross-recipes for + multiple machines. + Thus, build time decreases. + <note> + If + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> + settings change or fundamental configuration settings + such as the filesystem layout, you need to work with + a clean <filename>TMPDIR</filename>. + Sharing <filename>TMPDIR</filename> under these + circumstances might work but since it is not + guaranteed, you should use a clean + <filename>TMPDIR</filename>. + </note> + </para></listitem> + <listitem><para> + <emphasis>Enable the Appropriate Package Architecture:</emphasis> + By default, the OpenEmbedded build system enables three + levels of package architectures: "all", "tune" or "package", + and "machine". + Any given recipe usually selects one of these package + architectures (types) for its output. + Depending for what a given recipe creates packages, making + sure you enable the appropriate package architecture can + directly impact the build time.</para> + + <para>A recipe that just generates scripts can enable + "all" architecture because there are no binaries to build. + To specifically enable "all" architecture, be sure your + recipe inherits the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink> + class. + This class is useful for "all" architectures because it + configures many variables so packages can be used across + multiple architectures.</para> + + <para>If your recipe needs to generate packages that are + machine-specific or when one of the build or runtime + dependencies is already machine-architecture dependent, + which makes your recipe also machine-architecture dependent, + make sure your recipe enables the "machine" package + architecture through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink> + variable: + <literallayout class='monospaced'> + PACKAGE_ARCH = "${MACHINE_ARCH}" + </literallayout> + When you do not specifically enable a package + architecture through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>, + The OpenEmbedded build system defaults to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink> + setting: + <literallayout class='monospaced'> + PACKAGE_ARCH = "${TUNE_PKGARCH}" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Choose a Generic Tuning File if Possible:</emphasis> + Some tunes are more generic and can run on multiple targets + (e.g. an <filename>armv5</filename> set of packages could + run on <filename>armv6</filename> and + <filename>armv7</filename> processors in most cases). + Similarly, <filename>i486</filename> binaries could work + on <filename>i586</filename> and higher processors. + You should realize, however, that advances on newer + processor versions would not be used.</para> + + <para>If you select the same tune for several different + machines, the OpenEmbedded build system reuses software + previously built, thus speeding up the overall build time. + Realize that even though a new sysroot for each machine is + generated, the software is not recompiled and only one + package feed exists. + </para></listitem> + <listitem><para> + <emphasis>Manage Granular Level Packaging:</emphasis> + Sometimes cases exist where injecting another level of + package architecture beyond the three higher levels noted + earlier can be useful. + For example, consider how NXP (formerly Freescale) allows + for the easy reuse of binary packages in their layer + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/'><filename>meta-freescale</filename></ulink>. + In this example, the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/classes/fsl-dynamic-packagearch.bbclass'><filename>fsl-dynamic-packagearch</filename></ulink> + class shares GPU packages for i.MX53 boards because + all boards share the AMD GPU. + The i.MX6-based boards can do the same because all boards + share the Vivante GPU. + This class inspects the BitBake datastore to identify if + the package provides or depends on one of the + sub-architecture values. + If so, the class sets the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> + value based on the <filename>MACHINE_SUBARCH</filename> + value. + If the package does not provide or depend on one of the + sub-architecture values but it matches a value in the + machine-specific filter, it sets + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>. + This behavior reduces the number of packages built and + saves build time by reusing binaries. + </para></listitem> + <listitem><para> + <emphasis>Use Tools to Debug Issues:</emphasis> + Sometimes you can run into situations where software is + being rebuilt when you think it should not be. + For example, the OpenEmbedded build system might not be + using shared state between machines when you think it + should be. + These types of situations are usually due to references + to machine-specific variables such as + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>, + and so forth in code that is supposed to only be + tune-specific or when the recipe depends + (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>, + and so forth) on some other recipe that already has + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> + defined as "${MACHINE_ARCH}". + <note> + Patches to fix any issues identified are most welcome + as these issues occasionally do occur. + </note></para> + + <para>For such cases, you can use some tools to help you + sort out the situation: + <itemizedlist> + <listitem><para> + <emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis> + You can find this tool in the + <filename>scripts</filename> directory of the + Source Repositories. + See the comments in the script for information on + how to use the tool. + </para></listitem> + <listitem><para> + <emphasis>BitBake's "-S printdiff" Option:</emphasis> + Using this option causes BitBake to try to + establish the closest signature match it can + (e.g. in the shared state cache) and then run + <filename>bitbake-diffsigs</filename> over the + matches to determine the stamps and delta where + these two stamp trees diverge. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id="building-software-from-an-external-source"> + <title>Building Software from an External Source</title> + + <para> + By default, the OpenEmbedded build system uses the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + when building source code. + The build process involves fetching the source files, unpacking + them, and then patching them if necessary before the build takes + place. + </para> + + <para> + Situations exist where you might want to build software from source + files that are external to and thus outside of the + OpenEmbedded build system. + For example, suppose you have a project that includes a new BSP with + a heavily customized kernel. + And, you want to minimize exposing the build system to the + development team so that they can focus on their project and + maintain everyone's workflow as much as possible. + In this case, you want a kernel source directory on the development + machine where the development occurs. + You want the recipe's + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable to point to the external directory and use it as is, not + copy it. + </para> + + <para> + To build from software that comes from an external source, all you + need to do is inherit the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink> + class and then set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink> + variable to point to your external source code. + Here are the statements to put in your + <filename>local.conf</filename> file: + <literallayout class='monospaced'> + INHERIT += "externalsrc" + EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>" + </literallayout> + </para> + + <para> + This next example shows how to accomplish the same thing by setting + <filename>EXTERNALSRC</filename> in the recipe itself or in the + recipe's append file: + <literallayout class='monospaced'> + EXTERNALSRC = "<replaceable>path</replaceable>" + EXTERNALSRC_BUILD = "<replaceable>path</replaceable>" + </literallayout> + <note> + In order for these settings to take effect, you must globally + or locally inherit the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink> + class. + </note> + </para> + + <para> + By default, <filename>externalsrc.bbclass</filename> builds + the source code in a directory separate from the external source + directory as specified by + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>. + If you need to have the source built in the same directory in + which it resides, or some other nominated directory, you can set + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink> + to point to that directory: + <literallayout class='monospaced'> + EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>" + </literallayout> + </para> + </section> + </section> + + + + <section id='speeding-up-a-build'> + <title>Speeding Up a Build</title> + + <para> + Build time can be an issue. + By default, the build system uses simple controls to try and maximize + build efficiency. + In general, the default settings for all the following variables + result in the most efficient build times when dealing with single + socket systems (i.e. a single CPU). + If you have multiple CPUs, you might try increasing the default + values to gain more speed. + See the descriptions in the glossary for each variable for more + information: + <itemizedlist> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</ulink> + The maximum number of threads BitBake simultaneously executes. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename>:</ulink> + The number of threads BitBake uses during parsing. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</ulink> + Extra options passed to the <filename>make</filename> command + during the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink> + task in order to specify parallel compilation on the + local build host. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</ulink> + Extra options passed to the <filename>make</filename> command + during the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task in order to specify parallel installation on the + local build host. </para></listitem> </itemizedlist> + As mentioned, these variables all scale to the number of processor + cores available on the build system. + For single socket systems, this auto-scaling ensures that the build + system fundamentally takes advantage of potential parallel operations + during the build based on the build machine's capabilities. </para> <para> - Support for multiple configurations in this current release of - the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues: + Following are additional factors that can affect build speed: <itemizedlist> <listitem><para> - No inter-multi-configuration dependencies exist. + File system type: + The file system type that the build is being performed on can + also influence performance. + Using <filename>ext4</filename> is recommended as compared + to <filename>ext2</filename> and <filename>ext3</filename> + due to <filename>ext4</filename> improved features + such as extents. </para></listitem> <listitem><para> - Shared State (sstate) optimizations do not exist. - Consequently, if the build uses the same object twice - in, for example, two different - <filename>TMPDIR</filename> directories, the build - will either load from an existing sstate cache at the - start or build the object twice. + Disabling the updating of access time using + <filename>noatime</filename>: + The <filename>noatime</filename> mount option prevents the + build system from updating file and directory access times. + </para></listitem> + <listitem><para> + Setting a longer commit: + Using the "commit=" mount option increases the interval + in seconds between disk cache writes. + Changing this interval from the five second default to + something longer increases the risk of data loss but decreases + the need to write to the disk, thus increasing the build + performance. + </para></listitem> + <listitem><para> + Choosing the packaging backend: + Of the available packaging backends, IPK is the fastest. + Additionally, selecting a singular packaging backend also + helps. + </para></listitem> + <listitem><para> + Using <filename>tmpfs</filename> for + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> + as a temporary file system: + While this can help speed up the build, the benefits are + limited due to the compiler using + <filename>-pipe</filename>. + The build system goes to some lengths to avoid + <filename>sync()</filename> calls into the + file system on the principle that if there was a significant + failure, the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + contents could easily be rebuilt. + </para></listitem> + <listitem><para> + Inheriting the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink> + class: + Inheriting this class has shown to speed up builds due to + significantly lower amounts of data stored in the data + cache as well as on disk. + Inheriting this class also makes cleanup of + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> + faster, at the expense of being easily able to dive into the + source code. + File system maintainers have recommended that the fastest way + to clean up large numbers of files is to reformat partitions + rather than delete files due to the linear nature of + partitions. + This, of course, assumes you structure the disk partitions and + file systems in a way that this is practical. </para></listitem> </itemizedlist> + Aside from the previous list, you should keep some trade offs in + mind that can help you speed up the build: + <itemizedlist> + <listitem><para> + Remove items from + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> + that you might not need. + </para></listitem> + <listitem><para> + Exclude debug symbols and other debug information: + If you do not need these symbols and other debug information, + disabling the <filename>*-dbg</filename> package generation + can speed up the build. + You can disable this generation by setting the + <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></ulink> + variable to "1". + </para></listitem> + <listitem><para> + Disable static library generation for recipes derived from + <filename>autoconf</filename> or <filename>libtool</filename>: + Following is an example showing how to disable static + libraries and still provide an override to handle exceptions: + <literallayout class='monospaced'> + STATICLIBCONF = "--disable-static" + STATICLIBCONF_sqlite3-native = "" + EXTRA_OECONF += "${STATICLIBCONF}" + </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Some recipes need static libraries in order to work + correctly (e.g. <filename>pseudo-native</filename> + needs <filename>sqlite3-native</filename>). + Overrides, as in the previous example, account for + these kinds of exceptions. + </para></listitem> + <listitem><para> + Some packages have packaging code that assumes the + presence of the static libraries. + If so, you might need to exclude them as well. + </para></listitem> + </itemizedlist> + </note> + </para></listitem> + </itemizedlist> </para> </section> @@ -5929,8 +7164,7 @@ variable. </para></listitem> <listitem><para> - Set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink> + Set the <filename>EXTERNAL_TOOLCHAIN</filename> variable in your <filename>local.conf</filename> file to the location in which you installed the toolchain. </para></listitem> @@ -5980,7 +7214,7 @@ system. <note> For a kickstart file reference, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#openembedded-kickstart-wks-reference'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</ulink>" + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</ulink>" Chapter in the Yocto Project Reference Manual. </note> </para> @@ -6034,7 +7268,7 @@ Wic is a completely independent standalone utility that initially provides easier-to-use and more flexible replacements for an - existing functionality in OE Core's + existing functionality in OE-Core's <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink> class and <filename>mkefidisk.sh</filename> script. The difference between @@ -6346,7 +7580,7 @@ can use an existing file provided by the Wic installation. As shipped, kickstart files can be found in the Yocto Project - <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink> + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> in the following two locations: <literallayout class='monospaced'> poky/meta-yocto-bsp/wic @@ -6615,11 +7849,9 @@ <section id='generate-an-image-using-a-provided-kickstart-file'> <title>Generate an Image using an Existing Kickstart File</title> - <para role='writernotes'> + <para> This example runs in Cooked Mode and uses the <filename>mkefidisk</filename> kickstart file: - [OUTPUT IS WRONG DUE TO A BUG - ROOTFS_DIR AND BOOTIMG_DIR - ARE DISPLAYING TEMPORARY FILES THAT WIC CLEANS UP BY DELETING] <literallayout class='monospaced'> $ wic create mkefidisk -e core-image-minimal INFO: Building wic-tools... @@ -6627,16 +7859,16 @@ . . INFO: The new image(s) can be found here: - ./mkefidisk-201802211426-sda.direct + ./mkefidisk-201804191017-sda.direct The following build artifacts were used to create the image(s): - ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.zjs_iw41/rootfs_copy - BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share - KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86 - NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native + ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share + KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 + NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native INFO: The image(s) were created using OE kickstart file: - /home/scottrif/poky/scripts/lib/wic/canned-wks/mkefidisk.wks + /home/stephano/build/master/openembedded-core/scripts/lib/wic/canned-wks/mkefidisk.wks </literallayout> The previous example shows the easiest way to create an image by running in cooked mode and supplying @@ -6668,11 +7900,11 @@ <filename>bmaptool</filename> or <filename>dd</filename>: <literallayout class='monospaced'> - $ oe-run-native bmaptool copy mkefidisk-201802211426-sda.direct /dev/sd<replaceable>X</replaceable> + $ oe-run-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sd<replaceable>X</replaceable> </literallayout> or <literallayout class='monospaced'> - $ sudo dd if=mkefidisk-201802211426-sda.direct of=/dev/sd<replaceable>X</replaceable> + $ sudo dd if=mkefidisk-201804191017-sda.direct of=/dev/sd<replaceable>X</replaceable> </literallayout> <note> For more information on how to use the @@ -6732,8 +7964,8 @@ directory and then by changing the lines that specify the target disk from which to boot. <literallayout class='monospaced'> - $ cp /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \ - /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks + $ cp /home/stephano/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \ + /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks </literallayout> Next, the example modifies the <filename>directdisksdb-gpt.wks</filename> file and @@ -6769,13 +8001,13 @@ ./directdisksdb-gpt-201710090938-sdb.direct The following build artifacts were used to create the image(s): - ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.hk3wl6zn/rootfs_copy - BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share - KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86 - NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native + ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share + KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 + NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native INFO: The image(s) were created using OE kickstart file: - /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks + /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks </literallayout> Continuing with the example, you can now directly <filename>dd</filename> the image to a USB stick, or @@ -6802,25 +8034,25 @@ somewhere other than the default output directory, which is the current directory: <literallayout class='monospaced'> - $ wic create /home/scottrif/my_yocto/test.wks -o /home/scottrif/testwic \ - --rootfs-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \ - --bootimg-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \ - --kernel-dir /home/scottrif/poky/build/tmp/deploy/images/qemux86 \ - --native-sysroot /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native + $ wic create /home/stephano/my_yocto/test.wks -o /home/stephano/testwic \ + --rootfs-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \ + --bootimg-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \ + --kernel-dir /home/stephano/build/master/build/tmp/deploy/images/qemux86 \ + --native-sysroot /home/stephano/build/master/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native INFO: Creating image(s)... INFO: The new image(s) can be found here: - /home/scottrif/testwic/test-201710091445-sdb.direct + /home/stephano/testwic/test-201710091445-sdb.direct The following build artifacts were used to create the image(s): - ROOTFS_DIR: /home/scottrif/testwic/tmp.wic.x4wipbmb/rootfs_copy - BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share - KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86 - NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native + ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share + KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 + NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native INFO: The image(s) were created using OE kickstart file: - /home/scottrif/my_yocto/test.wks + /home/stephano/my_yocto/test.wks </literallayout> For this example, <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> @@ -6965,145 +8197,6 @@ </section> </section> - <section id='building-an-initramfs-image'> - <title>Building an Initial RAM Filesystem (initramfs) Image</title> - - <para> - An initial RAM filesystem (initramfs) image provides a temporary - root filesystem used for early system initialization (e.g. - loading of modules needed to locate and mount the "real" root - filesystem). - <note> - The initramfs image is the successor of initial RAM disk - (initrd). - It is a "copy in and out" (cpio) archive of the initial - filesystem that gets loaded into memory during the Linux - startup process. - Because Linux uses the contents of the archive during - initialization, the initramfs image needs to contain all of the - device drivers and tools needed to mount the final root - filesystem. - </note> - </para> - - <para> - Follow these steps to create an initramfs image: - <orderedlist> - <listitem><para> - <emphasis>Create the initramfs Image Recipe:</emphasis> - You can reference the - <filename>core-image-minimal-initramfs.bb</filename> - recipe found in the <filename>meta/recipes-core</filename> - directory of the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - as an example from which to work. - </para></listitem> - <listitem><para> - <emphasis>Decide if You Need to Bundle the initramfs Image - Into the Kernel Image:</emphasis> - If you want the initramfs image that is built to be - bundled in with the kernel image, set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink> - variable to "1" in your <filename>local.conf</filename> - configuration file and set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink> - variable in the recipe that builds the kernel image. - <note><title>Tip</title> - It is recommended that you do bundle the initramfs - image with the kernel image to avoid circular - dependencies between the kernel recipe and the - initramfs recipe should the initramfs image - include kernel modules. - </note> - Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename> - flag causes the initramfs image to be unpacked - into the <filename>${B}/usr/</filename> directory. - The unpacked initramfs image is then passed to the kernel's - <filename>Makefile</filename> using the - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink> - variable, allowing the initramfs image to be built into - the kernel normally. - <note> - If you choose to not bundle the initramfs image with - the kernel image, you are essentially using an - <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>. - Creating an initrd is handled primarily through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>, - <filename>INITRD_LIVE</filename>, and - <filename>INITRD_IMAGE_LIVE</filename> variables. - For more information, see the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink> - file. - </note> - </para></listitem> -<!-- -Some notes from Cal: - - A non-bundled initramfs is essentially an initrd, which I am discovering - to be rather confusingly supported in OE at the moment. - - Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM) - variables. INITRD_IMAGE* is the primary image target, which gets added to - INITRD*, which is a list of cpio filesystems. You can add more cpio - filesystems to the INITRD variable to add more to the initrd. For - instance, meta-intel adds intel-microcode via the following: - - INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}" - - If 'intel-ucode' is in MACHINE_FEATURES, this resolves to: - - INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio " - - Unfortunately you need the full path, and its up to you to sort out - dependencies as well. For instance, we have the following: - - MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}" - - which resolves to: - - MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode" - - However, the above is only true with the "live" IMAGE_FSTYPE. Wic is - another beast entirely, with current wic kickstart files not supporting - initrds, and only partial support in the source plugins. That being said, - I know the generic bootfs work Ed is working on will help immensely in this - aspect. He or Saul can provide more details here. - - Anyhow, its rather fractured and confusing and could probably use a - rework honestly. I don't know how feasible it is to document all the - details and corner cases of this area. ---> - <listitem><para> - <emphasis>Optionally Add Items to the initramfs Image - Through the initramfs Image Recipe:</emphasis> - If you add items to the initramfs image by way of its - recipe, you should use - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink> - rather than - <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>. - <filename>PACKAGE_INSTALL</filename> gives more direct - control of what is added to the image as compared to - the defaults you might not necessarily want that are - set by the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink> - classes. - </para></listitem> - <listitem><para> - <emphasis>Build the Kernel Image and the initramfs - Image:</emphasis> - Build your kernel image using BitBake. - Because the initramfs image recipe is a dependency of the - kernel image, the initramfs image is built as well and - bundled with the kernel image if you used the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink> - variable described earlier. - </para></listitem> - </orderedlist> - </para> - </section> - <section id='flashing-images-using-bmaptool'> <title>Flashing Images Using <filename>bmaptool</filename></title> @@ -7217,7 +8310,7 @@ Some notes from Cal: by Bruce Schneier </para></listitem> <listitem><para><emphasis> - "<ulink url='http://internetcensus2012.bitbucket.org/paper.html'>Internet Census 2012</ulink>"</emphasis> + "<ulink url='http://census2012.sourceforge.net/paper.html'>Internet Census 2012</ulink>"</emphasis> by Carna Botnet</para></listitem> <listitem><para><emphasis> "<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis> @@ -7425,7 +8518,7 @@ Some notes from Cal: more secure. You can find these tools in the <filename>meta-security</filename> layer of the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. + <ulink url='&YOCTO_GIT_URL;'>Yocto Project Source Repositories</ulink>. </para> </section> </section> @@ -7673,616 +8766,22 @@ Some notes from Cal: </para> </section> - <section id='building-a-tiny-system'> - <title>Building a Tiny System</title> + <section id='dev-saving-memory-during-a-build'> + <title>Conserving Disk Space During Builds</title> <para> - Very small distributions have some significant advantages such - as requiring less on-die or in-package memory (cheaper), better - performance through efficient cache usage, lower power requirements - due to less memory, faster boot times, and reduced development - overhead. - Some real-world examples where a very small distribution gives - you distinct advantages are digital cameras, medical devices, - and small headless systems. - </para> - - <para> - This section presents information that shows you how you can - trim your distribution to even smaller sizes than the - <filename>poky-tiny</filename> distribution, which is around - 5 Mbytes, that can be built out-of-the-box using the Yocto Project. - </para> - - <section id='tiny-system-overview'> - <title>Overview</title> - - <para> - The following list presents the overall steps you need to - consider and perform to create distributions with smaller - root filesystems, achieve faster boot times, maintain your critical - functionality, and avoid initial RAM disks: - <itemizedlist> - <listitem><para> - <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link> - </para></listitem> - <listitem><para> - <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link> - </para></listitem> - <listitem><para> - <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link> - </para></listitem> - <listitem><para> - <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link> - </para></listitem> - <listitem><para> - <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link> - </para></listitem> - <listitem><para> - <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link> - </para></listitem> - <listitem><para> - <link linkend='iterate-on-the-process'>Iterate on the process.</link> - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='goals-and-guiding-principles'> - <title>Goals and Guiding Principles</title> - - <para> - Before you can reach your destination, you need to know - where you are going. - Here is an example list that you can use as a guide when - creating very small distributions: - <itemizedlist> - <listitem><para>Determine how much space you need - (e.g. a kernel that is 1 Mbyte or less and - a root filesystem that is 3 Mbytes or less). - </para></listitem> - <listitem><para>Find the areas that are currently - taking 90% of the space and concentrate on reducing - those areas. - </para></listitem> - <listitem><para>Do not create any difficult "hacks" - to achieve your goals.</para></listitem> - <listitem><para>Leverage the device-specific - options.</para></listitem> - <listitem><para>Work in a separate layer so that you - keep changes isolated. - For information on how to create layers, see - the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='understand-what-gives-your-image-size'> - <title>Understand What Contributes to Your Image Size</title> - - <para> - It is easiest to have something to start with when creating - your own distribution. - You can use the Yocto Project out-of-the-box to create the - <filename>poky-tiny</filename> distribution. - Ultimately, you will want to make changes in your own - distribution that are likely modeled after - <filename>poky-tiny</filename>. - <note> - To use <filename>poky-tiny</filename> in your build, - set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> - variable in your - <filename>local.conf</filename> file to "poky-tiny" - as described in the - "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>" - section. - </note> - </para> - - <para> - Understanding some memory concepts will help you reduce the - system size. - Memory consists of static, dynamic, and temporary memory. - Static memory is the TEXT (code), DATA (initialized data - in the code), and BSS (uninitialized data) sections. - Dynamic memory represents memory that is allocated at runtime: - stacks, hash tables, and so forth. - Temporary memory is recovered after the boot process. - This memory consists of memory used for decompressing - the kernel and for the <filename>__init__</filename> - functions. - </para> - - <para> - To help you see where you currently are with kernel and root - filesystem sizes, you can use two tools found in the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> in - the <filename>scripts/tiny/</filename> directory: - <itemizedlist> - <listitem><para><filename>ksize.py</filename>: Reports - component sizes for the kernel build objects. - </para></listitem> - <listitem><para><filename>dirsize.py</filename>: Reports - component sizes for the root filesystem.</para></listitem> - </itemizedlist> - This next tool and command help you organize configuration - fragments and view file dependencies in a human-readable form: - <itemizedlist> - <listitem><para><filename>merge_config.sh</filename>: - Helps you manage configuration files and fragments - within the kernel. - With this tool, you can merge individual configuration - fragments together. - The tool allows you to make overrides and warns you - of any missing configuration options. - The tool is ideal for allowing you to iterate on - configurations, create minimal configurations, and - create configuration files for different machines - without having to duplicate your process.</para> - <para>The <filename>merge_config.sh</filename> script is - part of the Linux Yocto kernel Git repositories - (i.e. <filename>linux-yocto-3.14</filename>, - <filename>linux-yocto-3.10</filename>, - <filename>linux-yocto-3.8</filename>, and so forth) - in the - <filename>scripts/kconfig</filename> directory.</para> - <para>For more information on configuration fragments, - see the - "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>" - section in the Yocto Project Linux Kernel Development - Manual. - </para></listitem> - <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>: - Using the BitBake command with these options brings up - a Dependency Explorer from which you can view file - dependencies. - Understanding these dependencies allows you to make - informed decisions when cutting out various pieces of the - kernel and root filesystem.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='trim-the-root-filesystem'> - <title>Trim the Root Filesystem</title> - - <para> - The root filesystem is made up of packages for booting, - libraries, and applications. - To change things, you can configure how the packaging happens, - which changes the way you build them. - You can also modify the filesystem itself or select a different - filesystem. - </para> - - <para> - First, find out what is hogging your root filesystem by running the - <filename>dirsize.py</filename> script from your root directory: - <literallayout class='monospaced'> - $ cd <replaceable>root-directory-of-image</replaceable> - $ dirsize.py 100000 > dirsize-100k.log - $ cat dirsize-100k.log - </literallayout> - You can apply a filter to the script to ignore files under - a certain size. - The previous example filters out any files below 100 Kbytes. - The sizes reported by the tool are uncompressed, and thus - will be smaller by a relatively constant factor in a - compressed root filesystem. - When you examine your log file, you can focus on areas of the - root filesystem that take up large amounts of memory. - </para> - - <para> - You need to be sure that what you eliminate does not cripple - the functionality you need. - One way to see how packages relate to each other is by using - the Dependency Explorer UI with the BitBake command: - <literallayout class='monospaced'> - $ cd <replaceable>image-directory</replaceable> - $ bitbake -u taskexp -g <replaceable>image</replaceable> - </literallayout> - Use the interface to select potential packages you wish to - eliminate and see their dependency relationships. - </para> - - <para> - When deciding how to reduce the size, get rid of packages that - result in minimal impact on the feature set. - For example, you might not need a VGA display. - Or, you might be able to get by with <filename>devtmpfs</filename> - and <filename>mdev</filename> instead of - <filename>udev</filename>. - </para> - - <para> - Use your <filename>local.conf</filename> file to make changes. - For example, to eliminate <filename>udev</filename> and - <filename>glib</filename>, set the following in the - local configuration file: - <literallayout class='monospaced'> - VIRTUAL-RUNTIME_dev_manager = "" - </literallayout> - </para> - - <para> - Finally, you should consider exactly the type of root - filesystem you need to meet your needs while also reducing - its size. - For example, consider <filename>cramfs</filename>, - <filename>squashfs</filename>, <filename>ubifs</filename>, - <filename>ext2</filename>, or an <filename>initramfs</filename> - using <filename>initramfs</filename>. - Be aware that <filename>ext3</filename> requires a 1 Mbyte - journal. - If you are okay with running read-only, you do not need this - journal. - </para> - - <note> - After each round of elimination, you need to rebuild your - system and then use the tools to see the effects of your - reductions. - </note> - - - </section> - - <section id='trim-the-kernel'> - <title>Trim the Kernel</title> - - <para> - The kernel is built by including policies for hardware-independent - aspects. - What subsystems do you enable? - For what architecture are you building? - Which drivers do you build by default? - <note>You can modify the kernel source if you want to help - with boot time. - </note> - </para> - - <para> - Run the <filename>ksize.py</filename> script from the top-level - Linux build directory to get an idea of what is making up - the kernel: - <literallayout class='monospaced'> - $ cd <replaceable>top-level-linux-build-directory</replaceable> - $ ksize.py > ksize.log - $ cat ksize.log - </literallayout> - When you examine the log, you will see how much space is - taken up with the built-in <filename>.o</filename> files for - drivers, networking, core kernel files, filesystem, sound, - and so forth. - The sizes reported by the tool are uncompressed, and thus - will be smaller by a relatively constant factor in a compressed - kernel image. - Look to reduce the areas that are large and taking up around - the "90% rule." - </para> - - <para> - To examine, or drill down, into any particular area, use the - <filename>-d</filename> option with the script: - <literallayout class='monospaced'> - $ ksize.py -d > ksize.log - </literallayout> - Using this option breaks out the individual file information - for each area of the kernel (e.g. drivers, networking, and - so forth). - </para> - - <para> - Use your log file to see what you can eliminate from the kernel - based on features you can let go. - For example, if you are not going to need sound, you do not - need any drivers that support sound. - </para> - - <para> - After figuring out what to eliminate, you need to reconfigure - the kernel to reflect those changes during the next build. - You could run <filename>menuconfig</filename> and make all your - changes at once. - However, that makes it difficult to see the effects of your - individual eliminations and also makes it difficult to replicate - the changes for perhaps another target device. - A better method is to start with no configurations using - <filename>allnoconfig</filename>, create configuration - fragments for individual changes, and then manage the - fragments into a single configuration file using - <filename>merge_config.sh</filename>. - The tool makes it easy for you to iterate using the - configuration change and build cycle. - </para> - - <para> - Each time you make configuration changes, you need to rebuild - the kernel and check to see what impact your changes had on - the overall size. - </para> - </section> - - <section id='remove-package-management-requirements'> - <title>Remove Package Management Requirements</title> - - <para> - Packaging requirements add size to the image. - One way to reduce the size of the image is to remove all the - packaging requirements from the image. - This reduction includes both removing the package manager - and its unique dependencies as well as removing the package - management data itself. - </para> - - <para> - To eliminate all the packaging requirements for an image, - be sure that "package-management" is not part of your - <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> - statement for the image. - When you remove this feature, you are removing the package - manager as well as its dependencies from the root filesystem. - </para> - </section> - - <section id='look-for-other-ways-to-minimize-size'> - <title>Look for Other Ways to Minimize Size</title> - - <para> - Depending on your particular circumstances, other areas that you - can trim likely exist. - The key to finding these areas is through tools and methods - described here combined with experimentation and iteration. - Here are a couple of areas to experiment with: - <itemizedlist> - <listitem><para><filename>glibc</filename>: - In general, follow this process: - <orderedlist> - <listitem><para>Remove <filename>glibc</filename> - features from - <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> - that you think you do not need.</para></listitem> - <listitem><para>Build your distribution. - </para></listitem> - <listitem><para>If the build fails due to missing - symbols in a package, determine if you can - reconfigure the package to not need those - features. - For example, change the configuration to not - support wide character support as is done for - <filename>ncurses</filename>. - Or, if support for those characters is needed, - determine what <filename>glibc</filename> - features provide the support and restore the - configuration. - </para></listitem> - <listitem><para>Rebuild and repeat the process. - </para></listitem> - </orderedlist></para></listitem> - <listitem><para><filename>busybox</filename>: - For BusyBox, use a process similar as described for - <filename>glibc</filename>. - A difference is you will need to boot the resulting - system to see if you are able to do everything you - expect from the running system. - You need to be sure to integrate configuration fragments - into Busybox because BusyBox handles its own core - features and then allows you to add configuration - fragments on top. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='iterate-on-the-process'> - <title>Iterate on the Process</title> - - <para> - If you have not reached your goals on system size, you need - to iterate on the process. - The process is the same. - Use the tools and see just what is taking up 90% of the root - filesystem and the kernel. - Decide what you can eliminate without limiting your device - beyond what you need. - </para> - - <para> - Depending on your system, a good place to look might be - Busybox, which provides a stripped down - version of Unix tools in a single, executable file. - You might be able to drop virtual terminal services or perhaps - ipv6. - </para> - </section> - </section> - - <section id='building-images-for-more-than-one-machine'> - <title>Building Images for More than One Machine</title> - - <para> - A common scenario developers face is creating images for several - different machines that use the same software environment. - In this situation, it is tempting to set the - tunings and optimization flags for each build specifically for - the targeted hardware (i.e. "maxing out" the tunings). - Doing so can considerably add to build times and package feed - maintenance collectively for the machines. - For example, selecting tunes that are extremely specific to a - CPU core used in a system might enable some micro optimizations - in GCC for that particular system but would otherwise not gain - you much of a performance difference across the other systems - as compared to using a more general tuning across all the builds - (e.g. setting - <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink> - specifically for each machine's build). - Rather than "max out" each build's tunings, you can take steps that - cause the OpenEmbedded build system to reuse software across the - various machines where it makes sense. - </para> - <para> - If build speed and package feed maintenance are considerations, - you should consider the points in this section that can help you - optimize your tunings to best consider build times and package - feed maintenance. - <itemizedlist> - <listitem><para><emphasis>Share the Build Directory:</emphasis> - If at all possible, share the - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> - across builds. - The Yocto Project supports switching between different - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - values in the same <filename>TMPDIR</filename>. - This practice is well supported and regularly used by - developers when building for multiple machines. - When you use the same <filename>TMPDIR</filename> for - multiple machine builds, the OpenEmbedded build system can - reuse the existing native and often cross-recipes for - multiple machines. - Thus, build time decreases. - <note> - If - <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> - settings change or fundamental configuration settings - such as the filesystem layout, you need to work with - a clean <filename>TMPDIR</filename>. - Sharing <filename>TMPDIR</filename> under these - circumstances might work but since it is not - guaranteed, you should use a clean - <filename>TMPDIR</filename>. - </note> - </para></listitem> - <listitem><para><emphasis>Enable the Appropriate Package Architecture:</emphasis> - By default, the OpenEmbedded build system enables three - levels of package architectures: "all", "tune" or "package", - and "machine". - Any given recipe usually selects one of these package - architectures (types) for its output. - Depending for what a given recipe creates packages, making - sure you enable the appropriate package architecture can - directly impact the build time.</para> - <para>A recipe that just generates scripts can enable - "all" architecture because there are no binaries to build. - To specifically enable "all" architecture, be sure your - recipe inherits the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink> - class. - This class is useful for "all" architectures because it - configures many variables so packages can be used across - multiple architectures.</para> - <para>If your recipe needs to generate packages that are - machine-specific or when one of the build or runtime - dependencies is already machine-architecture dependent, - which makes your recipe also machine-architecture dependent, - make sure your recipe enables the "machine" package - architecture through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink> - variable: - <literallayout class='monospaced'> - PACKAGE_ARCH = "${MACHINE_ARCH}" - </literallayout> - When you do not specifically enable a package - architecture through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>, - The OpenEmbedded build system defaults to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink> - setting: - <literallayout class='monospaced'> - PACKAGE_ARCH = "${TUNE_PKGARCH}" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Choose a Generic Tuning File if Possible:</emphasis> - Some tunes are more generic and can run on multiple targets - (e.g. an <filename>armv5</filename> set of packages could - run on <filename>armv6</filename> and - <filename>armv7</filename> processors in most cases). - Similarly, <filename>i486</filename> binaries could work - on <filename>i586</filename> and higher processors. - You should realize, however, that advances on newer - processor versions would not be used.</para> - <para>If you select the same tune for several different - machines, the OpenEmbedded build system reuses software - previously built, thus speeding up the overall build time. - Realize that even though a new sysroot for each machine is - generated, the software is not recompiled and only one - package feed exists. - </para></listitem> - <listitem><para><emphasis>Manage Granular Level Packaging:</emphasis> - Sometimes cases exist where injecting another level - of package architecture beyond the three higher levels - noted earlier can be useful. - For example, consider the <filename>emgd</filename> - graphics stack in the - <filename>meta-intel</filename> layer. - In this layer, a subset of software exists that is - compiled against something different from the rest of the - generic packages. - You can examine the key code in the - <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink> - "daisy" branch in - <filename>classes/emgd-gl.bbclass</filename>. - For a specific set of packages, the code redefines - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>. - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXTRA_ARCHS'><filename>PACKAGE_EXTRA_ARCHS</filename></ulink> - is then appended with this extra tune name in - <filename>meta-intel-emgd.inc</filename>. - The result is that when searching for packages, the - build system uses a four-level search and the packages - in this new level are preferred as compared to the standard - tune. - The overall result is that the build system reuses most - software from the common tune except for specific cases - as needed. - </para></listitem> - <listitem><para><emphasis>Use Tools to Debug Issues:</emphasis> - Sometimes you can run into situations where software is - being rebuilt when you think it should not be. - For example, the OpenEmbedded build system might not be - using shared state between machines when you think it - should be. - These types of situations are usually due to references - to machine-specific variables such as - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>, - and so forth in code that is supposed to only be - tune-specific or when the recipe depends - (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>, - and so forth) on some other recipe that already has - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> - defined as "${MACHINE_ARCH}". - <note> - Patches to fix any issues identified are most welcome - as these issues occasionally do occur. - </note></para> - <para>For such cases, you can use some tools to help you - sort out the situation: - <itemizedlist> - <listitem><para><emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis> - You can find this tool in the - <filename>scripts</filename> directory of the - Source Repositories. - See the comments in the script for information on - how to use the tool. - </para></listitem> - <listitem><para><emphasis>BitBake's "-S printdiff" Option:</emphasis> - Using this option causes BitBake to try to - establish the closest signature match it can - (e.g. in the shared state cache) and then run - <filename>bitbake-diffsigs</filename> over the - matches to determine the stamps and delta where - these two stamp trees diverge. - </para></listitem> - </itemizedlist> - </para></listitem> - </itemizedlist> + To help conserve disk space during builds, you can add the + following statement to your project's + <filename>local.conf</filename> configuration file found in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: + <literallayout class='monospaced'> + INHERIT += "rm_work" + </literallayout> + Adding this statement deletes the work directory used for building + a recipe once the recipe is built. + For more information on "rm_work", see the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink> + class in the Yocto Project Reference Manual. </para> </section> @@ -8486,7 +8985,7 @@ Some notes from Cal: <para> Because the OpenEmbedded build system uses - "<ulink url='&YOCTO_DOCS_CM_URL;#overview-checksums'>signatures</ulink>", + "<ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>signatures</ulink>", which are unique to a given build, the build system knows when to rebuild packages. All the inputs into a given task are represented by a @@ -8590,8 +9089,9 @@ Some notes from Cal: <para> For more information on shared state, see the - "<ulink url='&YOCTO_DOCS_CM_URL;#shared-state-cache'>Shared State Cache</ulink>" - section in the Yocto Project Concepts Manual. + "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>Shared State Cache</ulink>" + section in the Yocto Project Overview and Concepts + Manual. </para> </note> </section> @@ -8835,7 +9335,7 @@ Some notes from Cal: <filename>connman.inc</filename> file in the <filename>meta/recipes-connectivity/connman/</filename> directory of the <filename>poky</filename> - <ulink url='&YOCTO_DOCS_GS_URL;#yocto-project-repositories'>source repository</ulink>. + <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>source repository</ulink>. You can also find examples in <filename>meta/classes/kernel.bbclass</filename>. </para> @@ -9833,81 +10333,6 @@ Some notes from Cal: </section> </section> - <section id="building-software-from-an-external-source"> - <title>Building Software from an External Source</title> - - <para> - By default, the OpenEmbedded build system uses the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - when building source code. - The build process involves fetching the source files, unpacking - them, and then patching them if necessary before the build takes - place. - </para> - - <para> - Situations exist where you might want to build software from source - files that are external to and thus outside of the - OpenEmbedded build system. - For example, suppose you have a project that includes a new BSP with - a heavily customized kernel. - And, you want to minimize exposing the build system to the - development team so that they can focus on their project and - maintain everyone's workflow as much as possible. - In this case, you want a kernel source directory on the development - machine where the development occurs. - You want the recipe's - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable to point to the external directory and use it as is, not - copy it. - </para> - - <para> - To build from software that comes from an external source, all you - need to do is inherit the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink> - class and then set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink> - variable to point to your external source code. - Here are the statements to put in your - <filename>local.conf</filename> file: - <literallayout class='monospaced'> - INHERIT += "externalsrc" - EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>" - </literallayout> - </para> - - <para> - This next example shows how to accomplish the same thing by setting - <filename>EXTERNALSRC</filename> in the recipe itself or in the - recipe's append file: - <literallayout class='monospaced'> - EXTERNALSRC = "<replaceable>path</replaceable>" - EXTERNALSRC_BUILD = "<replaceable>path</replaceable>" - </literallayout> - <note> - In order for these settings to take effect, you must globally - or locally inherit the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink> - class. - </note> - </para> - - <para> - By default, <filename>externalsrc.bbclass</filename> builds - the source code in a directory separate from the external source - directory as specified by - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>. - If you need to have the source built in the same directory in - which it resides, or some other nominated directory, you can set - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink> - to point to that directory: - <literallayout class='monospaced'> - EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>" - </literallayout> - </para> - </section> - <section id="selecting-an-initialization-manager"> <title>Selecting an Initialization Manager</title> @@ -10378,7 +10803,7 @@ Some notes from Cal: Enabling build history as previously described causes the OpenEmbedded build system to collect build output information and commit it as a single commit to a local - <ulink url='&YOCTO_DOCS_GS_URL;#git'>Git</ulink> + <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> repository. <note> Enabling build history increases your build times slightly, @@ -10928,6 +11353,25 @@ Some notes from Cal: which should generate a list of tap devices. This is the option typically chosen for Autobuilder-type environments. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Be sure to use an absolute path + when calling this script + with sudo. + </para></listitem> + <listitem><para> + The package recipe + <filename>qemu-helper-native</filename> + is required to run this script. + Build the package using the + following command: + <literallayout class='monospaced'> + $ bitbake qemu-helper-native + </literallayout> + </para></listitem> + </itemizedlist> + </note> </para></listitem> </itemizedlist></para></listitem> <listitem><para><emphasis>Set the @@ -11067,8 +11511,8 @@ Some notes from Cal: within a separately started QEMU or any other virtual machine manager. </para></listitem> - <listitem><para><emphasis>"Systemd-bootTarget":</emphasis> - Choose "Systemd-bootTarget" if your hardware is + <listitem><para><emphasis>"SystemdbootTarget":</emphasis> + Choose "SystemdbootTarget" if your hardware is an EFI-based machine with <filename>systemd-boot</filename> as bootloader and <filename>core-image-testmaster</filename> @@ -11076,10 +11520,10 @@ Some notes from Cal: Also, your hardware under test must be in a DHCP-enabled network that gives it the same IP address for each reboot.</para> - <para>If you choose "Systemd-bootTarget", there are + <para>If you choose "SystemdbootTarget", there are additional requirements and considerations. See the - "<link linkend='selecting-systemd-boottarget'>Selecting Systemd-bootTarget</link>" + "<link linkend='selecting-systemdboottarget'>Selecting SystemdbootTarget</link>" section, which follows, for more information. </para></listitem> <listitem><para><emphasis>"BeagleBoneTarget":</emphasis> @@ -11125,12 +11569,12 @@ Some notes from Cal: </para> </section> - <section id='selecting-systemd-boottarget'> - <title>Selecting Systemd-bootTarget</title> + <section id='selecting-systemdboottarget'> + <title>Selecting SystemdbootTarget</title> <para> If you did not set <filename>TEST_TARGET</filename> to - "Systemd-bootTarget", then you do not need any information + "SystemdbootTarget", then you do not need any information in this section. You can skip down to the "<link linkend='qemu-image-running-tests'>Running Tests</link>" @@ -11139,7 +11583,7 @@ Some notes from Cal: <para> If you did set <filename>TEST_TARGET</filename> to - "Systemd-bootTarget", you also need to perform a one-time + "SystemdbootTarget", you also need to perform a one-time setup of your master image by doing the following: <orderedlist> <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis> @@ -11210,7 +11654,7 @@ Some notes from Cal: <para> The final thing you need to do when setting - <filename>TEST_TARGET</filename> to "Systemd-bootTarget" is + <filename>TEST_TARGET</filename> to "SystemdbootTarget" is to set up the test image: <orderedlist> <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis> @@ -11219,7 +11663,7 @@ Some notes from Cal: <literallayout class='monospaced'> IMAGE_FSTYPES += "tar.gz" INHERIT += "testimage" - TEST_TARGET = "Systemd-bootTarget" + TEST_TARGET = "SystemdbootTarget" TEST_TARGET_IP = "192.168.2.3" </literallayout> </para></listitem> @@ -11636,7 +12080,7 @@ Some notes from Cal: The target controller object used to deploy and start an image on a particular target (e.g. QemuTarget, SimpleRemote, and - Systemd-bootTarget). + SystemdbootTarget). Tests usually use the following: <itemizedlist> <listitem><para><emphasis><filename>ip</filename>:</emphasis> @@ -12240,7 +12684,7 @@ Some notes from Cal: ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 </literallayout> For tasks that are accelerated through the shared state - (<ulink url='&YOCTO_DOCS_CM_URL;#shared-state-cache'>sstate</ulink>) + (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>) cache, an additional <filename>siginfo</filename> file is written into <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink> @@ -12312,6 +12756,98 @@ Some notes from Cal: </para> </section> + <section id='dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'> + <title>Viewing Metadata Used to Create the Input Signature of a Shared State Task</title> + + <para> + Seeing what metadata went into creating the input signature + of a shared state (sstate) task can be a useful debugging + aid. + This information is available in signature information + (<filename>siginfo</filename>) files in + <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>. + For information on how to view and interpret information in + <filename>siginfo</filename> files, see the + "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>" + section. + </para> + + <para> + For conceptual information on shared state, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>Shared State</ulink>" + section in the Yocto Project Overview and Concepts Manual. + </para> + </section> + + <section id='dev-invalidating-shared-state-to-force-a-task-to-run'> + <title>Invalidating Shared State to Force a Task to Run</title> + + <para> + The OpenEmbedded build system uses + <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>checksums</ulink> + and + <ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>shared state</ulink> + cache to avoid unnecessarily rebuilding tasks. + Collectively, this scheme is known as "shared state code." + </para> + + <para> + As with all schemes, this one has some drawbacks. + It is possible that you could make implicit changes to your + code that the checksum calculations do not take into + account. + These implicit changes affect a task's output but do not + trigger the shared state code into rebuilding a recipe. + Consider an example during which a tool changes its output. + Assume that the output of <filename>rpmdeps</filename> + changes. + The result of the change should be that all the + <filename>package</filename> and + <filename>package_write_rpm</filename> shared state cache + items become invalid. + However, because the change to the output is + external to the code and therefore implicit, + the associated shared state cache items do not become + invalidated. + In this case, the build process uses the cached items + rather than running the task again. + Obviously, these types of implicit changes can cause + problems. + </para> + + <para> + To avoid these problems during the build, you need to + understand the effects of any changes you make. + Realize that changes you make directly to a function + are automatically factored into the checksum calculation. + Thus, these explicit changes invalidate the associated + area of shared state cache. + However, you need to be aware of any implicit changes that + are not obvious changes to the code and could affect + the output of a given task. + </para> + + <para> + When you identify an implicit change, you can easily + take steps to invalidate the cache and force the tasks + to run. + The steps you can take are as simple as changing a + function's comments in the source code. + For example, to invalidate package shared state files, + change the comment statements of + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> + or the comments of one of the functions it calls. + Even though the change is purely cosmetic, it causes the + checksum to be recalculated and forces the build system to + run the task again. + <note> + For an example of a commit that makes a cosmetic + change to invalidate shared state, see this + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. + </note> + </para> + </section> + <section id='dev-debugging-taskrunning'> <title>Running Specific Tasks</title> @@ -12349,21 +12885,21 @@ Some notes from Cal: <filename>-c</filename>, BitBake will only run the task if it considers it "out of date". See the - "<ulink url='&YOCTO_DOCS_CM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>" - section in the Yocto Project Concepts Manual for + "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>" + section in the Yocto Project Overview and Concepts Manual for how BitBake determines whether a task is "out of date". </para> <para> If you want to force an up-to-date task to be rerun (e.g. because you made manual modifications to the recipe's - <ulink linkend='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> that you want to try out), then you can use the <filename>-f</filename> option. <note> The reason <filename>-f</filename> is never required when running the - <ulink linkend='&YOCTO_DOCS_REF_URL;#ref-tasks-devshell'><filename>do_devshell</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-devshell'><filename>do_devshell</filename></ulink> task is because the <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename> variable flag is already set for the task. @@ -13358,127 +13894,1142 @@ Some notes from Cal: </section> </section> - <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'> - <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title> + <section id='making-changes-to-the-yocto-project'> + <title>Making Changes to the Yocto Project</title> <para> - One of the concerns for a development organization using open source - software is how to maintain compliance with various open source - licensing during the lifecycle of the product. - While this section does not provide legal advice or - comprehensively cover all scenarios, it does - present methods that you can use to - assist you in meeting the compliance requirements during a software - release. + Because the Yocto Project is an open-source, community-based + project, you can effect changes to the project. + This section presents procedures that show you how to submit + a defect against the project and how to submit a change. </para> - <para> - With hundreds of different open source licenses that the Yocto - Project tracks, it is difficult to know the requirements of each - and every license. - However, the requirements of the major FLOSS licenses can begin - to be covered by - assuming that three main areas of concern exist: - <itemizedlist> - <listitem><para>Source code must be provided.</para></listitem> - <listitem><para>License text for the software must be - provided.</para></listitem> - <listitem><para>Compilation scripts and modifications to the - source code must be provided. - </para></listitem> - </itemizedlist> - There are other requirements beyond the scope of these - three and the methods described in this section - (e.g. the mechanism through which source code is distributed). - </para> + <section id='submitting-a-defect-against-the-yocto-project'> + <title>Submitting a Defect Against the Yocto Project</title> - <para> - As different organizations have different methods of complying with - open source licensing, this section is not meant to imply that - there is only one single way to meet your compliance obligations, - but rather to describe one method of achieving compliance. - The remainder of this section describes methods supported to meet the - previously mentioned three requirements. - Once you take steps to meet these requirements, - and prior to releasing images, sources, and the build system, - you should audit all artifacts to ensure completeness. - <note> - The Yocto Project generates a license manifest during - image creation that is located - in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename> - to assist with any audits. - </note> - </para> + <para> + Use the Yocto Project implementation of + <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> + to submit a defect (bug) against the Yocto Project. + For additional information on this implementation of Bugzilla see the + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>" + section in the Yocto Project Reference Manual. + For more detail on any of the following steps, see the Yocto Project + <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>. + </para> + + <para> + Use the following general steps to submit a bug" + + <orderedlist> + <listitem><para> + Open the Yocto Project implementation of + <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>. + </para></listitem> + <listitem><para> + Click "File a Bug" to enter a new bug. + </para></listitem> + <listitem><para> + Choose the appropriate "Classification", "Product", and + "Component" for which the bug was found. + Bugs for the Yocto Project fall into one of several + classifications, which in turn break down into several + products and components. + For example, for a bug against the + <filename>meta-intel</filename> layer, you would choose + "Build System, Metadata & Runtime", "BSPs", and + "bsps-meta-intel", respectively. + </para></listitem> + <listitem><para> + Choose the "Version" of the Yocto Project for which you found + the bug (e.g. &DISTRO;). + </para></listitem> + <listitem><para> + Determine and select the "Severity" of the bug. + The severity indicates how the bug impacted your work. + </para></listitem> + <listitem><para> + Choose the "Hardware" that the bug impacts. + </para></listitem> + <listitem><para> + Choose the "Architecture" that the bug impacts. + </para></listitem> + <listitem><para> + Choose a "Documentation change" item for the bug. + Fixing a bug might or might not affect the Yocto Project + documentation. + If you are unsure of the impact to the documentation, select + "Don't Know". + </para></listitem> + <listitem><para> + Provide a brief "Summary" of the bug. + Try to limit your summary to just a line or two and be sure + to capture the essence of the bug. + </para></listitem> + <listitem><para> + Provide a detailed "Description" of the bug. + You should provide as much detail as you can about the context, + behavior, output, and so forth that surrounds the bug. + You can even attach supporting files for output from logs by + using the "Add an attachment" button. + </para></listitem> + <listitem><para> + Click the "Submit Bug" button submit the bug. + A new Bugzilla number is assigned to the bug and the defect + is logged in the bug tracking system. + </para></listitem> + </orderedlist> + Once you file a bug, the bug is processed by the Yocto Project Bug + Triage Team and further details concerning the bug are assigned + (e.g. priority and owner). + You are the "Submitter" of the bug and any further categorization, + progress, or comments on the bug result in Bugzilla sending you an + automated email concerning the particular change or progress to the + bug. + </para> + </section> - <section id='providing-the-source-code'> - <title>Providing the Source Code</title> + <section id='how-to-submit-a-change'> + <title>Submitting a Change to the Yocto Project</title> <para> - Compliance activities should begin before you generate the - final image. - The first thing you should look at is the requirement that - tops the list for most compliance groups - providing - the source. - The Yocto Project has a few ways of meeting this - requirement. + Contributions to the Yocto Project and OpenEmbedded are very welcome. + Because the system is extremely configurable and flexible, we recognize + that developers will want to extend, configure or optimize it for + their specific uses. </para> <para> - One of the easiest ways to meet this requirement is - to provide the entire - <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> - used by the build. - This method, however, has a few issues. - The most obvious is the size of the directory since it includes - all sources used in the build and not just the source used in - the released image. - It will include toolchain source, and other artifacts, which - you would not generally release. - However, the more serious issue for most companies is accidental - release of proprietary software. - The Yocto Project provides an - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink> - class to help avoid some of these concerns. + The Yocto Project uses a mailing list and a patch-based workflow + that is similar to the Linux kernel but contains important + differences. + In general, a mailing list exists through which you can submit + patches. + You should send patches to the appropriate mailing list so that they + can be reviewed and merged by the appropriate maintainer. + The specific mailing list you need to use depends on the + location of the code you are changing. + Each component (e.g. layer) should have a + <filename>README</filename> file that indicates where to send + the changes and which process to follow. + </para> + + <para> + You can send the patch to the mailing list using whichever approach + you feel comfortable with to generate the patch. + Once sent, the patch is usually reviewed by the community at large. + If somebody has concerns with the patch, they will usually voice + their concern over the mailing list. + If a patch does not receive any negative reviews, the maintainer of + the affected layer typically takes the patch, tests it, and then + based on successful testing, merges the patch. + </para> + + <para id='figuring-out-the-mailing-list-to-use'> + The "poky" repository, which is the Yocto Project's reference build + environment, is a hybrid repository that contains several + individual pieces (e.g. BitBake, Metadata, documentation, + and so forth) built using the combo-layer tool. + The upstream location used for submitting changes varies by + component: + <itemizedlist> + <listitem><para> + <emphasis>Core Metadata:</emphasis> + Send your patch to the + <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink> + mailing list. For example, a change to anything under + the <filename>meta</filename> or + <filename>scripts</filename> directories should be sent + to this mailing list. + </para></listitem> + <listitem><para> + <emphasis>BitBake:</emphasis> + For changes to BitBake (i.e. anything under the + <filename>bitbake</filename> directory), send your patch + to the + <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink> + mailing list. + </para></listitem> + <listitem><para> + <emphasis>"meta-*" trees:</emphasis> + These trees contain Metadata. + Use the + <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink> + mailing list. + </para></listitem> + </itemizedlist> + </para> + + <para> + For changes to other layers hosted in the Yocto Project source + repositories (i.e. <filename>yoctoproject.org</filename>), tools, + and the Yocto Project documentation, use the + <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink> + general mailing list. + <note> + Sometimes a layer's documentation specifies to use a + particular mailing list. + If so, use that list. + </note> + For additional recipes that do not fit into the core Metadata, you + should determine which layer the recipe should go into and submit + the change in the manner recommended by the documentation (e.g. + the <filename>README</filename> file) supplied with the layer. + If in doubt, please ask on the Yocto general mailing list or on + the openembedded-devel mailing list. </para> <para> - Before you employ <filename>DL_DIR</filename> or the - <filename>archiver</filename> class, you need to decide how - you choose to provide source. - The source <filename>archiver</filename> class can generate - tarballs and SRPMs and can create them with various levels of - compliance in mind. + You can also push a change upstream and request a maintainer to + pull the change into the component's upstream repository. + You do this by pushing to a contribution repository that is upstream. + See the + "<ulink url='&YOCTO_DOCS_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>" + section in the Yocto Project Overview and Concepts Manual for additional + concepts on working in the Yocto Project development environment. </para> <para> - One way of doing this (but certainly not the only way) is to - release just the source as a tarball. - You can do this by adding the following to the - <filename>local.conf</filename> file found in the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: + Two commonly used testing repositories exist for + OpenEmbedded-Core: + <itemizedlist> + <listitem><para> + <emphasis>"ross/mut" branch:</emphasis> + The "mut" (master-under-test) tree + exists in the <filename>poky-contrib</filename> repository + in the + <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>. + </para></listitem> + <listitem><para> + <emphasis>"master-next" branch:</emphasis> + This branch is part of the main + "poky" repository in the Yocto Project source repositories. + </para></listitem> + </itemizedlist> + Maintainers use these branches to test submissions prior to merging + patches. + Thus, you can get an idea of the status of a patch based on + whether the patch has been merged into one of these branches. + <note> + This system is imperfect and changes can sometimes get lost in the + flow. + Asking about the status of a patch or change is reasonable if the + change has been idle for a while with no feedback. + The Yocto Project does have plans to use + <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink> + to track the status of patches and also to automatically preview + patches. + </note> + </para> + + <para> + The following sections provide procedures for submitting a change. + </para> + + <section id='pushing-a-change-upstream'> + <title>Using Scripts to Push a Change Upstream and Request a Pull</title> + + <para> + Follow this procedure to push a change to an upstream "contrib" + Git repository: + <note> + You can find general Git information on how to push a change + upstream in the + <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>. + </note> + <orderedlist> + <listitem><para> + <emphasis>Make Your Changes Locally:</emphasis> + Make your changes in your local Git repository. + You should make small, controlled, isolated changes. + Keeping changes small and isolated aids review, + makes merging/rebasing easier and keeps the change + history clean should anyone need to refer to it in + future. + </para></listitem> + <listitem><para> + <emphasis>Stage Your Changes:</emphasis> + Stage your changes by using the <filename>git add</filename> + command on each file you changed. + </para></listitem> + <listitem><para id='making-sure-you-have-correct-commit-information'> + <emphasis>Commit Your Changes:</emphasis> + Commit the change by using the + <filename>git commit</filename> command. + Make sure your commit information follows standards by + following these accepted conventions: + <itemizedlist> + <listitem><para> + Be sure to include a "Signed-off-by:" line in the + same style as required by the Linux kernel. + Adding this line signifies that you, the submitter, + have agreed to the Developer's Certificate of + Origin 1.1 as follows: + <literallayout class='monospaced'> + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + </literallayout> + </para></listitem> + <listitem><para> + Provide a single-line summary of the change. + and, + if more explanation is needed, provide more + detail in the body of the commit. + This summary is typically viewable in the + "shortlist" of changes. + Thus, providing something short and descriptive + that gives the reader a summary of the change is + useful when viewing a list of many commits. + You should prefix this short description with the + recipe name (if changing a recipe), or else with + the short form path to the file being changed. + </para></listitem> + <listitem><para> + For the body of the commit message, provide + detailed information that describes what you + changed, why you made the change, and the approach + you used. + It might also be helpful if you mention how you + tested the change. + Provide as much detail as you can in the body of + the commit message. + <note> + You do not need to provide a more detailed + explanation of a change if the change is + minor to the point of the single line + summary providing all the information. + </note> + </para></listitem> + <listitem><para> + If the change addresses a specific bug or issue + that is associated with a bug-tracking ID, + include a reference to that ID in your detailed + description. + For example, the Yocto Project uses a specific + convention for bug references - any commit that + addresses a specific bug should use the following + form for the detailed description. + Be sure to use the actual bug-tracking ID from + Bugzilla for + <replaceable>bug-id</replaceable>: + <literallayout class='monospaced'> + Fixes [YOCTO #<replaceable>bug-id</replaceable>] + + <replaceable>detailed description of change</replaceable> + </literallayout> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis> + If you have arranged for permissions to push to an + upstream contrib repository, push the change to that + repository: + <literallayout class='monospaced'> + $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable> + </literallayout> + For example, suppose you have permissions to push into the + upstream <filename>meta-intel-contrib</filename> + repository and you are working in a local branch named + <replaceable>your_name</replaceable><filename>/README</filename>. + The following command pushes your local commits to the + <filename>meta-intel-contrib</filename> upstream + repository and puts the commit in a branch named + <replaceable>your_name</replaceable><filename>/README</filename>: + <literallayout class='monospaced'> + $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README + </literallayout> + </para></listitem> + <listitem><para id='push-determine-who-to-notify'> + <emphasis>Determine Who to Notify:</emphasis> + Determine the maintainer or the mailing list + that you need to notify for the change.</para> + + <para>Before submitting any change, you need to be sure + who the maintainer is or what mailing list that you need + to notify. + Use either these methods to find out: + <itemizedlist> + <listitem><para> + <emphasis>Maintenance File:</emphasis> + Examine the <filename>maintainers.inc</filename> + file, which is located in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + at + <filename>meta/conf/distro/include</filename>, + to see who is responsible for code. + </para></listitem> + <listitem><para> + <emphasis>Search by File:</emphasis> + Using <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>, + you can enter the following command to bring up a + short list of all commits against a specific file: + <literallayout class='monospaced'> + git shortlog -- <replaceable>filename</replaceable> + </literallayout> + Just provide the name of the file for which you + are interested. + The information returned is not ordered by history + but does include a list of everyone who has + committed grouped by name. + From the list, you can see who is responsible for + the bulk of the changes against the file. + </para></listitem> + <listitem><para> + <emphasis>Examine the List of Mailing Lists:</emphasis> + For a list of the Yocto Project and related mailing + lists, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" + section in the Yocto Project Reference Manual. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Make a Pull Request:</emphasis> + Notify the maintainer or the mailing list that you have + pushed a change by making a pull request.</para> + + <para>The Yocto Project provides two scripts that + conveniently let you generate and send pull requests to the + Yocto Project. + These scripts are <filename>create-pull-request</filename> + and <filename>send-pull-request</filename>. + You can find these scripts in the + <filename>scripts</filename> directory within the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>~/poky/scripts</filename>). + </para> + + <para>Using these scripts correctly formats the requests + without introducing any whitespace or HTML formatting. + The maintainer that receives your patches either directly + or through the mailing list needs to be able to save and + apply them directly from your emails. + Using these scripts is the preferred method for sending + patches.</para> + + <para>First, create the pull request. + For example, the following command runs the script, + specifies the upstream repository in the contrib directory + into which you pushed the change, and provides a subject + line in the created patch files: + <literallayout class='monospaced'> + $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" + </literallayout> + Running this script forms + <filename>*.patch</filename> files in a folder named + <filename>pull-</filename><replaceable>PID</replaceable> + in the current directory. + One of the patch files is a cover letter.</para> + + <para>Before running the + <filename>send-pull-request</filename> script, you must + edit the cover letter patch to insert information about + your change. + After editing the cover letter, send the pull request. + For example, the following command runs the script and + specifies the patch directory and email address. + In this example, the email address is a mailing list: + <literallayout class='monospaced'> + $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org + </literallayout> + You need to follow the prompts as the script is + interactive. + <note> + For help on using these scripts, simply provide the + <filename>-h</filename> argument as follows: + <literallayout class='monospaced'> + $ poky/scripts/create-pull-request -h + $ poky/scripts/send-pull-request -h + </literallayout> + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='submitting-a-patch'> + <title>Using Email to Submit a Patch</title> + + <para> + You can submit patches without using the + <filename>create-pull-request</filename> and + <filename>send-pull-request</filename> scripts described in the + previous section. + However, keep in mind, the preferred method is to use the scripts. + </para> + + <para> + Depending on the components changed, you need to submit the email + to a specific mailing list. + For some guidance on which mailing list to use, see the + <link linkend='figuring-out-the-mailing-list-to-use'>list</link> + at the beginning of this section. + For a description of all the available mailing lists, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" + section in the Yocto Project Reference Manual. + </para> + + <para> + Here is the general procedure on how to submit a patch through + email without using the scripts: + <orderedlist> + <listitem><para> + <emphasis>Make Your Changes Locally:</emphasis> + Make your changes in your local Git repository. + You should make small, controlled, isolated changes. + Keeping changes small and isolated aids review, + makes merging/rebasing easier and keeps the change + history clean should anyone need to refer to it in + future. + </para></listitem> + <listitem><para> + <emphasis>Stage Your Changes:</emphasis> + Stage your changes by using the <filename>git add</filename> + command on each file you changed. + </para></listitem> + <listitem><para> + <emphasis>Commit Your Changes:</emphasis> + Commit the change by using the + <filename>git commit --signoff</filename> command. + Using the <filename>--signoff</filename> option identifies + you as the person making the change and also satisfies + the Developer's Certificate of Origin (DCO) shown earlier. + </para> + + <para>When you form a commit, you must follow certain + standards established by the Yocto Project development + team. + See + <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link> + in the previous section for information on how to + provide commit information that meets Yocto Project + commit message standards. + </para></listitem> + <listitem><para> + <emphasis>Format the Commit:</emphasis> + Format the commit into an email message. + To format commits, use the + <filename>git format-patch</filename> command. + When you provide the command, you must include a revision + list or a number of patches as part of the command. + For example, either of these two commands takes your most + recent single commit and formats it as an email message in + the current directory: + <literallayout class='monospaced'> + $ git format-patch -1 + </literallayout> + or + <literallayout class='monospaced'> + $ git format-patch HEAD~ + </literallayout></para> + + <para>After the command is run, the current directory + contains a numbered <filename>.patch</filename> file for + the commit.</para> + + <para>If you provide several commits as part of the + command, the <filename>git format-patch</filename> command + produces a series of numbered files in the current + directory – one for each commit. + If you have more than one patch, you should also use the + <filename>--cover</filename> option with the command, + which generates a cover letter as the first "patch" in + the series. + You can then edit the cover letter to provide a + description for the series of patches. + For information on the + <filename>git format-patch</filename> command, + see <filename>GIT_FORMAT_PATCH(1)</filename> displayed + using the <filename>man git-format-patch</filename> + command. + <note> + If you are or will be a frequent contributor to the + Yocto Project or to OpenEmbedded, you might consider + requesting a contrib area and the necessary associated + rights. + </note> + </para></listitem> + <listitem><para> + <emphasis>Import the Files Into Your Mail Client:</emphasis> + Import the files into your mail client by using the + <filename>git send-email</filename> command. + <note> + In order to use <filename>git send-email</filename>, + you must have the proper Git packages installed on + your host. + For Ubuntu, Debian, and Fedora the package is + <filename>git-email</filename>. + </note></para> + + <para>The <filename>git send-email</filename> command + sends email by using a local or remote Mail Transport Agent + (MTA) such as <filename>msmtp</filename>, + <filename>sendmail</filename>, or through a direct + <filename>smtp</filename> configuration in your Git + <filename>~/.gitconfig</filename> file. + If you are submitting patches through email only, it is + very important that you submit them without any whitespace + or HTML formatting that either you or your mailer + introduces. + The maintainer that receives your patches needs to be able + to save and apply them directly from your emails. + A good way to verify that what you are sending will be + applicable by the maintainer is to do a dry run and send + them to yourself and then save and apply them as the + maintainer would.</para> + + <para>The <filename>git send-email</filename> command is + the preferred method for sending your patches using + email since there is no risk of compromising whitespace + in the body of the message, which can occur when you use + your own mail client. + The command also has several options that let you + specify recipients and perform further editing of the + email message. + For information on how to use the + <filename>git send-email</filename> command, + see <filename>GIT-SEND-EMAIL(1)</filename> displayed using + the <filename>man git-send-email</filename> command. + </para></listitem> + </orderedlist> + </para> + </section> + </section> + </section> + + <section id='working-with-licenses'> + <title>Working With Licenses</title> + + <para> + As mentioned in the + "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>" + section in the Yocto Project Overview and Concepts Manual, + open source projects are open to the public and they + consequently have different licensing structures in place. + This section describes the mechanism by which the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> + tracks changes to licensing text and covers how to maintain open + source license compliance during your project's lifecycle. + The section also describes how to enable commercially licensed + recipes, which by default are disabled. + </para> + + <section id="usingpoky-configuring-LIC_FILES_CHKSUM"> + <title>Tracking License Changes</title> + + <para> + The license of an upstream project might change in the future. + In order to prevent these changes going unnoticed, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> + variable tracks changes to the license text. The checksums are + validated at the end of the configure step, and if the + checksums do not match, the build will fail. + </para> + + <section id="usingpoky-specifying-LIC_FILES_CHKSUM"> + <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title> + + <para> + The <filename>LIC_FILES_CHKSUM</filename> + variable contains checksums of the license text in the + source code for the recipe. + Following is an example of how to specify + <filename>LIC_FILES_CHKSUM</filename>: + <literallayout class='monospaced'> + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + When using "beginline" and "endline", realize + that line numbering begins with one and not + zero. + Also, the included lines are inclusive (i.e. + lines five through and including 29 in the + previous example for + <filename>licfile1.txt</filename>). + </para></listitem> + <listitem><para> + When a license check fails, the selected license + text is included as part of the QA message. + Using this output, you can determine the exact + start and finish for the needed license text. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + The build system uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> + variable as the default directory when searching files + listed in <filename>LIC_FILES_CHKSUM</filename>. + The previous example employs the default directory. + </para> + + <para> + Consider this next example: + <literallayout class='monospaced'> + LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + </literallayout> + </para> + + <para> + The first line locates a file in + <filename>${S}/src/ls.c</filename> and isolates lines five + through 16 as license text. + The second line refers to a file in + <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>. + </para> + + <para> + Note that <filename>LIC_FILES_CHKSUM</filename> variable is + mandatory for all recipes, unless the + <filename>LICENSE</filename> variable is set to "CLOSED". + </para> + </section> + + <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"> + <title>Explanation of Syntax</title> + + <para> + As mentioned in the previous section, the + <filename>LIC_FILES_CHKSUM</filename> variable lists all + the important files that contain the license text for the + source code. + It is possible to specify a checksum for an entire file, + or a specific section of a file (specified by beginning and + ending line numbers with the "beginline" and "endline" + parameters, respectively). + The latter is useful for source files with a license + notice header, README documents, and so forth. + If you do not use the "beginline" parameter, then it is + assumed that the text begins on the first line of the file. + Similarly, if you do not use the "endline" parameter, + it is assumed that the license text ends with the last + line of the file. + </para> + + <para> + The "md5" parameter stores the md5 checksum of the license + text. + If the license text changes in any way as compared to + this parameter then a mismatch occurs. + This mismatch triggers a build failure and notifies + the developer. + Notification allows the developer to review and address + the license text changes. + Also note that if a mismatch occurs during the build, + the correct md5 checksum is placed in the build log and + can be easily copied to the recipe. + </para> + + <para> + There is no limit to how many files you can specify using + the <filename>LIC_FILES_CHKSUM</filename> variable. + Generally, however, every project requires a few + specifications for license tracking. + Many projects have a "COPYING" file that stores the + license information for all the source code files. + This practice allows you to just track the "COPYING" + file as long as it is kept up to date. + <note><title>Tips</title> + <itemizedlist> + <listitem><para> + If you specify an empty or invalid "md5" + parameter, + <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> + returns an md5 mis-match + error and displays the correct "md5" parameter + value during the build. + The correct parameter is also captured in + the build log. + </para></listitem> + <listitem><para> + If the whole file contains only license text, + you do not need to use the "beginline" and + "endline" parameters. + </para></listitem> + </itemizedlist> + </note> + </para> + </section> + </section> + + <section id="enabling-commercially-licensed-recipes"> + <title>Enabling Commercially Licensed Recipes</title> + + <para> + By default, the OpenEmbedded build system disables + components that have commercial or other special licensing + requirements. + Such requirements are defined on a + recipe-by-recipe basis through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> + variable definition in the affected recipe. + For instance, the + <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> + recipe contains the following statement: <literallayout class='monospaced'> - INHERIT += "archiver" - ARCHIVER_MODE[src] = "original" + LICENSE_FLAGS = "commercial" </literallayout> - During the creation of your image, the source from all - recipes that deploy packages to the image is placed within - subdirectories of - <filename>DEPLOY_DIR/sources</filename> based on the - <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> - for each recipe. - Releasing the entire directory enables you to comply with - requirements concerning providing the unmodified source. - It is important to note that the size of the directory can - get large. + Here is a slightly more complicated example that contains both + an explicit recipe name and version (after variable expansion): + <literallayout class='monospaced'> + LICENSE_FLAGS = "license_${PN}_${PV}" + </literallayout> + In order for a component restricted by a + <filename>LICENSE_FLAGS</filename> definition to be enabled and + included in an image, it needs to have a matching entry in the + global + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink> + variable, which is a variable typically defined in your + <filename>local.conf</filename> file. + For example, to enable the + <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>. + See the + "<link linkend='license-flag-matching'>License Flag Matching</link>" + section for a full + explanation of how <filename>LICENSE_FLAGS</filename> matching + works. + Here is the example: + <literallayout class='monospaced'> + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + </literallayout> + Likewise, to additionally enable the package built from the + recipe containing + <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, + and assuming that the actual recipe name was + <filename>emgd_1.10.bb</filename>, the following string would + enable that package as well as the original + <filename>gst-plugins-ugly</filename> package: + <literallayout class='monospaced'> + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + </literallayout> + As a convenience, you do not need to specify the complete + license string in the whitelist for every package. + You can use an abbreviated form, which consists + of just the first portion or portions of the license + string before the initial underscore character or characters. + A partial string will match any license that contains the + given string as the first portion of its license. + For example, the following whitelist string will also match + both of the packages previously mentioned as well as any other + packages that have licenses starting with "commercial" or + "license". + <literallayout class='monospaced'> + LICENSE_FLAGS_WHITELIST = "commercial license" + </literallayout> + </para> + + <section id="license-flag-matching"> + <title>License Flag Matching</title> + + <para> + License flag matching allows you to control what recipes + the OpenEmbedded build system includes in the build. + Fundamentally, the build system attempts to match + <filename>LICENSE_FLAGS</filename> strings found in recipes + against <filename>LICENSE_FLAGS_WHITELIST</filename> + strings found in the whitelist. + A match causes the build system to include a recipe in the + build, while failure to find a match causes the build + system to exclude a recipe. + </para> + + <para> + In general, license flag matching is simple. + However, understanding some concepts will help you + correctly and effectively use matching. + </para> + + <para> + Before a flag + defined by a particular recipe is tested against the + contents of the whitelist, the expanded string + <filename>_${PN}</filename> is appended to the flag. + This expansion makes each + <filename>LICENSE_FLAGS</filename> value recipe-specific. + After expansion, the string is then matched against the + whitelist. + Thus, specifying + <filename>LICENSE_FLAGS = "commercial"</filename> + in recipe "foo", for example, results in the string + <filename>"commercial_foo"</filename>. + And, to create a match, that string must appear in the + whitelist. + </para> + + <para> + Judicious use of the <filename>LICENSE_FLAGS</filename> + strings and the contents of the + <filename>LICENSE_FLAGS_WHITELIST</filename> variable + allows you a lot of flexibility for including or excluding + recipes based on licensing. + For example, you can broaden the matching capabilities by + using license flags string subsets in the whitelist. + <note> + When using a string subset, be sure to use the part of + the expanded string that precedes the appended + underscore character (e.g. + <filename>usethispart_1.3</filename>, + <filename>usethispart_1.4</filename>, and so forth). + </note> + For example, simply specifying the string "commercial" in + the whitelist matches any expanded + <filename>LICENSE_FLAGS</filename> definition that starts + with the string "commercial" such as "commercial_foo" and + "commercial_bar", which are the strings the build system + automatically generates for hypothetical recipes named + "foo" and "bar" assuming those recipes simply specify the + following: + <literallayout class='monospaced'> + LICENSE_FLAGS = "commercial" + </literallayout> + Thus, you can choose to exhaustively + enumerate each license flag in the whitelist and + allow only specific recipes into the image, or + you can use a string subset that causes a broader range of + matches to allow a range of recipes into the image. + </para> + + <para> + This scheme works even if the + <filename>LICENSE_FLAGS</filename> string already + has <filename>_${PN}</filename> appended. + For example, the build system turns the license flag + "commercial_1.2_foo" into "commercial_1.2_foo_foo" and + would match both the general "commercial" and the specific + "commercial_1.2_foo" strings found in the whitelist, as + expected. + </para> + + <para> + Here are some other scenarios: + <itemizedlist> + <listitem><para> + You can specify a versioned string in the recipe + such as "commercial_foo_1.2" in a "foo" recipe. + The build system expands this string to + "commercial_foo_1.2_foo". + Combine this license flag with a whitelist that has + the string "commercial" and you match the flag + along with any other flag that starts with the + string "commercial". + </para></listitem> + <listitem><para> + Under the same circumstances, you can use + "commercial_foo" in the whitelist and the build + system not only matches "commercial_foo_1.2" but + also matches any license flag with the string + "commercial_foo", regardless of the version. + </para></listitem> + <listitem><para> + You can be very specific and use both the + package and version parts in the whitelist (e.g. + "commercial_foo_1.2") to specifically match a + versioned recipe. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id="other-variables-related-to-commercial-licenses"> + <title>Other Variables Related to Commercial Licenses</title> + + <para> + Other helpful variables related to commercial + license handling exist and are defined in the + <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file: + <literallayout class='monospaced'> + COMMERCIAL_AUDIO_PLUGINS ?= "" + COMMERCIAL_VIDEO_PLUGINS ?= "" + </literallayout> + If you want to enable these components, you can do so by + making sure you have statements similar to the following + in your <filename>local.conf</filename> configuration file: + <literallayout class='monospaced'> + COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ + gst-plugins-ugly-mpegaudioparse" + COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ + gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" + </literallayout> + Of course, you could also create a matching whitelist + for those components using the more general "commercial" + in the whitelist, but that would also enable all the + other packages with <filename>LICENSE_FLAGS</filename> + containing "commercial", which you may or may not want: + <literallayout class='monospaced'> + LICENSE_FLAGS_WHITELIST = "commercial" + </literallayout> + </para> + + <para> + Specifying audio and video plug-ins as part of the + <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and + <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements + (along with the enabling + <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the + plug-ins or components into built images, thus adding + support for media formats or components. + </para> + </section> + </section> + + <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'> + <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title> + + <para> + One of the concerns for a development organization using open source + software is how to maintain compliance with various open source + licensing during the lifecycle of the product. + While this section does not provide legal advice or + comprehensively cover all scenarios, it does + present methods that you can use to + assist you in meeting the compliance requirements during a software + release. </para> <para> - A way to help mitigate the size issue is to only release - tarballs for licenses that require the release of - source. - Let us assume you are only concerned with GPL code as - identified by running the following script: - <literallayout class='monospaced'> + With hundreds of different open source licenses that the Yocto + Project tracks, it is difficult to know the requirements of each + and every license. + However, the requirements of the major FLOSS licenses can begin + to be covered by + assuming that three main areas of concern exist: + <itemizedlist> + <listitem><para>Source code must be provided.</para></listitem> + <listitem><para>License text for the software must be + provided.</para></listitem> + <listitem><para>Compilation scripts and modifications to the + source code must be provided. + </para></listitem> + </itemizedlist> + There are other requirements beyond the scope of these + three and the methods described in this section + (e.g. the mechanism through which source code is distributed). + </para> + + <para> + As different organizations have different methods of complying with + open source licensing, this section is not meant to imply that + there is only one single way to meet your compliance obligations, + but rather to describe one method of achieving compliance. + The remainder of this section describes methods supported to meet the + previously mentioned three requirements. + Once you take steps to meet these requirements, + and prior to releasing images, sources, and the build system, + you should audit all artifacts to ensure completeness. + <note> + The Yocto Project generates a license manifest during + image creation that is located + in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename> + to assist with any audits. + </note> + </para> + + <section id='providing-the-source-code'> + <title>Providing the Source Code</title> + + <para> + Compliance activities should begin before you generate the + final image. + The first thing you should look at is the requirement that + tops the list for most compliance groups - providing + the source. + The Yocto Project has a few ways of meeting this + requirement. + </para> + + <para> + One of the easiest ways to meet this requirement is + to provide the entire + <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> + used by the build. + This method, however, has a few issues. + The most obvious is the size of the directory since it includes + all sources used in the build and not just the source used in + the released image. + It will include toolchain source, and other artifacts, which + you would not generally release. + However, the more serious issue for most companies is accidental + release of proprietary software. + The Yocto Project provides an + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink> + class to help avoid some of these concerns. + </para> + + <para> + Before you employ <filename>DL_DIR</filename> or the + <filename>archiver</filename> class, you need to decide how + you choose to provide source. + The source <filename>archiver</filename> class can generate + tarballs and SRPMs and can create them with various levels of + compliance in mind. + </para> + + <para> + One way of doing this (but certainly not the only way) is to + release just the source as a tarball. + You can do this by adding the following to the + <filename>local.conf</filename> file found in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: + <literallayout class='monospaced'> + INHERIT += "archiver" + ARCHIVER_MODE[src] = "original" + </literallayout> + During the creation of your image, the source from all + recipes that deploy packages to the image is placed within + subdirectories of + <filename>DEPLOY_DIR/sources</filename> based on the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> + for each recipe. + Releasing the entire directory enables you to comply with + requirements concerning providing the unmodified source. + It is important to note that the size of the directory can + get large. + </para> + + <para> + A way to help mitigate the size issue is to only release + tarballs for licenses that require the release of + source. + Let us assume you are only concerned with GPL code as + identified by running the following script: + <literallayout class='monospaced'> # Script to archive a subset of packages matching specific license(s) # Source and license files are copied into sub folders of package folder # Must be run from build folder @@ -13501,96 +15052,97 @@ Some notes from Cal: cp tmp/deploy/licenses/$p/* $src_release_dir/$p/license 2> /dev/null fi done - done </literallayout> - At this point, you could create a tarball from the - <filename>gpl_source_release</filename> directory and - provide that to the end user. - This method would be a step toward achieving compliance - with section 3a of GPLv2 and with section 6 of GPLv3. - </para> - </section> + done + </literallayout> + At this point, you could create a tarball from the + <filename>gpl_source_release</filename> directory and + provide that to the end user. + This method would be a step toward achieving compliance + with section 3a of GPLv2 and with section 6 of GPLv3. + </para> + </section> - <section id='providing-license-text'> - <title>Providing License Text</title> + <section id='providing-license-text'> + <title>Providing License Text</title> - <para> - One requirement that is often overlooked is inclusion - of license text. - This requirement also needs to be dealt with prior to - generating the final image. - Some licenses require the license text to accompany - the binary. - You can achieve this by adding the following to your - <filename>local.conf</filename> file: - <literallayout class='monospaced'> + <para> + One requirement that is often overlooked is inclusion + of license text. + This requirement also needs to be dealt with prior to + generating the final image. + Some licenses require the license text to accompany + the binary. + You can achieve this by adding the following to your + <filename>local.conf</filename> file: + <literallayout class='monospaced'> COPY_LIC_MANIFEST = "1" COPY_LIC_DIRS = "1" LICENSE_CREATE_PACKAGE = "1" - </literallayout> - Adding these statements to the configuration file ensures - that the licenses collected during package generation - are included on your image. - <note> - <para>Setting all three variables to "1" results in the - image having two copies of the same license file. - One copy resides in - <filename>/usr/share/common-licenses</filename> and - the other resides in - <filename>/usr/share/license</filename>.</para> - - <para>The reason for this behavior is because - <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink> - add a copy of the license when the image is built but do - not offer a path for adding licenses for newly installed - packages to an image. - <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink> - adds a separate package and an upgrade path for adding - licenses to an image.</para> - </note> - </para> + </literallayout> + Adding these statements to the configuration file ensures + that the licenses collected during package generation + are included on your image. + <note> + <para>Setting all three variables to "1" results in the + image having two copies of the same license file. + One copy resides in + <filename>/usr/share/common-licenses</filename> and + the other resides in + <filename>/usr/share/license</filename>.</para> + + <para>The reason for this behavior is because + <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink> + add a copy of the license when the image is built but do + not offer a path for adding licenses for newly installed + packages to an image. + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink> + adds a separate package and an upgrade path for adding + licenses to an image.</para> + </note> + </para> - <para> - As the source <filename>archiver</filename> class has already - archived the original - unmodified source that contains the license files, - you would have already met the requirements for inclusion - of the license information with source as defined by the GPL - and other open source licenses. - </para> - </section> + <para> + As the source <filename>archiver</filename> class has already + archived the original + unmodified source that contains the license files, + you would have already met the requirements for inclusion + of the license information with source as defined by the GPL + and other open source licenses. + </para> + </section> - <section id='providing-compilation-scripts-and-source-code-modifications'> - <title>Providing Compilation Scripts and Source Code Modifications</title> + <section id='providing-compilation-scripts-and-source-code-modifications'> + <title>Providing Compilation Scripts and Source Code Modifications</title> - <para> - At this point, we have addressed all we need to - prior to generating the image. - The next two requirements are addressed during the final - packaging of the release. - </para> + <para> + At this point, we have addressed all we need to + prior to generating the image. + The next two requirements are addressed during the final + packaging of the release. + </para> - <para> - By releasing the version of the OpenEmbedded build system - and the layers used during the build, you will be providing both - compilation scripts and the source code modifications in one - step. - </para> + <para> + By releasing the version of the OpenEmbedded build system + and the layers used during the build, you will be providing both + compilation scripts and the source code modifications in one + step. + </para> - <para> - If the deployment team has a - <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink> - and a distro layer, and those those layers are used to patch, - compile, package, or modify (in any way) any open source - software included in your released images, you - might be required to release those layers under section 3 of - GPLv2 or section 1 of GPLv3. - One way of doing that is with a clean - checkout of the version of the Yocto Project and layers used - during your build. - Here is an example: - <literallayout class='monospaced'> + <para> + If the deployment team has a + <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink> + and a distro layer, and those those layers are used to patch, + compile, package, or modify (in any way) any open source + software included in your released images, you + might be required to release those layers under section 3 of + GPLv2 or section 1 of GPLv3. + One way of doing that is with a clean + checkout of the version of the Yocto Project and layers used + during your build. + Here is an example: + <literallayout class='monospaced'> # We built using the &DISTRO_NAME_NO_CAP; branch of the poky repo $ git clone -b &DISTRO_NAME_NO_CAP; git://git.yoctoproject.org/poky $ cd poky @@ -13599,18 +15151,18 @@ Some notes from Cal: $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer # clean up the .git repos $ find . -name ".git" -type d -exec rm -rf {} \; - </literallayout> - One thing a development organization might want to consider - for end-user convenience is to modify - <filename>meta-poky/conf/bblayers.conf.sample</filename> to - ensure that when the end user utilizes the released build - system to build an image, the development organization's - layers are included in the <filename>bblayers.conf</filename> - file automatically: - <literallayout class='monospaced'> - # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf + </literallayout> + One thing a development organization might want to consider + for end-user convenience is to modify + <filename>meta-poky/conf/bblayers.conf.sample</filename> to + ensure that when the end user utilizes the released build + system to build an image, the development organization's + layers are included in the <filename>bblayers.conf</filename> + file automatically: + <literallayout class='monospaced'> + # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf # changes incompatibly - LCONF_VERSION = "6" + POKY_BBLAYERS_CONF_VERSION = "2" BBPATH = "${TOPDIR}" BBFILES ?= "" @@ -13621,13 +15173,39 @@ Some notes from Cal: ##OEROOT##/meta-yocto-bsp \ ##OEROOT##/meta-mylayer \ " + </literallayout> + Creating and providing an archive of the + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> + layers (recipes, configuration files, and so forth) + enables you to meet your + requirements to include the scripts to control compilation + as well as any modifications to the original source. + </para> + </section> + </section> + + <section id='copying-licenses-that-do-not-exist'> + <title>Copying Licenses that Do Not Exist</title> + + <para> + Some packages, such as the linux-firmware package, have many + licenses that are not in any way common. + You can avoid adding a lot of these types of common license + files, which are only applicable to a specific package, by using + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-NO_GENERIC_LICENSE'><filename>NO_GENERIC_LICENSE</filename></ulink> + variable. + Using this variable also avoids QA errors when you use a + non-common, non-CLOSED license in a recipe. + </para> + + <para> + The following is an example that uses the + <filename>LICENSE.Abilis.txt</filename> + file as the license from the fetched source: + <literallayout class='monospaced'> + NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" </literallayout> - Creating and providing an archive of the - <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> - layers (recipes, configuration files, and so forth) - enables you to meet your - requirements to include the scripts to control compilation - as well as any modifications to the original source. </para> </section> </section> @@ -13747,6 +15325,136 @@ Some notes from Cal: </para> </section> </section> + + <section id="dev-using-wayland-and-weston"> + <title>Using Wayland and Weston</title> + + <para> + <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink> + is a computer display server protocol that + provides a method for compositing window managers to communicate + directly with applications and video hardware and expects them to + communicate with input hardware using other libraries. + Using Wayland with supporting targets can result in better control + over graphics frame rendering than an application might otherwise + achieve. + </para> + + <para> + The Yocto Project provides the Wayland protocol libraries and the + reference + <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink> + compositor as part of its release. + You can find the integrated packages in the + <filename>meta</filename> layer of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + Specifically, you can find the recipes that build both Wayland + and Weston at <filename>meta/recipes-graphics/wayland</filename>. + </para> + + <para> + You can build both the Wayland and Weston packages for use only + with targets that accept the + <ulink url='https://en.wikipedia.org/wiki/Mesa_(computer_graphics)'>Mesa 3D and Direct Rendering Infrastructure</ulink>, + which is also known as Mesa DRI. + This implies that you cannot build and use the packages if your + target uses, for example, the + <trademark class='registered'>Intel</trademark> Embedded Media + and Graphics Driver + (<trademark class='registered'>Intel</trademark> EMGD) that + overrides Mesa DRI. + <note> + Due to lack of EGL support, Weston 1.0.3 will not run + directly on the emulated QEMU hardware. + However, this version of Weston will run under X emulation + without issues. + </note> + </para> + + <para> + This section describes what you need to do to implement Wayland and + use the Weston compositor when building an image for a supporting + target. + </para> + + <section id="enabling-wayland-in-an-image"> + <title>Enabling Wayland in an Image</title> + + <para> + To enable Wayland, you need to enable it to be built and enable + it to be included (installed) in the image. + </para> + + <section id="enable-building"> + <title>Building</title> + + <para> + To cause Mesa to build the <filename>wayland-egl</filename> + platform and Weston to build Wayland with Kernel Mode + Setting + (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>) + support, include the "wayland" flag in the + <ulink url="&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></ulink> + statement in your <filename>local.conf</filename> file: + <literallayout class='monospaced'> + DISTRO_FEATURES_append = " wayland" + </literallayout> + <note> + If X11 has been enabled elsewhere, Weston will build + Wayland with X11 support + </note> + </para> + </section> + + <section id="enable-installation-in-an-image"> + <title>Installing</title> + + <para> + To install the Wayland feature into an image, you must + include the following + <ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></ulink> + statement in your <filename>local.conf</filename> file: + <literallayout class='monospaced'> + CORE_IMAGE_EXTRA_INSTALL += "wayland weston" + </literallayout> + </para> + </section> + </section> + + <section id="running-weston"> + <title>Running Weston</title> + + <para> + To run Weston inside X11, enabling it as described earlier and + building a Sato image is sufficient. + If you are running your image under Sato, a Weston Launcher + appears in the "Utility" category. + </para> + + <para> + Alternatively, you can run Weston through the command-line + interpretor (CLI), which is better suited for development work. + To run Weston under the CLI, you need to do the following after + your image is built: + <orderedlist> + <listitem><para> + Run these commands to export + <filename>XDG_RUNTIME_DIR</filename>: + <literallayout class='monospaced'> + mkdir -p /tmp/$USER-weston + chmod 0700 /tmp/$USER-weston + export XDG_RUNTIME_DIR=/tmp/$USER-weston + </literallayout> + </para></listitem> + <listitem><para> + Launch Weston in the shell: + <literallayout class='monospaced'> + weston + </literallayout></para></listitem> + </orderedlist> + </para> + </section> + </section> </chapter> <!-- |