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

dev-manual: Updated to the "Creating Partitioned Images" section 

new information on how wic works

(From yocto-docs rev: 7b6a54a593a678442541b1fa6847498a792183c7)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2016-12-12 17:04:46 -08:00 committed by Richard Purdie
parent 617b5bd4f3
commit 27751642cd
1 changed files with 908 additions and 810 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3984,7 +3984,7 @@
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
'
<para> <para>
For the RPM Package Management System, the following implementation details For the RPM Package Management System, the following implementation details
exist: exist:
@ -4365,40 +4365,85 @@
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. Wic, to create the properly partitioned image.
</para> </para>
<para> <para>
The <filename>wic</filename> command generates partitioned images You can generate Wic-partitioned images
from existing OpenEmbedded build artifacts. (<replaceable>image</replaceable><filename>.wic</filename>)
Image generation is driven by partitioning commands contained two ways: using the OpenEmbedded build system and by running
in an Openembedded kickstart file (<filename>.wks</filename>) the OpenEmbedded Image Creator Wic directly.
specified either directly on the command line or as one of a The former way is preferable as it is easier to use and understand.
selection of canned <filename>.wks</filename> files as shown </para>
with the <filename>wic list images</filename> command in the
"<link linkend='using-a-provided-kickstart_file'>Using an Existing Kickstart File</link>" <section id='creating-wic-images-oe'>
<title>Creating Wic-Partitioned Images</title>
<para>
The OpenEmbedded build system can generate
Wic-partitioned images the same way as it generates
any other image type.
To generate a Wic-partitioned image, you need to modify
two variables.
<itemizedlist>
<listitem><para>
Include "wic" as part of the
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
variable.
</para></listitem>
<listitem><para>
Include the name of the
<link linkend='openembedded-kickstart-wks-reference'>wic kickstart file</link>
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 Wic-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. section.
When applied to a given set of build artifacts, the result is an </para>
image or set of images that can be directly written onto media and </section>
used on a particular system.
<section id='create-wic-images-wic'>
<title>Using OpenEmbedded Image Creator Wic to Generate Partitioned Images</title>
<para>
The <filename>wic</filename> command generates partitioned
images from existing OpenEmbedded build artifacts.
Image generation is driven by partitioning commands
contained in an Openembedded kickstart file
(<filename>.wks</filename>) specified either directly on
the command line or as one of a selection of canned
<filename>.wks</filename> files as shown with the
<filename>wic list images</filename> command in the
"<link linkend='using-a-provided-kickstart-file'>Using an Existing Kickstart File</link>"
section.
When you apply the command to a given set of build
artifacts, the result is an image or set of images that
can be directly written onto media and used on a particular
system.
</para> </para>
<para> <para>
The <filename>wic</filename> command and the infrastructure The <filename>wic</filename> command and the infrastructure
it is based on is by definition incomplete. it is based on is by definition incomplete.
Its purpose is to allow the generation of customized images, The purpose of the command is to allow the generation of
and as such was designed to be completely extensible through a customized images, and as such, was designed to be
plug-in interface. completely extensible through a plug-in interface.
See the See the
"<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>"
section for information on these plug-ins. section for information on these plug-ins.
</para> </para>
<para> <para>
This section provides some background information on This section provides some background information on Wic,
<filename>wic</filename>, describes what you need to have in describes what you need to have in
place to run the tool, provides instruction on how to use place to run the tool, provides instruction on how to use
<filename>wic</filename>, and provides several examples. the <filename>wic</filename> utility,
and provides several examples.
</para> </para>
<section id='wic-background'> <section id='wic-background'>
@ -4408,33 +4453,35 @@
This section provides some background on the This section provides some background on the
<filename>wic</filename> utility. <filename>wic</filename> utility.
While none of this information is required to use While none of this information is required to use
<filename>wic</filename>, you might find it interesting. Wic, you might find it interesting.
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
The name "wic" is derived from OpenEmbedded The name "Wic" is derived from OpenEmbedded
Image Creator (oeic). Image Creator (oeic).
The "oe" diphthong in "oeic" was promoted to the The "oe" diphthong in "oeic" was promoted to the
letter "w", because "oeic" is both difficult to remember and letter "w", because "oeic" is both difficult to
pronounce.</para></listitem> remember and to pronounce.
</para></listitem>
<listitem><para> <listitem><para>
<filename>wic</filename> is loosely based on the Wic is loosely based on the
Meego Image Creator (<filename>mic</filename>) Meego Image Creator (<filename>mic</filename>)
framework. framework.
The <filename>wic</filename> implementation has been The Wic implementation has been
heavily modified to make direct use of OpenEmbedded heavily modified to make direct use of OpenEmbedded
build artifacts instead of package installation and build artifacts instead of package installation and
configuration, which are already incorporated within configuration, which are already incorporated within
the OpenEmbedded artifacts.</para></listitem> the OpenEmbedded artifacts.
</para></listitem>
<listitem><para> <listitem><para>
<filename>wic</filename> is a completely independent Wic is a completely independent
standalone utility that initially provides standalone utility that initially provides
easier-to-use and more flexible replacements for a easier-to-use and more flexible replacements for a
couple bits of existing functionality in OE Core's existing functionality in OE Core's
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
class and <filename>mkefidisk.sh</filename> script. class and <filename>mkefidisk.sh</filename> script.
The difference between The difference between
<filename>wic</filename> and those examples is Wic and those examples is
that with <filename>wic</filename> the that with Wic the
functionality of those scripts is implemented functionality of those scripts is implemented
by a general-purpose partitioning language, which is by a general-purpose partitioning language, which is
based on Redhat kickstart syntax.</para></listitem> based on Redhat kickstart syntax.</para></listitem>
@ -4454,8 +4501,10 @@
development host must support the Yocto Project. development host must support the Yocto Project.
See the See the
"<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
section in the Yocto Project Reference Manual for this section in the Yocto Project Reference Manual for
list of distributions.</para></listitem> the list of distributions that support the
Yocto Project.
</para></listitem>
<listitem><para> <listitem><para>
The standard system utilities, such as The standard system utilities, such as
<filename>cp</filename>, must be installed on your <filename>cp</filename>, must be installed on your
@ -4467,10 +4516,10 @@
have already created an image using the have already created an image using the
Openembedded build system (e.g. Openembedded build system (e.g.
<filename>core-image-minimal</filename>). <filename>core-image-minimal</filename>).
While it might seem redundant to generate an image in While it might seem redundant to generate an image
order to create an image using in order to create an image using
<filename>wic</filename>, the current version of Wic, the current version of
<filename>wic</filename> requires the artifacts Wic requires the artifacts
in the form generated by the build system. in the form generated by the build system.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
@ -4498,8 +4547,9 @@
<para> <para>
You can get general help for the <filename>wic</filename> You can get general help for the <filename>wic</filename>
by entering the <filename>wic</filename> command by itself command by entering the <filename>wic</filename> command
or by entering the command with a help argument as follows: by itself or by entering the command with a help argument
as follows:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic -h $ wic -h
$ wic --help $ wic --help
@ -4507,11 +4557,13 @@
</para> </para>
<para> <para>
Currently, <filename>wic</filename> supports two commands: Currently, Wic supports two commands:
<filename>create</filename> and <filename>list</filename>. <filename>create</filename> and <filename>list</filename>.
You can get help for these commands as follows: You can get help for these commands as follows:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic help <replaceable>command</replaceable> $ wic help <replaceable>command</replaceable>
with <replaceable>command</replaceable> being either
<filename>create</filename> or <filename>list</filename>.
</literallayout> </literallayout>
</para> </para>
@ -4531,13 +4583,13 @@
<para> <para>
You can find out more about the images You can find out more about the images
<filename>wic</filename> creates using the existing Wic creates using the existing
kickstart files with the following form of the command: kickstart files with the following form of the command:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic list <replaceable>image</replaceable> help $ wic list <replaceable>image</replaceable> help
</literallayout> </literallayout>
where <filename><replaceable>image</replaceable></filename> is either with <filename><replaceable>image</replaceable></filename>
<filename>directdisk</filename> or being either <filename>directdisk</filename> or
<filename>mkefidisk</filename>. <filename>mkefidisk</filename>.
</para> </para>
</section> </section>
@ -4546,19 +4598,23 @@
<title>Operational Modes</title> <title>Operational Modes</title>
<para> <para>
You can use <filename>wic</filename> in two different You can use Wic in two different
modes, depending on how much control you need for modes, depending on how much control you need for
specifying the Openembedded build artifacts that are specifying the Openembedded build artifacts that are
used for creating the image: Raw and Cooked: used for creating the image: Raw and Cooked:
<itemizedlist> <itemizedlist>
<listitem><para><emphasis>Raw Mode:</emphasis> <listitem><para>
<emphasis>Raw Mode:</emphasis>
You explicitly specify build artifacts through You explicitly specify build artifacts through
command-line arguments.</para></listitem> command-line arguments.
<listitem><para><emphasis>Cooked Mode:</emphasis> </para></listitem>
<listitem><para>
<emphasis>Cooked Mode:</emphasis>
The current The current
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
setting and image name are used to automatically locate setting and image name are used to automatically
and provide the build artifacts.</para></listitem> locate and provide the build artifacts.
</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -4577,7 +4633,8 @@
<title>Raw Mode</title> <title>Raw Mode</title>
<para> <para>
The general form of the 'wic' command in raw mode is: The general form of the
<filename>wic</filename> command in raw mode is:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...] $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...]
@ -4624,7 +4681,7 @@
</literallayout> </literallayout>
<note> <note>
You do not need root privileges to run You do not need root privileges to run
<filename>wic</filename>. Wic.
In fact, you should not run as root when using the In fact, you should not run as root when using the
utility. utility.
</note> </note>
@ -4644,7 +4701,7 @@
<replaceable>kickstart_file</replaceable> <replaceable>kickstart_file</replaceable>
An OpenEmbedded kickstart file. You can provide your own An OpenEmbedded kickstart file. You can provide your own
custom file or supplied file. custom file or a supplied file.
<replaceable>image_name</replaceable> <replaceable>image_name</replaceable>
Specifies the image built using the OpenEmbedded build Specifies the image built using the OpenEmbedded build
@ -4659,13 +4716,13 @@
</section> </section>
</section> </section>
<section id='using-a-provided-kickstart_file'> <section id='using-a-provided-kickstart-file'>
<title>Using an Existing Kickstart File</title> <title>Using an Existing Kickstart File</title>
<para> <para>
If you do not want to create your own If you do not want to create your own
<filename>.wks</filename> file, you can use an existing <filename>.wks</filename> file, you can use an existing
file provided by the <filename>wic</filename> installation. file provided by the Wic installation.
Use the following command to list the available files: Use the following command to list the available files:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ wic list images $ wic list images
@ -4684,8 +4741,8 @@
<para> <para>
Here are the actual partition language commands Here are the actual partition language commands
used in the <filename>mkefidisk.wks</filename> file to generate used in the <filename>mkefidisk.wks</filename> file to
an image: generate an image:
<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
@ -4709,8 +4766,8 @@
This section provides several examples that show how to use This section provides several examples that show how to use
the <filename>wic</filename> utility. the <filename>wic</filename> utility.
All the examples assume the list of requirements in the All the examples assume the list of requirements in the
"<link linkend='wic-requirements'>Requirements</link>" section "<link linkend='wic-requirements'>Requirements</link>"
have been met. section have been met.
The examples assume the previously generated image is The examples assume the previously generated image is
<filename>core-image-minimal</filename>. <filename>core-image-minimal</filename>.
</para> </para>
@ -4737,14 +4794,13 @@
KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel 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 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
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>
This example shows the easiest way to create an image The previous example shows the easiest way to create
by running in Cooked Mode and using the an image by running in Cooked Mode and using the
<filename>-e</filename> option with an existing kickstart <filename>-e</filename> option with an existing
file. kickstart file.
All that is necessary is to specify the image used to All that is necessary is to specify the image used to
generate the artifacts. generate the artifacts.
Your <filename>local.conf</filename> needs to have the Your <filename>local.conf</filename> needs to have the
@ -4757,12 +4813,12 @@
The output specifies the exact image created as well as The output specifies the exact image created as well as
where it was created. where it was created.
The output also names the artifacts used and the exact The output also names the artifacts used and the exact
<filename>.wks</filename> script that was used to generate <filename>.wks</filename> script that was used to
the image. generate the image.
<note> <note>
You should always verify the details provided in the You should always verify the details provided in the
output to make sure that the image was indeed created output to make sure that the image was indeed
exactly as expected. created exactly as expected.
</note> </note>
</para> </para>
@ -4777,7 +4833,7 @@
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 at empanada ~]$ sudo eject /dev/sdb
</literallayout> </literallayout>
</para> </para>
</section> </section>
@ -4786,9 +4842,9 @@
<title>Using a Modified Kickstart File</title> <title>Using a Modified Kickstart File</title>
<para> <para>
Because <filename>wic</filename> image creation is driven Because Wic-partitioned image creation is
by the kickstart file, it is easy to affect image creation driven by the kickstart file, it is easy to affect
by changing the parameters in the file. image creation by changing the parameters in the file.
This next example demonstrates that through modification This next example demonstrates that through modification
of the <filename>directdisk</filename> kickstart file. of the <filename>directdisk</filename> kickstart file.
</para> </para>
@ -4801,19 +4857,21 @@
<filename>scripts/lib/image/canned-wks/</filename> <filename>scripts/lib/image/canned-wks/</filename>
located in the located in the
<link linkend='source-directory'>Source Directory</link>. <link linkend='source-directory'>Source Directory</link>.
Because the available files reside in this directory, you Because the available files reside in this directory,
can create and add your own custom files to the directory. you can create and add your own custom files to the
Subsequent use of the <filename>wic list images</filename> directory.
command would then include your kickstart files. Subsequent use of the
<filename>wic list images</filename> command would then
include your kickstart files.
</para> </para>
<para> <para>
In this example, the existing In this example, the existing
<filename>directdisk</filename> file already does most <filename>directdisk</filename> file already does most
of what is needed. of what is needed.
However, for the hardware in this example, the image will However, for the hardware in this example, the image
need to boot from <filename>sdb</filename> instead of will need to boot from <filename>sdb</filename> instead
<filename>sda</filename>, which is what the of <filename>sda</filename>, which is what the
<filename>directdisk</filename> kickstart file uses. <filename>directdisk</filename> kickstart file uses.
</para> </para>
@ -4821,18 +4879,18 @@
The example begins by making a copy of the The example begins by making a copy of the
<filename>directdisk.wks</filename> file in the <filename>directdisk.wks</filename> file in the
<filename>scripts/lib/image/canned-wks</filename> <filename>scripts/lib/image/canned-wks</filename>
directory and then changing the lines that specify the directory and then by changing the lines that specify
target disk from which to boot. the target disk from which to boot.
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.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 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
</literallayout> </literallayout>
Next, the example modifies the Next, the example modifies the
<filename>directdisksdb.wks</filename> file and changes all <filename>directdisksdb.wks</filename> file and changes
instances of "<filename>--ondisk sda</filename>" all instances of "<filename>--ondisk sda</filename>"
to "<filename>--ondisk sdb</filename>". to "<filename>--ondisk sdb</filename>".
The example changes the following two lines and leaves the The example changes the following two lines and leaves
remaining lines untouched: the remaining lines untouched:
<literallayout class='monospaced'> <literallayout class='monospaced'>
part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 part /boot --source bootimg-pcbios --ondisk sdb --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
@ -4840,8 +4898,8 @@
Once the lines are changed, the example generates the Once the lines are changed, the example generates the
<filename>directdisksdb</filename> image. <filename>directdisksdb</filename> image.
The command points the process at the The command points the process at the
<filename>core-image-minimal</filename> artifacts for the <filename>core-image-minimal</filename> artifacts for
Next Unit of Computing (nuc) the Next Unit of Computing (nuc)
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
the <filename>local.conf</filename>. the <filename>local.conf</filename>.
<literallayout class='monospaced'> <literallayout class='monospaced'>
@ -4855,12 +4913,12 @@
/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct
The following build artifacts were used to create the image(s): 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 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 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 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 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
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>
@ -4873,7 +4931,7 @@
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 at empanada tmp]$ sudo eject /dev/sdb
</literallayout> </literallayout>
</para> </para>
</section> </section>
@ -4918,7 +4976,7 @@
This next example manually specifies each build artifact This next example manually specifies each build artifact
(runs in Raw Mode) and uses a modified kickstart file. (runs in Raw Mode) and uses a modified kickstart file.
The example also uses the <filename>-o</filename> option The example also uses the <filename>-o</filename> option
to cause <filename>wic</filename> to create the output to cause Wic to create the output
somewhere other than the default somewhere other than the default
<filename>/var/tmp/wic</filename> directory: <filename>/var/tmp/wic</filename> directory:
<literallayout class='monospaced'> <literallayout class='monospaced'>
@ -4946,8 +5004,8 @@
For this example, For this example,
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
did not have to be specified in the did not have to be specified in the
<filename>local.conf</filename> file since the artifact is <filename>local.conf</filename> file since the
manually specified. artifact is manually specified.
</para> </para>
</section> </section>
</section> </section>
@ -4956,65 +5014,65 @@
<title>Plug-ins</title> <title>Plug-ins</title>
<para> <para>
Plug-ins allow <filename>wic</filename> functionality to Plug-ins allow Wic functionality to
be extended and specialized by users. be extended and specialized by users.
This section documents the plugin interface, which is This section documents the plug-in interface, which is
currently restricted to source plug ins. currently restricted to source plug-ins.
</para> </para>
<para> <para>
Source plug ins provide a mechanism to customize Source plug-ins provide a mechanism to customize
various aspects of the image generation process in various aspects of the image generation process in
<filename>wic</filename>, mainly the contents of Wic, mainly the contents of
partitions. partitions.
The plug ins provide a mechanism for mapping values The plug-ins provide a mechanism for mapping values
specified in <filename>.wks</filename> files using the specified in <filename>.wks</filename> files using the
<filename>--source</filename> keyword to a <filename>--source</filename> keyword to a
particular plugin implementation that populates a particular plug-in implementation that populates a
corresponding partition. corresponding partition.
</para> </para>
<para> <para>
A source plugin is created as a subclass of A source plug-in is created as a subclass of
<filename>SourcePlugin</filename>. <filename>SourcePlugin</filename>.
The plugin file containing it is added to The plug-in file containing it is added to
<filename>scripts/lib/wic/plugins/source/</filename> to <filename>scripts/lib/wic/plugins/source/</filename> to
make the plugin implementation available to the make the plug-in implementation available to the
<filename>wic</filename> implementation. Wic implementation.
For more information, see For more information, see
<filename>scripts/lib/wic/pluginbase.py</filename>. <filename>scripts/lib/wic/pluginbase.py</filename>.
</para> </para>
<para> <para>
Source plugins can also be implemented and added by Source plug-ins can also be implemented and added by
external layers. external layers.
As such, any plugins found in a As such, any plug-ins found in a
<filename>scripts/lib/wic/plugins/source/</filename> <filename>scripts/lib/wic/plugins/source/</filename>
directory in an external layer are also made directory in an external layer are also made
available. available.
</para> </para>
<para> <para>
When the <filename>wic</filename> implementation needs When the Wic implementation needs
to invoke a partition-specific implementation, it looks to invoke a partition-specific implementation, it looks
for the plugin that has the same name as the for the plug-in that has the same name as the
<filename>--source</filename> parameter given to <filename>--source</filename> parameter given to
that partition. that partition.
For example, if the partition is set up as follows: For example, if the partition is set up as follows:
<literallayout class='monospaced'> <literallayout class='monospaced'>
part /boot --source bootimg-pcbios ... part /boot --source bootimg-pcbios ...
</literallayout> </literallayout>
The methods defined as class members of the plugin The methods defined as class members of the plug-in
having the matching <filename>bootimg-pcbios.name</filename> having the matching <filename>bootimg-pcbios.name</filename>
class member are used. class member are used.
</para> </para>
<para> <para>
To be more concrete, here is the plugin definition that To be more concrete, here is the plug-in definition that
matches a matches a
<filename>--source bootimg-pcbios</filename> usage, <filename>--source bootimg-pcbios</filename> usage,
along with an example along with an example
method called by the <filename>wic</filename> implementation method called by the Wic implementation
when it needs to invoke an implementation-specific when it needs to invoke an implementation-specific
partition-preparation function: partition-preparation function:
<literallayout class='monospaced'> <literallayout class='monospaced'>
@ -5026,7 +5084,7 @@
</literallayout> </literallayout>
If the subclass itself does not implement a function, a If the subclass itself does not implement a function, a
default version in a superclass is located and default version in a superclass is located and
used, which is why all plugins must be derived from used, which is why all plug-ins must be derived from
<filename>SourcePlugin</filename>. <filename>SourcePlugin</filename>.
</para> </para>
@ -5034,7 +5092,7 @@
The <filename>SourcePlugin</filename> class defines the The <filename>SourcePlugin</filename> class defines the
following methods, which is the current set of methods following methods, which is the current set of methods
that can be implemented or overridden by that can be implemented or overridden by
<filename>--source</filename> plugins. <filename>--source</filename> plug-ins.
Any methods not implemented by a Any methods not implemented by a
<filename>SourcePlugin</filename> subclass inherit the <filename>SourcePlugin</filename> subclass inherit the
implementations present in the implementations present in the
@ -5045,27 +5103,31 @@
<para> <para>
<itemizedlist> <itemizedlist>
<listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis> <listitem><para>
<emphasis><filename>do_prepare_partition()</filename>:</emphasis>
Called to do the actual content population for a Called to do the actual content population for a
partition. partition.
In other words, the method prepares the final In other words, the method prepares the final
partition image that is incorporated into the partition image that is incorporated into the
disk image. disk image.
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis> <listitem><para>
<emphasis><filename>do_configure_partition()</filename>:</emphasis>
Called before Called before
<filename>do_prepare_partition()</filename>. <filename>do_prepare_partition()</filename>.
This method is typically used to create custom This method is typically used to create custom
configuration files for a partition (e.g. syslinux or configuration files for a partition (e.g. syslinux
grub configuration files). or grub configuration files).
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis> <listitem><para>
<emphasis><filename>do_install_disk()</filename>:</emphasis>
Called after all partitions have been prepared and Called after all partitions have been prepared and
assembled into a disk image. assembled into a disk image.
This method provides a hook to allow finalization of a This method provides a hook to allow finalization
disk image, (e.g. writing an MBR). of a disk image, (e.g. writing an MBR).
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis> <listitem><para>
<emphasis><filename>do_stage_partition()</filename>:</emphasis>
Special content-staging hook called before Special content-staging hook called before
<filename>do_prepare_partition()</filename>. <filename>do_prepare_partition()</filename>.
This method is normally empty.</para> This method is normally empty.</para>
@ -5091,9 +5153,9 @@
<para> <para>
This scheme is extensible. This scheme is extensible.
Adding more hooks is a simple matter of adding more Adding more hooks is a simple matter of adding more
plugin methods to <filename>SourcePlugin</filename> and plug-in methods to <filename>SourcePlugin</filename> and
derived classes. derived classes.
The code that then needs to call the plugin methods uses The code that then needs to call the plug-in methods uses
<filename>plugin.get_source_plugin_methods()</filename> <filename>plugin.get_source_plugin_methods()</filename>
to find the method or methods needed by the call. to find the method or methods needed by the call.
Retrieval of those methods is accomplished Retrieval of those methods is accomplished
@ -5101,16 +5163,16 @@
containing the method names of interest. containing the method names of interest.
On success, these will be filled in with the actual On success, these will be filled in with the actual
methods. methods.
Please see the <filename>wic</filename> Please see the Wic
implementation for examples and details. implementation for examples and details.
</para> </para>
</section> </section>
<section id='openembedded-kickstart-wks-reference'> <section id='openembedded-kickstart-wks-reference'>
<title>OpenEmbedded Kickstart (.wks) Reference</title> <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title>
<para> <para>
The current <filename>wic</filename> implementation supports The current Wic implementation supports
only the basic kickstart partitioning commands: only the basic kickstart partitioning commands:
<filename>partition</filename> (or <filename>part</filename> <filename>partition</filename> (or <filename>part</filename>
for short) and <filename>bootloader</filename>. for short) and <filename>bootloader</filename>.
@ -5126,7 +5188,7 @@
and meanings. and meanings.
The commands are based on the Fedora The commands are based on the Fedora
kickstart versions but with modifications to kickstart versions but with modifications to
reflect <filename>wic</filename> capabilities. reflect Wic capabilities.
You can see the original documentation for those commands You can see the original documentation for those commands
at the following links: at the following links:
<itemizedlist> <itemizedlist>
@ -5144,27 +5206,30 @@
<para> <para>
Either of these commands create a partition on the system Either of these commands create a partition on the system
and uses the following syntax: and use the following syntax:
<literallayout class='monospaced'> <literallayout class='monospaced'>
part [<replaceable>mntpoint</replaceable>] part [<replaceable>mntpoint</replaceable>]
partition [<replaceable>mntpoint</replaceable>] partition [<replaceable>mntpoint</replaceable>]
</literallayout> </literallayout>
If you do not provide If you do not provide
<replaceable>mntpoint</replaceable>, wic creates a partition <replaceable>mntpoint</replaceable>, Wic creates a
but does not mount it. partition but does not mount it.
</para> </para>
<para> <para>
The <filename><replaceable>mntpoint</replaceable></filename> The
is where the <filename><replaceable>mntpoint</replaceable></filename>
partition will be mounted and must be of one of the is where the partition will be mounted and must be of
following forms: one of the following forms:
<itemizedlist> <itemizedlist>
<listitem><para><filename>/<replaceable>path</replaceable></filename>: <listitem><para>
<filename>/<replaceable>path</replaceable></filename>:
For example, <filename>/</filename>, For example, <filename>/</filename>,
<filename>/usr</filename>, or <filename>/usr</filename>, or
<filename>/home</filename></para></listitem> <filename>/home</filename>
<listitem><para><filename>swap</filename>: </para></listitem>
<listitem><para>
<filename>swap</filename>:
The created partition is used as swap space. The created partition is used as swap space.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
@ -5178,8 +5243,8 @@
In order for wic to generate a valid fstab, you must In order for wic to generate a valid fstab, you must
also provide one of the <filename>--ondrive</filename>, also provide one of the <filename>--ondrive</filename>,
<filename>--ondisk</filename>, or <filename>--ondisk</filename>, or
<filename>--use-uuid</filename> partition options as part <filename>--use-uuid</filename> partition options as
of the command. part of the command.
Here is an example using "/" as the mountpoint. Here is an example using "/" as the mountpoint.
The command uses "--ondisk" to force the partition onto The command uses "--ondisk" to force the partition onto
the <filename>sdb</filename> disk: the <filename>sdb</filename> disk:
@ -5189,32 +5254,35 @@
</para> </para>
<para> <para>
Here is a list that describes other supported options you Here is a list that describes other supported options
can use with the <filename>part</filename> and you can use with the <filename>part</filename> and
<filename>partition</filename> commands: <filename>partition</filename> commands:
<itemizedlist> <itemizedlist>
<listitem><para><emphasis><filename>--size</filename>:</emphasis> <listitem><para>
<emphasis><filename>--size</filename>:</emphasis>
The minimum partition size in MBytes. The minimum partition size in MBytes.
Specify an integer value such as 500. Specify an integer value such as 500.
Do not append the number with "MB". Do not append the number with "MB".
You do not need this option if you use You do not need this option if you use
<filename>--source</filename>.</para></listitem> <filename>--source</filename>.
<listitem><para><emphasis><filename>--source</filename>:</emphasis> </para></listitem>
<listitem><para>
<emphasis><filename>--source</filename>:</emphasis>
This option is a This option is a
<filename>wic</filename>-specific option that Wic-specific option that
names the source of the data that populates names the source of the data that populates
the partition. the partition.
The most common value for this option is The most common value for this option is
"rootfs", but you can use any value that maps to "rootfs", but you can use any value that maps to
a valid source plugin. a valid source plug-in.
For information on the source plugins, see the For information on the source plug-ins, see the
"<link linkend='openembedded-kickstart-plugins'>Plugins</link>" "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>"
section.</para> section.</para>
<para>If you use <para>If you use
<filename>--source rootfs</filename>, <filename>--source rootfs</filename>,
<filename>wic</filename> creates a partition as Wic creates a partition as
large as needed and to fill it with the contents of large as needed and to fill it with the contents
the root filesystem pointed to by the of the root filesystem pointed to by the
<filename>-r</filename> command-line option <filename>-r</filename> command-line option
or the equivalent rootfs derived from the or the equivalent rootfs derived from the
<filename>-e</filename> command-line <filename>-e</filename> command-line
@ -5229,30 +5297,33 @@
</para> </para>
<para>If you use <para>If you use
<filename>--source <replaceable>plugin-name</replaceable></filename>, <filename>--source <replaceable>plugin-name</replaceable></filename>,
<filename>wic</filename> creates a partition as Wic creates a partition as
large as needed and fills it with the contents of large as needed and fills it with the contents
the partition that is generated by the of the partition that is generated by the
specified plugin name using the data pointed specified plug-in name using the data pointed
to by the <filename>-r</filename> command-line to by the <filename>-r</filename> command-line
option or the equivalent rootfs derived from the option or the equivalent rootfs derived from the
<filename>-e</filename> command-line <filename>-e</filename> command-line
option. option.
Exactly what those contents and filesystem type end Exactly what those contents and filesystem type
up being are dependent on the given plugin end up being are dependent on the given plug-in
implementation. implementation.
</para> </para>
<para>If you do not use the <para>If you do not use the
<filename>--source</filename> option, the <filename>--source</filename> option, the
<filename>wic</filename> command creates an empty <filename>wic</filename> command creates an
partition. empty partition.
Consequently, you must use the Consequently, you must use the
<filename>--size</filename> option to specify the <filename>--size</filename> option to specify
size of the empty partition. the size of the empty partition.
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> <listitem><para>
Forces the partition to be created on a particular <emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis>
disk.</para></listitem> Forces the partition to be created on a
<listitem><para><emphasis><filename>--fstype</filename>:</emphasis> particular disk.
</para></listitem>
<listitem><para>
<emphasis><filename>--fstype</filename>:</emphasis>
Sets the file system type for the partition. Sets the file system type for the partition.
Valid values are: Valid values are:
<itemizedlist> <itemizedlist>
@ -5268,8 +5339,10 @@
</para></listitem> </para></listitem>
<listitem><para><filename>swap</filename> <listitem><para><filename>swap</filename>
</para></listitem> </para></listitem>
</itemizedlist></para></listitem> </itemizedlist>
<listitem><para><emphasis><filename>--fsoptions</filename>:</emphasis> </para></listitem>
<listitem><para>
<emphasis><filename>--fsoptions</filename>:</emphasis>
Specifies a free-form string of options to be Specifies a free-form string of options to be
used when mounting the filesystem. used when mounting the filesystem.
This string will be copied into the This string will be copied into the
@ -5279,59 +5352,78 @@
If not specified, the default string If not specified, the default string
is "defaults". is "defaults".
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--label label</filename>:</emphasis> <listitem><para>
<emphasis><filename>--label label</filename>:</emphasis>
Specifies the label to give to the filesystem to Specifies the label to give to the filesystem to
be made on the partition. be made on the partition.
If the given label is already in use by another If the given label is already in use by another
filesystem, a new label is created for the filesystem, a new label is created for the
partition.</para></listitem> partition.
<listitem><para><emphasis><filename>--active</filename>:</emphasis> </para></listitem>
Marks the partition as active.</para></listitem> <listitem><para>
<listitem><para><emphasis><filename>--align (in KBytes)</filename>:</emphasis> <emphasis><filename>--active</filename>:</emphasis>
This option is a <filename>wic</filename>-specific Marks the partition as active.
option that says to start a partition on an </para></listitem>
x KBytes boundary.</para></listitem> <listitem><para>
<listitem><para><emphasis><filename>--no-table</filename>:</emphasis> <emphasis><filename>--align (in KBytes)</filename>:</emphasis>
This option is a <filename>wic</filename>-specific This option is a
option. Wic-specific option that
Using the option reserves space for the partition says to start a partition on an
and causes it to become populated. <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 However, the partition is not added to the
partition table. partition table.
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--extra-space</filename>:</emphasis> <listitem><para>
This option is a <filename>wic</filename>-specific <emphasis><filename>--extra-space</filename>:</emphasis>
option that adds extra space after the space This option is a
filled by the content of the partition. 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 The final size can go beyond the size specified
by the <filename>--size</filename> option. by the <filename>--size</filename> option.
The default value is 10 Mbytes. The default value is 10 Mbytes.
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--overhead-factor</filename>:</emphasis> <listitem><para>
This option is a <filename>wic</filename>-specific <emphasis><filename>--overhead-factor</filename>:</emphasis>
option that multiplies the size of the partition by This option is a
the option's value. 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 You must supply a value greater than or equal to
"1". "1".
The default value is "1.3". The default value is "1.3".
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--part-type</filename>:</emphasis> <listitem><para>
This option is a <filename>wic</filename>-specific <emphasis><filename>--part-type</filename>:</emphasis>
option that specifies the partition type globally This option is a
Wic-specific option that
specifies the partition type globally
unique identifier (GUID) for GPT partitions. unique identifier (GUID) for GPT partitions.
You can find the list of partition type GUIDs You can find the list of partition type GUIDs
at at
<ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>. <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>.
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--use-uuid</filename>:</emphasis> <listitem><para>
This option is a <filename>wic</filename>-specific <emphasis><filename>--use-uuid</filename>:</emphasis>
option that causes <filename>wic</filename> to This option is a
generate a random GUID for the partition. Wic-specific option that
The generated identifier is used in the bootloader causes Wic to generate a
configuration to specify the root partition. random GUID for the partition.
The generated identifier is used in the
bootloader configuration to specify the root
partition.
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--uuid</filename>:</emphasis> <listitem><para>
This option is a <filename>wic</filename>-specific <emphasis><filename>--uuid</filename>:</emphasis>
This option is a
Wic-specific
option that specifies the partition UUID. option that specifies the partition UUID.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
@ -5342,40 +5434,46 @@
<title>Command: bootloader</title> <title>Command: bootloader</title>
<para> <para>
This command specifies how the boot loader should be This command specifies how the bootloader should be
configured and supports the following options: configured and supports the following options:
<note> <note>
Bootloader functionality and boot partitions are Bootloader functionality and boot partitions are
implemented by the various implemented by the various
<filename>--source</filename> <filename>--source</filename>
plugins that implement bootloader functionality. plug-ins that implement bootloader functionality.
The bootloader command essentially provides a means of The bootloader command essentially provides a
modifying bootloader configuration. means of modifying bootloader configuration.
</note> </note>
<itemizedlist> <itemizedlist>
<listitem><para><emphasis><filename>--timeout</filename>:</emphasis> <listitem><para>
<emphasis><filename>--timeout</filename>:</emphasis>
Specifies the number of seconds before the Specifies the number of seconds before the
bootloader times out and boots the default option. bootloader times out and boots the default
option.
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--append</filename>:</emphasis> <listitem><para>
<emphasis><filename>--append</filename>:</emphasis>
Specifies kernel parameters. Specifies kernel parameters.
These parameters will be added to the syslinux These parameters will be added to the syslinux
<filename>APPEND</filename> or <filename>APPEND</filename> or
<filename>grub</filename> kernel command line. <filename>grub</filename> kernel command line.
</para></listitem> </para></listitem>
<listitem><para><emphasis><filename>--configfile</filename>:</emphasis> <listitem><para>
<emphasis><filename>--configfile</filename>:</emphasis>
Specifies a user-defined configuration file for Specifies a user-defined configuration file for
the bootloader. the bootloader.
You can provide a full pathname for the file or You can provide a full pathname for the file or
a file that exists in the a file that exists in the
<filename>canned-wks</filename> folder. <filename>canned-wks</filename> folder.
This option overrides all other bootloader options. This option overrides all other bootloader
options.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</section> </section>
</section> </section>
</section> </section>
</section>
<section id='configuring-the-kernel'> <section id='configuring-the-kernel'>
<title>Configuring the Kernel</title> <title>Configuring the Kernel</title>