diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml | 4429 |
1 files changed, 1694 insertions, 2735 deletions
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml index 598f8775db..0081738087 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml @@ -18,7 +18,8 @@ <para> The OpenEmbedded build system supports organizing - <link linkend='metadata'>Metadata</link> into multiple layers. + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> into + multiple layers. Layers allow you to isolate different types of customizations from each other. You might find it tempting to keep everything in one layer when @@ -58,7 +59,7 @@ <title>Layers</title> <para> - The <link linkend='source-directory'>Source Directory</link> + The <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> contains both general layers and BSP layers right out of the box. You can easily identify layers that ship with a @@ -107,7 +108,7 @@ "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the Yocto Project Board Support Package (BSP) Developer's Guide and the - "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" + "<link linkend='creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</link>" section further down in this manual. </para> @@ -254,197 +255,182 @@ </section> <section id='best-practices-to-follow-when-creating-layers'> - <title>Best Practices to Follow When Creating Layers</title> + <title>Following Best Practices When Creating Layers</title> <para> To create layers that are easier to maintain and that will not impact builds for other machines, you should consider the - information in the following sections. - </para> - - <section id='avoid-overlaying-entire-recipes'> - <title>Avoid "Overlaying" Entire Recipes</title> - - <para> - Avoid "overlaying" entire recipes from other layers in your - configuration. - In other words, do not copy an entire recipe into your - layer and then modify it. - Rather, use an append file (<filename>.bbappend</filename>) - to override - only those parts of the original recipe you need to modify. - </para> - </section> - - <section id='avoid-duplicating-include-files'> - <title>Avoid Duplicating Include Files</title> - - <para> - Avoid duplicating include files. - Use append files (<filename>.bbappend</filename>) - for each recipe - that uses an include file. - Or, if you are introducing a new recipe that requires - the included file, use the path relative to the original - layer directory to refer to the file. - For example, use - <filename>require recipes-core/</filename><replaceable>package</replaceable><filename>/</filename><replaceable>file</replaceable><filename>.inc</filename> - instead of <filename>require </filename><replaceable>file</replaceable><filename>.inc</filename>. - If you're finding you have to overlay the include file, - it could indicate a deficiency in the include file in - the layer to which it originally belongs. - If this is the case, you should try to address that - deficiency instead of overlaying the include file. - For example, you could address this by getting the - maintainer of the include file to add a variable or - variables to make it easy to override the parts needing - to be overridden. - </para> - </section> - - <section id='structure-your-layers'> - <title>Structure Your Layers</title> - - <para> - Proper use of overrides within append files and placement - of machine-specific files within your layer can ensure that - a build is not using the wrong Metadata and negatively - impacting a build for a different machine. - Following are some examples: - <itemizedlist> - <listitem><para><emphasis>Modifying Variables to Support - a Different Machine:</emphasis> - Suppose you have a layer named - <filename>meta-one</filename> that adds support - for building machine "one". - To do so, you use an append file named - <filename>base-files.bbappend</filename> and - create a dependency on "foo" by altering the - <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> - variable: - <literallayout class='monospaced'> + information in the following list: + <itemizedlist> + <listitem><para> + <emphasis>Avoid "Overlaying" Entire Recipes from Other Layers in Your Configuration:</emphasis> + In other words, do not copy an entire recipe into your + layer and then modify it. + Rather, use an append file + (<filename>.bbappend</filename>) to override only those + parts of the original recipe you need to modify. + </para></listitem> + <listitem><para> + <emphasis>Avoid Duplicating Include Files:</emphasis> + Use append files (<filename>.bbappend</filename>) + for each recipe that uses an include file. + Or, if you are introducing a new recipe that requires + the included file, use the path relative to the + original layer directory to refer to the file. + For example, use + <filename>require recipes-core/</filename><replaceable>package</replaceable><filename>/</filename><replaceable>file</replaceable><filename>.inc</filename> + instead of + <filename>require </filename><replaceable>file</replaceable><filename>.inc</filename>. + If you're finding you have to overlay the include file, + it could indicate a deficiency in the include file in + the layer to which it originally belongs. + If this is the case, you should try to address that + deficiency instead of overlaying the include file. + For example, you could address this by getting the + maintainer of the include file to add a variable or + variables to make it easy to override the parts needing + to be overridden. + </para></listitem> + <listitem><para> + <emphasis>Structure Your Layers:</emphasis> + Proper use of overrides within append files and + placement of machine-specific files within your layer + can ensure that a build is not using the wrong Metadata + and negatively impacting a build for a different + machine. + Following are some examples: + <itemizedlist> + <listitem><para> + <emphasis>Modify Variables to Support a + Different Machine:</emphasis> + Suppose you have a layer named + <filename>meta-one</filename> that adds support + for building machine "one". + To do so, you use an append file named + <filename>base-files.bbappend</filename> and + create a dependency on "foo" by altering the + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> + variable: + <literallayout class='monospaced'> DEPENDS = "foo" - </literallayout> - The dependency is created during any build that - includes the layer - <filename>meta-one</filename>. - However, you might not want this dependency - for all machines. - For example, suppose you are building for - machine "two" but your - <filename>bblayers.conf</filename> file has the - <filename>meta-one</filename> layer included. - During the build, the - <filename>base-files</filename> for machine - "two" will also have the dependency on - <filename>foo</filename>.</para> - <para>To make sure your changes apply only when - building machine "one", use a machine override - with the <filename>DEPENDS</filename> statement: - <literallayout class='monospaced'> + </literallayout> + The dependency is created during any build that + includes the layer + <filename>meta-one</filename>. + However, you might not want this dependency + for all machines. + For example, suppose you are building for + machine "two" but your + <filename>bblayers.conf</filename> file has the + <filename>meta-one</filename> layer included. + During the build, the + <filename>base-files</filename> for machine + "two" will also have the dependency on + <filename>foo</filename>.</para> + <para>To make sure your changes apply only when + building machine "one", use a machine override + with the <filename>DEPENDS</filename> statement: + <literallayout class='monospaced'> DEPENDS_one = "foo" - </literallayout> - You should follow the same strategy when using - <filename>_append</filename> and - <filename>_prepend</filename> operations: - <literallayout class='monospaced'> + </literallayout> + You should follow the same strategy when using + <filename>_append</filename> and + <filename>_prepend</filename> operations: + <literallayout class='monospaced'> DEPENDS_append_one = " foo" DEPENDS_prepend_one = "foo " - </literallayout> - As an actual example, here's a line from the recipe - for gnutls, which adds dependencies on - "argp-standalone" when building with the musl C - library: - <literallayout class='monospaced'> + </literallayout> + As an actual example, here's a line from the recipe + for gnutls, which adds dependencies on + "argp-standalone" when building with the musl C + library: + <literallayout class='monospaced'> DEPENDS_append_libc-musl = " argp-standalone" - </literallayout> - <note> - Avoiding "+=" and "=+" and using - machine-specific - <filename>_append</filename> - and <filename>_prepend</filename> operations - is recommended as well. - </note></para></listitem> - <listitem><para><emphasis>Place Machine-Specific Files - in Machine-Specific Locations:</emphasis> - When you have a base recipe, such as - <filename>base-files.bb</filename>, that - contains a - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement to a file, you can use an append file - to cause the build to use your own version of - the file. - For example, an append file in your layer at - <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename> - could extend - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> - using - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - as follows: - <literallayout class='monospaced'> + </literallayout> + <note> + Avoiding "+=" and "=+" and using + machine-specific + <filename>_append</filename> + and <filename>_prepend</filename> operations + is recommended as well. + </note> + </para></listitem> + <listitem><para> + <emphasis>Place Machine-Specific Files in + Machine-Specific Locations:</emphasis> + When you have a base recipe, such as + <filename>base-files.bb</filename>, that + contains a + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement to a file, you can use an append file + to cause the build to use your own version of + the file. + For example, an append file in your layer at + <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename> + could extend + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> + using + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + as follows: + <literallayout class='monospaced'> FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:" - </literallayout> - The build for machine "one" will pick up your - machine-specific file as long as you have the - file in - <filename>meta-one/recipes-core/base-files/base-files/</filename>. - However, if you are building for a different - machine and the - <filename>bblayers.conf</filename> file includes - the <filename>meta-one</filename> layer and - the location of your machine-specific file is - the first location where that file is found - according to <filename>FILESPATH</filename>, - builds for all machines will also use that - machine-specific file.</para> - <para>You can make sure that a machine-specific - file is used for a particular machine by putting - the file in a subdirectory specific to the - machine. - For example, rather than placing the file in - <filename>meta-one/recipes-core/base-files/base-files/</filename> - as shown above, put it in - <filename>meta-one/recipes-core/base-files/base-files/one/</filename>. - Not only does this make sure the file is used - only when building for machine "one", but the - build process locates the file more quickly.</para> - <para>In summary, you need to place all files - referenced from <filename>SRC_URI</filename> - in a machine-specific subdirectory within the - layer in order to restrict those files to - machine-specific builds.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='other-recommendations'> - <title>Other Recommendations</title> - - <para> - We also recommend the following: - <itemizedlist> - <listitem><para>If you want permission to use the - Yocto Project Compatibility logo with your layer - or application that uses your layer, perform the - steps to apply for compatibility. - See the - "<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>" - section for more information. - </para></listitem> - <listitem><para>Store custom layers in a Git repository - that uses the - <filename>meta-<replaceable>layer_name</replaceable></filename> format. - </para></listitem> - <listitem><para>Clone the repository alongside other - <filename>meta</filename> directories in the - <link linkend='source-directory'>Source Directory</link>. - </para></listitem> - </itemizedlist> - Following these recommendations keeps your Source Directory and - its configuration entirely inside the Yocto Project's core - base. - </para> - </section> + </literallayout> + The build for machine "one" will pick up your + machine-specific file as long as you have the + file in + <filename>meta-one/recipes-core/base-files/base-files/</filename>. + However, if you are building for a different + machine and the + <filename>bblayers.conf</filename> file includes + the <filename>meta-one</filename> layer and + the location of your machine-specific file is + the first location where that file is found + according to <filename>FILESPATH</filename>, + builds for all machines will also use that + machine-specific file.</para> + <para>You can make sure that a machine-specific + file is used for a particular machine by putting + the file in a subdirectory specific to the + machine. + For example, rather than placing the file in + <filename>meta-one/recipes-core/base-files/base-files/</filename> + as shown above, put it in + <filename>meta-one/recipes-core/base-files/base-files/one/</filename>. + Not only does this make sure the file is used + only when building for machine "one", but the + build process locates the file more quickly.</para> + <para>In summary, you need to place all files + referenced from <filename>SRC_URI</filename> + in a machine-specific subdirectory within the + layer in order to restrict those files to + machine-specific builds. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Perform Steps to Apply for Yocto Project Compatibility:</emphasis> + If you want permission to use the + Yocto Project Compatibility logo with your layer + or application that uses your layer, perform the + steps to apply for compatibility. + See the + "<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>" + section for more information. + </para></listitem> + <listitem><para> + <emphasis>Follow the Layer Naming Convention:</emphasis> + Store custom layers in a Git repository that use the + <filename>meta-<replaceable>layer_name</replaceable></filename> + format. + </para></listitem> + <listitem><para> + <emphasis>Group Your Layers Locally:</emphasis> + Clone your repository alongside other cloned + <filename>meta</filename> directories from the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + </para></listitem> + </itemizedlist> + </para> </section> <section id='making-sure-your-layer-is-compatible-with-yocto-project'> @@ -456,65 +442,74 @@ existing Yocto Project layers (i.e. the layer is compatible with the Yocto Project). Ensuring compatibility makes the layer easy to be consumed - by others in the Yocto Project community and allows you - permission to use the Yocto Project Compatibility logo. - </para> - - <para> - Version 1.0 of the Yocto Project Compatibility Program has - been in existence for a number of releases. - This version of the program consists of the layer application - process that requests permission to use the Yocto Project - Compatibility logo for your layer and application. - You can find version 1.0 of the form at - <ulink url='https://www.yoctoproject.org/webform/yocto-project-compatible-registration'></ulink>. - To be granted permission to use the logo, you need to be able - to answer "Yes" to the questions or have an acceptable - explanation for any questions answered "No". - </para> - - <para> - A second version (2.0) of the Yocto Project Compatibility - Program is currently under development. - Included as part of version 2.0 (and currently available) is - the <filename>yocto-compat-layer.py</filename> script. - When run against a layer, this script tests the layer against - tighter constraints based on experiences of how layers have - worked in the real world and where pitfalls have been found. - </para> - - <para> - Part of the 2.0 version of the program that is not currently - available but is in development is an updated compatibility - application form. - This updated form, among other questions, specifically - asks if your layer has passed the test using the - <filename>yocto-compat-layer.py</filename> script. - <note><title>Tip</title> - Even though the updated application form is currently - unavailable for version 2.0 of the Yocto Project - Compatibility Program, the - <filename>yocto-compat-layer.py</filename> script is - available in OE-Core. - You can use the script to assess the status of your - layers in advance of the 2.0 release of the program. + by others in the Yocto Project community and could allow you + permission to use the Yocto Project Compatible Logo. + <note> + Only Yocto Project member organizations are permitted to + use the Yocto Project Compatible Logo. + The logo is not available for general use. + For information on how to become a Yocto Project member + organization, see the + <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>. </note> </para> <para> + The Yocto Project Compatibility Program consists of a layer + application process that requests permission to use the Yocto + Project Compatibility Logo for your layer and application. + The process consists of two parts: + <orderedlist> + <listitem><para> + Successfully passing a script + (<filename>yocto-check-layer</filename>) that + when run against your layer, tests it against + constraints based on experiences of how layers have + worked in the real world and where pitfalls have been + found. + Getting a "PASS" result from the script is required for + successful compatibility registration. + </para></listitem> + <listitem><para> + Completion of an application acceptance form, which + you can find at + <ulink url='https://www.yoctoproject.org/webform/yocto-project-compatible-registration'></ulink>. + </para></listitem> + </orderedlist> + </para> + + <para> + To be granted permission to use the logo, you need to satisfy + the following: + <itemizedlist> + <listitem><para> + Be able to check the box indicating that you + got a "PASS" when running the script against your + layer. + </para></listitem> + <listitem><para> + Answer "Yes" to the questions on the form or have an + acceptable explanation for any questions answered "No". + </para></listitem> + <listitem><para> + You need to be a Yocto Project Member Organization. + </para></listitem> + </itemizedlist> + </para> + + <para> The remainder of this section presents information on the - version 1.0 registration form and on the - <filename>yocto-compat-layer.py</filename> script. + registration form and on the + <filename>yocto-check-layer</filename> script. </para> - <section id='yocto-project-compatibility-program-application'> - <title>Yocto Project Compatibility Program Application</title> + <section id='yocto-project-compatible-program-application'> + <title>Yocto Project Compatible Program Application</title> <para> - Use the 1.0 version of the form to apply for your - layer's compatibility approval. + Use the form to apply for your layer's approval. Upon successful application, you can use the Yocto - Project Compatibility logo with your layer and the + Project Compatibility Logo with your layer and the application that uses your layer. </para> @@ -552,26 +547,18 @@ </para> </section> - <section id='yocto-compat-layer-py-script'> - <title><filename>yocto-compat-layer.py</filename> Script</title> + <section id='yocto-check-layer-script'> + <title><filename>yocto-check-layer</filename> Script</title> <para> - The <filename>yocto-compat-layer.py</filename> script, - which is currently available, provides you a way to - assess how compatible your layer is with the Yocto - Project. + The <filename>yocto-check-layer</filename> script + provides you a way to assess how compatible your layer is + with the Yocto Project. You should run this script prior to using the form to apply for compatibility as described in the previous section. - <note> - Because the script is part of the 2.0 release of the - Yocto Project Compatibility Program, you are not - required to successfully run your layer against it - in order to be granted compatibility status. - However, it is a good idea as it promotes - well-behaved layers and gives you an idea of where your - layer stands regarding compatibility. - </note> + You need to achieve a "PASS" result in order to have + your application form successfully processed. </para> <para> @@ -588,7 +575,7 @@ your build directory: <literallayout class='monospaced'> $ source oe-init-build-env - $ yocto-compat-layer.py <replaceable>your_layer_directory</replaceable> + $ yocto-check-layer <replaceable>your_layer_directory</replaceable> </literallayout> Be sure to provide the actual directory for your layer as part of the command. @@ -655,7 +642,7 @@ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename> variable in your <filename>conf/bblayers.conf</filename> file, which is found in the - <link linkend='build-directory'>Build Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. The following example shows how to enable a layer named <filename>meta-mylayer</filename>: <literallayout class='monospaced'> @@ -736,7 +723,7 @@ <para> As an example, consider the main formfactor recipe and a corresponding formfactor append file both from the - <link linkend='source-directory'>Source Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and located in the "meta" layer at @@ -975,128 +962,163 @@ ... EXTRA_OECONF = "--enable-something --enable-somethingelse" ... - </literallayout></para></listitem> - </itemizedlist></para></listitem> + </literallayout> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis><filename>layerindex-fetch</filename>:</emphasis> + Fetches a layer from a layer index, along with its + dependent layers, and adds the layers to the + <filename>conf/bblayers.conf</filename> file. + </para></listitem> + <listitem><para> + <emphasis><filename>layerindex-show-depends</filename>:</emphasis> + Finds layer dependencies from the layer index. + </para></listitem> + <listitem><para> + <emphasis><filename>create-layer</filename>:</emphasis> + Creates a basic layer. + </para></listitem> </itemizedlist> </para> </section> - <section id='creating-a-general-layer-using-the-yocto-layer-script'> - <title>Creating a General Layer Using the yocto-layer Script</title> + <section id='creating-a-general-layer-using-the-bitbake-layers-script'> + <title>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</title> <para> - The <filename>yocto-layer</filename> script simplifies + The <filename>bitbake-layers</filename> script with the + <filename>create-layer</filename> subcommand simplifies creating a new general layer. - <note> - For information on BSP layers, see the - "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" - section in the Yocto Project Board Specific (BSP) - Developer's Guide. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + For information on BSP layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Specific (BSP) + Developer's Guide. + </para></listitem> + <listitem><para> + The <filename>bitbake-layers</filename> script + replaces the <filename>yocto-layer</filename> + script, which is deprecated in the Yocto Project + 2.4 release. + The <filename>yocto-layer</filename> script + continues to function as part of the 2.4 release + but will be removed post 2.4. + </para></listitem> + </itemizedlist> </note> - The default mode of the script's operation is to prompt you for - information needed to generate the layer: + The default mode of the script's operation with this + subcommand is to create a layer with the following: <itemizedlist> - <listitem><para>The layer priority. + <listitem><para>A layer priority of 6. </para></listitem> - <listitem><para>Whether or not to create a sample recipe. + <listitem><para>A <filename>conf</filename> + subdirectory that contains a + <filename>layer.conf</filename> file. </para></listitem> - <listitem><para>Whether or not to create a sample - append file. - </para></listitem> - </itemizedlist> - </para> - - <para> - Use the <filename>yocto-layer create</filename> sub-command - to create a new general layer. - In its simplest form, you can create a layer as follows: - <literallayout class='monospaced'> - $ yocto-layer create mylayer - </literallayout> - The previous example creates a layer named - <filename>meta-mylayer</filename> in the current directory. - </para> - - <para> - As the <filename>yocto-layer create</filename> command runs, - default values for the prompts appear in brackets. - Pressing enter without supplying anything for the prompts - or pressing enter and providing an invalid response causes the - script to accept the default value. - Once the script completes, the new layer - is created in the current working directory. - The script names the layer by prepending - <filename>meta-</filename> to the name you provide. - </para> - - <para> - Minimally, the script creates the following within the layer: - <itemizedlist> - <listitem><para><emphasis>The <filename>conf</filename> - directory:</emphasis> - This directory contains the layer's configuration file. - The root name for the file is the same as the root name - your provided for the layer (e.g. - <filename><replaceable>layer</replaceable>.conf</filename>). + <listitem><para> + A <filename>recipes-example</filename> subdirectory + that contains a further subdirectory named + <filename>example</filename>, which contains + an <filename>example.bb</filename> recipe file. </para></listitem> - <listitem><para><emphasis>The - <filename>COPYING.MIT</filename> file:</emphasis> - The copyright and use notice for the software. + <listitem><para>A <filename >COPYING.MIT</filename>, + which is the license statement for the layer. + The script assumes you want to use the MIT license, + which is typical for most layers, for the contents of + the layer itself. </para></listitem> - <listitem><para><emphasis>The <filename>README</filename> - file:</emphasis> - A file describing the contents of your new layer. + <listitem><para> + A <filename>README</filename> file, which is a file + describing the contents of your new layer. </para></listitem> </itemizedlist> </para> <para> - If you choose to generate a sample recipe file, the script - prompts you for the name for the recipe and then creates it - in <filename><replaceable>layer</replaceable>/recipes-example/example/</filename>. - The script creates a <filename>.bb</filename> file and a - directory, which contains a sample - <filename>helloworld.c</filename> source file, along with - a sample patch file. - If you do not provide a recipe name, the script uses - "example". + In its simplest form, you can use the following command form + to create a layer. + The command creates a layer whose name corresponds to + <replaceable>your_layer_name</replaceable> in the current + directory: + <literallayout class='monospaced'> + $ bitbake-layers create-layer <replaceable>your_layer_name</replaceable> + </literallayout> </para> <para> - If you choose to generate a sample append file, the script - prompts you for the name for the file and then creates it - in <filename><replaceable>layer</replaceable>/recipes-example-bbappend/example-bbappend/</filename>. - The script creates a <filename>.bbappend</filename> file and a - directory, which contains a sample patch file. - If you do not provide a recipe name, the script uses - "example". - The script also prompts you for the version of the append file. - The version should match the recipe to which the append file - is associated. + If you want to set the priority of the layer to other than the + default value of "6", you can either use the + <filename>‐‐priority</filename> option or you can + edit the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink> + value in the <filename>conf/layer.conf</filename> after the + script creates it. + Furthermore, if you want to give the example recipe file + some name other than the default, you can + use the + <filename>‐‐example-recipe-name</filename> option. </para> <para> - The easiest way to see how the <filename>yocto-layer</filename> - script works is to experiment with the script. + The easiest way to see how the + <filename>bitbake-layers create-layer</filename> command + works is to experiment with the script. You can also read the usage information by entering the following: <literallayout class='monospaced'> - $ yocto-layer help + $ bitbake-layers create-layer --help + NOTE: Starting bitbake server... + usage: bitbake-layers create-layer [-h] [--priority PRIORITY] + [--example-recipe-name EXAMPLERECIPE] + layerdir + + Create a basic layer + + positional arguments: + layerdir Layer directory to create + + optional arguments: + -h, --help show this help message and exit + --priority PRIORITY, -p PRIORITY + Layer directory to create + --example-recipe-name EXAMPLERECIPE, -e EXAMPLERECIPE + Filename of the example recipe </literallayout> </para> <para> Once you create your general layer, you must add it to your <filename>bblayers.conf</filename> file. + You can add your layer by using the + <filename>bitbake-layers add-layer</filename> command: + <literallayout class='monospaced'> + $ bitbake-layers add-layer <replaceable>your_layer_name</replaceable> + </literallayout> Here is an example where a layer named - <filename>meta-mylayer</filename> is added: + <filename>meta-scottrif</filename> is added and then the + layers are shown using the + <filename>bitbake-layers show-layers</filename> command: <literallayout class='monospaced'> - BBLAYERS = ?" \ - /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-poky \ - /usr/local/src/yocto/meta-yocto-bsp \ - /usr/local/src/yocto/meta-mylayer \ - " + $ bitbake-layers add-layer meta-scottrif + NOTE: Starting bitbake server... + Loading cache: 100% |############################################| Time: 0:00:00 + Loaded 1275 entries from dependency cache. + Parsing recipes: 100% |##########################################| Time: 0:00:00 + Parsing of 819 .bb files complete (817 cached, 2 parsed). 1276 targets, 44 skipped, 0 masked, 0 errors. + $ bitbake-layers show-layers + NOTE: Starting bitbake server... + layer path priority + ========================================================================== + meta /home/scottrif/poky/meta 5 + meta-poky /home/scottrif/poky/meta-poky 5 + meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5 + meta-mylayer /home/scottrif/meta-mylayer 6 + workspace /home/scottrif/poky/build/workspace 99 + meta-scottrif /home/scottrif/poky/build/meta-scottrif 6 </literallayout> Adding the layer to this file enables the build system to locate the layer during the build. @@ -1193,7 +1215,7 @@ from within a recipe and using <filename>EXTRA_IMAGE_FEATURES</filename> from within your <filename>local.conf</filename> file, which is found in the - <link linkend='build-directory'>Build Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. </para> <para> @@ -1496,6 +1518,11 @@ similar in function to the recipe you need. </para></listitem> </itemizedlist> + <note> + For information on recipe syntax, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#recipe-syntax'>Recipe Syntax</ulink>" + section in the Yocto Project Reference Manual. + </note> </para> <section id='new-recipe-creating-the-base-recipe-using-devtool'> @@ -1516,8 +1543,9 @@ <para> You can find a complete description of the <filename>devtool add</filename> command in the - "<link linkend='use-devtool-to-integrate-new-code'>Use <filename>devtool add</filename> to Add an Application</link>" - section. + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-a-closer-look-at-devtool-add'>A Closer Look at <filename>devtool</filename> add</ulink>" + section in the Yocto Project Application Development + and the Extensible Software Development Kit (eSDK) manual. </para> </section> @@ -1540,12 +1568,10 @@ <para> To run the tool, you just need to be in your - <link linkend='build-directory'>Build Directory</link> + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> and have sourced the build environment setup script (i.e. - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>). Here is the basic <filename>recipetool</filename> syntax: <note> Running <filename>recipetool -h</filename> or @@ -1715,303 +1741,6 @@ </itemizedlist> </section> - <section id='understanding-recipe-syntax'> - <title>Understanding Recipe Syntax</title> - - <para> - Understanding recipe file syntax is important for - writing recipes. - The following list overviews the basic items that make up a - BitBake recipe file. - For more complete BitBake syntax descriptions, see the - "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>" - chapter of the BitBake User Manual. - <itemizedlist> - <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis> - Variable assignments allow a value to be assigned to a - variable. - The assignment can be static text or might include - the contents of other variables. - In addition to the assignment, appending and prepending - operations are also supported.</para> - <para>The following example shows some of the ways - you can use variables in recipes: - <literallayout class='monospaced'> - S = "${WORKDIR}/postfix-${PV}" - CFLAGS += "-DNO_ASM" - SRC_URI_append = " file://fixup.patch" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Functions:</emphasis> - Functions provide a series of actions to be performed. - You usually use functions to override the default - implementation of a task function or to complement - a default function (i.e. append or prepend to an - existing function). - Standard functions use <filename>sh</filename> shell - syntax, although access to OpenEmbedded variables and - internal methods are also available.</para> - <para>The following is an example function from the - <filename>sed</filename> recipe: - <literallayout class='monospaced'> - do_install () { - autotools_do_install - install -d ${D}${base_bindir} - mv ${D}${bindir}/sed ${D}${base_bindir}/sed - rmdir ${D}${bindir}/ - } - </literallayout> - It is also possible to implement new functions that - are called between existing tasks as long as the - new functions are not replacing or complementing the - default functions. - You can implement functions in Python - instead of shell. - Both of these options are not seen in the majority of - recipes.</para></listitem> - <listitem><para><emphasis>Keywords:</emphasis> - BitBake recipes use only a few keywords. - You use keywords to include common - functions (<filename>inherit</filename>), load parts - of a recipe from other files - (<filename>include</filename> and - <filename>require</filename>) and export variables - to the environment (<filename>export</filename>).</para> - <para>The following example shows the use of some of - these keywords: - <literallayout class='monospaced'> - export POSTCONF = "${STAGING_BINDIR}/postconf" - inherit autoconf - require otherfile.inc - </literallayout> - </para></listitem> - <listitem><para><emphasis>Comments:</emphasis> - Any lines that begin with the hash character - (<filename>#</filename>) are treated as comment lines - and are ignored: - <literallayout class='monospaced'> - # This is a comment - </literallayout> - </para></listitem> - </itemizedlist> - </para> - - <para> - This next list summarizes the most important and most commonly - used parts of the recipe syntax. - For more information on these parts of the syntax, you can - reference the - <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink> - chapter in the BitBake User Manual. - <itemizedlist> - <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> - - Use the backward slash (<filename>\</filename>) - character to split a statement over multiple lines. - Place the slash character at the end of the line that - is to be continued on the next line: - <literallayout class='monospaced'> - VAR = "A really long \ - line" - </literallayout> - <note> - You cannot have any characters including spaces - or tabs after the slash character. - </note> - </para></listitem> - <listitem><para> - <emphasis>Using Variables: <filename>${...}</filename></emphasis> - - Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to - access the contents of a variable: - <literallayout class='monospaced'> - SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" - </literallayout> - <note> - It is important to understand that the value of a - variable expressed in this form does not get - substituted automatically. - The expansion of these expressions happens - on-demand later (e.g. usually when a function that - makes reference to the variable executes). - This behavior ensures that the values are most - appropriate for the context in which they are - finally used. - On the rare occasion that you do need the variable - expression to be expanded immediately, you can use - the <filename>:=</filename> operator instead of - <filename>=</filename> when you make the - assignment, but this is not generally needed. - </note> - </para></listitem> - <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> - - Use double quotes around the value in all variable - assignments. - <literallayout class='monospaced'> - VAR1 = "${OTHERVAR}" - VAR2 = "The version is ${PV}" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> - - Conditional assignment is used to assign a value to - a variable, but only when the variable is currently - unset. - Use the question mark followed by the equal sign - (<filename>?=</filename>) to make a "soft" assignment - used for conditional assignment. - Typically, "soft" assignments are used in the - <filename>local.conf</filename> file for variables - that are allowed to come through from the external - environment. - </para> - <para>Here is an example where - <filename>VAR1</filename> is set to "New value" if - it is currently empty. - However, if <filename>VAR1</filename> has already been - set, it remains unchanged: - <literallayout class='monospaced'> - VAR1 ?= "New value" - </literallayout> - In this next example, <filename>VAR1</filename> - is left with the value "Original value": - <literallayout class='monospaced'> - VAR1 = "Original value" - VAR1 ?= "New value" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> - - Use the plus character followed by the equals sign - (<filename>+=</filename>) to append values to existing - variables. - <note> - This operator adds a space between the existing - content of the variable and the new content. - </note></para> - <para>Here is an example: - <literallayout class='monospaced'> - SRC_URI += "file://fix-makefile.patch" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> - - Use the equals sign followed by the plus character - (<filename>=+</filename>) to prepend values to existing - variables. - <note> - This operator adds a space between the new content - and the existing content of the variable. - </note></para> - <para>Here is an example: - <literallayout class='monospaced'> - VAR =+ "Starts" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> - - Use the <filename>_append</filename> operator to - append values to existing variables. - This operator does not add any additional space. - Also, the operator is applied after all the - <filename>+=</filename>, and - <filename>=+</filename> operators have been applied and - after all <filename>=</filename> assignments have - occurred. - </para> - <para>The following example shows the space being - explicitly added to the start to ensure the appended - value is not merged with the existing value: - <literallayout class='monospaced'> - SRC_URI_append = " file://fix-makefile.patch" - </literallayout> - You can also use the <filename>_append</filename> - operator with overrides, which results in the actions - only being performed for the specified target or - machine: - <literallayout class='monospaced'> - SRC_URI_append_sh4 = " file://fix-makefile.patch" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> - - Use the <filename>_prepend</filename> operator to - prepend values to existing variables. - This operator does not add any additional space. - Also, the operator is applied after all the - <filename>+=</filename>, and - <filename>=+</filename> operators have been applied and - after all <filename>=</filename> assignments have - occurred. - </para> - <para>The following example shows the space being - explicitly added to the end to ensure the prepended - value is not merged with the existing value: - <literallayout class='monospaced'> - CFLAGS_prepend = "-I${S}/myincludes " - </literallayout> - You can also use the <filename>_prepend</filename> - operator with overrides, which results in the actions - only being performed for the specified target or - machine: - <literallayout class='monospaced'> - CFLAGS_prepend_sh4 = "-I${S}/myincludes " - </literallayout> - </para></listitem> - <listitem><para><emphasis>Overrides:</emphasis> - - You can use overrides to set a value conditionally, - typically based on how the recipe is being built. - For example, to set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> - variable's value to "standard/base" for any target - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, - except for qemuarm where it should be set to - "standard/arm-versatile-926ejs", you would do the - following: - <literallayout class='monospaced'> - KBRANCH = "standard/base" - KBRANCH_qemuarm = "standard/arm-versatile-926ejs" - </literallayout> - Overrides are also used to separate alternate values - of a variable in other situations. - For example, when setting variables such as - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> - that are specific to individual packages produced by - a recipe, you should always use an override that - specifies the name of the package. - </para></listitem> - <listitem><para><emphasis>Indentation:</emphasis> - Use spaces for indentation rather than than tabs. - For shell functions, both currently work. - However, it is a policy decision of the Yocto Project - to use tabs in shell functions. - Realize that some layers have a policy to use spaces - for all indentation. - </para></listitem> - <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> - - For more advanced processing, it is possible to use - Python code during variable assignments (e.g. - search and replacement on a variable).</para> - <para>You indicate Python code using the - <filename>${@<replaceable>python_code</replaceable>}</filename> - syntax for the variable assignment: - <literallayout class='monospaced'> - SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz - </literallayout> - </para></listitem> - <listitem><para><emphasis>Shell Function Syntax:</emphasis> - Write shell functions as if you were writing a shell - script when you describe a list of actions to take. - You should ensure that your script works with a generic - <filename>sh</filename> and that it does not require - any <filename>bash</filename> or other shell-specific - functionality. - The same considerations apply to various system - utilities (e.g. <filename>sed</filename>, - <filename>grep</filename>, <filename>awk</filename>, - and so forth) that you might wish to use. - If in doubt, you should check with multiple - implementations - including those from BusyBox. - </para></listitem> - </itemizedlist> - </para> - </section> - <section id='new-recipe-running-a-build-on-the-recipe'> <title>Running a Build on the Recipe</title> @@ -2023,12 +1752,10 @@ </para> <para> - Assuming you have sourced a build environment setup script (i.e. - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) + Assuming you have sourced the build environment setup script (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>) and you are in the - <link linkend='build-directory'>Build Directory</link>, + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, use BitBake to process your recipe. All you need to provide is the <filename><replaceable>basename</replaceable></filename> of the recipe as described @@ -2083,8 +1810,8 @@ </para> <para> - You can find more information about the build process in the - "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>" + You can find more information about the build process in + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-development-environment'>The Yocto Project Development Environment</ulink>" chapter of the Yocto Project Reference Manual. </para> </section> @@ -3074,7 +2801,7 @@ class. See the <filename>systemd.bbclass</filename> file located in your - <link linkend='source-directory'>Source Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. section for more information. </para></listitem> </itemizedlist> @@ -3967,6 +3694,417 @@ </section> </section> + <section id='finding-the-temporary-source-code'> + <title>Finding Temporary Source Code</title> + + <para> + You might find it helpful during development to modify the + temporary source code used by recipes to build packages. + For example, suppose you are developing a patch and you need to + experiment a bit to figure out your solution. + After you have initially built the package, you can iteratively + tweak the source code, which is located in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, + and then you can force a re-compile and quickly test your altered + code. + Once you settle on a solution, you can then preserve your changes + in the form of patches. + </para> + + <para> + During a build, the unpacked temporary source code used by recipes + to build packages is available in the Build Directory as + defined by the + <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> + variable. + Below is the default value for the <filename>S</filename> variable + as defined in the + <filename>meta/conf/bitbake.conf</filename> configuration file + in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>: + <literallayout class='monospaced'> + S = "${WORKDIR}/${BP}" + </literallayout> + You should be aware that many recipes override the + <filename>S</filename> variable. + For example, recipes that fetch their source from Git usually set + <filename>S</filename> to <filename>${WORKDIR}/git</filename>. + <note> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> + represents the base recipe name, which consists of the name + and version: + <literallayout class='monospaced'> + BP = "${BPN}-${PV}" + </literallayout> + </note> + </para> + + <para> + The path to the work directory for the recipe + (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) + is defined as follows: + <literallayout class='monospaced'> + ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} + </literallayout> + The actual directory depends on several things: + <itemizedlist> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>: + The top-level build output directory. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>: + The target system identifier. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>: + The recipe name. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>: + The epoch - (if + <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink> + is not specified, which is usually the case for most + recipes, then <filename>EXTENDPE</filename> is blank). + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: + The recipe version. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: + The recipe revision. + </para></listitem> + </itemizedlist> + </para> + + <para> + As an example, assume a Source Directory top-level folder + named <filename>poky</filename>, a default Build Directory at + <filename>poky/build</filename>, and a + <filename>qemux86-poky-linux</filename> machine target + system. + Furthermore, suppose your recipe is named + <filename>foo_1.3.0.bb</filename>. + In this case, the work directory the build system uses to + build the package would be as follows: + <literallayout class='monospaced'> + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + </literallayout> + </para> + </section> + + <section id="using-a-quilt-workflow"> + <title>Using Quilt in Your Workflow</title> + + <para> + <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> + is a powerful tool that allows you to capture source code changes + without having a clean source tree. + This section outlines the typical workflow you can use to modify + source code, test changes, and then preserve the changes in the + form of a patch all using Quilt. + <note><title>Tip</title> + With regard to preserving changes to source files, if you + clean a recipe or have <filename>rm_work</filename> enabled, + the + <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink> + as described in the Yocto Project Application Development + and the Extensible Software Development Kit (eSDK) manual + is a safer development flow than the flow that uses Quilt. + </note> + </para> + + <para> + Follow these general steps: + <orderedlist> + <listitem><para> + <emphasis>Find the Source Code:</emphasis> + Temporary source code used by the OpenEmbedded build system + is kept in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. + See the + "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>" + section to learn how to locate the directory that has the + temporary source code for a particular package. + </para></listitem> + <listitem><para> + <emphasis>Change Your Working Directory:</emphasis> + You need to be in the directory that has the temporary + source code. + That directory is defined by the + <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> + variable.</para></listitem> + <listitem><para> + <emphasis>Create a New Patch:</emphasis> + Before modifying source code, you need to create a new + patch. + To create a new patch file, use + <filename>quilt new</filename> as below: + <literallayout class='monospaced'> + $ quilt new my_changes.patch + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Notify Quilt and Add Files:</emphasis> + After creating the patch, you need to notify Quilt about + the files you plan to edit. + You notify Quilt by adding the files to the patch you + just created: + <literallayout class='monospaced'> + $ quilt add file1.c file2.c file3.c + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Edit the Files:</emphasis> + Make your changes in the source code to the files you added + to the patch. + </para></listitem> + <listitem><para> + <emphasis>Test Your Changes:</emphasis> + Once you have modified the source code, the easiest way to + test your changes is by calling the + <filename>do_compile</filename> task as shown in the + following example: + <literallayout class='monospaced'> + $ bitbake -c compile -f <replaceable>package</replaceable> + </literallayout> + The <filename>-f</filename> or <filename>--force</filename> + option forces the specified task to execute. + If you find problems with your code, you can just keep + editing and re-testing iteratively until things work + as expected. + <note> + All the modifications you make to the temporary + source code disappear once you run the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink> + tasks using BitBake (i.e. + <filename>bitbake -c clean <replaceable>package</replaceable></filename> + and + <filename>bitbake -c cleanall <replaceable>package</replaceable></filename>). + 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. + </note> + </para></listitem> + <listitem><para> + <emphasis>Generate the Patch:</emphasis> + Once your changes work as expected, you need to use Quilt + to generate the final patch that contains all your + modifications. + <literallayout class='monospaced'> + $ quilt refresh + </literallayout> + At this point, the <filename>my_changes.patch</filename> + file has all your edits made to the + <filename>file1.c</filename>, <filename>file2.c</filename>, + and <filename>file3.c</filename> files.</para> + + <para>You can find the resulting patch file in the + <filename>patches/</filename> subdirectory of the source + (<filename>S</filename>) directory. + </para></listitem> + <listitem><para> + <emphasis>Copy the Patch File:</emphasis> + For simplicity, copy the patch file into a directory + named <filename>files</filename>, which you can create + in the same directory that holds the recipe + (<filename>.bb</filename>) file or the append + (<filename>.bbappend</filename>) file. + Placing the patch here guarantees that the OpenEmbedded + build system will find the patch. + Next, add the patch into the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> + of the recipe. + Here is an example: + <literallayout class='monospaced'> + SRC_URI += "file://my_changes.patch" + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id="platdev-appdev-devshell"> + <title>Using a Development Shell</title> + + <para> + When debugging certain commands or even when just editing packages, + <filename>devshell</filename> can be a useful tool. + When you invoke <filename>devshell</filename>, all tasks up to and + including + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> + are run for the specified target. + Then, a new terminal is opened and you are placed in + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>, + the source directory. + In the new terminal, all the OpenEmbedded build-related environment variables are + still defined so you can use commands such as <filename>configure</filename> and + <filename>make</filename>. + The commands execute just as if the OpenEmbedded build system were executing them. + Consequently, working this way can be helpful when debugging a build or preparing + software to be used with the OpenEmbedded build system. + </para> + + <para> + Following is an example that uses <filename>devshell</filename> on a target named + <filename>matchbox-desktop</filename>: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c devshell + </literallayout> + </para> + + <para> + This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. + The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink> + variable controls what type of shell is opened. + </para> + + <para> + For spawned terminals, the following occurs: + <itemizedlist> + <listitem><para>The <filename>PATH</filename> variable includes the + cross-toolchain.</para></listitem> + <listitem><para>The <filename>pkgconfig</filename> variables find the correct + <filename>.pc</filename> files.</para></listitem> + <listitem><para>The <filename>configure</filename> command finds the + Yocto Project site files as well as any other necessary files.</para></listitem> + </itemizedlist> + </para> + + <para> + Within this environment, you can run configure or compile + commands as if they were being run by + the OpenEmbedded build system itself. + As noted earlier, the working directory also automatically changes to the + Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>). + </para> + + <para> + To manually run a specific task using <filename>devshell</filename>, + run the corresponding <filename>run.*</filename> script in + the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename> + directory (e.g., + <filename>run.do_configure.</filename><replaceable>pid</replaceable>). + If a task's script does not exist, which would be the case if the task was + skipped by way of the sstate cache, you can create the task by first running + it outside of the <filename>devshell</filename>: + <literallayout class='monospaced'> + $ bitbake -c <replaceable>task</replaceable> + </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para>Execution of a task's <filename>run.*</filename> + script and BitBake's execution of a task are identical. + In other words, running the script re-runs the task + just as it would be run using the + <filename>bitbake -c</filename> command. + </para></listitem> + <listitem><para>Any <filename>run.*</filename> file that does not + have a <filename>.pid</filename> extension is a + symbolic link (symlink) to the most recent version of that + file. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + Remember, that the <filename>devshell</filename> is a mechanism that allows + you to get into the BitBake task execution environment. + And as such, all commands must be called just as BitBake would call them. + That means you need to provide the appropriate options for + cross-compilation and so forth as applicable. + </para> + + <para> + When you are finished using <filename>devshell</filename>, exit the shell + or close the terminal window. + </para> + + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + It is worth remembering that when using <filename>devshell</filename> + you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> + instead of just using <filename>gcc</filename>. + The same applies to other applications such as <filename>binutils</filename>, + <filename>libtool</filename> and so forth. + BitBake sets up environment variables such as <filename>CC</filename> + to assist applications, such as <filename>make</filename> to find the correct tools. + </para></listitem> + <listitem><para> + It is also worth noting that <filename>devshell</filename> still works over + X11 forwarding and similar situations. + </para></listitem> + </itemizedlist> + </note> + </section> + + <section id="platdev-appdev-devpyshell"> + <title>Using a Development Python Shell</title> + + <para> + Similar to working within a development shell as described in + the previous section, you can also spawn and work within an + interactive Python development shell. + When debugging certain commands or even when just editing packages, + <filename>devpyshell</filename> can be a useful tool. + When you invoke <filename>devpyshell</filename>, all tasks up to and + including + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> + are run for the specified target. + Then a new terminal is opened. + Additionally, key Python objects and code are available in the same + way they are to BitBake tasks, in particular, the data store 'd'. + So, commands such as the following are useful when exploring the data + store and running functions: + <literallayout class='monospaced'> + pydevshell> d.getVar("STAGING_DIR", True) + '/media/build1/poky/build/tmp/sysroots' + pydevshell> d.getVar("STAGING_DIR", False) + '${TMPDIR}/sysroots' + pydevshell> d.setVar("FOO", "bar") + pydevshell> d.getVar("FOO", True) + 'bar' + pydevshell> d.delVar("FOO") + pydevshell> d.getVar("FOO", True) + pydevshell> bb.build.exec_func("do_unpack", d) + pydevshell> + </literallayout> + The commands execute just as if the OpenEmbedded build system were executing them. + Consequently, working this way can be helpful when debugging a build or preparing + software to be used with the OpenEmbedded build system. + </para> + + <para> + Following is an example that uses <filename>devpyshell</filename> on a target named + <filename>matchbox-desktop</filename>: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c devpyshell + </literallayout> + </para> + + <para> + This command spawns a terminal and places you in an interactive + Python interpreter within the OpenEmbedded build environment. + The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink> + variable controls what type of shell is opened. + </para> + + <para> + When you are finished using <filename>devpyshell</filename>, you + can exit the shell either by using Ctrl+d or closing the terminal + window. + </para> + </section> + <section id='platdev-building-targets-with-multiple-configurations'> <title>Building Targets with Multiple Configurations</title> @@ -4177,7 +4315,7 @@ <para> Several examples exist in the <filename>meta-skeleton</filename> layer found in the - <link linkend='source-directory'>Source Directory</link>: + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>: <itemizedlist> <listitem><para><filename>conf/multilib-example.conf</filename> configuration file</para></listitem> @@ -4203,7 +4341,7 @@ Many standard recipes are already extended and support multiple libraries. You can check in the <filename>meta/conf/multilib.conf</filename> configuration file in the - <link linkend='source-directory'>Source Directory</link> to see how this is + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> to see how this is done using the <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink> variable. @@ -4239,7 +4377,7 @@ combination of multiple libraries you want to build. You accomplish this through your <filename>local.conf</filename> configuration file in the - <link linkend='build-directory'>Build Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. An example configuration would be as follows: <literallayout class='monospaced'> MACHINE = "qemux86-64" @@ -4315,7 +4453,7 @@ <listitem><para>A unique architecture is defined for the Multilib packages, along with creating a unique deploy folder under <filename>tmp/deploy/rpm</filename> in the - <link linkend='build-directory'>Build Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. For example, consider <filename>lib32</filename> in a <filename>qemux86-64</filename> image. The possible architectures in the system are "all", "qemux86_64", @@ -4675,8 +4813,8 @@ </para> </section> - <section id='creating-partitioned-images'> - <title>Creating Partitioned Images</title> + <section id='creating-partitioned-images-using-wic'> + <title>Creating Partitioned Images Using Wic</title> <para> Creating an image for a particular hardware target using the @@ -4692,1124 +4830,781 @@ </para> <para> - You can generate partitioned images - (<replaceable>image</replaceable><filename>.wic</filename>) - two ways: using the OpenEmbedded build system and by running - the OpenEmbedded Image Creator Wic directly. - The former way is preferable as it is easier to use and understand. + The <filename>wic</filename> command generates partitioned + images from existing OpenEmbedded build artifacts. + Image generation is driven by partitioning commands + contained in an Openembedded kickstart file + (<filename>.wks</filename>) specified either directly on + the command line or as one of a selection of canned + kickstart files as shown with the + <filename>wic list images</filename> command in the + "<link linkend='using-a-provided-kickstart-file'>Using an Existing Kickstart File</link>" + section. + When you apply the command to a given set of build + artifacts, the result is an image or set of images that + can be directly written onto media and used on a particular + 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>" + Chapter in the Yocto Project Reference Manual. + </note> </para> - <section id='creating-wic-images-oe'> - <title>Creating Partitioned Images</title> + <para> + The <filename>wic</filename> command and the infrastructure + it is based on is by definition incomplete. + The purpose of the command is to allow the generation of + customized images, and as such, was designed to be + completely extensible through a plug-in interface. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#wic-plug-ins-interface'>Wic Plug-Ins Interface</ulink>" + section in the Yocto Project Reference Manual for information + on these plug-ins. + </para> + + <para> + This section provides some background information on Wic, + describes what you need to have in + place to run the tool, provides instruction on how to use + the Wic utility, and provides several examples. + </para> + + <section id='wic-background'> + <title>Background</title> <para> - The OpenEmbedded build system can generate - partitioned images the same way as it generates - any other image type. - To generate a partitioned image, you need to modify - two variables. + This section provides some background on the Wic utility. + While none of this information is required to use + Wic, you might find it interesting. <itemizedlist> <listitem><para> + The name "Wic" is derived from OpenEmbedded + Image Creator (oeic). + The "oe" diphthong in "oeic" was promoted to the + letter "w", because "oeic" is both difficult to + remember and to pronounce. + </para></listitem> + <listitem><para> + Wic is loosely based on the + Meego Image Creator (<filename>mic</filename>) + framework. + The Wic implementation has been + heavily modified to make direct use of OpenEmbedded + build artifacts instead of package installation and + configuration, which are already incorporated within + the OpenEmbedded artifacts. + </para></listitem> + <listitem><para> + 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 + <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 + Wic and those examples is + that with Wic the + functionality of those scripts is implemented + by a general-purpose partitioning language, which is + based on Redhat kickstart syntax.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='wic-requirements'> + <title>Requirements</title> + + <para> + In order to use the Wic utility with the OpenEmbedded Build + system, your system needs to meet the following + requirements: + <itemizedlist> + <listitem><para> + The Linux distribution on your development host must + support the Yocto Project. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" + section in the Yocto Project Reference Manual for + the list of distributions that support the + Yocto Project. + </para></listitem> + <listitem><para> + The standard system utilities, such as + <filename>cp</filename>, must be installed on your + development host system. + </para></listitem> + <listitem><para> + You must have sourced the build environment + setup script (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>) + found in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. + </para></listitem> + <listitem><para> + You need to have the build artifacts already + available, which typically means that you must + have already created an image using the + Openembedded build system (e.g. + <filename>core-image-minimal</filename>). + While it might seem redundant to generate an image + in order to create an image using + Wic, the current version of + Wic requires the artifacts + in the form generated by the OpenEmbedded build + system. + </para></listitem> + <listitem><para> + You must build several native tools, which are + built to run on the build system: + <literallayout class='monospaced'> + $ bitbake parted-native dosfstools-native mtools-native + </literallayout> + </para></listitem> + <listitem><para> Include "wic" as part of the <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink> variable. </para></listitem> <listitem><para> Include the name of the - <link linkend='openembedded-kickstart-wks-reference'>wic kickstart file</link> + <ulink url='&YOCTO_DOCS_REF_URL;#openembedded-kickstart-wks-reference'>wic kickstart file</ulink> as part of the <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink> variable </para></listitem> </itemizedlist> - Further steps to generate a partitioned image - are the same as for any other image type. - For information on image types, see the - "<link linkend='building-images'>Building Images</link>" - section. </para> </section> - <section id='create-wic-images-wic'> - <title>Using OpenEmbedded Image Creator Wic to Generate Partitioned Images</title> + <section id='wic-getting-help'> + <title>Getting Help</title> <para> - The <filename>wic</filename> command generates partitioned - images from existing OpenEmbedded build artifacts. - Image generation is driven by partitioning commands - contained in an Openembedded kickstart file - (<filename>.wks</filename>) specified either directly on - the command line or as one of a selection of canned - <filename>.wks</filename> files as shown with the - <filename>wic list images</filename> command in the - "<link linkend='using-a-provided-kickstart-file'>Using an Existing Kickstart File</link>" - section. - When you apply the command to a given set of build - artifacts, the result is an image or set of images that - can be directly written onto media and used on a particular - system. + You can get general help for the <filename>wic</filename> + command by entering the <filename>wic</filename> command + by itself or by entering the command with a help argument + as follows: + <literallayout class='monospaced'> + $ wic -h + $ wic --help + </literallayout> </para> <para> - The <filename>wic</filename> command and the infrastructure - it is based on is by definition incomplete. - The purpose of the command is to allow the generation of - customized images, and as such, was designed to be - completely extensible through a plug-in interface. - See the - "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" - section for information on these plug-ins. + Currently, Wic supports seven commands: + <filename>cp</filename>, <filename>create</filename>, + <filename>help</filename>, <filename>list</filename>, + <filename>ls</filename>, <filename>rm</filename>, and + <filename>write</filename>. + You can get help for these commands as follows with + <replaceable>command</replaceable> being one of the + supported commands: + <literallayout class='monospaced'> + $ wic help <replaceable>command</replaceable> + </literallayout> </para> <para> - This section provides some background information on Wic, - describes what you need to have in - place to run the tool, provides instruction on how to use - the <filename>wic</filename> utility, - and provides several examples. + You can also get detailed help on a number of topics + from the help system. + The output of <filename>wic --help</filename> + displays a list of available help + topics under a "Help topics" heading. + You can have the help system display the help text for + a given topic by prefacing the topic with + <filename>wic help</filename>: + <literallayout class='monospaced'> + $ wic help <replaceable>help_topic</replaceable> + </literallayout> </para> - <section id='wic-background'> - <title>Background</title> + <para> + You can find out more about the images Wic creates using + the existing kickstart files with the following form of + the command: + <literallayout class='monospaced'> + $ wic list <replaceable>image</replaceable> help + </literallayout> + For <replaceable>image</replaceable>, you can provide + any of the following: + <literallayout class='monospaced'> + beaglebone + mpc8315e-rdb + genericx86 + edgerouter + qemux86-directdisk + directdisk-gpt + mkefidisk + directdisk + systemd-bootdisk + mkhybridiso + sdimage-bootpart + directdisk-multi-rootfs + directdisk-bootloader-config + </literallayout> + </para> + </section> - <para> - This section provides some background on the - <filename>wic</filename> utility. - While none of this information is required to use - Wic, you might find it interesting. - <itemizedlist> - <listitem><para> - The name "Wic" is derived from OpenEmbedded - Image Creator (oeic). - The "oe" diphthong in "oeic" was promoted to the - letter "w", because "oeic" is both difficult to - remember and to pronounce. - </para></listitem> - <listitem><para> - Wic is loosely based on the - Meego Image Creator (<filename>mic</filename>) - framework. - The Wic implementation has been - heavily modified to make direct use of OpenEmbedded - build artifacts instead of package installation and - configuration, which are already incorporated within - the OpenEmbedded artifacts. - </para></listitem> - <listitem><para> - 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 - <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 - Wic and those examples is - that with Wic the - functionality of those scripts is implemented - by a general-purpose partitioning language, which is - based on Redhat kickstart syntax.</para></listitem> - </itemizedlist> - </para> - </section> + <section id='operational-modes'> + <title>Operational Modes</title> - <section id='wic-requirements'> - <title>Requirements</title> + <para> + You can use Wic in two different + modes, depending on how much control you need for + specifying the Openembedded build artifacts that are + used for creating the image: Raw and Cooked: + <itemizedlist> + <listitem><para> + <emphasis>Raw Mode:</emphasis> + You explicitly specify build artifacts through + <filename>wic</filename> command-line arguments. + </para></listitem> + <listitem><para> + <emphasis>Cooked Mode:</emphasis> + The current + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + setting and image name are used to automatically + locate and provide the build artifacts. + You just supply a kickstart file and the name + of the image from which to use artifacts. + </para></listitem> + </itemizedlist> + </para> - <para> - In order to use the <filename>wic</filename> utility - with the OpenEmbedded Build system, your system needs - to meet the following requirements: - <itemizedlist> - <listitem><para>The Linux distribution on your - development host must support the Yocto Project. - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" - section in the Yocto Project Reference Manual for - the list of distributions that support the - Yocto Project. - </para></listitem> - <listitem><para> - The standard system utilities, such as - <filename>cp</filename>, must be installed on your - development host system. - </para></listitem> - <listitem><para> - You need to have the build artifacts already - available, which typically means that you must - have already created an image using the - Openembedded build system (e.g. - <filename>core-image-minimal</filename>). - While it might seem redundant to generate an image - in order to create an image using - Wic, the current version of - Wic requires the artifacts - in the form generated by the build system. - </para></listitem> - <listitem><para> - You must build several native tools, which are tools - built to run on the build system: - <literallayout class='monospaced'> - $ bitbake parted-native dosfstools-native mtools-native - </literallayout> - </para></listitem> - <listitem><para> - You must have sourced one of the build environment - setup scripts (i.e. - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) - found in the - <link linkend='build-directory'>Build Directory</link>. - </para></listitem> - </itemizedlist> - </para> - </section> + <para> + Regardless of the mode you use, you need to have the build + artifacts ready and available. + </para> - <section id='wic-getting-help'> - <title>Getting Help</title> + <section id='raw-mode'> + <title>Raw Mode</title> <para> - You can get general help for the <filename>wic</filename> - command by entering the <filename>wic</filename> command - by itself or by entering the command with a help argument - as follows: - <literallayout class='monospaced'> - $ wic -h - $ wic --help - </literallayout> + Running Wic in raw mode allows you to specify all the + partitions through the <filename>wic</filename> + command line. + The primary use for raw mode is if you have built + your kernel outside of the Yocto Project + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. + In other words, you can point to arbitrary kernel, + root filesystem locations, and so forth. + Contrast this behavior with cooked mode where Wic + looks in the Build Directory (e.g. + <filename>tmp/deploy/images/</filename><replaceable>machine</replaceable>). </para> <para> - Currently, Wic supports two commands: - <filename>create</filename> and <filename>list</filename>. - You can get help for these commands as follows: + The general form of the + <filename>wic</filename> command in raw mode is: <literallayout class='monospaced'> - $ wic help <replaceable>command</replaceable> - with <replaceable>command</replaceable> being either - <filename>create</filename> or <filename>list</filename>. - </literallayout> - </para> + $ wic create <replaceable>wks_file</replaceable> <replaceable>options</replaceable> ... - <para> - You can also get detailed help on a number of topics - from the help system. - The output of <filename>wic --help</filename> - displays a list of available help - topics under a "Help topics" heading. - You can have the help system display the help text for - a given topic by prefacing the topic with - <filename>wic help</filename>: - <literallayout class='monospaced'> - $ wic help <replaceable>help_topic</replaceable> - </literallayout> - </para> + Where: - <para> - You can find out more about the images - Wic creates using the existing - kickstart files with the following form of the command: - <literallayout class='monospaced'> - $ wic list <replaceable>image</replaceable> help + <replaceable>wks_file</replaceable>: + An OpenEmbedded kickstart file. You can provide + your own custom file or use a file from a set of + existing files as described by further options. + + optional arguments: + -h, --help show this help message and exit + -o <replaceable>OUTDIR</replaceable>, --outdir <replaceable>OUTDIR</replaceable> + name of directory to create image in + -e <replaceable>IMAGE_NAME</replaceable>, --image-name <replaceable>IMAGE_NAME</replaceable> + name of the image to use the artifacts from e.g. core- + image-sato + -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir <replaceable>ROOTFS_DIR</replaceable> + path to the /rootfs dir to use as the .wks rootfs + source + -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir <replaceable>BOOTIMG_DIR</replaceable> + path to the dir containing the boot artifacts (e.g. + /EFI or /syslinux dirs) to use as the .wks bootimg + source + -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir <replaceable>KERNEL_DIR</replaceable> + path to the dir containing the kernel to use in the + .wks bootimg + -n <replaceable>NATIVE_SYSROOT</replaceable>, --native-sysroot <replaceable>NATIVE_SYSROOT</replaceable> + path to the native sysroot containing the tools to use + to build the image + -s, --skip-build-check + skip the build check + -f, --build-rootfs build rootfs + -c {gzip,bzip2,xz}, --compress-with {gzip,bzip2,xz} + compress image with specified compressor + -m, --bmap generate .bmap + --no-fstab-update Do not change fstab file. + -v <replaceable>VARS_DIR</replaceable>, --vars <replaceable>VARS_DIR</replaceable> + directory with <image>.env files that store bitbake + variables + -D, --debug output debug information </literallayout> - with <filename><replaceable>image</replaceable></filename> - being either <filename>directdisk</filename> or - <filename>mkefidisk</filename>. + <note> + You do not need root privileges to run + Wic. + In fact, you should not run as root when using the + utility. + </note> </para> </section> - <section id='operational-modes'> - <title>Operational Modes</title> + <section id='cooked-mode'> + <title>Cooked Mode</title> <para> - You can use Wic in two different - modes, depending on how much control you need for - specifying the Openembedded build artifacts that are - used for creating the image: Raw and Cooked: - <itemizedlist> - <listitem><para> - <emphasis>Raw Mode:</emphasis> - You explicitly specify build artifacts through - command-line arguments. - </para></listitem> - <listitem><para> - <emphasis>Cooked Mode:</emphasis> - The current - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - setting and image name are used to automatically - locate and provide the build artifacts. - </para></listitem> - </itemizedlist> + Running Wic in cooked mode leverages off artifacts in + Build Directory. + In other words, you do not have to specify kernel or + root filesystem locations as part of the command. + All you need to provide is a kickstart file and the + name of the image from which to use artifacts by using + the "-e" option. + Wic looks in the Build Directory (e.g. + <filename>tmp/deploy/images/</filename><replaceable>machine</replaceable>) + for artifacts. </para> <para> - Regardless of the mode you use, you need to have the build - artifacts ready and available. - Additionally, the environment must be set up using the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> - script found in the - <link linkend='build-directory'>Build Directory</link>. - </para> - - <section id='raw-mode'> - <title>Raw Mode</title> - - <para> - The general form of the - <filename>wic</filename> command in raw mode is: - <literallayout class='monospaced'> - $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...] + The general form of the <filename>wic</filename> + command using Cooked Mode is as follows: + <literallayout class='monospaced'> + $ wic create <replaceable>wks_file</replaceable> -e <replaceable>IMAGE_NAME</replaceable> Where: - <replaceable>image_name</replaceable>.wks + <replaceable>wks_file</replaceable>: An OpenEmbedded kickstart file. You can provide your own custom file or use a file from a set of - existing files as described by further options. - - -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable> - The name of a directory in which to create image. - - -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable> - The name of a file containing the values for image - properties as a JSON file. - - -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable> - The name of the image from which to use the artifacts - (e.g. <filename>core-image-sato</filename>). - - -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> - The path to the <filename>/rootfs</filename> directory to use as the - <filename>.wks</filename> rootfs source. - - -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> - The path to the directory containing the boot artifacts - (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg - source. - - -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable> - The path to the directory containing the kernel to use - in the <filename>.wks</filename> boot image. + existing files provided with the Yocto Project + release. - -n <replaceable>NATIVE_SYSROOT</replaceable>, --native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> - The path to the native sysroot containing the tools to use - to build the image. - - -s, --skip-build-check - Skips the build check. - - -D, --debug - Output debug information. - </literallayout> - <note> - You do not need root privileges to run - Wic. - In fact, you should not run as root when using the - utility. - </note> - </para> - </section> - - <section id='cooked-mode'> - <title>Cooked Mode</title> - - <para> - The general form of the <filename>wic</filename> command - using Cooked Mode is: - <literallayout class='monospaced'> - $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable> - - Where: - - <replaceable>kickstart_file</replaceable> - An OpenEmbedded kickstart file. You can provide your own - custom file or a supplied file. - - <replaceable>image_name</replaceable> - Specifies the image built using the OpenEmbedded build - system. - </literallayout> - This form is the simplest and most user-friendly, as it - does not require specifying all individual parameters. - All you need to provide is your own - <filename>.wks</filename> file or one provided with the - release. - </para> - </section> + required argument: + -e <replaceable>IMAGE_NAME</replaceable>, --image-name <replaceable>IMAGE_NAME</replaceable> + name of the image to use the artifacts from e.g. core- + image-sato + </literallayout> + </para> </section> + </section> - <section id='using-a-provided-kickstart-file'> - <title>Using an Existing Kickstart File</title> + <section id='using-a-provided-kickstart-file'> + <title>Using an Existing Kickstart File</title> - <para> - If you do not want to create your own - <filename>.wks</filename> file, you can use an existing - file provided by the Wic installation. - Use the following command to list the available files: - <literallayout class='monospaced'> + <para> + If you do not want to create your own kickstart file, you + 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_REF_URL;#source-repositories'>Source Repositories</ulink> + in the following two locations: + <literallayout class='monospaced'> + poky/meta-yocto-bsp/wic + poky/scripts/lib/wic/canned-wks + </literallayout> + Use the following command to list the available kickstart + files: + <literallayout class='monospaced'> $ wic list images - directdisk Create a 'pcbios' direct disk image - mkefidisk Create an EFI disk image - </literallayout> - When you use an existing file, you do not have to use the - <filename>.wks</filename> extension. - Here is an example in Raw Mode that uses the - <filename>directdisk</filename> file: - <literallayout class='monospaced'> + beaglebone Create SD card image for Beaglebone + mpc8315e-rdb Create SD card image for MPC8315E-RDB + genericx86 Create an EFI disk image for genericx86* + edgerouter Create SD card image for Edgerouter + qemux86-directdisk Create a qemu machine 'pcbios' direct disk image + directdisk-gpt Create a 'pcbios' direct disk image + mkefidisk Create an EFI disk image + directdisk Create a 'pcbios' direct disk image + systemd-bootdisk Create an EFI disk image with systemd-boot + mkhybridiso Create a hybrid ISO image + sdimage-bootpart Create SD card image with a boot partition + directdisk-multi-rootfs Create multi rootfs image using rootfs plugin + directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config + </literallayout> + When you use an existing file, you do not have to use the + <filename>.wks</filename> extension. + Here is an example in Raw Mode that uses the + <filename>directdisk</filename> file: + <literallayout class='monospaced'> $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \ -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable> - </literallayout> - </para> - - <para> - Here are the actual partition language commands - used in the <filename>mkefidisk.wks</filename> file to - generate an image: - <literallayout class='monospaced'> - # short-description: Create an EFI disk image - # long-description: Creates a partitioned EFI disk image that the user - # can directly dd to boot media. - - part /boot --source bootimg-efi --ondisk sda --label msdos --active --align 1024 - - part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 + </literallayout> + </para> + <para> + Here are the actual partition language commands + used in the <filename>genericx86.wks</filename> file to + generate an image: + <literallayout class='monospaced'> + # short-description: Create an EFI disk image for genericx86* + # long-description: Creates a partitioned EFI disk image for genericx86* machines + part /boot --source bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos --active --align 1024 + part / --source rootfs --ondisk sda --fstype=ext4 --label platform --align 1024 --use-uuid part swap --ondisk sda --size 44 --label swap1 --fstype=swap - bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0" - </literallayout> - </para> - </section> + bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0" + </literallayout> + </para> + </section> - <section id='wic-usage-examples'> - <title>Examples</title> + <section id='wic-usage-examples'> + <title>Examples</title> - <para> - This section provides several examples that show how to use - the <filename>wic</filename> utility. - All the examples assume the list of requirements in the - "<link linkend='wic-requirements'>Requirements</link>" - section have been met. - The examples assume the previously generated image is - <filename>core-image-minimal</filename>. - </para> + <para> + This section provides several examples that show how to use + the Wic utility. + All the examples assume the list of requirements in the + "<link linkend='wic-requirements'>Requirements</link>" + section have been met. + The examples assume the previously generated image is + <filename>core-image-minimal</filename>. + </para> - <section id='generate-an-image-using-a-provided-kickstart-file'> - <title>Generate an Image using an Existing Kickstart File</title> + <section id='generate-an-image-using-a-provided-kickstart-file'> + <title>Generate an Image using an Existing Kickstart File</title> - <para> - This example runs in Cooked Mode and uses the - <filename>mkefidisk</filename> kickstart file: - <literallayout class='monospaced'> + <para> + This example runs in Cooked Mode and uses the + <filename>mkefidisk</filename> kickstart file: + <literallayout class='monospaced'> $ wic create mkefidisk -e core-image-minimal - Checking basic build environment... - Done. - - Creating image(s)... - - Info: The new image(s) can be found here: - <replaceable>current_directory</replaceable>/build/mkefidisk-201310230946-sda.direct - - The following build artifacts were used to create the image(s): - ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs - BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg - KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel - NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux - - The image(s) were created using OE kickstart file: - /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks - </literallayout> - The previous example shows the easiest way to create - an image by running in Cooked Mode and using the - <filename>-e</filename> option with an existing - kickstart file. - All that is necessary is to specify the image used to - generate the artifacts. - Your <filename>local.conf</filename> needs to have the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable set to the machine you are using, which is - "minnow" in this example. - </para> - - <para> - The output specifies the exact image created as well as - where it was created, which is in the current - directory by default. - The output also names the artifacts used and the exact - <filename>.wks</filename> script that was used to - generate the image. - <note> - You should always verify the details provided in the - output to make sure that the image was indeed - created exactly as expected. - </note> - </para> - - <para> - Continuing with the example, you can now write the - image to a USB stick, or whatever media for which you - built your image, and boot the resulting media. - You can write the image by using - <filename>bmaptool</filename> or - <filename>dd</filename>: - <literallayout class='monospaced'> - $ oe-run-native bmaptool copy build/mkefidisk-201310230946-sda.direct /dev/sd<replaceable>X</replaceable> - </literallayout> - or - <literallayout class='monospaced'> - $ sudo dd if=build/mkefidisk-201310230946-sda.direct of=/dev/sd<replaceable>X</replaceable> - </literallayout> - <note> - For more information on how to use the - <filename>bmaptool</filename> to flash a device - with an image, see the - "<link linkend='flashing-images-using-bmaptool'>Flashing Images Using <filename>bmaptool</filename></link>" - section. - </note> - </para> - </section> - - <section id='using-a-modified-kickstart-file'> - <title>Using a Modified Kickstart File</title> - - <para> - Because partitioned image creation is - driven by the kickstart file, it is easy to affect - image creation by changing the parameters in the file. - This next example demonstrates that through modification - of the <filename>directdisk</filename> kickstart file. - </para> - - <para> - As mentioned earlier, you can use the command - <filename>wic list images</filename> to show the list - of existing kickstart files. - The directory in which these files reside is - <filename>scripts/lib/image/canned-wks/</filename> - located in the - <link linkend='source-directory'>Source Directory</link>. - Because the available files reside in this directory, - you can create and add your own custom files to the - directory. - Subsequent use of the - <filename>wic list images</filename> command would then - include your kickstart files. - </para> - - <para> - In this example, the existing - <filename>directdisk</filename> file already does most - of what is needed. - However, for the hardware in this example, the image - will need to boot from <filename>sdb</filename> instead - of <filename>sda</filename>, which is what the - <filename>directdisk</filename> kickstart file uses. - </para> - - <para> - The example begins by making a copy of the - <filename>directdisk.wks</filename> file in the - <filename>scripts/lib/image/canned-wks</filename> - directory and then by changing the lines that specify - the target disk from which to boot. - <literallayout class='monospaced'> - $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \ - /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks - </literallayout> - Next, the example modifies the - <filename>directdisksdb.wks</filename> file and changes - all instances of "<filename>--ondisk sda</filename>" - to "<filename>--ondisk sdb</filename>". - The example changes the following two lines and leaves - the remaining lines untouched: - <literallayout class='monospaced'> - part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 - part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 - </literallayout> - Once the lines are changed, the example generates the - <filename>directdisksdb</filename> image. - The command points the process at the - <filename>core-image-minimal</filename> artifacts for - the Next Unit of Computing (nuc) - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - the <filename>local.conf</filename>. - <literallayout class='monospaced'> - $ wic create directdisksdb -e core-image-minimal - Checking basic build environment... - Done. - - Creating image(s)... - - Info: The new image(s) can be found here: - <replaceable>current_directory</replaceable>/build/directdisksdb-201310231131-sdb.direct - - The following build artifacts were used to create the image(s): - - ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs - BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share - KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel - NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux - - The image(s) were created using OE kickstart file: - /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks - </literallayout> - Continuing with the example, you can now directly - <filename>dd</filename> the image to a USB stick, or - whatever media for which you built your image, - and boot the resulting media: - <literallayout class='monospaced'> - $ sudo dd if=build/directdisksdb-201310231131-sdb.direct of=/dev/sdb - 86018+0 records in - 86018+0 records out - 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s - [trz at empanada tmp]$ sudo eject /dev/sdb - </literallayout> - </para> - </section> - - <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'> - <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title> - - <para> - This example creates an image based on - <filename>core-image-minimal</filename> and a - <filename>crownbay-noemgd</filename> - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - that works right out of the box. - <literallayout class='monospaced'> - $ wic create directdisk -e core-image-minimal - - Checking basic build environment... - Done. - - Creating image(s)... - - Info: The new image(s) can be found here: - <replaceable>current_directory</replaceable>/build/directdisk-201309252350-sda.direct - - The following build artifacts were used to create the image(s): - - ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs - BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share - KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel - NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel - - The image(s) were created using OE kickstart file: - /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks - </literallayout> - </para> - </section> - - <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'> - <title>Using a Modified Kickstart File and Running in Raw Mode</title> - - <para> - This next example manually specifies each build artifact - (runs in Raw Mode) and uses a modified kickstart file. - The example also uses the <filename>-o</filename> option - to cause Wic to create the output - somewhere other than the default output directory, - which is the current directory: - <literallayout class='monospaced'> - $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \ - /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ - --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ - --kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \ - --native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux - - Creating image(s)... - - Info: The new image(s) can be found here: - /home/trz/testwic/build/test-201309260032-sda.direct + INFO: Building wic-tools... + . + . + . + INFO: The new image(s) can be found here: + ./mkefidisk-201710061409-sda.direct The following build artifacts were used to create the image(s): + ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.r4hkds0b/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/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs - BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share - KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel - NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel - - The image(s) were created using OE kickstart file: - /home/trz/test.wks - </literallayout> - For this example, - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - did not have to be specified in the - <filename>local.conf</filename> file since the - artifact is manually specified. - </para> - </section> - </section> - - <section id='openembedded-kickstart-plugins'> - <title>Plug-ins</title> + INFO: The image(s) were created using OE kickstart file: + /home/scottrif/poky/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 + a kickstart file and the "-e" option to point to the + existing build artifacts. + Your <filename>local.conf</filename> file needs to have + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable set to the machine you are using, which is + "qemux86" in this example. + </para> <para> - Plug-ins allow Wic functionality to - be extended and specialized by users. - This section documents the plug-in interface, which is - currently restricted to source plug-ins. + Once the image builds, the output provides image + location, artifact use, and kickstart file information. + <note> + You should always verify the details provided in the + output to make sure that the image was indeed + created exactly as expected. + </note> </para> <para> - Source plug-ins provide a mechanism to customize - various aspects of the image generation process in - Wic, mainly the contents of - partitions. - The plug-ins provide a mechanism for mapping values - specified in <filename>.wks</filename> files using the - <filename>--source</filename> keyword to a - particular plug-in implementation that populates a - corresponding partition. + Continuing with the example, you can now write the + image to a USB stick, or whatever media for which you + built your image, and boot from the media. + You can write the image by using + <filename>bmaptool</filename> or + <filename>dd</filename>: + <literallayout class='monospaced'> + $ oe-run-native bmaptool copy build/mkefidisk-201710061409-sda.direct /dev/sd<replaceable>X</replaceable> + </literallayout> + or + <literallayout class='monospaced'> + $ sudo dd if=build/mkefidisk-201710061409-sda.direct of=/dev/sd<replaceable>X</replaceable> + </literallayout> <note> - If you use plug-ins that have build-time dependencies - (e.g. native tools, bootloaders, and so forth) - when building a Wic image, you need to specify those - dependencies using the - <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></ulink> - variable. + For more information on how to use the + <filename>bmaptool</filename> to flash a device + with an image, see the + "<link linkend='flashing-images-using-bmaptool'>Flashing Images Using <filename>bmaptool</filename></link>" + section. </note> </para> + </section> + + <section id='using-a-modified-kickstart-file'> + <title>Using a Modified Kickstart File</title> <para> - A source plug-in is created as a subclass of - <filename>SourcePlugin</filename>. - The plug-in file containing it is added to - <filename>scripts/lib/wic/plugins/source/</filename> to - make the plug-in implementation available to the - Wic implementation. - For more information, see - <filename>scripts/lib/wic/pluginbase.py</filename>. + Because partitioned image creation is driven by the + kickstart file, it is easy to affect image creation by + changing the parameters in the file. + This next example demonstrates that through modification + of the <filename>directdisk-gpt</filename> kickstart + file. </para> <para> - Source plug-ins can also be implemented and added by - external layers. - As such, any plug-ins found in a - <filename>scripts/lib/wic/plugins/source/</filename> - directory in an external layer are also made - available. + As mentioned earlier, you can use the command + <filename>wic list images</filename> to show the list + of existing kickstart files. + The directory in which the + <filename>directdisk-gpt.wks</filename> file resides is + <filename>scripts/lib/image/canned-wks/</filename>, + which is located in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky</filename>). + Because available files reside in this directory, + you can create and add your own custom files to the + directory. + Subsequent use of the + <filename>wic list images</filename> command would then + include your kickstart files. </para> <para> - When the Wic implementation needs - to invoke a partition-specific implementation, it looks - for the plug-in that has the same name as the - <filename>--source</filename> parameter given to - that partition. - For example, if the partition is set up as follows: - <literallayout class='monospaced'> - part /boot --source bootimg-pcbios ... - </literallayout> - The methods defined as class members of the plug-in - having the matching <filename>bootimg-pcbios.name</filename> - class member are used. + In this example, the existing + <filename>directdisk-gpt</filename> file already does + most of what is needed. + However, for the hardware in this example, the image + will need to boot from <filename>sdb</filename> instead + of <filename>sda</filename>, which is what the + <filename>directdisk-gpt</filename> kickstart file + uses. </para> <para> - To be more concrete, here is the plug-in definition that - matches a - <filename>--source bootimg-pcbios</filename> usage, - along with an example - method called by the Wic implementation - when it needs to invoke an implementation-specific - partition-preparation function: + The example begins by making a copy of the + <filename>directdisk-gpt.wks</filename> file in the + <filename>scripts/lib/image/canned-wks</filename> + directory and then by changing the lines that specify + the target disk from which to boot. <literallayout class='monospaced'> - class BootimgPcbiosPlugin(SourcePlugin): - name = 'bootimg-pcbios' + $ cp /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \ + /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks + </literallayout> + Next, the example modifies the + <filename>directdisksdb-gpt.wks</filename> file and + changes all instances of + "<filename>--ondisk sda</filename>" to + "<filename>--ondisk sdb</filename>". + The example changes the following two lines and leaves + the remaining lines untouched: + <literallayout class='monospaced'> + part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 + part / --source rootfs --ondisk sdb --fstype=ext4 --label platform --align 1024 --use-uuid + </literallayout> + Once the lines are changed, the example generates the + <filename>directdisksdb-gpt</filename> image. + The command points the process at the + <filename>core-image-minimal</filename> artifacts for + the Next Unit of Computing (nuc) + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + the <filename>local.conf</filename>. + <literallayout class='monospaced'> + $ wic create directdisksdb-gpt -e core-image-minimal + INFO: Building wic-tools... + . + . + . + Initialising tasks: 100% |#######################################| Time: 0:00:01 + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + NOTE: Tasks Summary: Attempted 1161 tasks of which 1157 didn't need to be rerun and all succeeded. + INFO: Creating image(s)... + + INFO: The new image(s) can be found here: + ./directdisksdb-gpt-201710090938-sdb.direct - @classmethod - def do_prepare_partition(self, part, ...) + 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 + + INFO: The image(s) were created using OE kickstart file: + /home/scottrif/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 + whatever media for which you built your image, + and boot the resulting media: + <literallayout class='monospaced'> + $ sudo dd if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb + 140966+0 records in + 140966+0 records out + 72174592 bytes (72 MB, 69 MiB) copied, 78.0282 s, 925 kB/s + $ sudo eject /dev/sdb </literallayout> - If the subclass itself does not implement a function, a - default version in a superclass is located and - used, which is why all plug-ins must be derived from - <filename>SourcePlugin</filename>. </para> + </section> - <para> - The <filename>SourcePlugin</filename> class defines the - following methods, which is the current set of methods - that can be implemented or overridden by - <filename>--source</filename> plug-ins. - Any methods not implemented by a - <filename>SourcePlugin</filename> subclass inherit the - implementations present in the - <filename>SourcePlugin</filename> class. - For more information, see the - <filename>SourcePlugin</filename> source for details: - </para> + <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'> + <title>Using a Modified Kickstart File and Running in Raw Mode</title> <para> - <itemizedlist> - <listitem><para> - <emphasis><filename>do_prepare_partition()</filename>:</emphasis> - Called to do the actual content population for a - partition. - In other words, the method prepares the final - partition image that is incorporated into the - disk image. - </para></listitem> - <listitem><para> - <emphasis><filename>do_configure_partition()</filename>:</emphasis> - Called before - <filename>do_prepare_partition()</filename>. - This method is typically used to create custom - configuration files for a partition (e.g. syslinux - or grub configuration files). - </para></listitem> - <listitem><para> - <emphasis><filename>do_install_disk()</filename>:</emphasis> - Called after all partitions have been prepared and - assembled into a disk image. - This method provides a hook to allow finalization - of a disk image, (e.g. writing an MBR). - </para></listitem> - <listitem><para> - <emphasis><filename>do_stage_partition()</filename>:</emphasis> - Special content-staging hook called before - <filename>do_prepare_partition()</filename>. - This method is normally empty.</para> - <para>Typically, a partition just uses the passed-in - parameters (e.g. the unmodified value of - <filename>bootimg_dir</filename>). - However, in some cases things might need to be - more tailored. - As an example, certain files might additionally - need to be taken from - <filename>bootimg_dir + /boot</filename>. - This hook allows those files to be staged in a - customized fashion. - <note> - <filename>get_bitbake_var()</filename> - allows you to access non-standard variables - that you might want to use for this. - </note> - </para></listitem> - </itemizedlist> - </para> + This next example manually specifies each build artifact + (runs in Raw Mode) and uses a modified kickstart file. + The example also uses the <filename>-o</filename> option + to cause Wic to create the output + 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 - <para> - This scheme is extensible. - Adding more hooks is a simple matter of adding more - plug-in methods to <filename>SourcePlugin</filename> and - derived classes. - The code that then needs to call the plug-in methods uses - <filename>plugin.get_source_plugin_methods()</filename> - to find the method or methods needed by the call. - Retrieval of those methods is accomplished - by filling up a dict with keys - containing the method names of interest. - On success, these will be filled in with the actual - methods. - Please see the Wic - implementation for examples and details. + INFO: Creating image(s)... + + INFO: The new image(s) can be found here: + /home/scottrif/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 + + INFO: The image(s) were created using OE kickstart file: + /home/scottrif/my_yocto/test.wks + </literallayout> + For this example, + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + did not have to be specified in the + <filename>local.conf</filename> file since the + artifact is manually specified. </para> </section> - <section id='openembedded-kickstart-wks-reference'> - <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title> + <section id='using-wic-to-manipulate-an-image'> + <title>Using Wic to Manipulate an Image</title> <para> - The current Wic implementation supports - only the basic kickstart partitioning commands: - <filename>partition</filename> (or <filename>part</filename> - for short) and <filename>bootloader</filename>. + Wic image manipulation allows you to shorten turnaround + time during image development. + For example, you can use Wic to delete the kernel partition + of a Wic image and then insert a newly built kernel. + This saves you time from having to rebuild the entire image + each time you modify the kernel. <note> - Future updates will implement more commands and options. - If you use anything that is not specifically - supported, results can be unpredictable. + In order to use Wic to manipulate a Wic image as in + this example, your development machine must have the + <filename>mtools</filename> package installed. </note> </para> <para> - The following is a list of the commands, their syntax, - and meanings. - The commands are based on the Fedora - kickstart versions but with modifications to - reflect Wic capabilities. - You can see the original documentation for those commands - at the following links: - <itemizedlist> + The following example examines the contents of the Wic + image, deletes the existing kernel, and then inserts a + new kernel: + <orderedlist> <listitem><para> - <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink> + <emphasis>List the Partitions:</emphasis> + Use the <filename>wic ls</filename> command to list + all the partitions in the Wic image: + <literallayout class='monospaced'> + $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic + Num Start End Size Fstype + 1 1048576 25041919 23993344 fat16 + 2 25165824 72157183 46991360 ext4 + </literallayout> + The previous output shows two partitions in the + <filename>core-image-minimal-qemux86.wic</filename> + image. </para></listitem> <listitem><para> - <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink> - </para></listitem> - </itemizedlist> - </para> - - <section id='command-part-or-partition'> - <title>Command: part or partition</title> - - <para> - Either of these commands create a partition on the system - and use the following syntax: - <literallayout class='monospaced'> - part [<replaceable>mntpoint</replaceable>] - partition [<replaceable>mntpoint</replaceable>] - </literallayout> - If you do not provide - <replaceable>mntpoint</replaceable>, Wic creates a - partition but does not mount it. - </para> - - <para> - The - <filename><replaceable>mntpoint</replaceable></filename> - is where the partition will be mounted and must be of - one of the following forms: - <itemizedlist> - <listitem><para> - <filename>/<replaceable>path</replaceable></filename>: - For example, "/", "/usr", or "/home" - </para></listitem> - <listitem><para> - <filename>swap</filename>: - The created partition is used as swap space. - </para></listitem> - </itemizedlist> - </para> - - <para> - Specifying a <replaceable>mntpoint</replaceable> causes - the partition to automatically be mounted. - Wic achieves this by adding entries to the filesystem - table (fstab) during image generation. - In order for wic to generate a valid fstab, you must - also provide one of the <filename>--ondrive</filename>, - <filename>--ondisk</filename>, or - <filename>--use-uuid</filename> partition options as - part of the command. - Here is an example using "/" as the mountpoint. - The command uses "--ondisk" to force the partition onto - the <filename>sdb</filename> disk: - <literallayout class='monospaced'> - part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 - </literallayout> - </para> - - <para> - Here is a list that describes other supported options - you can use with the <filename>part</filename> and - <filename>partition</filename> commands: - <itemizedlist> - <listitem><para> - <emphasis><filename>--size</filename>:</emphasis> - The minimum partition size in MBytes. - Specify an integer value such as 500. - Do not append the number with "MB". - You do not need this option if you use - <filename>--source</filename>. - </para></listitem> - <listitem><para> - <emphasis><filename>--source</filename>:</emphasis> - This option is a - Wic-specific option that - names the source of the data that populates - the partition. - The most common value for this option is - "rootfs", but you can use any value that maps to - a valid source plug-in. - For information on the source plug-ins, see the - "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" - section.</para> - <para>If you use - <filename>--source rootfs</filename>, - Wic creates a partition as - large as needed and to fill it with the contents - of the root filesystem pointed to by the - <filename>-r</filename> command-line option - or the equivalent rootfs derived from the - <filename>-e</filename> command-line - option. - The filesystem type used to create the - partition is driven by the value of the - <filename>--fstype</filename> option - specified for the partition. - See the entry on - <filename>--fstype</filename> that - follows for more information. - </para> - <para>If you use - <filename>--source <replaceable>plugin-name</replaceable></filename>, - Wic creates a partition as - large as needed and fills it with the contents - of the partition that is generated by the - specified plug-in name using the data pointed - to by the <filename>-r</filename> command-line - option or the equivalent rootfs derived from the - <filename>-e</filename> command-line - option. - Exactly what those contents and filesystem type - end up being are dependent on the given plug-in - implementation. - </para> - <para>If you do not use the - <filename>--source</filename> option, the - <filename>wic</filename> command creates an - empty partition. - Consequently, you must use the - <filename>--size</filename> option to specify - the size of the empty partition. - </para></listitem> - <listitem><para> - <emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> - Forces the partition to be created on a - particular disk. - </para></listitem> - <listitem><para> - <emphasis><filename>--fstype</filename>:</emphasis> - Sets the file system type for the partition. - Valid values are: - <itemizedlist> - <listitem><para><filename>ext4</filename> - </para></listitem> - <listitem><para><filename>ext3</filename> - </para></listitem> - <listitem><para><filename>ext2</filename> - </para></listitem> - <listitem><para><filename>btrfs</filename> - </para></listitem> - <listitem><para><filename>squashfs</filename> - </para></listitem> - <listitem><para><filename>swap</filename> - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - <emphasis><filename>--fsoptions</filename>:</emphasis> - Specifies a free-form string of options to be - used when mounting the filesystem. - This string will be copied into the - <filename>/etc/fstab</filename> file of the - installed system and should be enclosed in - quotes. - If not specified, the default string - is "defaults". - </para></listitem> - <listitem><para> - <emphasis><filename>--label label</filename>:</emphasis> - Specifies the label to give to the filesystem to - be made on the partition. - If the given label is already in use by another - filesystem, a new label is created for the - partition. - </para></listitem> - <listitem><para> - <emphasis><filename>--active</filename>:</emphasis> - Marks the partition as active. - </para></listitem> - <listitem><para> - <emphasis><filename>--align (in KBytes)</filename>:</emphasis> - This option is a - Wic-specific option that - says to start a partition on an - <replaceable>x</replaceable> KBytes - boundary.</para></listitem> - <listitem><para> - <emphasis><filename>--no-table</filename>:</emphasis> - This option is a - Wic-specific option. - Using the option reserves space for the - partition and causes it to become populated. - However, the partition is not added to the - partition table. - </para></listitem> - <listitem><para> - <emphasis><filename>--extra-space</filename>:</emphasis> - This option is a - Wic-specific option that - adds extra space after the space filled by the - content of the partition. - The final size can go beyond the size specified - by the <filename>--size</filename> option. - The default value is 10 Mbytes. - </para></listitem> - <listitem><para> - <emphasis><filename>--overhead-factor</filename>:</emphasis> - This option is a - Wic-specific option that - multiplies the size of the partition by the - option's value. - You must supply a value greater than or equal to - "1". - The default value is "1.3". - </para></listitem> - <listitem><para> - <emphasis><filename>--part-type</filename>:</emphasis> - This option is a - Wic-specific option that - specifies the partition type globally - unique identifier (GUID) for GPT partitions. - You can find the list of partition type GUIDs - at - <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>. - </para></listitem> - <listitem><para> - <emphasis><filename>--use-uuid</filename>:</emphasis> - This option is a - Wic-specific option that - causes Wic to generate a - random GUID for the partition. - The generated identifier is used in the - bootloader configuration to specify the root - partition. - </para></listitem> - <listitem><para> - <emphasis><filename>--uuid</filename>:</emphasis> - This option is a - Wic-specific - option that specifies the partition UUID. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='command-bootloader'> - <title>Command: bootloader</title> - - <para> - This command specifies how the bootloader should be - configured and supports the following options: - <note> - Bootloader functionality and boot partitions are - implemented by the various - <filename>--source</filename> - plug-ins that implement bootloader functionality. - The bootloader command essentially provides a - means of modifying bootloader configuration. - </note> - <itemizedlist> - <listitem><para> - <emphasis><filename>--timeout</filename>:</emphasis> - Specifies the number of seconds before the - bootloader times out and boots the default - option. - </para></listitem> - <listitem><para> - <emphasis><filename>--append</filename>:</emphasis> - Specifies kernel parameters. - These parameters will be added to the syslinux - <filename>APPEND</filename> or - <filename>grub</filename> kernel command line. - </para></listitem> - <listitem><para> - <emphasis><filename>--configfile</filename>:</emphasis> - Specifies a user-defined configuration file for - the bootloader. - You can provide a full pathname for the file or - a file that exists in the - <filename>canned-wks</filename> folder. - This option overrides all other bootloader - options. - </para></listitem> - </itemizedlist> - </para> - </section> - </section> + <emphasis>Examine a Particular Partition:</emphasis> + Use the <filename>wic ls</filename> command again + but in a different form to examine a particular + partition. + <note> + You can get command usage on any Wic command + using the following form: + <literallayout class='monospaced'> + $ wic help <replaceable>command</replaceable> + </literallayout> + For example, the following command shows you + the various ways to use the + <filename>wic ls</filename> command: + <literallayout class='monospaced'> + $ wic help ls + </literallayout> + </note> + The following command shows what is in Partition + one: + <literallayout class='monospaced'> + $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1 + Volume in drive : is boot + Volume Serial Number is E894-1809 + Directory for ::/ + + libcom32 c32 186500 2017-10-09 16:06 + libutil c32 24148 2017-10-09 16:06 + syslinux cfg 220 2017-10-09 16:06 + vesamenu c32 27104 2017-10-09 16:06 + vmlinuz 6904608 2017-10-09 16:06 + 5 files 7 142 580 bytes + 16 582 656 bytes free + </literallayout> + The previous output shows five files, with the + <filename>vmlinuz</filename> being the kernel. + <note> + If you see the following error, you need to + update or create a + <filename>~/.mtoolsrc</filename> file and + be sure to have the line “mtools_skip_check=1“ + in the file. + Then, run the Wic command again: + <literallayout class='monospaced'> + ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0 + output: Total number of sectors (47824) not a multiple of sectors per track (32)! + Add mtools_skip_check=1 to your .mtoolsrc file to skip this test + </literallayout> + </note> + </para></listitem> + <listitem><para> + <emphasis>Remove the Old Kernel:</emphasis> + Use the <filename>wic rm</filename> command to + remove the <filename>vmlinuz</filename> file + (kernel): + <literallayout class='monospaced'> + $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Add In the New Kernel:</emphasis> + Use the <filename>wic cp</filename> command to + add the updated kernel to the Wic image. + Depending on how you built your kernel, it could + be in different places. + If you used <filename>devtool</filename> and + an SDK to build your kernel, it resides in the + <filename>tmp/work</filename> directory of the + extensible SDK. + If you used <filename>make</filename> to build the + kernel, the kernel will be in the + <filename>workspace/sources</filename> area. + </para> + + <para>The following example assumes + <filename>devtool</filename> was used to build + the kernel: + <literallayout class='monospaced'> + cp ~/poky_sdk/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+git999-r0/linux-yocto-4.12.12+git999/arch/x86/boot/bzImage \ + ~/poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz + </literallayout> + Once the new kernel is added back into the image, + you can use the <filename>dd</filename> + command or + <link linkend='flashing-images-using-bmaptool'><filename>bmaptool</filename></link> + to flash your wic image onto an SD card + or USB stick and test your target. + <note> + Using <filename>bmaptool</filename> is + generally 10 to 20 times faster than using + <filename>dd</filename>. + </note> + </para></listitem> + </orderedlist> + </para> + </section> </section> </section> @@ -5817,887 +5612,231 @@ <title>Building an Initial RAM Filesystem (initramfs) Image</title> <para> - initramfs is the successor of Initial RAM Disk (initrd). - It is a "copy in and out" (cpio) archive of the initial file system - that gets loaded into memory during the Linux startup process. - Because Linux uses the contents of the archive during - initialization, the initramfs needs to contain all of the device - drivers and tools needed to mount the final root filesystem. - </para> - - <para> - To build an initramfs image and bundle it into the kernel, set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink> - variable in your <filename>local.conf</filename> file, and set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink> - variable in your <filename>machine.conf</filename> file: - <literallayout class='monospaced'> - INITRAMFS_IMAGE_BUNDLE = "1" - INITRAMFS_IMAGE = "<replaceable>image_recipe_name</replaceable>" - </literallayout> - Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename> - flag causes the initramfs created by the recipe and defined by - <filename>INITRAMFS_IMAGE</filename> to be unpacked into the - <filename>${B}/usr/</filename> directory. - The unpacked initramfs 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 initramfs to be built in to the kernel - normally. - <note> - The preferred method is to use the - <filename>INITRAMFS_IMAGE</filename> variable rather than the - <filename>INITRAMFS_TASK</filename> variable. - Setting <filename>INITRAMFS_TASK</filename> is supported for - backward compatibility. - However, use of this variable has circular dependency - problems. - See the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink> - variable for additional information on these dependency - problems. - </note> - </para> - - <para> - The recipe that <filename>INITRAMFS_IMAGE</filename> - points to must produce a <filename>.cpio.gz</filename>, - <filename>.cpio.tar</filename>, <filename>.cpio.lz4</filename>, - <filename>.cpio.lzma</filename>, or - <filename>.cpio.xz</filename> file. - You can ensure you produce one of these <filename>.cpio.*</filename> - files by setting the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></ulink> - variable in your configuration file to one or more of the above - file types. + 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> - 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. + 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> - </section> - - <section id='configuring-the-kernel'> - <title>Configuring the Kernel</title> <para> - Configuring the Yocto Project kernel consists of making sure the - <filename>.config</filename> file has all the right information - in it for the image you are building. - You can use the <filename>menuconfig</filename> tool and - configuration fragments to make sure your - <filename>.config</filename> file is just how you need it. - You can also save known configurations in a - <filename>defconfig</filename> file that the build system can use - for kernel configuration. - </para> - - <para> - This section describes how to use <filename>menuconfig</filename>, - create and use configuration fragments, and how to interactively - modify your <filename>.config</filename> file to create the - leanest kernel configuration file possible. - </para> - - <para> - For more information on kernel configuration, see the - "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>" - section in the Yocto Project Linux Kernel Development Manual. - </para> - - <section id='using-menuconfig'> - <title>Using <filename>menuconfig</filename></title> - - <para> - The easiest way to define kernel configurations is to set them through the - <filename>menuconfig</filename> tool. - This tool provides an interactive method with which - to set kernel configurations. - For general information on <filename>menuconfig</filename>, see - <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>. - </para> - - <para> - To use the <filename>menuconfig</filename> tool in the Yocto Project development - environment, you must launch it using BitBake. - Thus, the environment must be set up using the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> - script found in the - <link linkend='build-directory'>Build Directory</link>. - You must also be sure of the state of your build in the - <link linkend='source-directory'>Source Directory</link>. - The following commands run <filename>menuconfig</filename> - assuming the Source Directory's top-level folder is - <filename>~/poky</filename>: - <literallayout class='monospaced'> - $ cd poky - $ source oe-init-build-env - $ bitbake linux-yocto -c kernel_configme -f - $ bitbake linux-yocto -c menuconfig - </literallayout> - Once <filename>menuconfig</filename> comes up, its standard - interface allows you to interactively examine and configure - all the kernel configuration parameters. - After making your changes, simply exit the tool and save your - changes to create an updated version of the - <filename>.config</filename> configuration file. - </para> - - <para> - Consider an example that configures the <filename>linux-yocto-3.14</filename> - kernel. - The OpenEmbedded build system recognizes this kernel as - <filename>linux-yocto</filename>. - Thus, the following commands from the shell in which you previously sourced the - environment initialization script cleans the shared state cache and the - <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> - directory and then runs <filename>menuconfig</filename>: - <literallayout class='monospaced'> - $ bitbake linux-yocto -c menuconfig - </literallayout> - </para> - - <para> - Once <filename>menuconfig</filename> launches, use the interface - to navigate through the selections to find the configuration settings in - which you are interested. - For example, consider the <filename>CONFIG_SMP</filename> configuration setting. - You can find it at <filename>Processor Type and Features</filename> under - the configuration selection <filename>Symmetric Multi-processing Support</filename>. - After highlighting the selection, use the arrow keys to select or deselect - the setting. - When you are finished with all your selections, exit out and save them. - </para> - - <para> - Saving the selections updates the <filename>.config</filename> configuration file. - This is the file that the OpenEmbedded build system uses to configure the - kernel during the build. - You can find and examine this file in the Build Directory in - <filename>tmp/work/</filename>. - The actual <filename>.config</filename> is located in the area where the - specific kernel is built. - For example, if you were building a Linux Yocto kernel based on the - Linux 3.14 kernel and you were building a QEMU image targeted for - <filename>x86</filename> architecture, the - <filename>.config</filename> file would be located here: - <literallayout class='monospaced'> - poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f... - ...656ed30-r1/linux-qemux86-standard-build - </literallayout> - <note> - The previous example directory is artificially split and many of the characters - in the actual filename are omitted in order to make it more readable. - Also, depending on the kernel you are using, the exact pathname - for <filename>linux-yocto-3.14...</filename> might differ. - </note> - </para> - - <para> - Within the <filename>.config</filename> file, you can see the kernel settings. - For example, the following entry shows that symmetric multi-processor support - is not set: - <literallayout class='monospaced'> - # CONFIG_SMP is not set - </literallayout> - </para> - - <para> - A good method to isolate changed configurations is to use a combination of the - <filename>menuconfig</filename> tool and simple shell commands. - Before changing configurations with <filename>menuconfig</filename>, copy the - existing <filename>.config</filename> and rename it to something else, - use <filename>menuconfig</filename> to make - as many changes as you want and save them, then compare the renamed configuration - file against the newly created file. - You can use the resulting differences as your base to create configuration fragments - to permanently save in your kernel layer. - <note> - Be sure to make a copy of the <filename>.config</filename> and don't just - rename it. - The build system needs an existing <filename>.config</filename> - from which to work. - </note> - </para> - </section> - - <section id='creating-a-defconfig-file'> - <title>Creating a <filename>defconfig</filename> File</title> - - <para> - A <filename>defconfig</filename> file is simply a - <filename>.config</filename> renamed to "defconfig". - You can use a <filename>defconfig</filename> file - to retain a known set of kernel configurations from which the - OpenEmbedded build system can draw to create the final - <filename>.config</filename> file. - <note> - Out-of-the-box, the Yocto Project never ships a - <filename>defconfig</filename> or - <filename>.config</filename> file. - The OpenEmbedded build system creates the final - <filename>.config</filename> file used to configure the - kernel. - </note> - </para> - - <para> - To create a <filename>defconfig</filename>, start with a - complete, working Linux kernel <filename>.config</filename> - file. - Copy that file to the appropriate - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> - directory in your layer's - <filename>recipes-kernel/linux</filename> directory, and rename - the copied file to "defconfig". - Then, add the following lines to the linux-yocto - <filename>.bbappend</filename> file in your layer: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - SRC_URI += "file://defconfig" - </literallayout> - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - tells the build system how to search for the file, while the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - extends the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> - variable (search directories) to include the - <filename>${PN}</filename> directory you created to hold the - configuration changes. - <note> - The build system applies the configurations from the - <filename>defconfig</filename> file before applying any - subsequent configuration fragments. - The final kernel configuration is a combination of the - configurations in the <filename>defconfig</filename> - file and any configuration fragments you provide. - You need to realize that if you have any configuration - fragments, the build system applies these on top of and - after applying the existing defconfig file configurations. - </note> - For more information on configuring the kernel, see the - "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>" - and - "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" - sections, both in the Yocto Project Linux Kernel Development - Manual. - </para> - </section> - - <section id='creating-config-fragments'> - <title>Creating Configuration Fragments</title> - - <para> - Configuration fragments are simply kernel options that appear in a file - placed where the OpenEmbedded build system can find and apply them. - Syntactically, the configuration statement is identical to what would appear - in the <filename>.config</filename> file, which is in the - <link linkend='build-directory'>Build Directory</link>: - <literallayout class='monospaced'> - tmp/work/<replaceable>arch</replaceable>-poky-linux/linux-yocto-<replaceable>release_specific_string</replaceable>/linux-<replaceable>arch</replaceable>-<replaceable>build_type</replaceable> - </literallayout> - </para> - - <para> - It is simple to create a configuration fragment. - For example, issuing the following from the shell creates a configuration fragment - file named <filename>my_smp.cfg</filename> that enables multi-processor support - within the kernel: - <literallayout class='monospaced'> - $ echo "CONFIG_SMP=y" >> my_smp.cfg - </literallayout> - <note> - All configuration fragment files must use the - <filename>.cfg</filename> extension in order for the - OpenEmbedded build system to recognize them as a - configuration fragment. - </note> - </para> - - <para> - Where do you put your configuration fragment files? - You can place these files in the same area pointed to by - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. - The OpenEmbedded build system picks up the configuration and - adds it to the kernel's configuration. - For example, suppose you had a set of configuration options - in a file called <filename>myconfig.cfg</filename>. - If you put that file inside a directory named - <filename>linux-yocto</filename> that resides in the same - directory as the kernel's append file and then add a - <filename>SRC_URI</filename> statement such as the following - to the kernel's append file, those configuration options - will be picked up and applied when the kernel is built. - <literallayout class='monospaced'> - SRC_URI += "file://myconfig.cfg" - </literallayout> - </para> - - <para> - As mentioned earlier, you can group related configurations into multiple files and - name them all in the <filename>SRC_URI</filename> statement as well. - For example, you could group separate configurations specifically for Ethernet and graphics - into their own files and add those by using a <filename>SRC_URI</filename> statement like the - following in your append file: - <literallayout class='monospaced'> - SRC_URI += "file://myconfig.cfg \ - file://eth.cfg \ - file://gfx.cfg" - </literallayout> - </para> - </section> + 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: - <section id='fine-tuning-the-kernel-configuration-file'> - <title>Fine-Tuning the Kernel Configuration File</title> + A non-bundled initramfs is essentially an initrd, which I am discovering + to be rather confusingly supported in OE at the moment. - <para> - You can make sure the <filename>.config</filename> file is as lean or efficient as - possible by reading the output of the kernel configuration fragment audit, - noting any issues, making changes to correct the issues, and then repeating. - </para> + 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: - <para> - As part of the kernel build process, the - <filename>do_kernel_configcheck</filename> task runs. - This task validates the kernel configuration by checking the final - <filename>.config</filename> file against the input files. - During the check, the task produces warning messages for the following - issues: - <itemizedlist> - <listitem><para>Requested options that did not make the final - <filename>.config</filename> file.</para></listitem> - <listitem><para>Configuration items that appear twice in the same - configuration fragment.</para></listitem> - <listitem><para>Configuration items tagged as "required" that were overridden. - </para></listitem> - <listitem><para>A board overrides a non-board specific option.</para></listitem> - <listitem><para>Listed options not valid for the kernel being processed. - In other words, the option does not appear anywhere.</para></listitem> - </itemizedlist> - <note> - The <filename>do_kernel_configcheck</filename> task can - also optionally report if an option is overridden during - processing. - </note> - </para> + INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}" - <para> - For each output warning, a message points to the file - that contains a list of the options and a pointer to the - configuration fragment that defines them. - Collectively, the files are the key to streamlining the - configuration. - </para> + If 'intel-ucode' is in MACHINE_FEATURES, this resolves to: - <para> - To streamline the configuration, do the following: - <orderedlist> - <listitem><para>Start with a full configuration that you - know works - it builds and boots successfully. - This configuration file will be your baseline. - </para></listitem> - <listitem><para>Separately run the - <filename>do_kernel_configme</filename> and - <filename>do_kernel_configcheck</filename> tasks. - </para></listitem> - <listitem><para>Take the resulting list of files from the - <filename>do_kernel_configcheck</filename> task - warnings and do the following: - <itemizedlist> - <listitem><para> - Drop values that are redefined in the fragment - but do not change the final - <filename>.config</filename> file. - </para></listitem> - <listitem><para> - Analyze and potentially drop values from the - <filename>.config</filename> file that override - required configurations. - </para></listitem> - <listitem><para> - Analyze and potentially remove non-board - specific options. - </para></listitem> - <listitem><para> - Remove repeated and invalid options. - </para></listitem> - </itemizedlist></para></listitem> - <listitem><para> - After you have worked through the output of the kernel - configuration audit, you can re-run the - <filename>do_kernel_configme</filename> and - <filename>do_kernel_configcheck</filename> tasks to - see the results of your changes. - If you have more issues, you can deal with them as - described in the previous step. - </para></listitem> - </orderedlist> - </para> + INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio " - <para> - Iteratively working through steps two through four eventually yields - a minimal, streamlined configuration file. - Once you have the best <filename>.config</filename>, you can build the Linux - Yocto kernel. - </para> - </section> + Unfortunately you need the full path, and its up to you to sort out + dependencies as well. For instance, we have the following: - <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'> - <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title> + MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}" - <para> - This section describes part of the kernel configuration audit - phase that most developers can ignore. - During this part of the audit phase, the contents of the final - <filename>.config</filename> file are compared against the - fragments specified by the system. - These fragments can be system fragments, distro fragments, - or user specified configuration elements. - Regardless of their origin, the OpenEmbedded build system - warns the user if a specific option is not included in the - final kernel configuration. - </para> + which resolves to: - <para> - In order to not overwhelm the user with configuration warnings, - by default the system only reports on missing "hardware" - options because a missing hardware option could mean a boot - failure or that important hardware is not available. - </para> + MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode" - <para> - To determine whether or not a given option is "hardware" or - "non-hardware", the kernel Metadata contains files that - classify individual or groups of options as either hardware - or non-hardware. - To better show this, consider a situation where the - Yocto Project kernel cache contains the following files: - <literallayout class='monospaced'> - kernel-cache/features/drm-psb/hardware.cfg - kernel-cache/features/kgdb/hardware.cfg - kernel-cache/ktypes/base/hardware.cfg - kernel-cache/bsp/mti-malta32/hardware.cfg - kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg - kernel-cache/bsp/qemu-ppc32/hardware.cfg - kernel-cache/bsp/qemuarma9/hardware.cfg - kernel-cache/bsp/mti-malta64/hardware.cfg - kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg - kernel-cache/bsp/common-pc/hardware.cfg - kernel-cache/bsp/common-pc-64/hardware.cfg - kernel-cache/features/rfkill/non-hardware.cfg - kernel-cache/ktypes/base/non-hardware.cfg - kernel-cache/features/aufs/non-hardware.kcf - kernel-cache/features/ocf/non-hardware.kcf - kernel-cache/ktypes/base/non-hardware.kcf - kernel-cache/ktypes/base/hardware.kcf - kernel-cache/bsp/qemu-ppc32/hardware.kcf - </literallayout> - The following list provides explanations for the various - files: - <itemizedlist> - <listitem><para><filename>hardware.kcf</filename>: - Specifies a list of kernel Kconfig files that contain - hardware options only. - </para></listitem> - <listitem><para><filename>non-hardware.kcf</filename>: - Specifies a list of kernel Kconfig files that contain - non-hardware options only. - </para></listitem> - <listitem><para><filename>hardware.cfg</filename>: - Specifies a list of kernel - <filename>CONFIG_</filename> options that are hardware, - regardless of whether or not they are within a Kconfig - file specified by a hardware or non-hardware - Kconfig file (i.e. <filename>hardware.kcf</filename> or - <filename>non-hardware.kcf</filename>). - </para></listitem> - <listitem><para><filename>non-hardware.cfg</filename>: - Specifies a list of kernel - <filename>CONFIG_</filename> options that are - not hardware, regardless of whether or not they are - within a Kconfig file specified by a hardware or - non-hardware Kconfig file (i.e. - <filename>hardware.kcf</filename> or - <filename>non-hardware.kcf</filename>). - </para></listitem> - </itemizedlist> - Here is a specific example using the - <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>: - <literallayout class='monospaced'> - CONFIG_SERIAL_8250 - CONFIG_SERIAL_8250_CONSOLE - CONFIG_SERIAL_8250_NR_UARTS - CONFIG_SERIAL_8250_PCI - CONFIG_SERIAL_CORE - CONFIG_SERIAL_CORE_CONSOLE - CONFIG_VGA_ARB - </literallayout> - The kernel configuration audit automatically detects these - files (hence the names must be exactly the ones discussed here), - and uses them as inputs when generating warnings about the - final <filename>.config</filename> file. - </para> + 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. - <para> - A user-specified kernel Metadata repository, or recipe space - feature, can use these same files to classify options that are - found within its <filename>.cfg</filename> files as hardware - or non-hardware, to prevent the OpenEmbedded build system from - producing an error or warning when an option is not in the - final <filename>.config</filename> file. - </para> - </section> + 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="patching-the-kernel"> - <title>Patching the Kernel</title> + <section id='flashing-images-using-bmaptool'> + <title>Flashing Images Using <filename>bmaptool</filename></title> <para> - Patching the kernel involves changing or adding configurations to an existing kernel, - changing or adding recipes to the kernel that are needed to support specific hardware features, - or even altering the source code itself. - <note> - You can use the <filename>yocto-kernel</filename> script - found in the <link linkend='source-directory'>Source Directory</link> - under <filename>scripts</filename> to manage kernel patches and configuration. - See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>" - section in the Yocto Project Board Support Packages (BSP) Developer's Guide for - more information.</note> - </para> - - <para> - This example creates a simple patch by adding some QEMU emulator console - output at boot time through <filename>printk</filename> statements in the kernel's - <filename>calibrate.c</filename> source code file. - Applying the patch and booting the modified image causes the added - messages to appear on the emulator's console. + An easy way to flash an image to a bootable device is to use + <filename>bmaptool</filename>, which is integrated into the + OpenEmbedded build system. </para> <para> - The example assumes a clean build exists for the <filename>qemux86</filename> - machine in a - <link linkend='source-directory'>Source Directory</link> - named <filename>poky</filename>. - Furthermore, the <link linkend='build-directory'>Build Directory</link> is - <filename>build</filename> and is located in <filename>poky</filename> and - the kernel is based on the Linux 3.4 kernel. + Following, is an example that shows how to flash a Wic image. + <note> + You can use <filename>bmaptool</filename> to flash any + type of image. + </note> + Use these steps to flash an image using + <filename>bmaptool</filename>: + <note> + Unless you are able to install the + <filename>bmap-tools</filename> package as mentioned in the note + in the second bullet of step 3 further down, you will need to build + <filename>bmaptool</filename> before using it. + Build the tool using the following command: + <literallayout class='monospaced'> + $ bitbake bmap-tools-native + </literallayout> + </note> + <orderedlist> + <listitem><para> + <emphasis>Update the <filename>local.conf</filename> File:</emphasis> + Add the following to your <filename>local.conf</filename> + file: + <literallayout class='monospaced'> + IMAGE_FSTYPES += "wic wic.bmap" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Get Your Image:</emphasis> + Either have your image ready (pre-built) or take the step + build the image: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Flash the Device:</emphasis> + Flash the device with the image by using + <filename>bmaptool</filename> depending on your particular + setup: + <itemizedlist> + <listitem><para> + If you have write access to the media, + use this command form: + <literallayout class='monospaced'> + $ oe-run-native bmap-tools-native bmaptool copy ./tmp/deploy/images/qemux86-64-core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable> + </literallayout> + </para></listitem> + <listitem><para> + If you do not have write access to + the media, use the following + commands: + <literallayout class='monospaced'> + $ sudo chmod 666 /dev/sd<replaceable>X</replaceable> + $ oe-run-native bmap-tools-native bmaptool copy ./tmp/deploy/images/qemux86-64-core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable> + </literallayout> + <note> + If you are using Ubuntu or Debian distributions, + you can install the + <filename>bmap-tools</filename> package using + the following command and then use the tool + without specifying + <filename>PATH</filename> even from the + root account: + <literallayout class='monospaced'> + $ sudo apt-get install bmap-tools + </literallayout> + </note> + </para></listitem> + </itemizedlist> + </para></listitem> + </orderedlist> </para> <para> - Also, for more information on patching the kernel, see the - "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>" - section in the Yocto Project Linux Kernel Development Manual. + For help on the <filename>bmaptool</filename> command, use the + following command: + <literallayout class='monospaced'> + $ bmaptool --help + </literallayout> </para> - - <section id='create-a-layer-for-your-changes'> - <title>Create a Layer for your Changes</title> - - <para> - The first step is to create a layer so you can isolate your - changes. - Rather than use the <filename>yocto-layer</filename> script - to create the layer, this example steps through the process - by hand. - If you want information on the script that creates a general - layer, see the - "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" - section. - </para> - - <para> - These two commands create a directory you can use for your - layer: - <literallayout class='monospaced'> - $ cd ~/poky - $ mkdir meta-mylayer - </literallayout> - Creating a directory that follows the Yocto Project layer naming - conventions sets up the layer for your changes. - The layer is where you place your configuration files, append - files, and patch files. - To learn more about creating a layer and filling it with the - files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding - and Creating Layers</link>" section. - </para> - </section> - - <section id='finding-the-kernel-source-code'> - <title>Finding the Kernel Source Code</title> - - <para> - Each time you build a kernel image, the kernel source code is fetched - and unpacked into the following directory: - <literallayout class='monospaced'> - ${S}/linux - </literallayout> - See the "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>" - section and the - <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable - for more information about where source is kept during a build. - </para> - - <para> - For this example, we are going to patch the - <filename>init/calibrate.c</filename> file - by adding some simple console <filename>printk</filename> statements that we can - see when we boot the image using QEMU. - </para> - </section> - - <section id='creating-the-patch'> - <title>Creating the Patch</title> - - <para> - Two methods exist by which you can create the patch: - <link linkend='using-devtool-in-your-workflow'><filename>devtool</filename></link> and - <link linkend='using-a-quilt-workflow'>Quilt</link>. - For kernel patches, the Git workflow is more appropriate. - This section assumes the Git workflow and shows the steps specific to - this example. - <orderedlist> - <listitem><para><emphasis>Change the working directory</emphasis>: - Change to where the kernel source code is before making - your edits to the <filename>calibrate.c</filename> file: - <literallayout class='monospaced'> - $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux - </literallayout> - Because you are working in an established Git repository, - you must be in this directory in order to commit your changes - and create the patch file. - <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables - represent the version and revision for the - <filename>linux-yocto</filename> recipe. - The <filename>PV</filename> variable includes the Git meta and machine - hashes, which make the directory name longer than you might - expect. - </note></para></listitem> - <listitem><para><emphasis>Edit the source file</emphasis>: - Edit the <filename>init/calibrate.c</filename> file to have the - following changes: - <literallayout class='monospaced'> - void calibrate_delay(void) - { - unsigned long lpj; - static bool printed; - int this_cpu = smp_processor_id(); - - printk("*************************************\n"); - printk("* *\n"); - printk("* HELLO YOCTO KERNEL *\n"); - printk("* *\n"); - printk("*************************************\n"); - - if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { - . - . - . - </literallayout></para></listitem> - <listitem><para><emphasis>Stage and commit your changes</emphasis>: - These Git commands display the modified file, stage it, and then - commit the file: - <literallayout class='monospaced'> - $ git status - $ git add init/calibrate.c - $ git commit -m "calibrate: Add printk example" - </literallayout></para></listitem> - <listitem><para><emphasis>Generate the patch file</emphasis>: - This Git command creates the a patch file named - <filename>0001-calibrate-Add-printk-example.patch</filename> - in the current directory. - <literallayout class='monospaced'> - $ git format-patch -1 - </literallayout> - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='set-up-your-layer-for-the-build'> - <title>Set Up Your Layer for the Build</title> - - <para>These steps get your layer set up for the build: - <orderedlist> - <listitem><para><emphasis>Create additional structure</emphasis>: - Create the additional layer structure: - <literallayout class='monospaced'> - $ cd ~/poky/meta-mylayer - $ mkdir conf - $ mkdir recipes-kernel - $ mkdir recipes-kernel/linux - $ mkdir recipes-kernel/linux/linux-yocto - </literallayout> - The <filename>conf</filename> directory holds your configuration files, while the - <filename>recipes-kernel</filename> directory holds your append file and - your patch file.</para></listitem> - <listitem><para><emphasis>Create the layer configuration file</emphasis>: - Move to the <filename>meta-mylayer/conf</filename> directory and create - the <filename>layer.conf</filename> file as follows: - <literallayout class='monospaced'> - # We have a conf and classes directory, add to BBPATH - BBPATH .= ":${LAYERDIR}" - - # We have recipes-* directories, add to BBFILES - BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ - ${LAYERDIR}/recipes-*/*/*.bbappend" - - BBFILE_COLLECTIONS += "mylayer" - BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" - BBFILE_PRIORITY_mylayer = "5" - </literallayout> - Notice <filename>mylayer</filename> as part of the last three - statements.</para></listitem> - <listitem><para><emphasis>Create the kernel recipe append file</emphasis>: - Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create - the <filename>linux-yocto_3.4.bbappend</filename> file as follows: - <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - - SRC_URI += "file://0001-calibrate-Add-printk-example.patch" - </literallayout> - The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statements enable the OpenEmbedded build system to find the patch file. - For more information on using append files, see the - "<link linkend='using-bbappend-files'>Using .bbappend Files in Your Layer</link>" - section. - </para></listitem> - <listitem><para><emphasis>Put the patch file in your layer</emphasis>: - Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to - the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> - directory.</para></listitem> - </orderedlist> - </para> - </section> - - <section id='set-up-for-the-build'> - <title>Set Up for the Build</title> - - <para> - Do the following to make sure the build parameters are set up for the example. - Once you set up these build parameters, they do not have to change unless you - change the target architecture of the machine you are building: - <itemizedlist> - <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your - selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - definition within the <filename>local.conf</filename> file in the - <link linkend='build-directory'>Build Directory</link> - specifies the target architecture used when building the Linux kernel. - By default, <filename>MACHINE</filename> is set to - <filename>qemux86</filename>, which specifies a 32-bit - <trademark class='registered'>Intel</trademark> Architecture - target machine suitable for the QEMU emulator.</para></listitem> - <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename> - layer:</emphasis> The - <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> - variable in the - <filename>bblayers.conf</filename> file found in the - <filename>poky/build/conf</filename> directory needs to have the path to your local - <filename>meta-mylayer</filename> layer. - By default, the <filename>BBLAYERS</filename> variable contains paths to - <filename>meta</filename>, <filename>meta-poky</filename>, and - <filename>meta-yocto-bsp</filename> in the - <filename>poky</filename> Git repository. - Add the path to your <filename>meta-mylayer</filename> location: - <literallayout class='monospaced'> - BBLAYERS ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-poky \ - $HOME/poky/meta-yocto-bsp \ - $HOME/poky/meta-mylayer \ - " - </literallayout></para></listitem> - </itemizedlist> - </para> - </section> - - <section id='build-the-modified-qemu-kernel-image'> - <title>Build the Modified QEMU Kernel Image</title> - - <para> - The following steps build your modified kernel image: - <orderedlist> - <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>: - Your environment should be set up since you previously sourced - the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - script. - If it is not, source the script again from <filename>poky</filename>. - <literallayout class='monospaced'> - $ cd ~/poky - $ source &OE_INIT_FILE; - </literallayout> - </para></listitem> - <listitem><para><emphasis>Clean up</emphasis>: - Be sure to clean the shared state out by using BitBake - to run from within the Build Directory the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink> - task as follows: - <literallayout class='monospaced'> - $ bitbake -c cleansstate linux-yocto - </literallayout></para> - <para> - <note> - Never remove any files by hand from the - <filename>tmp/deploy</filename> - directory inside the - <link linkend='build-directory'>Build Directory</link>. - Always use the various BitBake clean tasks to - clear out previous build artifacts. - For information on the clean tasks, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>", - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>", - and - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>" - sections all in the Yocto Project Reference - Manual. - </note> - </para></listitem> - <listitem><para><emphasis>Build the image</emphasis>: - Next, build the kernel image using this command: - <literallayout class='monospaced'> - $ bitbake -k linux-yocto - </literallayout></para></listitem> - </orderedlist> - </para> - </section> - - <section id='boot-the-image-and-verify-your-changes'> - <title>Boot the Image and Verify Your Changes</title> - - <para> - These steps boot the image and allow you to see the changes - <orderedlist> - <listitem><para><emphasis>Boot the image</emphasis>: - Boot the modified image in the QEMU emulator - using this command: - <literallayout class='monospaced'> - $ runqemu qemux86 - </literallayout></para></listitem> - <listitem><para><emphasis>Verify the changes</emphasis>: - Log into the machine using <filename>root</filename> with no password and then - use the following shell command to scroll through the console's boot output. - <literallayout class='monospaced'> - # dmesg | less - </literallayout> - You should see the results of your <filename>printk</filename> statements - as part of the output.</para></listitem> - </orderedlist> - </para> - </section> </section> <section id='making-images-more-secure'> @@ -6812,7 +5951,7 @@ The security flags are in the <filename>meta/conf/distro/include/security_flags.inc</filename> file in your - <link linkend='source-directory'>Source Directory</link> + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> (e.g. <filename>poky</filename>). <note> Depending on the recipe, certain security flags are enabled @@ -6932,8 +6071,8 @@ <para> When you build an image using the Yocto Project and do not alter any distribution - <link linkend='metadata'>Metadata</link>, you are creating a - Poky distribution. + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>, + you are creating a Poky distribution. If you wish to gain more control over package alternative selections, compile-time options, and other low-level configurations, you can create your own distribution. @@ -6956,7 +6095,7 @@ configuration file makes it easier to reproduce the same build configuration when using multiple build machines. See the - "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" + "<link linkend='creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</link>" section for information on how to quickly set up a layer. </para></listitem> <listitem><para><emphasis>Create the distribution configuration file:</emphasis> @@ -7019,7 +6158,7 @@ previous bulleted item.</para></listitem> <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis> In your <filename>local.conf</filename> file in the - <link linkend='build-directory'>Build Directory</link>, + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, set your <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> variable to point to your distribution's configuration file. @@ -7044,7 +6183,7 @@ on how to add recipes to your layer, see the "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>" and - "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>" + "<link linkend='best-practices-to-follow-when-creating-layers'>Following Best Practices When Creating Layers</link>" sections.</para></listitem> <listitem><para>Add any image recipes that are specific to your distribution.</para></listitem> @@ -7079,7 +6218,7 @@ <filename>TEMPLATECONF</filename> to locate the directory from which it gathers configuration information that ultimately ends up in the - <link linkend='build-directory'>Build Directory's</link> + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> <filename>conf</filename> directory. By default, <filename>TEMPLATECONF</filename> is set as follows in the <filename>poky</filename> repository: @@ -7106,7 +6245,7 @@ The <filename>TEMPLATECONF</filename> variable is set in the <filename>.templateconf</filename> file, which is in the top-level - <link linkend='source-directory'>Source Directory</link> + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> folder (e.g. <filename>poky</filename>). Edit the <filename>.templateconf</filename> so that it can locate your directory. @@ -7137,12 +6276,10 @@ Aside from the <filename>*.sample</filename> configuration files, the <filename>conf-notes.txt</filename> also resides in the default <filename>meta-poky/conf</filename> directory. - The scripts that set up the build environment + The script that sets up the build environment (i.e. - <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> - and - <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>) - use this file to display BitBake targets as part of the script + <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>) + uses this file to display BitBake targets as part of the script output. Customizing this <filename>conf-notes.txt</filename> file is a good way to make sure your list of custom targets appears @@ -7296,7 +6433,7 @@ <para> To help you see where you currently are with kernel and root filesystem sizes, you can use two tools found in the - <link linkend='source-directory'>Source Directory</link> in + <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 @@ -7328,10 +6465,10 @@ <filename>scripts/kconfig</filename> directory.</para> <para>For more information on configuration fragments, see the - "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" - section of the Yocto Project Linux Kernel Development - Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" - section, which is in this manual.</para></listitem> + "<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 @@ -7957,7 +7094,7 @@ <para> As mentioned, attempting to maintain revision numbers in the - <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> is error prone, inaccurate, and causes problems for people submitting recipes. Conversely, the PR Service automatically generates @@ -8032,7 +7169,7 @@ setting <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink> in your <filename>local.conf</filename> file in the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: <literallayout class='monospaced'> PRSERV_HOST = "localhost:0" </literallayout> @@ -8333,7 +7470,7 @@ <filename>connman.inc</filename> file in the <filename>meta/recipes-connectivity/connman/</filename> directory of the <filename>poky</filename> - <link linkend='yocto-project-repositories'>source repository</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>source repository</ulink>. You can also find examples in <filename>meta/classes/kernel.bbclass</filename>. </para> @@ -8568,7 +7705,7 @@ <listitem><para> Open the <filename>local.conf</filename> file inside your - <link linkend='build-directory'>Build Directory</link> + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> (e.g. <filename>~/poky/build/conf/local.conf</filename>). </para></listitem> <listitem><para> @@ -8738,7 +7875,7 @@ file with the following content: <literallayout class='monospaced'> [oe-packages] - baseurl="http://my.server/rpm/i586 http://my.server/rpm/qemux86 http://my.server/rpm/all" + baseurl=http://my.server/rpm/i586 http://my.server/rpm/qemux86 http://my.server/rpm/all </literallayout> From the target machine, fetch the repository: <literallayout class='monospaced'> @@ -8920,13 +8057,10 @@ <para> In addition to being able to sign RPM packages, you can - also enable the OpenEmbedded build system to be able to - handle previously signed package feeds for IPK - packages. - <note> - The OpenEmbedded build system does not currently - support signed DPKG or RPM package feeds. - </note> + also enable signed package feeds for IPK and RPM packages. + </para> + + <para> The steps you need to take to enable signed package feed use are similar to the steps used to sign RPM packages. You must define the following in your @@ -9026,7 +8160,7 @@ and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> variables to your <filename>local.conf</filename> file, which is found in the - <link linkend='build-directory'>Build Directory</link>: + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: <literallayout class='monospaced'> DISTRO_FEATURES_append = " ptest" EXTRA_IMAGE_FEATURES += "ptest-pkgs" @@ -9262,8 +8396,8 @@ <para> By default, the OpenEmbedded build system uses the - <link linkend='build-directory'>Build Directory</link> when - building source code. + <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. @@ -9627,7 +8761,7 @@ Using either of the following statements in your image recipe or from within the <filename>local.conf</filename> file found in the - <link linkend='build-directory'>Build Directory</link> + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> causes the build system to create a read-only root filesystem: <literallayout class='monospaced'> IMAGE_FEATURES = "read-only-rootfs" @@ -10221,7 +9355,7 @@ <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink> variable to "1" in your <filename>local.conf</filename> file in the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: <literallayout class='monospaced'> TEST_IMAGE = "1" </literallayout> @@ -10249,7 +9383,7 @@ <para> All test files reside in <filename>meta/lib/oeqa/runtime</filename> in the - <link linkend='source-directory'>Source Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. A test name maps directly to a Python module. Each test module may contain a number of individual tests. Tests are usually grouped together by the area @@ -10353,7 +9487,8 @@ $ bitbake <replaceable>image</replaceable> -c testexport </literallayout> Exporting the tests places them in the - <link linkend='build-directory'>Build Directory</link> in + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + in <filename>tmp/testexport/</filename><replaceable>image</replaceable>, which is controlled by the <filename>TEST_EXPORT_DIR</filename> variable. @@ -10893,182 +10028,6 @@ </para> </section> -<!-- - <section id='platdev-gdb-remotedebug-setup'> - <title>Set Up the Cross-Development Debugging Environment</title> - - <para> - Before you can initiate a remote debugging session, you need - to be sure you have set up the cross-development environment, - toolchain, and sysroot. - The <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink> - describes this process. - </para> - </section> - - <section id="platdev-gdb-remotedebug-launch-gdbserver"> - <title>Launch gdbserver on the Target</title> - - <para> - Make sure gdbserver is installed on the target. - If it is not, install the package - <filename>gdbserver</filename>, which needs the - <filename>libthread-db1</filename> package. - </para> - - <para> - Here is an example, that when entered from the host, - connects to the target and launches gdbserver in order to - "debug" a binary named <filename>helloworld</filename>: - <literallayout class='monospaced'> - $ gdbserver localhost:2345 /usr/bin/helloworld - </literallayout> - gdbserver should now be listening on port 2345 for debugging - commands coming from a remote GDB process that is running on - the host computer. - Communication between gdbserver and the host GDB are done - using TCP. - To use other communication protocols, please refer to the - <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>. - </para> - </section> - - <section id="platdev-gdb-remotedebug-launch-gdb"> - <title>Launch GDB on the Host Computer</title> - - <para> - Running GDB on the host computer takes a number of stages, which - this section describes. - </para> - - <section id="platdev-gdb-remotedebug-launch-gdb-buildcross"> - <title>Build the Cross-GDB Package</title> - <para> - A suitable GDB cross-binary is required that runs on your - host computer but also knows about the the ABI of the - remote target. - You can get this binary from the - <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>. - Here is an example where the toolchain has been installed - in the default directory - <filename>/opt/poky/&DISTRO;</filename>: - <literallayout class='monospaced'> - /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb - </literallayout> - where <filename>arm</filename> is the target architecture - and <filename>linux-gnueabi</filename> is the target ABI. - </para> - - <para> - Alternatively, you can use BitBake to build the - <filename>gdb-cross</filename> binary. - Here is an example: - <literallayout class='monospaced'> - $ bitbake gdb-cross - </literallayout> - Once the binary is built, you can find it here: - <literallayout class='monospaced'> - tmp/sysroots/<replaceable>host-arch</replaceable>/usr/bin/<replaceable>target-platform</replaceable>/<replaceable>target-abi</replaceable>-gdb - </literallayout> - </para> - </section> - - <section id='create-the-gdb-initialization-file'> - <title>Create the GDB Initialization File and Point to Your Root Filesystem</title> - - <para> - Aside from the GDB cross-binary, you also need a GDB - initialization file in the same top directory in which - your binary resides. - When you start GDB on your host development system, GDB - finds this initialization file and executes all the - commands within. - For information on the <filename>.gdbinit</filename>, see - "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>", - which is maintained by - <ulink url='http://www.sourceware.org'>sourceware.org</ulink>. - </para> - - <para> - You need to add a statement in the - <filename>~/.gdbinit</filename> file that points to your - root filesystem. - Here is an example that points to the root filesystem for - an ARM-based target device: - <literallayout class='monospaced'> - set sysroot ~/sysroot_arm - </literallayout> - </para> - </section> - - <section id="platdev-gdb-remotedebug-launch-gdb-launchhost"> - <title>Launch the Host GDB</title> - - <para> - Before launching the host GDB, you need to be sure - you have sourced the cross-debugging environment script, - which if you installed the root filesystem in the default - location is at <filename>/opt/poky/&DISTRO;</filename> - and begins with the string "environment-setup". - For more information, see the - <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's - Guide</ulink>. - </para> - - <para> - Finally, switch to the directory where the binary resides - and run the <filename>cross-gdb</filename> binary. - Provide the binary file you are going to debug. - For example, the following command continues with the - example used in the previous section by loading - the <filename>helloworld</filename> binary as well as the - debugging information: - <literallayout class='monospaced'> - $ arm-poky-linux-gnuabi-gdb helloworld - </literallayout> - The commands in your <filename>.gdbinit</filename> execute - and the GDB prompt appears. - </para> - </section> - </section> - - <section id='platdev-gdb-connect-to-the-remote-gdb-server'> - <title>Connect to the Remote GDB Server</title> - - <para> - From the target, you need to connect to the remote GDB - server that is running on the host. - You need to specify the remote host and port. - Here is the command continuing with the example: - <literallayout class='monospaced'> - target remote 192.168.7.2:2345 - </literallayout> - </para> - </section> - - <section id="platdev-gdb-remotedebug-launch-gdb-using"> - <title>Use the Debugger</title> - - <para> - You can now proceed with debugging as normal - as if you were debugging - on the local machine. - For example, to instruct GDB to break in the "main" function and then - continue with execution of the inferior binary use the following commands - from within GDB: - <literallayout class='monospaced'> - (gdb) break main - (gdb) continue - </literallayout> - </para> - - <para> - For more information about using GDB, see the project's online documentation at - <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>. - </para> - </section> - </section> ---> - <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'> <title>Debugging with the GNU Project Debugger (GDB) on the Target</title> @@ -11347,7 +10306,7 @@ Once the patch file exists, you need to add it back to the originating recipe folder. Here is an example assuming a top-level - <link linkend='source-directory'>Source Directory</link> + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> named <filename>poky</filename>: <literallayout class='monospaced'> $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard @@ -11407,7 +10366,7 @@ need to submit the fix for the recipe in OE-Core and upstream so that the problem is taken care of at its source. See the - "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" + "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>" section for more information. </para> </section> @@ -11510,7 +10469,7 @@ 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 - <link linkend='build-directory'>Build Directory</link>: + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: <literallayout class='monospaced'> INHERIT += "archiver" ARCHIVER_MODE[src] = "original" @@ -11678,8 +10637,8 @@ " </literallayout> Creating and providing an archive of the - <link linkend='metadata'>Metadata</link> layers - (recipes, configuration files, and so forth) + <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. @@ -11697,7 +10656,7 @@ browse errors, view statistics, and query for errors. The tool works using a client-server system where the client portion is integrated with the installed Yocto Project - <link linkend='source-directory'>Source Directory</link> + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> (e.g. <filename>poky</filename>). The server receives the information collected and saves it in a database. @@ -11725,7 +10684,7 @@ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-report-error'><filename>report-error</filename></ulink> class by adding the following statement to the end of your <filename>local.conf</filename> file in your - <link linkend='build-directory'>Build Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. <literallayout class='monospaced'> INHERIT += "report-error" </literallayout> @@ -11784,7 +10743,7 @@ To disable the error reporting feature, simply remove or comment out the following statement from the end of your <filename>local.conf</filename> file in your - <link linkend='build-directory'>Build Directory</link>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. <literallayout class='monospaced'> INHERIT += "report-error" </literallayout> |