mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-31 12:49:46 +00:00
Code Issues Projects Releases Wiki Activity

dev-manual: More work on the new wic section.

Browse Source 
I am working through the raw text.  Not clear through yet but
needed to commit this.

(From yocto-docs rev: 4da28c311443ad31a0a36b07b39aa7ce4180b49c)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2013-11-13 17:14:56 -08:00
committed by Richard Purdie
parent fa191d4882
commit b0c4c855a0
1 changed files with 388 additions and 409 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/dev-manual/dev-manual-common-tasks.xml
+388 -409
View File
@@ -1926,18 +1926,16 @@
that image as is on your device. that image as is on your device.
Physical devices accept and boot images in various ways depending Physical devices accept and boot images in various ways depending
on the specifics of the device. on the specifics of the device.
Usually information about the hardware can tell you what image Usually, information about the hardware can tell you what image
format the device requires. format the device requires.
Should your device require multiple partitions on an SD card, flash, Should your device require multiple partitions on an SD card, flash,
or an HDD, you can use the OpenEmbedded Image Creator or an HDD, you can use the OpenEmbedded Image Creator
(<filename>wic</filename>) to create the properly partitioned image. () to create the properly partitioned image.
</para> </para>
<para> <para>
Using the <filename>wic</filename> command, you can also describe The <filename>wic</filename> command generates partitioned images
your desired final image and have BitBake assemble the image. from existing OpenEmbedded build artifacts.
The 'wic' command generates partitioned images from existing
OpenEmbedded build artifacts.
Image generation is driven by partitioning commands contained Image generation is driven by partitioning commands contained
in an Openembedded kickstart file (<filename>.wks</filename>) in an Openembedded kickstart file (<filename>.wks</filename>)
specified either directly on the command-line or as one of a specified either directly on the command-line or as one of a
@@ -1949,28 +1947,53 @@
</para> </para>
<para> <para>
'wic' is based loosely on the 'mic' (Meego Image Creator) framework, This section provides some background information on
but heavily modified to make direct use of OpenEmbedded build <filename>wic</filename>, describes what you need to have in
artifacts instead of package installation and configuration, things place to run the tool, provides instruction on how to use
already incorporated in the OE artifacts. <filename>wic</filename>, and provides several examples.
</para> </para>
<note> <section id='wic-background'>
The name 'wic' comes from 'oeic', which stands for 'OpenEmbedded <title>Background</title>
Image Creator'. The 'oe' diphthong in 'oeic' has been promoted to the
letter 'w', because 'oeic' is impossible to remember or pronounce.
</note>
<note> <para>
This is a completely independent standalone utility that This section provides some background on the
initially provides easier-to-use and more flexible replacements for a <filename>wic</filename> utility.
couple bits of existing functionality in oe-core: directdisk.bbclass While none of this information is required to use
and mkefidisk.sh. The replaced scripts are implemented by a <filename>wic</filename>, you might find it interesting.
general-purpose partitioning 'language' based on Red Hat kickstart <itemizedlist>
syntax (with the underlying code borrowed from Tizen mic, which in <listitem><para>
turn was borrowed from Meego mic, in turn borrowed from Fedora livecd, The name "wic" is derived from OpenEmbedded
etc.). Image Creator (oeic).
</note> The "oe" diphthong in "oeic" was promoted to the
letter "w", because "oeic" is both difficult to remember and
pronounce.</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
<filename>directdisk.bbclass</filename> and
<filename>mkefidisk.sh</filename> script.
The replaced scripts are implemented by a
general-purpose partitioning language based on Red Hat
kickstart syntax.
Underlying code for <filename>wic</filename> succeeded
from several projects over time.</para></listitem>
</itemizedlist>
</para>
</section>
<!--
<para> <para>
This section covers the mechanics of invoking and providing help for This section covers the mechanics of invoking and providing help for
@@ -1996,310 +2019,233 @@ or missing feature of the tool, please file a bug report describing
the details. the details.
</note> </note>
<section id='requirements'> -->
<section id='wic-requirements'>
<title>Requirements</title> <title>Requirements</title>
<para> <para>
wic has only been tested on and is only designed to work on the In order to use the <filename>wic</filename> utility with the
distros officially supported by Yocto. OpenEmbedded Build system, you need to meet the following
</para> requirements:
<para>
Aside from the standard system utilities, such as 'cp', wic expects the
following utilities to be installed on the host machine:
<itemizedlist> <itemizedlist>
<listitem><para><emphasis>parted:</emphasis> <listitem><para>The Linux distribution on your
GNU Parted - a partition manipulation program 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>
The
<ulink url='http://www.gnu.org/software/parted/'>GNU Parted</ulink>
package must be installed on your development host
system.
</para></listitem>
<listitem><para>
Have the build artifacts already available.
You must already have created an image using the
Openembedded build system (e.g.
<filename>core-image-minimal</filename>.
It might seem redundant to generate an image in order
to create an image using <filename>wic</filename>,
but the artifacts are needed and they are generated
with the build system.</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> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</section> </section>
<section id='raw-vs-cooked-mode'> <section id='wic-getting-help'>
<title>Raw Vs. Cooked Mode</title> <title>Getting Help</title>
<para> <para>
'wic' can be used in 'raw' mode, where artifacts are explicitly You can get general help for the <filename>wic</filename>
specified via command-line arguments (see the command documentation by entering the <filename>wic</filename> command by itself
and examples below), or it can be used in a more easily usable or by entering the command with a help argument as follows:
'cooked' mode which uses the current MACHINE setting and a specified <literallayout class='monospaced'>
image name to automatically locate the artifacts used to create the $ wic -h
image. $ wic --help
</literallayout>
</para> </para>
<note> <para>
The prerequisite for generating any image is to have the build Currently, <filename>wic</filename> supports two commands:
artifacts already available. For example, to create a 'wic' image <filename>create</filename> and <filename>list</filename>.
using the build artifacts from a core-image-minimal build, you must You can get help for these commands as follows:
already have created a core-image-minimal OpenembeddedCore image. It <literallayout class='monospaced'>
may seem redundant to generate an OpenEmbedded image in order to $ wic help &lt;command&gt;
create a 'wic' image, and in fact to some degree it is. At the </literallayout>
moment, however, that's typically how build artifacts are generated, </para>
and future versions will likely be more integrated into the build
system and will be able to skip that step. There is a benefit <para>
however, in that 'wic' images are created more quickly and without the You can find more out about the images
need for root access. <filename>wic</filename> creates using the provided
</note> kickstart files with the following form of the command:
<literallayout class='monospaced'>
$ wic list &lt;image&gt; help
</literallayout>
Where <filename>&lt;image&gt;</filename> is either
<filename>directdisk</filename> or
<filename>mkefidisk</filename>.
</para>
</section> </section>
<section id='command-summary'> <section id='operational-modes'>
<title>Command Summary</title> <title>Operational Modes</title>
<para> <para>
The general form of the 'wic' command in raw mode is: You can run <filename>wic</filename> in two modes: Raw and
<literallayout class='monospaced'> Cooked:
$ wic create myimage.wks -r &lt;rootfs-dir&gt; -b &lt;bootimg-dir&gt;
-k &lt;kernel-dir&gt; -n &lt;native-sysroot&gt;
</literallayout>
<note>
The 'wic' does NOT require root privileges, and in fact should
not be run as root.
</note>
</para>
<para>
The .wks file specified in the command is an OE kickstart file (see
the OE kickstart syntax section below) and can of course be specified
directly on the command-line, but the user can also choose from a set
of 'canned' .wks files available via the 'wic list images' command
(example below).
</para>
<para>
The -r, -b, -k, and -n options refer to the corresponding OpenEmbedded
build artifacts. Using OpenEmbedded terminology:
<itemizedlist> <itemizedlist>
<listitem><para><emphasis>-r option:</emphasis> <listitem><para><emphasis>Raw Mode:</emphasis>
Used to specify the path to the /rootfs dir to You explicitly specify build artifacts through
use as the .wks rootfs source.</para></listitem> command-line arguments.</para></listitem>
<listitem><para><emphasis>-b option:</emphasis> <listitem><para><emphasis>Cooked Mode:</emphasis>
Used to specify the path to the dir containing The current
the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the <ulink url='&YOCTO_DOCS_REF_URL;var-MACHINE'><filename>MACHINE</filename></ulink>
.wks bootimg source.</para></listitem> setting and image name are used to automatically locate
<listitem><para><emphasis>-k option:</emphasis> and provide the build artifacts.</para></listitem>
Used to specify the path to the dir containing
the kernel to use in the .wks bootimg.
</para></listitem>
<listitem><para><emphasis>-n option:</emphasis>
Used to specify the path to the native sysroot
containing the tools to use to build the image.
</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <section id='raw-mode'>
For more technical detail on the origin and meanings of those <title>Raw Mode</title>
artifacts, see the Yocto documentation corresponding to those topics
elsewhere. In most cases, it's not important to know that, because <para>
'cooked' mode provides a convenient shortcut allowing the user to The general form of the 'wic' command in raw mode is:
forget about the raw details and simply specify artifacts via a <literallayout class='monospaced'>
high-level OpenEmbedded image name. $ wic create &lt;image_name&gt;.wks -r &lt;rootfs_dir&gt; -b &lt;bootimg_dir&gt; /
</para> -k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt;
</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>
<para>
Following is a description of the <filename>wic</filename>
parameters and options:
<itemizedlist>
<listitem><para><emphasis><filename>&lt;image_name&gt;.wks</filename>:</emphasis>
An OpenEmbedded kickstart file.
You can provide your own custom file or use a
file from a set of provided files as described
following this list.</para></listitem>
<listitem><para><emphasis><filename>-r &lt;rootfs_dir&gt;</filename>:</emphasis>
Specifies the path to the root filesystem directory
to be used and the <filename>.wks</filename>
root filesystem source.</para></listitem>
<listitem><para><emphasis><filename>-b &lt;bootimg_dir&gt;</filename>:</emphasis>
Specifies the path to the directory that contains
the boot artifacts (e.g. the
<filename>EFI</filename> or
<filename>syslinux</filename> directories) to use
as the <filename>.wks</filename> boot image source.
</para></listitem>
<listitem><para><emphasis><filename>-k &lt;kernel_dir&gt;</filename>:</emphasis>
Specifies the path to the dir containing the kernel
to use in the <filename>.wks</filename> boot
image.</para></listitem>
<listitem><para><emphasis><filename>-n &lt;native_sysroot&gt;</filename>:</emphasis>
Specifies the path to the native sysroot
that contains the tools used to build the image.
</para></listitem>
</itemizedlist>
</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 &lt;kickstart_file&gt; -e &lt;image_name&gt;
</literallayout>
This form is the simplest and most user-friendly, as it
does not requre specifying all individual parameters.
All you need to provide is your own
<filename>.wks</filename> file or one provided with the
release.
</para>
<para>
Following is a description of the <filename>wic</filename>
parameters and options:
<itemizedlist>
<listitem><para><emphasis><filename>&lt;kickstart&gt;</filename>:</emphasis>
An OpenEmbedded kickstart file.
You can provide your own custom file or supplied
file.</para></listitem>
<listitem><para><emphasis><filename>-e &lt;image_name&gt;</filename>:</emphasis>
Specifies the image built using the OpenEmbedded
build system.</para></listitem>
</itemizedlist>
</para>
</section>
</section>
<section id='using-a-provided-kickstart_file'>
<title>Using a Provided Kickstart File</title>
<para> <para>
If instead of specifying a user-defined .wks file, you prefer to use If you do not want to create your own
one of the 'canned' wic images, you can simply specify a canned image <filename>.wks</filename> file, you can use a provided
name (without the .wks extension) in place of a .wks file. Use 'wic file.
list images' to get a list of 'canned' images: Use the following command to list the available files:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic list images $ wic list images
mkefidisk Create an EFI disk image mkefidisk Create an EFI disk image
directdisk Create a 'pcbios' direct disk image directdisk Create a 'pcbios' direct disk image
</literallayout> </literallayout>
To use one of the canned images, simply specify it in the raw command. When you use a provided file, you do not have to use the
For example: <filename>.wks</filename> extension.
<literallayout class='monospaced'> Here is an example in Raw Mode that uses the
$ wic create directdisk -r &lt;rootfs-dir&gt; -b &lt;bootimg-dir&gt; <filename>directdisk</filename> file:
-k &lt;kernel-dir&gt; -n &lt;native-sysroot&gt; <literallayout class='monospaced'>
</literallayout> $ wic create directdisk -r &lt;rootfs_dir&gt; -b &lt;bootimg_dir&gt; \
Finally, the general form of the 'wic' command in cooked mode is: -k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt;
<literallayout class='monospaced'> </literallayout>
$ wic create directdisk -e &lt;image-name&gt;
</literallayout>
This form is the simplest and most user-friendly, as it allows you to
skip the need for specifying all the parameters individually.
</para>
<para>
<filename>&lt;image-name&gt;</filename> refers to the Openembedded image name that you've already
build the artifacts for, for example, 'core-image-minimal'.
<note>
In order to use cooked mode, you must have the machine that you
built the artifacts with selected in local.conf.
</note>
</para> </para>
</section> </section>
<section id='wic-usage-examples'> <section id='wic-usage-examples'>
<title>'wic' Usage Examples</title> <title>Examples</title>
<para> <para>
As mentioned, the main prerequisite for generating any image is to This section provides several examples that show how to use
have the build artifacts already available. The below examples assume the <filename>wic</filename> utility.
the user has already built a 'core-image-minimal' for a specific All the examples assume the list of requirements in the
machine (future versions won't require this redundant step, but for "<link linkend='wic-requirements'>Requirements</link>" section
now that's typically how build artifacts get generated). have been met.
The examples assume the previously generated image is
<filename>core-image-minimal</filename>.
</para> </para>
<para> <section id='generate-an-image-using-a-provided-kickstart-file'>
The other prerequisite is to source the build environment: <title>Generate an Image using a Provided Kickstart File</title>
<literallayout class='monospaced'>
$ source oe-init-build-env
</literallayout>
To start out with, we'll generate an image from one of the canned .wks
files. The following generates a list of available images:
<literallayout class='monospaced'>
$ wic list images
mkefidisk Create an EFI disk image
directdisk Create a 'pcbios' direct disk image
</literallayout>
You can get more information about any of the available images by typing
'wic list xxx help', where 'xxx' is one of the image names.
</para>
<para> <para>
For example: This example runs in Cooked Mode and uses the
<literallayout class='monospaced'> <filename>mkefidisk</filename> kickstart file:
$ wic list mkefidisk help <literallayout class='monospaced'>
</literallayout>
Creates a partitioned EFI disk image that the user
can directly dd to boot media.
</para>
<para>
At any time, you can get help on the 'wic' command or any subcommand
(currently 'list' and 'create'). For instance, to get the description
of 'wic create' command and its parameters:
<literallayout class='monospaced'>
$ wic create
Usage:
Create a new OpenEmbedded image
usage: wic create &lt;wks file or image name&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
[-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY FILE&gt;]
[-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir]
[-k, --kernel-dir] [-n, --native-sysroot] [-s, --skip-build-check]
This command creates an OpenEmbedded image based on the 'OE kickstart
commands' found in the &lt;wks file&gt;.
The -o option can be used to place the image in a directory with a
different name and location.
See 'wic help create' for more detailed instructions.
[...]
</literallayout>
</para>
<para>
Continuing further, as mentioned in the command, you can get even more
detailed information by adding 'help' to the above:
<literallayout class='monospaced'>
$ wic help create
NAME
wic create - Create a new OpenEmbedded image
SYNOPSIS
wic create &lt;wks file or image name&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
[-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY FILE&gt;]
[-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir]
[-k, --kernel-dir] [-n, --native-sysroot] [-s,
--skip-build-check]
DESCRIPTION
This command creates an OpenEmbedded image based on the 'OE
kickstart commands' found in the &lt;wks file&gt;.
In order to do this, wic needs to know the locations of the
various build artifacts required to build the image.
Users can explicitly specify the build artifact locations using
the -r, -b, -k, and -n options. See below for details on where
the corresponding artifacts are typically found in a normal
OpenEmbedded build.
Alternatively, users can use the -e option to have 'mic' determine
those locations for a given image. If the -e option is used, the
user needs to have set the appropriate MACHINE variable in
local.conf, and have sourced the build environment.
The -e option is used to specify the name of the image to use the
artifacts from e.g. core-image-sato.
The -r option is used to specify the path to the /rootfs dir to
use as the .wks rootfs source.
The -b option is used to specify the path to the dir containing
the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the
.wks bootimg source.
The -k option is used to specify the path to the dir containing
the kernel to use in the .wks bootimg.
The -n option is used to specify the path to the native sysroot
containing the tools to use to build the image.
The -s option is used to skip the build check. The build check is
a simple sanity check used to determine whether the user has
sourced the build environment so that the -e option can operate
correctly. If the user has specified the build artifact locations
explicitly, 'wic' assumes the user knows what he or she is doing
and skips the build check.
When 'wic -e' is used, the locations for the build artifacts
values are determined by 'wic -e' from the output of the 'bitbake
-e' command given an image name e.g. 'core-image-minimal' and a
given machine set in local.conf. In that case, the image is
created as if the following 'bitbake -e' variables were used:
-r: IMAGE_ROOTFS
-k: STAGING_KERNEL_DIR
-n: STAGING_DIR_NATIVE
-b: HDDDIR and STAGING_DATA_DIR (handlers decide which to use)
If 'wic -e' is not used, the user needs to select the appropriate
value for -b (as well as -r, -k, and -n).
The -o option can be used to place the image in a directory with a
different name and location.
As an alternative to the wks file, the image-specific properties
that define the values that will be used to generate a particular
image can be specified on the command-line using the -i option and
supplying a JSON object consisting of the set of name:value pairs
needed by image creation.
The set of properties available for a given image type can be
listed using the 'wic list' command.
</literallayout>
So, the easiest way to create an image is to use the -e option with a
canned .wks file. To use the -e option, you need to specify the image
used to generate the artifacts and you actually need to have the
MACHINE used to build them specified in your local.conf (these
requirements aren't necessary if you aren't using the -e options.
</para>
<para>
Below, we generate a mkefidisk image, pointing the process at the
core-image-minimal artifacts for the minnow, selected as our current
MACHINE in local.conf.
</para>
<para>
First, once we've set the build up, we run a core-image-minimal minnow
build:
<literallayout class='monospaced'>
$ bitbake core-image-minimal
</literallayout>
Once the build is finished, we can then use wic to create an EFI image
for the minnow to boot. In this case, we'll use the '-e' option to
have wic discover the appropriate build artifacts and generate the
image:
<literallayout class='monospaced'>
$ wic create mkefidisk -e core-image-minimal $ wic create mkefidisk -e core-image-minimal
Checking basic build environment... Checking basic build environment...
Done. Done.
@@ -2318,86 +2264,118 @@ image:
The image(s) were created using OE kickstart file: The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
</literallayout> </literallayout>
The output specifies exactly which image was created and where it was This example shows the easiest way to create an image
created. It also names the artifacts that were used and the exact by running in Cooked Mode and using the
.wks script that was used to generate the image. You should always <filename>&lt;-e&gt;</filename> option with a
verify the details provided in the output to make sure that the image provided kickstart file.
was indeed created exactly as expected. All that is necessary is to specify the image
</para> 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> <para>
Using the path specified in the output for the image name and The output specifies exactly which image were
location, you can now directly dd the image to a USB stick or whatever created and where the image was created.
media you built the image for, and boot the resulting media: The output also names the artifacts used and the exact
<literallayout class='monospaced'> <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 imagewas 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'>
$ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
[sudo] password for trz: [sudo] password for trz:
182274+0 records in 182274+0 records in
182274+0 records out 182274+0 records out
93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s
[trz@empanada ~]$ sudo eject /dev/sdb [trz@empanada ~]$ sudo eject /dev/sdb
</literallayout> </literallayout>
The next example uses a modified 'directdisk' script as an example. </para>
</para> </section>
<para> <section id='using-a-modified-kickstart-file'>
Because wic image creation is driven by .wks files, it's easy to <title>Using a Modified Kickstart File</title>
change the parameters that drive image creation: simply modify the
.wks file.
</para>
<para> <para>
As illustrated previously, 'wic list images' provides a list of Because <filename>wic</filename> image creation is driven
available images. The images displayed are simply the list of .wks by the kickstart file, it is easy to drive image creation
files in the scripts/lib/image/canned-wks/ directory, minus the .wks by changing the parameters in the file.
extension. This next example demonstrates that through modification
</para> of the <filename>directdisk</filename> kickstart file.
</para>
<para> <para>
To add a new image to that list, simply add a new .wks file. As mentioned earlier, you can use the command
</para> <filename>wic list images</filename> to show the list
of provided kickstart files.
The directory in which these files reside is in the
<link linkend='source-directory'>Source Directory</link>
in <filename>scripts/lib/image/canned-wks/</filename>.
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> <para>
For this example, we already have a .wks file that already does pretty In this example, the existing
much what we want, but for our particular hardware, we know we'll be <filename>directdisk</filename> file already does most
booting from sdb instead of sda, which is what the directdisk script uses. of what is needed.
</para> 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> <para>
What we can do is simply create a copy of the directdisk.wks file in The example begins by making a copy of the
the scripts/lib/image/canned-wks/ directory and change the lines that <filename>directdisk.wks</filename> file in the
specify the target disk to boot from. <filename>scripts/lib/image/canned-wks</filename>
</para> directory and then changing the lines that specify the
target disk from which to boot.
<para> <literallayout class='monospaced'>
First, we copy the directdisk.wks file to directdisksdb.wks:
<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 $ 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> </literallayout>
Then we modify the directdisksdb.wks file and change all instances of Next, the example modifies the
'--ondisk sda' to '--ondisk sdb'. The following two lines are the <filename>directdisksdb.wks</filename> file and changes all
lines we end up changing (leaving the rest alone): instances of "<filename>--ondisk sda</filename>"
<literallayout class='monospaced'> 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 --ondisk sdb --fstype=msdos --label boot --active --align 1024 part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
</literallayout> </literallayout>
Once we've made that change, we generate a directdisksdb image, (I AM HERE)
Once the lines are changed, Once we've made that change, we generate a directdisksdb image,
pointing the process at the core-image-minimal artifacts for the nuc pointing the process at the core-image-minimal artifacts for the nuc
(Next Unit of Computing), selected as our current MACHINE in (Next Unit of Computing), selected as our current MACHINE in
local.conf. local.conf.
</para> </para>
<para> <para>
Once we've set the build up, we run a core-image-minimal nuc build: Once we've set the build up, we run a core-image-minimal nuc build:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake core-image-minimal $ bitbake core-image-minimal
</literallayout> </literallayout>
Once the build is finished, we can then use nuc to create our Once the build is finished, we can then use nuc to create our
directdisk image for the nuc to boot. In this case, we'll use the directdisk image for the nuc to boot. In this case, we'll use the
'-e' option to have wic discover the appropriate build artifacts and '-e' option to have wic discover the appropriate build artifacts and
generate the image: generate the image:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic create directdisksdb -e core-image-minimal $ wic create directdisksdb -e core-image-minimal
Checking basic build environment... Checking basic build environment...
Done. Done.
@@ -2416,25 +2394,25 @@ generate the image:
The image(s) were created using OE kickstart file: The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
</literallayout> </literallayout>
Using the path specified in the output for the image name and Using the path specified in the output for the image name and
location, you can now directly dd the image to a USB stick or whatever location, you can now directly dd the image to a USB stick or whatever
media you built the image for, and boot the resulting media: media you built the image for, and boot the resulting media:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb
86018+0 records in 86018+0 records in
86018+0 records out 86018+0 records out
44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s
[trz@empanada tmp]$ sudo eject /dev/sdb [trz@empanada tmp]$ sudo eject /dev/sdb
</literallayout> </literallayout>
Of course, you can just use the directdisk image directly if you don't Of course, you can just use the directdisk image directly if you don't
have any special needs. have any special needs.
</para> </para>
<para> <para>
Here'we're creating a wic image based on core-image-minimal and Here'we're creating a wic image based on core-image-minimal and
crownbay-noemgd, which works right out of the box. crownbay-noemgd, which works right out of the box.
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic create directdisk -e core-image-minimal $ wic create directdisk -e core-image-minimal
Checking basic build environment... Checking basic build environment...
@@ -2454,12 +2432,12 @@ crownbay-noemgd, which works right out of the box.
The image(s) were created using OE kickstart file: The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
</literallayout> </literallayout>
Finally, here's an example that doesn't take the easy way out and Finally, here's an example that doesn't take the easy way out and
manually specifies each build artifact, along with a non-canned .wks manually specifies each build artifact, along with a non-canned .wks
file, and also uses the -o option to have wic create the output file, and also uses the -o option to have wic create the output
somewhere other than the default /var/tmp/wic: somewhere other than the default /var/tmp/wic:
<literallayout class='monospaced'> <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 $ 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)... Creating image(s)...
@@ -2476,17 +2454,17 @@ somewhere other than the default /var/tmp/wic:
The image(s) were created using OE kickstart file: The image(s) were created using OE kickstart file:
/home/trz/test.wks /home/trz/test.wks
</literallayout> </literallayout>
In this case, we didn't need to have the proper machine selected in In this case, we didn't need to have the proper machine selected in
local.conf - we manually specified each artifact and therefore wic local.conf - we manually specified each artifact and therefore wic
doesn't need further information from the build system. doesn't need further information from the build system.
</para> </para>
<para> <para>
Finally, here's an example of the actual partition language commands Finally, here's an example of the actual partition language commands
used to generate the mkefidisk image i.e. these are the contents of the used to generate the mkefidisk image i.e. these are the contents of the
mkefidisk.wks OE kickstart file: mkefidisk.wks OE kickstart file:
<literallayout class='monospaced'> <literallayout class='monospaced'>
# short-description: Create an EFI disk image # short-description: Create an EFI disk image
# long-description: Creates a partitioned EFI disk image that the user # long-description: Creates a partitioned EFI disk image that the user
# can directly dd to boot media. # can directly dd to boot media.
@@ -2498,56 +2476,56 @@ mkefidisk.wks OE kickstart file:
part swap --ondisk sda --size 44 --label swap1 --fstype=swap 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" bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda- intel.enable_msi=0"
</literallayout> </literallayout>
</para> </para>
</section>
</section> </section>
</section>
<section id='openembedded-kickstart-wks-reference'> <section id='openembedded-kickstart-wks-reference'>
<title>OpenEmbedded Kickstart (.wks) Reference</title> <title>OpenEmbedded Kickstart (.wks) Reference</title>
<para> <para>
The current 'wic' implementation supports only the basic kickstart The current 'wic' implementation supports only the basic kickstart
partitioning commands: 'partition' (or 'part' for short) and partitioning commands: 'partition' (or 'part' for short) and
'bootloader'. 'bootloader'.
</para> </para>
<para> <para>
They are listed below and mostly follow the syntax and meaning of the They are listed below and mostly follow the syntax and meaning of the
standard kickstart options for those commands. The documentation below standard kickstart options for those commands. The documentation below
is based on the Fedora kickstart documentation of the same commands, is based on the Fedora kickstart documentation of the same commands,
but modified to reflect wic capabilities. For reference: but modified to reflect wic capabilities. For reference:
<literallayout class='monospaced'> <literallayout class='monospaced'>
http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader
</literallayout>
</para>
<section id='command-part-or-partition'>
<title>Command: part or partition</title>
<para>
Creates a partition on the system.
Use the following syntax:
<literallayout class='monospaced'>
part &lt;mntpoint&gt;
</literallayout> </literallayout>
The &lt;mntpoint&gt; is where the partition will be mounted and must be of
one of the following forms:
<itemizedlist>
<listitem><para><filename>/&lt;path&gt;</filename>:
For example, <filename>/</filename>,
<filename>/usr</filename>, and
<filename>/home</filename></para></listitem>
<listitem><para><filename>swap</filename>:
The partition will be used as swap space.
</para></listitem>
</itemizedlist>
</para> </para>
<para> <section id='command-part-or-partition'>
Following are the supported options: <title>Command: part or partition</title>
<literallayout class='monospaced'>
<para>
Creates a partition on the system.
Use the following syntax:
<literallayout class='monospaced'>
part &lt;mntpoint&gt;
</literallayout>
The &lt;mntpoint&gt; is where the partition will be mounted and must be of
one of the following forms:
<itemizedlist>
<listitem><para><filename>/&lt;path&gt;</filename>:
For example, <filename>/</filename>,
<filename>/usr</filename>, and
<filename>/home</filename></para></listitem>
<listitem><para><filename>swap</filename>:
The partition will be used as swap space.
</para></listitem>
</itemizedlist>
</para>
<para>
Following are the supported options:
<literallayout class='monospaced'>
--size --size
The minimum partition size in megabytes. Specify an integer value The minimum partition size in megabytes. Specify an integer value
here such as 500. Do not append the number with MB. Not needed if here such as 500. Do not append the number with MB. Not needed if
@@ -2597,20 +2575,20 @@ one of the following forms:
--align (in kB) --align (in kB)
The '--align' option is a mic-specific option that says to start a The '--align' option is a mic-specific option that says to start a
partition on an x kB boundary. partition on an x kB boundary.
</literallayout> </literallayout>
</para> </para>
</section> </section>
<section id='command-bootloader'> <section id='command-bootloader'>
<title>Command: bootloader</title> <title>Command: bootloader</title>
<para> <para>
This command specifies how the boot loader should be installed. This command specifies how the boot loader should be installed.
</para> </para>
<para> <para>
Following are the supported options: Following are the supported options:
<literallayout class='monospaced'> <literallayout class='monospaced'>
--timeout --timeout
Specify the number of seconds before the bootloader times out and Specify the number of seconds before the bootloader times out and
boots the default option. boots the default option.
@@ -2631,8 +2609,9 @@ one of the following forms:
Future updates will implement more options - using anything not Future updates will implement more options - using anything not
explicitly supported can result in unpredictable results. explicitly supported can result in unpredictable results.
</literallayout> </literallayout>
</para> </para>
</section>
</section> </section>
</section> </section>