sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

797
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -1926,18 +1926,16 @@
that image as is on your device.
Physical devices accept and boot images in various ways depending
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.
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.
() to create the properly partitioned image.
</para>
<para>
Using the <filename>wic</filename> command, you can also describe
your desired final image and have BitBake assemble the image.
The 'wic' command generates partitioned images from existing
OpenEmbedded build artifacts.
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
@ -1949,28 +1947,53 @@
</para>
<para>
'wic' is based loosely on the 'mic' (Meego Image Creator) framework,
but heavily modified to make direct use of OpenEmbedded build
artifacts instead of package installation and configuration, things
already incorporated in the OE artifacts.
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>
<note>
The name 'wic' comes from 'oeic', which stands for 'OpenEmbedded
Image Creator'. The 'oe' diphthong in 'oeic' has been promoted to the
letter 'w', because 'oeic' is impossible to remember or pronounce.
</note>
<section id='wic-background'>
<title>Background</title>
<note>
This 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: directdisk.bbclass
and mkefidisk.sh. The replaced scripts are implemented by a
general-purpose partitioning 'language' based on Red Hat kickstart
syntax (with the underlying code borrowed from Tizen mic, which in
turn was borrowed from Meego mic, in turn borrowed from Fedora livecd,
etc.).
</note>
<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.
<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>
<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>
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.
</note>
<section id='requirements'>
-->
<section id='wic-requirements'>
<title>Requirements</title>
<para>
wic has only been tested on and is only designed to work on the
distros officially supported by Yocto.
</para>
<para>
Aside from the standard system utilities, such as 'cp', wic expects the
following utilities to be installed on the host machine:
In order to use the <filename>wic</filename> utility with the
OpenEmbedded Build system, you need to meet the following
requirements:
<itemizedlist>
<listitem><para><emphasis>parted:</emphasis>
GNU Parted - a partition manipulation program
<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>
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>
</itemizedlist>
</para>
</section>
<section id='raw-vs-cooked-mode'>
<title>Raw Vs. Cooked Mode</title>
<section id='wic-getting-help'>
<title>Getting Help</title>
<para>
'wic' can be used in 'raw' mode, where artifacts are explicitly
specified via command-line arguments (see the command documentation
and examples below), or it can be used in a more easily usable
'cooked' mode which uses the current MACHINE setting and a specified
image name to automatically locate the artifacts used to create the
image.
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'>
$ wic -h
$ wic --help
</literallayout>
</para>
<note>
The prerequisite for generating any image is to have the build
artifacts already available. For example, to create a 'wic' image
using the build artifacts from a core-image-minimal build, you must
already have created a core-image-minimal OpenembeddedCore image. It
may seem redundant to generate an OpenEmbedded image in order to
create a 'wic' image, and in fact to some degree it is. At the
moment, however, that's typically how build artifacts are generated,
and future versions will likely be more integrated into the build
system and will be able to skip that step. There is a benefit
however, in that 'wic' images are created more quickly and without the
need for root access.
</note>
<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 &lt;command&gt;
</literallayout>
</para>
<para>
You can find more out about the images
<filename>wic</filename> creates using the provided
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 id='command-summary'>
<title>Command Summary</title>
<section id='operational-modes'>
<title>Operational Modes</title>
<para>
The general form of the 'wic' command in raw mode is:
<literallayout class='monospaced'>
$ 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:
You can run <filename>wic</filename> in two modes: Raw and
Cooked:
<itemizedlist>
<listitem><para><emphasis>-r option:</emphasis>
Used to specify the path to the /rootfs dir to
use as the .wks rootfs source.</para></listitem>
<listitem><para><emphasis>-b option:</emphasis>
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.</para></listitem>
<listitem><para><emphasis>-k option:</emphasis>
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>
<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>
For more technical detail on the origin and meanings of those
artifacts, see the Yocto documentation corresponding to those topics
elsewhere. In most cases, it's not important to know that, because
'cooked' mode provides a convenient shortcut allowing the user to
forget about the raw details and simply specify artifacts via a
high-level OpenEmbedded image name.
</para>
<section id='raw-mode'>
<title>Raw Mode</title>
<para>
The general form of the 'wic' command in raw mode is:
<literallayout class='monospaced'>
$ wic create &lt;image_name&gt;.wks -r &lt;rootfs_dir&gt; -b &lt;bootimg_dir&gt; /
-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>
If instead of specifying a user-defined .wks file, you prefer to use
one of the 'canned' wic images, you can simply specify a canned image
name (without the .wks extension) in place of a .wks file. Use 'wic
list images' to get a list of 'canned' images:
<literallayout class='monospaced'>
If you do not want to create your own
<filename>.wks</filename> file, you can use a provided
file.
Use the following command to list the available files:
<literallayout class='monospaced'>
$ wic list images
mkefidisk Create an EFI disk image
directdisk Create a 'pcbios' direct disk image
</literallayout>
To use one of the canned images, simply specify it in the raw command.
For example:
<literallayout class='monospaced'>
$ wic create directdisk -r &lt;rootfs-dir&gt; -b &lt;bootimg-dir&gt;
-k &lt;kernel-dir&gt; -n &lt;native-sysroot&gt;
</literallayout>
Finally, the general form of the 'wic' command in cooked mode is:
<literallayout class='monospaced'>
$ 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>
</literallayout>
When you use a provided 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 &lt;rootfs_dir&gt; -b &lt;bootimg_dir&gt; \
-k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt;
</literallayout>
</para>
</section>
<section id='wic-usage-examples'>
<title>'wic' Usage Examples</title>
<title>Examples</title>
<para>
As mentioned, the main prerequisite for generating any image is to
have the build artifacts already available. The below examples assume
the user has already built a 'core-image-minimal' for a specific
machine (future versions won't require this redundant step, but for
now that's typically how build artifacts get generated).
This section provides several examples that show how to use
the <filename>wic</filename> utility.
All the examples assume the list of requirements in the
"<link linkend='wic-requirements'>Requirements</link>" section
have been met.
The examples assume the previously generated image is
<filename>core-image-minimal</filename>.
</para>
<para>
The other prerequisite is to source the build environment:
<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>
<section id='generate-an-image-using-a-provided-kickstart-file'>
<title>Generate an Image using a Provided Kickstart File</title>
<para>
For example:
<literallayout class='monospaced'>
$ wic list mkefidisk help
</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'>
<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.
@ -2318,86 +2264,118 @@ image:
The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
</literallayout>
The output specifies exactly which image was created and where it was
created. It also names the artifacts that were used and the exact
.wks script that was used to generate the image. You should always
verify the details provided in the output to make sure that the image
was indeed created exactly as expected.
</para>
</literallayout>
This example shows the easiest way to create an image
by running in Cooked Mode and using the
<filename>&lt;-e&gt;</filename> option with a
provided 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>
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
media you built the image for, and boot the resulting media:
<literallayout class='monospaced'>
<para>
The output specifies exactly which image were
created and where the image 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 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] 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>
The next example uses a modified 'directdisk' script as an example.
</para>
</literallayout>
</para>
</section>
<para>
Because wic image creation is driven by .wks files, it's easy to
change the parameters that drive image creation: simply modify the
.wks file.
</para>
<section id='using-a-modified-kickstart-file'>
<title>Using a Modified Kickstart File</title>
<para>
As illustrated previously, 'wic list images' provides a list of
available images. The images displayed are simply the list of .wks
files in the scripts/lib/image/canned-wks/ directory, minus the .wks
extension.
</para>
<para>
Because <filename>wic</filename> image creation is driven
by the kickstart file, it is easy to drive 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>
To add a new image to that list, simply add a new .wks file.
</para>
<para>
As mentioned earlier, you can use the command
<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>
For this example, we already have a .wks file that already does pretty
much what we want, but for our particular hardware, we know we'll be
booting from sdb instead of sda, which is what the directdisk script 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>
What we can do is simply create a copy of the directdisk.wks file in
the scripts/lib/image/canned-wks/ directory and change the lines that
specify the target disk to boot from.
</para>
<para>
First, we copy the directdisk.wks file to directdisksdb.wks:
<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 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>
Then we modify the directdisksdb.wks file and change all instances of
'--ondisk sda' to '--ondisk sdb'. The following two lines are the
lines we end up changing (leaving the rest alone):
<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 --ondisk sdb --fstype=msdos --label boot --active --align 1024
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
</literallayout>
Once we've made that change, we generate a directdisksdb image,
</literallayout>
(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
(Next Unit of Computing), selected as our current MACHINE in
local.conf.
</para>
</para>
<para>
Once we've set the build up, we run a core-image-minimal nuc build:
<literallayout class='monospaced'>
<para>
Once we've set the build up, we run a core-image-minimal nuc build:
<literallayout class='monospaced'>
$ bitbake core-image-minimal
</literallayout>
</literallayout>
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
'-e' option to have wic discover the appropriate build artifacts and
generate the image:
<literallayout class='monospaced'>
<literallayout class='monospaced'>
$ wic create directdisksdb -e core-image-minimal
Checking basic build environment...
Done.
@ -2416,25 +2394,25 @@ generate the image:
The image(s) were created using OE kickstart file:
/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
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:
<literallayout class='monospaced'>
<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>
</literallayout>
Of course, you can just use the directdisk image directly if you don't
have any special needs.
</para>
</para>
<para>
<para>
Here'we're creating a wic image based on core-image-minimal and
crownbay-noemgd, which works right out of the box.
<literallayout class='monospaced'>
<literallayout class='monospaced'>
$ wic create directdisk -e core-image-minimal
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:
/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
manually specifies each build artifact, along with a non-canned .wks
file, and also uses the -o option to have wic create the output
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
Creating image(s)...
@ -2476,17 +2454,17 @@ somewhere other than the default /var/tmp/wic:
The image(s) were created using OE kickstart file:
/home/trz/test.wks
</literallayout>
</literallayout>
In this case, we didn't need to have the proper machine selected in
local.conf - we manually specified each artifact and therefore wic
doesn't need further information from the build system.
</para>
</para>
<para>
<para>
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
mkefidisk.wks OE kickstart file:
<literallayout class='monospaced'>
<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.
@ -2498,56 +2476,56 @@ mkefidisk.wks OE kickstart file:
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>
</literallayout>
</para>
</section>
</section>
</section>
<section id='openembedded-kickstart-wks-reference'>
<title>OpenEmbedded Kickstart (.wks) Reference</title>
<section id='openembedded-kickstart-wks-reference'>
<title>OpenEmbedded Kickstart (.wks) Reference</title>
<para>
<para>
The current 'wic' implementation supports only the basic kickstart
partitioning commands: 'partition' (or 'part' for short) and
'bootloader'.
</para>
</para>
<para>
<para>
They are listed below and mostly follow the syntax and meaning of the
standard kickstart options for those commands. The documentation below
is based on the Fedora kickstart documentation of the same commands,
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#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>
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'>
<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>
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
The minimum partition size in megabytes. Specify an integer value
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)
The '--align' option is a mic-specific option that says to start a
partition on an x kB boundary.
</literallayout>
</para>
</section>
</literallayout>
</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 installed.
</para>
<para>
This command specifies how the boot loader should be installed.
</para>
<para>
Following are the supported options:
<literallayout class='monospaced'>
<para>
Following are the supported options:
<literallayout class='monospaced'>
--timeout
Specify the number of seconds before the bootloader times out and
boots the default option.
@ -2631,8 +2609,9 @@ one of the following forms:
Future updates will implement more options - using anything not
explicitly supported can result in unpredictable results.
</literallayout>
</para>
</literallayout>
</para>
</section>
</section>
</section>