Squashed 'import-layers/yocto-poky/' changes from dc8508f6099..67491b0c104
Yocto 2.2.2 (Morty)
Change-Id: Id9a452e28940d9f166957de243d9cb1d8818704e
git-subtree-dir: import-layers/yocto-poky
git-subtree-split: 67491b0c104101bb9f366d697edd23c895be4302
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 086d0ba..b2a2e32 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
@@ -1379,11 +1379,11 @@
</literallayout>
Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
The options direct <filename>recipetool</filename> to
- run in "quiet mode" and to generate debugging information.
+ generate debugging information.
Once generated, the recipe resides in the existing source
code layer:
<literallayout class='monospaced'>
- recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable>
+ recipetool create -d -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable>
</literallayout>
</para>
</section>
@@ -2891,9 +2891,9 @@
machine, and a sysroot exists for the build host.
<note>
You could find the term "staging" used within the Yocto
- project regarding files populating sysroot.
- The term "staging" was used for previous releases of
- the Yocto Project.
+ project regarding files populating sysroot (e.g. the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DIR'><filename>STAGING_DIR</filename></ulink>
+ variable).
</note>
</para>
@@ -2906,7 +2906,12 @@
task within the
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
directory.
- A subset of these files automatically populates the sysroot.
+ </para>
+
+ <para>
+ A subset of these files, as defined by the
+ the <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink>
+ variable, automatically populates the sysroot.
The reason for this limitation is that almost all files that
populate the sysroot are cataloged in manifests in order to
ensure the files can be removed later when a recipe is either
@@ -2915,6 +2920,17 @@
</para>
<para>
+ It is possible to modify the list of directories that populate
+ the sysroot.
+ The following example shows how you could add the
+ <filename>/opt</filename> directory to the list of
+ directories:
+ <literallayout class='monospaced'>
+ SYSROOT_DIRS += "/opt"
+ </literallayout>
+ </para>
+
+ <para>
For information on variables you can use to help control how
files sysroot is populated, see the
<ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink>,
@@ -2996,6 +3012,13 @@
If the script succeeds, the package is marked as installed.
If the script fails, the package is marked as unpacked and
the script is executed when the image boots again.
+ <note>
+ Any RPM post-installation script that runs on the target
+ should return a 0 exit code.
+ RPM does not allow non-zero exit codes for these scripts,
+ and the RPM package manager will cause the package to fail
+ installation on the target.
+ </note>
</para>
<para>
@@ -3961,7 +3984,7 @@
</para></listitem>
</itemizedlist>
</para>
-'
+
<para>
For the RPM Package Management System, the following implementation details
exist:
@@ -4342,328 +4365,385 @@
format the device requires.
Should your device require multiple partitions on an SD card, flash,
or an HDD, you can use the OpenEmbedded Image Creator,
- <filename>wic</filename>, to create the properly partitioned image.
+ Wic, to create the properly partitioned image.
</para>
<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 applied to a given set of build artifacts, the result is an
- image or set of images that can be directly written onto media and
- used on a particular system.
+ You can 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.
</para>
- <para>
- The <filename>wic</filename> command and the infrastructure
- it is based on is by definition incomplete.
- Its purpose 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
- <filename>wic</filename>, describes what you need to have in
- place to run the tool, provides instruction on how to use
- <filename>wic</filename>, and provides several examples.
- </para>
-
- <section id='wic-background'>
- <title>Background</title>
+ <section id='creating-wic-images-oe'>
+ <title>Creating Partitioned Images</title>
<para>
- This section provides some background on the
- <filename>wic</filename> utility.
- While none of this information is required to use
- <filename>wic</filename>, you might find it interesting.
+ 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.
<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
- pronounce.</para></listitem>
+ 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>
- <filename>wic</filename> is loosely based on the
- Meego Image Creator (<filename>mic</filename>)
- framework.
- The <filename>wic</filename> 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>
- <filename>wic</filename> is a completely independent
- standalone utility that initially provides
- easier-to-use and more flexible replacements for a
- couple bits of 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
- <filename>wic</filename> and those examples is
- that with <filename>wic</filename> the
- functionality of those scripts is implemented
- by a general-purpose partitioning language, which is
- based on Redhat kickstart syntax.</para></listitem>
+ Include the name of the
+ <link linkend='openembedded-kickstart-wks-reference'>wic kickstart file</link>
+ 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='wic-requirements'>
- <title>Requirements</title>
+ <section id='create-wic-images-wic'>
+ <title>Using OpenEmbedded Image Creator Wic to Generate Partitioned Images</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 this
- list of distributions.</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
- <filename>wic</filename>, the current version of
- <filename>wic</filename> 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'>
+ 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 a
+ 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>
+ </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>
+ <section id='wic-getting-help'>
+ <title>Getting Help</title>
- <para>
- You can get general help for the <filename>wic</filename>
- by entering the <filename>wic</filename> command by itself
- or by entering the command with a help argument as follows:
- <literallayout class='monospaced'>
+ <para>
+ You can get general help for the <filename>wic</filename>
+ command by entering the <filename>wic</filename> command
+ by itself or by entering the command with a help argument
+ as follows:
+ <literallayout class='monospaced'>
$ wic -h
$ wic --help
- </literallayout>
- </para>
-
- <para>
- Currently, <filename>wic</filename> supports two commands:
- <filename>create</filename> and <filename>list</filename>.
- You can get help for these commands as follows:
- <literallayout class='monospaced'>
- $ wic help <replaceable>command</replaceable>
- </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'>
- $ wic help <replaceable>help_topic</replaceable>
- </literallayout>
- </para>
-
- <para>
- You can find out more about the images
- <filename>wic</filename> creates using the existing
- kickstart files with the following form of the command:
- <literallayout class='monospaced'>
- $ wic list <replaceable>image</replaceable> help
- </literallayout>
- where <filename><replaceable>image</replaceable></filename> is either
- <filename>directdisk</filename> or
- <filename>mkefidisk</filename>.
- </para>
- </section>
-
- <section id='operational-modes'>
- <title>Operational Modes</title>
-
- <para>
- You can use <filename>wic</filename> 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>
- </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>
+ </literallayout>
+ </para>
<para>
- The general form of the 'wic' command in raw mode is:
+ Currently, Wic supports two commands:
+ <filename>create</filename> and <filename>list</filename>.
+ You can get help for these commands as follows:
<literallayout class='monospaced'>
+ $ wic help <replaceable>command</replaceable>
+ with <replaceable>command</replaceable> being either
+ <filename>create</filename> or <filename>list</filename>.
+ </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'>
+ $ wic help <replaceable>help_topic</replaceable>
+ </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'>
+ $ wic list <replaceable>image</replaceable> help
+ </literallayout>
+ with <filename><replaceable>image</replaceable></filename>
+ being either <filename>directdisk</filename> or
+ <filename>mkefidisk</filename>.
+ </para>
+ </section>
+
+ <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
+ 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>
+ </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>] [...]
- Where:
+ Where:
- <replaceable>image_name</replaceable>.wks
- 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.
+ <replaceable>image_name</replaceable>.wks
+ 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.
+ -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable>
+ The name of a directory in which to create image.
- -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable>
- The name of a file containing the values for image
- properties as a JSON file.
+ -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable>
+ The name of a file containing the values for image
+ properties as a JSON file.
- -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable>
- The name of the image from which to use the artifacts
- (e.g. <filename>core-image-sato</filename>).
+ -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable>
+ The name of the image from which to use the artifacts
+ (e.g. <filename>core-image-sato</filename>).
- -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable>
- The path to the <filename>/rootfs</filename> directory to use as the
- <filename>.wks</filename> rootfs source.
+ -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.
+ -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.
+ -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.
+ -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.
+ -s, --skip-build-check
+ Skips the build check.
- -D, --debug
- Output debug information.
- </literallayout>
- <note>
- You do not need root privileges to run
- <filename>wic</filename>.
- In fact, you should not run as root when using the
- utility.
- </note>
- </para>
- </section>
+ -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>
+ <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'>
+ <para>
+ The general form of the <filename>wic</filename> command
+ using Cooked Mode is:
+ <literallayout class='monospaced'>
$ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable>
- Where:
+ Where:
- <replaceable>kickstart_file</replaceable>
- An OpenEmbedded kickstart file. You can provide your own
- custom file or supplied file.
+ <replaceable>kickstart_file</replaceable>
+ An OpenEmbedded kickstart file. You can provide your own
+ custom file or a supplied file.
- <replaceable>image_name</replaceable>
- Specifies the image built using the OpenEmbedded build
- system.
- </literallayout>
- This form is the simplest and most user-friendly, as it
- does not require specifying all individual parameters.
- All you need to provide is your own
- <filename>.wks</filename> file or one provided with the
- release.
- </para>
+ <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>
- <section id='using-a-provided-kickstart_file'>
- <title>Using an Existing Kickstart File</title>
+ <section id='using-a-provided-kickstart-file'>
+ <title>Using an Existing Kickstart File</title>
- <para>
- If you do not want to create your own
- <filename>.wks</filename> file, you can use an existing
- file provided by the <filename>wic</filename> installation.
- Use the following command to list the available files:
- <literallayout class='monospaced'>
+ <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
- </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'>
+ </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'>
+ <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.
@@ -4675,30 +4755,30 @@
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>
+ </literallayout>
+ </para>
+ </section>
- <section id='wic-usage-examples'>
- <title>Examples</title>
-
- <para>
- This section provides several examples that show how to use
- the <filename>wic</filename> utility.
- All the examples assume the list of requirements in the
- "<link linkend='wic-requirements'>Requirements</link>" section
- have been met.
- The examples assume the previously generated image is
- <filename>core-image-minimal</filename>.
- </para>
-
- <section id='generate-an-image-using-a-provided-kickstart-file'>
- <title>Generate an Image using an Existing Kickstart File</title>
+ <section id='wic-usage-examples'>
+ <title>Examples</title>
<para>
- This example runs in Cooked Mode and uses the
- <filename>mkefidisk</filename> kickstart file:
- <literallayout class='monospaced'>
+ 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'>
$ wic create mkefidisk -e core-image-minimal
Checking basic build environment...
Done.
@@ -4714,114 +4794,115 @@
KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel
NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
-
The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
- </literallayout>
- This 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>
+ </literallayout>
+ The previous example shows the easiest way to create
+ an image by running in Cooked Mode and using the
+ <filename>-e</filename> option with an existing
+ kickstart file.
+ All that is necessary is to specify the image used to
+ generate the artifacts.
+ Your <filename>local.conf</filename> needs to have the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable set to the machine you are using, which is
+ "minnow" in this example.
+ </para>
- <para>
- The output specifies the exact image created as well as
- where it was created.
- 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>
+ The output specifies the exact image created as well as
+ where it was created.
+ The output also names the artifacts used and the exact
+ <filename>.wks</filename> script that was used to
+ generate the image.
+ <note>
+ You should always verify the details provided in the
+ output to make sure that the image was indeed
+ created exactly as expected.
+ </note>
+ </para>
- <para>
- Continuing with the example, you can now 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'>
+ <para>
+ 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=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
[sudo] password for trz:
182274+0 records in
182274+0 records out
93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s
- [trz@empanada ~]$ sudo eject /dev/sdb
- </literallayout>
- </para>
- </section>
+ [trz at empanada ~]$ sudo eject /dev/sdb
+ </literallayout>
+ </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 <filename>wic</filename> 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</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 these files reside is
+ <filename>scripts/lib/image/canned-wks/</filename>
+ located in the
+ <link linkend='source-directory'>Source Directory</link>.
+ Because the available files reside in this directory,
+ you can create and add your own custom files to the
+ directory.
+ Subsequent use of the
+ <filename>wic list images</filename> command would then
+ include your kickstart files.
+ </para>
- <para>
- In this example, the existing
- <filename>directdisk</filename> file already does most
- of what is needed.
- However, for the hardware in this example, the image will
- need to boot from <filename>sdb</filename> instead of
- <filename>sda</filename>, which is what the
- <filename>directdisk</filename> kickstart file uses.
- </para>
+ <para>
+ In this example, the existing
+ <filename>directdisk</filename> file already does most
+ of what is needed.
+ However, for the hardware in this example, the image
+ will need to boot from <filename>sdb</filename> instead
+ of <filename>sda</filename>, which is what the
+ <filename>directdisk</filename> kickstart file uses.
+ </para>
- <para>
- The example begins by making a copy of the
- <filename>directdisk.wks</filename> file in the
- <filename>scripts/lib/image/canned-wks</filename>
- directory and then changing the lines that specify the
- target disk from which to boot.
- <literallayout class='monospaced'>
+ <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'>
+ </literallayout>
+ Next, the example modifies the
+ <filename>directdisksdb.wks</filename> file and changes
+ all instances of "<filename>--ondisk sda</filename>"
+ to "<filename>--ondisk sdb</filename>".
+ The example changes the following two lines and leaves
+ the remaining lines untouched:
+ <literallayout class='monospaced'>
part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
- </literallayout>
- Once the lines are changed, the example generates the
- <filename>directdisksdb</filename> image.
- The command points the process at the
- <filename>core-image-minimal</filename> artifacts for the
- Next Unit of Computing (nuc)
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- the <filename>local.conf</filename>.
- <literallayout class='monospaced'>
+ </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.
@@ -4832,39 +4913,39 @@
/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct
The following build artifacts were used to create the image(s):
+
ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs
BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share
KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel
NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
-
The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
- </literallayout>
- Continuing with the example, you can now directly
- <filename>dd</filename> the image to a USB stick, or
- whatever media for which you built your image,
- and boot the resulting media:
- <literallayout class='monospaced'>
+ </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=/var/tmp/wic/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@empanada tmp]$ sudo eject /dev/sdb
- </literallayout>
- </para>
- </section>
+ [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>
+ <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'>
+ <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...
@@ -4884,21 +4965,21 @@
The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
- </literallayout>
- </para>
- </section>
+ </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>
+ <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 <filename>wic</filename> to create the output
- somewhere other than the default
- <filename>/var/tmp/wic</filename> directory:
- <literallayout class='monospaced'>
+ <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
+ <filename>/var/tmp/wic</filename> 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 \
@@ -4919,441 +5000,555 @@
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>
+ </literallayout>
+ For this example,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ did not have to be specified in the
+ <filename>local.conf</filename> file since the
+ artifact is manually specified.
+ </para>
+ </section>
</section>
- </section>
- <section id='openembedded-kickstart-plugins'>
- <title>Plug-ins</title>
+ <section id='openembedded-kickstart-plugins'>
+ <title>Plug-ins</title>
- <para>
- Plug-ins allow <filename>wic</filename> functionality to
- be extended and specialized by users.
- This section documents the plugin interface, which is
- currently restricted to source plug ins.
- </para>
+ <para>
+ Plug-ins allow Wic functionality to
+ be extended and specialized by users.
+ This section documents the plug-in interface, which is
+ currently restricted to source plug-ins.
+ </para>
- <para>
- Source plug ins provide a mechanism to customize
- various aspects of the image generation process in
- <filename>wic</filename>, 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 plugin implementation that populates a
- corresponding partition.
- </para>
+ <para>
+ Source plug-ins provide a mechanism to customize
+ various aspects of the image generation process in
+ Wic, mainly the contents of
+ partitions.
+ The plug-ins provide a mechanism for mapping values
+ specified in <filename>.wks</filename> files using the
+ <filename>--source</filename> keyword to a
+ particular plug-in implementation that populates a
+ corresponding partition.
+ </para>
- <para>
- A source plugin is created as a subclass of
- <filename>SourcePlugin</filename>.
- The plugin file containing it is added to
- <filename>scripts/lib/wic/plugins/source/</filename> to
- make the plugin implementation available to the
- <filename>wic</filename> implementation.
- For more information, see
- <filename>scripts/lib/wic/pluginbase.py</filename>.
- </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 plugins can also be implemented and added by
- external layers.
- As such, any plugins found in a
- <filename>scripts/lib/wic/plugins/source/</filename>
- directory in an external layer are also made
- available.
- </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 <filename>wic</filename> implementation needs
- to invoke a partition-specific implementation, it looks
- for the plugin 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'>
+ <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 plugin
- having the matching <filename>bootimg-pcbios.name</filename>
- class member are used.
- </para>
+ </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 plugin definition that
- matches a
- <filename>--source bootimg-pcbios</filename> usage,
- along with an example
- method called by the <filename>wic</filename> implementation
- when it needs to invoke an implementation-specific
- partition-preparation function:
- <literallayout class='monospaced'>
+ <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 plugins 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> plugins.
- 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>
- <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis>
- Called to do the actual content population for a
- partition.
- In other words, the method prepares the final
- partition image that is incorporated into the
- disk image.
- </para></listitem>
- <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis>
- Called before
- <filename>do_prepare_partition()</filename>.
- This method is typically used to create custom
- configuration files for a partition (e.g. syslinux or
- grub configuration files).
- </para></listitem>
- <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis>
- Called after all partitions have been prepared and
- assembled into a disk image.
- This method provides a hook to allow finalization of a
- disk image, (e.g. writing an MBR).
- </para></listitem>
- <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis>
- Special content-staging hook called before
- <filename>do_prepare_partition()</filename>.
- This method is normally empty.</para>
- <para>Typically, a partition just uses the passed-in
- parameters (e.g. the unmodified value of
- <filename>bootimg_dir</filename>).
- However, in some cases things might need to be
- more tailored.
- As an example, certain files might additionally
- need to be taken from
- <filename>bootimg_dir + /boot</filename>.
- This hook allows those files to be staged in a
- customized fashion.
- <note>
- <filename>get_bitbake_var()</filename>
- allows you to access non-standard variables
- that you might want to use for this.
- </note>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- This scheme is extensible.
- Adding more hooks is a simple matter of adding more
- plugin methods to <filename>SourcePlugin</filename> and
- derived classes.
- The code that then needs to call the plugin 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 <filename>wic</filename>
- implementation for examples and details.
- </para>
- </section>
-
- <section id='openembedded-kickstart-wks-reference'>
- <title>OpenEmbedded Kickstart (.wks) Reference</title>
-
- <para>
- The current <filename>wic</filename> 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 <filename>wic</filename> 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>
+ </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>
- Either of these commands create a partition on the system
- and uses the following syntax:
- <literallayout class='monospaced'>
+ 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>
+ <listitem><para>
+ <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
+ Called to do the actual content population for a
+ partition.
+ In other words, the method prepares the final
+ partition image that is incorporated into the
+ disk image.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_configure_partition()</filename>:</emphasis>
+ Called before
+ <filename>do_prepare_partition()</filename>.
+ This method is typically used to create custom
+ configuration files for a partition (e.g. syslinux
+ or grub configuration files).
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_install_disk()</filename>:</emphasis>
+ Called after all partitions have been prepared and
+ assembled into a disk image.
+ This method provides a hook to allow finalization
+ of a disk image, (e.g. writing an MBR).
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_stage_partition()</filename>:</emphasis>
+ Special content-staging hook called before
+ <filename>do_prepare_partition()</filename>.
+ This method is normally empty.</para>
+ <para>Typically, a partition just uses the passed-in
+ parameters (e.g. the unmodified value of
+ <filename>bootimg_dir</filename>).
+ However, in some cases things might need to be
+ more tailored.
+ As an example, certain files might additionally
+ need to be taken from
+ <filename>bootimg_dir + /boot</filename>.
+ This hook allows those files to be staged in a
+ customized fashion.
+ <note>
+ <filename>get_bitbake_var()</filename>
+ allows you to access non-standard variables
+ that you might want to use for this.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <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>
+
+ <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>
+ </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, <filename>/</filename>,
- <filename>/usr</filename>, or
- <filename>/home</filename></para></listitem>
- <listitem><para><filename>swap</filename>:
- The created partition is used as swap space.
- </para></listitem>
- </itemizedlist>
- </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, <filename>/</filename>,
+ <filename>/usr</filename>, or
+ <filename>/home</filename>
+ </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'>
+ <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>
+ </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
- <filename>wic</filename>-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 plugin.
- For information on the source plugins, see the
- "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
- section.</para>
- <para>If you use
- <filename>--source rootfs</filename>,
- <filename>wic</filename> 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>,
- <filename>wic</filename> creates a partition as
- large as needed and fills it with the contents of
- the partition that is generated by the
- specified plugin 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 plugin
- 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>
+ 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><filename>ext3</filename>
+ <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><filename>ext2</filename>
+ <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><filename>btrfs</filename>
+ <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><filename>squashfs</filename>
+ <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><filename>swap</filename>
+ <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>
- </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 <filename>wic</filename>-specific
- option that says to start a partition on an
- x KBytes boundary.</para></listitem>
- <listitem><para><emphasis><filename>--no-table</filename>:</emphasis>
- This option is a <filename>wic</filename>-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 <filename>wic</filename>-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 <filename>wic</filename>-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 <filename>wic</filename>-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 <filename>wic</filename>-specific
- option that causes <filename>wic</filename> 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 <filename>wic</filename>-specific
- option that specifies the partition UUID.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
+ <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>
+ <section id='command-bootloader'>
+ <title>Command: bootloader</title>
- <para>
- This command specifies how the boot loader should be
- configured and supports the following options:
- <note>
- Bootloader functionality and boot partitions are
- implemented by the various
- <filename>--source</filename>
- plugins 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>
+ <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>
</section>
</section>
+ <section id='building-an-initramfs-image'>
+ <title>Building an Initial RAM Filesystem (initramfs) Image</title>
+
+ <para>
+ initramfs is the successor of Initial RAM Disk (initrd).
+ It is a "copy in and out" (cpio) archive of the initial file system
+ that gets loaded into memory during the Linux startup process.
+ Because Linux uses the contents of the archive during
+ initialization, the initramfs needs to contain all of the device
+ drivers and tools needed to mount the final root filesystem.
+ </para>
+
+ <para>
+ To build an initramfs image and bundle it into the kernel, set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+ variable in your <filename>local.conf</filename> file, and set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
+ variable in your <filename>machine.conf</filename> file:
+ <literallayout class='monospaced'>
+ INITRAMFS_IMAGE_BUNDLE = "1"
+ INITRAMFS_IMAGE = "<replaceable>image_recipe_name</replaceable>"
+ </literallayout>
+ Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
+ flag causes the initramfs created by the recipe and defined by
+ <filename>INITRAMFS_IMAGE</filename> to be unpacked into the
+ <filename>${B}/usr/</filename> directory.
+ The unpacked initramfs is then passed to the kernel's
+ <filename>Makefile</filename> using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
+ variable, allowing initramfs to be built in to the kernel
+ normally.
+ <note>
+ The preferred method is to use the
+ <filename>INITRAMFS_IMAGE</filename> variable rather than the
+ <filename>INITRAMFS_TASK</filename> variable.
+ Setting <filename>INITRAMFS_TASK</filename> is supported for
+ backward compatibility.
+ However, use of this variable has circular dependency
+ problems.
+ See the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+ variable for additional information on these dependency
+ problems.
+ </note>
+ </para>
+
+ <para>
+ The recipe that <filename>INITRAMFS_IMAGE</filename>
+ points to must produce a <filename>.cpio.gz</filename>,
+ <filename>.cpio.tar</filename>, <filename>.cpio.lz4</filename>,
+ <filename>.cpio.lzma</filename>, or
+ <filename>.cpio.xz</filename> file.
+ You can ensure you produce one of these <filename>.cpio.*</filename>
+ files by setting the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></ulink>
+ variable in your configuration file to one or more of the above
+ file types.
+ <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>
@@ -7499,26 +7694,29 @@
</para>
<para>
- If a committed change results in changing the package output,
- then the value of the PR variable needs to be increased
- (or "bumped") as part of that commit.
+ If a committed change results in changing the package
+ output, then the value of the PR variable needs to be
+ increased (or "bumped") as part of that commit.
For new recipes you should add the <filename>PR</filename>
- variable and set its initial value equal to "r0", which is the default.
- Even though the default value is "r0", the practice of adding it to a new recipe makes
- it harder to forget to bump the variable when you make changes
- to the recipe in future.
+ variable and set its initial value equal to "r0", which is
+ the default.
+ Even though the default value is "r0", the practice of
+ adding it to a new recipe makes it harder to forget to bump
+ the variable when you make changes to the recipe in future.
</para>
<para>
- If you are sharing a common <filename>.inc</filename> file with multiple recipes,
- you can also use the
+ If you are sharing a common <filename>.inc</filename> file
+ with multiple recipes, you can also use the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
- variable to ensure that
- the recipes sharing the <filename>.inc</filename> file are rebuilt when the
+ variable to ensure that the recipes sharing the
+ <filename>.inc</filename> file are rebuilt when the
<filename>.inc</filename> file itself is changed.
- The <filename>.inc</filename> file must set <filename>INC_PR</filename>
- (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
- to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
+ The <filename>.inc</filename> file must set
+ <filename>INC_PR</filename> (initially to "r0"), and all
+ recipes referring to it should set <filename>PR</filename>
+ to "${INC_PR}.0" initially, incrementing the last number
+ when the recipe is changed.
If the <filename>.inc</filename> file is changed then its
<filename>INC_PR</filename> should be incremented.
</para>
@@ -7527,14 +7725,14 @@
When upgrading the version of a package, assuming the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
changes, the <filename>PR</filename> variable should be
- reset to "r0" (or "$(INC_PR).0" if you are using
+ reset to "r0" (or "${INC_PR}.0" if you are using
<filename>INC_PR</filename>).
</para>
<para>
Usually, version increases occur only to packages.
- However, if for some reason <filename>PV</filename> changes but does not
- increase, you can increase the
+ However, if for some reason <filename>PV</filename> changes
+ but does not increase, you can increase the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
variable (Package Epoch).
The <filename>PE</filename> variable defaults to "0".
@@ -7544,7 +7742,8 @@
Version numbering strives to follow the
<ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
Debian Version Field Policy Guidelines</ulink>.
- These guidelines define how versions are compared and what "increasing" a version means.
+ These guidelines define how versions are compared and what
+ "increasing" a version means.
</para>
</section>
</section>
@@ -9520,27 +9719,47 @@
<para>
If your image is already built, make sure the following are set
- in your <filename>local.conf</filename> file.
- Be sure to provide the IP address you need:
+ in your <filename>local.conf</filename> file:
<literallayout class='monospaced'>
INHERIT +="testexport"
- TEST_TARGET_IP = "192.168.7.2"
- TEST_SERVER_IP = "192.168.7.1"
+ TEST_TARGET_IP = "<replaceable>IP-address-for-the-test-target</replaceable>"
+ TEST_SERVER_IP = "<replaceable>IP-address-for-the-test-server</replaceable>"
</literallayout>
- You can then export the tests with the following:
+ You can then export the tests with the following BitBake
+ command form:
<literallayout class='monospaced'>
- $ bitbake core-image-sato -c testexport
+ $ bitbake <replaceable>image</replaceable> -c testexport
</literallayout>
Exporting the tests places them in the
<link linkend='build-directory'>Build Directory</link> in
- <filename>tmp/testexport/core-image-sato</filename>, which
- is controlled by the
+ <filename>tmp/testexport/</filename><replaceable>image</replaceable>,
+ which is controlled by the
<filename>TEST_EXPORT_DIR</filename> variable.
</para>
<para>
You can now run the tests outside of the build environment:
<literallayout class='monospaced'>
+ $ cd tmp/testexport/<replaceable>image</replaceable>
+ $ ./runexported.py testdata.json
+ </literallayout>
+ </para>
+
+ <para>
+ Here is a complete example that shows IP addresses and uses
+ the <filename>core-image-sato</filename> image:
+ <literallayout class='monospaced'>
+ INHERIT +="testexport"
+ TEST_TARGET_IP = "192.168.7.2"
+ TEST_SERVER_IP = "192.168.7.1"
+ </literallayout>
+ Use BitBake to export the tests:
+ <literallayout class='monospaced'>
+ $ bitbake core-image-sato -c testexport
+ </literallayout>
+ Run the tests outside of the build environment using the
+ following:
+ <literallayout class='monospaced'>
$ cd tmp/testexport/core-image-sato
$ ./runexported.py testdata.json
</literallayout>