Yocto 2.4
Move OpenBMC to Yocto 2.4(rocko)
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I12057b18610d6fb0e6903c60213690301e9b0c67
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
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 598f877..0081738 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 remainder of this section presents information on the
- version 1.0 registration form and on the
- <filename>yocto-compat-layer.py</filename> script.
+ 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>
- <section id='yocto-project-compatibility-program-application'>
- <title>Yocto Project Compatibility Program Application</title>
+ <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
+ registration form and on the
+ <filename>yocto-check-layer</filename> script.
+ </para>
+
+ <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.
+ <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>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>
+ A <filename>README</filename> file, which is a file
+ describing the contents of your new layer.
</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:
+ 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'>
- $ yocto-layer create mylayer
+ $ bitbake-layers create-layer <replaceable>your_layer_name</replaceable>
</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.
+ 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>
- 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>).
- </para></listitem>
- <listitem><para><emphasis>The
- <filename>COPYING.MIT</filename> file:</emphasis>
- The copyright and use notice for the software.
- </para></listitem>
- <listitem><para><emphasis>The <filename>README</filename>
- file:</emphasis>
- 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".
- </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.
- </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.
- Here is an example where a layer named
- <filename>meta-mylayer</filename> is added:
+ You can add your layer by using the
+ <filename>bitbake-layers add-layer</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 <replaceable>your_layer_name</replaceable>
+ </literallayout>
+ Here is an example where a layer named
+ <filename>meta-scottrif</filename> is added and then the
+ layers are shown using the
+ <filename>bitbake-layers show-layers</filename> command:
+ <literallayout class='monospaced'>
+ $ 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.
- </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.
- </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.
- </para>
-
- <section id='wic-background'>
- <title>Background</title>
-
- <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='wic-requirements'>
- <title>Requirements</title>
-
- <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>
-
- <section id='wic-getting-help'>
- <title>Getting Help</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'>
+ 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>
+ </literallayout>
+ </para>
- <para>
- Currently, Wic supports two commands:
- <filename>create</filename> and <filename>list</filename>.
- You can get help for these commands as follows:
- <literallayout class='monospaced'>
+ <para>
+ 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>
- with <replaceable>command</replaceable> being either
- <filename>create</filename> or <filename>list</filename>.
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <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'>
+ <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>
+ </literallayout>
+ </para>
- <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'>
+ <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>
- with <filename><replaceable>image</replaceable></filename>
- being either <filename>directdisk</filename> or
- <filename>mkefidisk</filename>.
- </para>
- </section>
+ </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>
- <section id='operational-modes'>
- <title>Operational Modes</title>
+ <section id='operational-modes'>
+ <title>Operational Modes</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>
+ Regardless of the mode you use, you need to have the build
+ artifacts ready and available.
+ </para>
+
+ <section id='raw-mode'>
+ <title>Raw 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 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>
- 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 in raw mode is:
+ <literallayout class='monospaced'>
+ $ wic create <replaceable>wks_file</replaceable> <replaceable>options</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.
+ 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>
+ <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>
- -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.
+ <section id='cooked-mode'>
+ <title>Cooked Mode</title>
- -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>).
+ <para>
+ 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>
- -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.
-
- -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>
+ <para>
+ 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>kickstart_file</replaceable>
- An OpenEmbedded kickstart file. You can provide your own
- custom file or a supplied file.
+ <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 provided with the Yocto Project
+ release.
- <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>
- </section>
-
- <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'>
- $ wic list images
- directdisk Create a 'pcbios' direct disk image
- mkefidisk Create an EFI disk image
+ 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>
- 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'>
+ </para>
+ </section>
+ </section>
+
+ <section id='using-a-provided-kickstart-file'>
+ <title>Using an Existing Kickstart File</title>
+
+ <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
+ 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>
+ </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
-
+ <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 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>
<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>
-
- <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'>
+ 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
+ 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/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
+ 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
- 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>
+ 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>
- 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>
+ 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>
- 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>
+ <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 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>
+ 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>
+ <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>
+ 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>
- 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>
+ 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>
- 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>
+ 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>
- 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'>
+ <para>
+ 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'>
+ $ 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=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.
+ 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)...
- Creating image(s)...
-
- Info: The new image(s) can be found here:
- <replaceable>current_directory</replaceable>/build/directdisksdb-201310231131-sdb.direct
+ INFO: The new image(s) can be found here:
+ ./directdisksdb-gpt-201710090938-sdb.direct
The following build artifacts were used to create the image(s):
+ ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.hk3wl6zn/rootfs_copy
+ BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
- ROOTFS_DIR: /home/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
-
- 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/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>
+ 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>
+ </para>
</section>
- <section id='openembedded-kickstart-plugins'>
- <title>Plug-ins</title>
+ <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>
- 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.
+ 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
+
+ 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='using-wic-to-manipulate-an-image'>
+ <title>Using Wic to Manipulate an Image</title>
<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.
+ 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>
- 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.
+ 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>
- 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>.
- </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.
- </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.
- </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:
- <literallayout class='monospaced'>
- class BootimgPcbiosPlugin(SourcePlugin):
- name = 'bootimg-pcbios'
-
- @classmethod
- def do_prepare_partition(self, part, ...)
- </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>
-
- <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>
-
- <para>
- <itemizedlist>
+ The following example examines the contents of the Wic
+ image, deletes the existing kernel, and then inserts a
+ new kernel:
+ <orderedlist>
<listitem><para>
- <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
- Called to do the actual content population for a
+ <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>
+ <emphasis>Examine a Particular Partition:</emphasis>
+ Use the <filename>wic ls</filename> command again
+ but in a different form to examine a particular
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.
+ 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>
- </para></listitem>
- </itemizedlist>
- </para>
+ 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 ::/
- <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.
- </para>
- </section>
+ 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>
- <section id='openembedded-kickstart-wks-reference'>
- <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</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>.
- <note>
- Future updates will implement more commands and options.
- If you use anything that is not specifically
- supported, results can be unpredictable.
- </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>
- <listitem><para>
- <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
- </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>
+ <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.
+ An initial RAM filesystem (initramfs) image provides a temporary
+ root filesystem used for early system initialization (e.g.
+ loading of modules needed to locate and mount the "real" root
+ filesystem).
+ <note>
+ The initramfs image is the successor of initial RAM disk
+ (initrd).
+ It is a "copy in and out" (cpio) archive of the initial
+ filesystem that gets loaded into memory during the Linux
+ startup process.
+ Because Linux uses the contents of the archive during
+ initialization, the initramfs image needs to contain all of the
+ device drivers and tools needed to mount the final root
+ filesystem.
+ </note>
</para>
<para>
- 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:
+ Follow these steps to create an initramfs image:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Create the initramfs Image Recipe:</emphasis>
+ You can reference the
+ <filename>core-image-minimal-initramfs.bb</filename>
+ recipe found in the <filename>meta/recipes-core</filename>
+ directory of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ as an example from which to work.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Decide if You Need to Bundle the initramfs Image
+ Into the Kernel Image:</emphasis>
+ If you want the initramfs image that is built to be
+ bundled in with the kernel image, set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+ variable to "1" in your <filename>local.conf</filename>
+ configuration file and set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
+ variable in the recipe that builds the kernel image.
+ <note><title>Tip</title>
+ It is recommended that you do bundle the initramfs
+ image with the kernel image to avoid circular
+ dependencies between the kernel recipe and the
+ initramfs recipe should the initramfs image
+ include kernel modules.
+ </note>
+ Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
+ flag causes the initramfs image to be unpacked
+ into the <filename>${B}/usr/</filename> directory.
+ The unpacked initramfs image is then passed to the kernel's
+ <filename>Makefile</filename> using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
+ variable, allowing the initramfs image to be built into
+ the kernel normally.
+ <note>
+ If you choose to not bundle the initramfs image with
+ the kernel image, you are essentially using an
+ <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
+ Creating an initrd is handled primarily through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
+ <filename>INITRD_LIVE</filename>, and
+ <filename>INITRD_IMAGE_LIVE</filename> variables.
+ For more information, see the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
+ file.
+ </note>
+ </para></listitem>
+<!--
+Some notes from Cal:
+
+ A non-bundled initramfs is essentially an initrd, which I am discovering
+ to be rather confusingly supported in OE at the moment.
+
+ Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM)
+ variables. INITRD_IMAGE* is the primary image target, which gets added to
+ INITRD*, which is a list of cpio filesystems. You can add more cpio
+ filesystems to the INITRD variable to add more to the initrd. For
+ instance, meta-intel adds intel-microcode via the following:
+
+ INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}"
+
+ If 'intel-ucode' is in MACHINE_FEATURES, this resolves to:
+
+ INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio "
+
+ Unfortunately you need the full path, and its up to you to sort out
+ dependencies as well. For instance, we have the following:
+
+ MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}"
+
+ which resolves to:
+
+ MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode"
+
+ However, the above is only true with the "live" IMAGE_FSTYPE. Wic is
+ another beast entirely, with current wic kickstart files not supporting
+ initrds, and only partial support in the source plugins. That being said,
+ I know the generic bootfs work Ed is working on will help immensely in this
+ aspect. He or Saul can provide more details here.
+
+ Anyhow, its rather fractured and confusing and could probably use a
+ rework honestly. I don't know how feasible it is to document all the
+ details and corner cases of this area.
+-->
+ <listitem><para>
+ <emphasis>Optionally Add Items to the initramfs Image
+ Through the initramfs Image Recipe:</emphasis>
+ If you add items to the initramfs image by way of its
+ recipe, you should use
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
+ rather than
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
+ <filename>PACKAGE_INSTALL</filename> gives more direct
+ control of what is added to the image as compared to
+ the defaults you might not necessarily want that are
+ set by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
+ classes.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Kernel Image and the initramfs
+ Image:</emphasis>
+ Build your kernel image using BitBake.
+ Because the initramfs image recipe is a dependency of the
+ kernel image, the initramfs image is built as well and
+ bundled with the kernel image if you used the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+ variable described earlier.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='flashing-images-using-bmaptool'>
+ <title>Flashing Images Using <filename>bmaptool</filename></title>
+
+ <para>
+ 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>
+ 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>
+ For help on the <filename>bmaptool</filename> command, use the
+ following command:
<literallayout class='monospaced'>
- INITRAMFS_IMAGE_BUNDLE = "1"
- INITRAMFS_IMAGE = "<replaceable>image_recipe_name</replaceable>"
+ $ bmaptool --help
</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.
- <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.
- </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>
-
- <section id='fine-tuning-the-kernel-configuration-file'>
- <title>Fine-Tuning the Kernel Configuration File</title>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
- </section>
-
- <section id="patching-the-kernel">
- <title>Patching the Kernel</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.
- </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.
- </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.
- </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>