[gnome-continuous-yocto/gnomeostree-3.28-rocko: 3968/8267] dev-manual: Updated to the "Creating Partitioned Images" section
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-continuous-yocto/gnomeostree-3.28-rocko: 3968/8267] dev-manual: Updated to the "Creating Partitioned Images" section
- Date: Sun, 17 Dec 2017 01:22:38 +0000 (UTC)
commit 27751642cd7669f649c5de0d5330727b67e100c2
Author: Scott Rifenbark <srifenbark gmail com>
Date: Mon Dec 12 17:04:46 2016 -0800
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>
.../dev-manual/dev-manual-common-tasks.xml | 1692 +++++++++++---------
1 files changed, 895 insertions(+), 797 deletions(-)
---
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml
b/documentation/dev-manual/dev-manual-common-tasks.xml
index 2c95ecb..d48724c 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3984,7 +3984,7 @@
</para></listitem>
</itemizedlist>
</para>
-'
+
<para>
For the RPM Package Management System, the following implementation details
exist:
@@ -4365,328 +4365,385 @@
format the device requires.
Should your device require multiple partitions on an SD card, flash,
or an HDD, you can use the OpenEmbedded Image Creator,
- <filename>wic</filename>, to create the properly partitioned image.
- </para>
-
- <para>
- The <filename>wic</filename> command generates partitioned images
- from existing OpenEmbedded build artifacts.
- Image generation is driven by partitioning commands contained
- in an Openembedded kickstart file (<filename>.wks</filename>)
- specified either directly on the command line or as one of a
- selection of canned <filename>.wks</filename> files as shown
- with the <filename>wic list images</filename> command in the
- "<link linkend='using-a-provided-kickstart_file'>Using an Existing Kickstart File</link>"
- section.
- When applied to a given set of build artifacts, the result is an
- image or set of images that can be directly written onto media and
- used on a particular system.
+ Wic, to create the properly partitioned image.
</para>
<para>
- The <filename>wic</filename> command and the infrastructure
- it is based on is by definition incomplete.
- Its purpose is to allow the generation of customized images,
- and as such was designed to be completely extensible through a
- plug-in interface.
- See the
- "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>"
- section for information on these plug-ins.
- </para>
-
- <para>
- This section provides some background information on
- <filename>wic</filename>, describes what you need to have in
- place to run the tool, provides instruction on how to use
- <filename>wic</filename>, and provides several examples.
+ You can generate Wic-partitioned images
+ (<replaceable>image</replaceable><filename>.wic</filename>)
+ two ways: using the OpenEmbedded build system and by running
+ the OpenEmbedded Image Creator Wic directly.
+ The former way is preferable as it is easier to use and understand.
</para>
- <section id='wic-background'>
- <title>Background</title>
+ <section id='creating-wic-images-oe'>
+ <title>Creating Wic-Partitioned Images</title>
<para>
- This section provides some background on the
- <filename>wic</filename> utility.
- While none of this information is required to use
- <filename>wic</filename>, you might find it interesting.
+ The OpenEmbedded build system can generate
+ 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>
- 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
- <ulink
url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
- class and <filename>mkefidisk.sh</filename> script.
- The difference between
- <filename>wic</filename> and those examples is
- that with <filename>wic</filename> the
- functionality of those scripts is implemented
- by a general-purpose partitioning language, which is
- based on Redhat kickstart syntax.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='wic-requirements'>
- <title>Requirements</title>
-
- <para>
- In order to use the <filename>wic</filename> utility
- with the OpenEmbedded Build system, your system needs
- to meet the following requirements:
- <itemizedlist>
- <listitem><para>The Linux distribution on your
- development host must support the Yocto Project.
- See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux
Distributions</ulink>"
- section in the Yocto Project Reference Manual for this
- list of distributions.</para></listitem>
- <listitem><para>
- The standard system utilities, such as
- <filename>cp</filename>, must be installed on your
- development host system.
- </para></listitem>
- <listitem><para>
- You need to have the build artifacts already
- available, which typically means that you must
- have already created an image using the
- Openembedded build system (e.g.
- <filename>core-image-minimal</filename>).
- While it might seem redundant to generate an image in
- order to create an image using
- <filename>wic</filename>, the current version of
- <filename>wic</filename> requires the artifacts
- in the form generated by the build system.
- </para></listitem>
- <listitem><para>
- You must build several native tools, which are tools
- built to run on the build system:
- <literallayout class='monospaced'>
- $ bitbake parted-native dosfstools-native mtools-native
- </literallayout>
+ 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>
- 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>.
+ 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.
</para>
</section>
- <section id='wic-getting-help'>
- <title>Getting Help</title>
+ <section id='create-wic-images-wic'>
+ <title>Using OpenEmbedded Image Creator Wic to Generate Partitioned Images</title>
<para>
- You can get general help for the <filename>wic</filename>
- by entering the <filename>wic</filename> command by itself
- or by entering the command with a help argument as follows:
- <literallayout class='monospaced'>
- $ wic -h
- $ wic --help
- </literallayout>
+ 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>
- Currently, <filename>wic</filename> supports two commands:
- <filename>create</filename> and <filename>list</filename>.
- You can get help for these commands as follows:
- <literallayout class='monospaced'>
- $ wic help <replaceable>command</replaceable>
- </literallayout>
+ The <filename>wic</filename> command and the infrastructure
+ it is based on is by definition incomplete.
+ The purpose of the command is to allow the generation of
+ customized images, and as such, was designed to be
+ completely extensible through a plug-in interface.
+ See the
+ "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>"
+ section for information on these plug-ins.
</para>
<para>
- You can also get detailed help on a number of topics
- from the help system.
- The output of <filename>wic --help</filename>
- displays a list of available help
- topics under a "Help topics" heading.
- You can have the help system display the help text for
- a given topic by prefacing the topic with
- <filename>wic help</filename>:
- <literallayout class='monospaced'>
- $ wic help <replaceable>help_topic</replaceable>
- </literallayout>
+ This section provides some background information on Wic,
+ describes what you need to have in
+ place to run the tool, provides instruction on how to use
+ the <filename>wic</filename> utility,
+ and provides several examples.
</para>
- <para>
- You can find out more about the images
- <filename>wic</filename> creates using the existing
- kickstart files with the following form of the command:
- <literallayout class='monospaced'>
- $ wic list <replaceable>image</replaceable> help
- </literallayout>
- where <filename><replaceable>image</replaceable></filename> is either
- <filename>directdisk</filename> or
- <filename>mkefidisk</filename>.
- </para>
- </section>
+ <section id='wic-background'>
+ <title>Background</title>
- <section id='operational-modes'>
- <title>Operational Modes</title>
+ <para>
+ This section provides some background on the
+ <filename>wic</filename> utility.
+ While none of this information is required to use
+ Wic, you might find it interesting.
+ <itemizedlist>
+ <listitem><para>
+ The name "Wic" is derived from OpenEmbedded
+ Image Creator (oeic).
+ The "oe" diphthong in "oeic" was promoted to the
+ letter "w", because "oeic" is both difficult to
+ remember and to pronounce.
+ </para></listitem>
+ <listitem><para>
+ Wic is loosely based on the
+ Meego Image Creator (<filename>mic</filename>)
+ framework.
+ The Wic implementation has been
+ heavily modified to make direct use of OpenEmbedded
+ build artifacts instead of package installation and
+ configuration, which are already incorporated within
+ the OpenEmbedded artifacts.
+ </para></listitem>
+ <listitem><para>
+ Wic is a completely independent
+ standalone utility that initially provides
+ easier-to-use and more flexible replacements for a
+ existing functionality in OE Core's
+ <ulink
url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
+ class and <filename>mkefidisk.sh</filename> script.
+ The difference between
+ Wic and those examples is
+ that with Wic the
+ functionality of those scripts is implemented
+ by a general-purpose partitioning language, which is
+ based on Redhat kickstart syntax.</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
- <para>
- You can use <filename>wic</filename> in two different
- modes, depending on how much control you need for
- specifying the Openembedded build artifacts that are
- used for creating the image: Raw and Cooked:
- <itemizedlist>
- <listitem><para><emphasis>Raw Mode:</emphasis>
- You explicitly specify build artifacts through
- command-line arguments.</para></listitem>
- <listitem><para><emphasis>Cooked Mode:</emphasis>
- The current
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- setting and image name are used to automatically locate
- and provide the build artifacts.</para></listitem>
- </itemizedlist>
- </para>
+ <section id='wic-requirements'>
+ <title>Requirements</title>
- <para>
- Regardless of the mode you use, you need to have the build
- artifacts ready and available.
- Additionally, the environment must be set up using the
- <ulink
url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
- or
- <ulink
url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
- script found in the
- <link linkend='build-directory'>Build Directory</link>.
- </para>
+ <para>
+ In order to use the <filename>wic</filename> utility
+ with the OpenEmbedded Build system, your system needs
+ to meet the following requirements:
+ <itemizedlist>
+ <listitem><para>The Linux distribution on your
+ development host must support the Yocto Project.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux
Distributions</ulink>"
+ section in the Yocto Project Reference Manual for
+ the list of distributions that support the
+ Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ The standard system utilities, such as
+ <filename>cp</filename>, must be installed on your
+ development host system.
+ </para></listitem>
+ <listitem><para>
+ You need to have the build artifacts already
+ available, which typically means that you must
+ have already created an image using the
+ Openembedded build system (e.g.
+ <filename>core-image-minimal</filename>).
+ While it might seem redundant to generate an image
+ in order to create an image using
+ Wic, the current version of
+ Wic requires the artifacts
+ in the form generated by the build system.
+ </para></listitem>
+ <listitem><para>
+ You must build several native tools, which are tools
+ built to run on the build system:
+ <literallayout class='monospaced'>
+ $ bitbake parted-native dosfstools-native mtools-native
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ You must have sourced one of the build environment
+ setup scripts (i.e.
+ <ulink
url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+ or
+ <ulink
url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
+ found in the
+ <link linkend='build-directory'>Build Directory</link>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='wic-getting-help'>
+ <title>Getting Help</title>
+
+ <para>
+ You can get general help for the <filename>wic</filename>
+ command by entering the <filename>wic</filename> command
+ by itself or by entering the command with a help argument
+ as follows:
+ <literallayout class='monospaced'>
+ $ wic -h
+ $ wic --help
+ </literallayout>
+ </para>
+
+ <para>
+ Currently, Wic supports two commands:
+ <filename>create</filename> and <filename>list</filename>.
+ You can get help for these commands as follows:
+ <literallayout class='monospaced'>
+ $ wic help <replaceable>command</replaceable>
+ with <replaceable>command</replaceable> being either
+ <filename>create</filename> or <filename>list</filename>.
+ </literallayout>
+ </para>
- <section id='raw-mode'>
- <title>Raw Mode</title>
+ <para>
+ You can also get detailed help on a number of topics
+ from the help system.
+ The output of <filename>wic --help</filename>
+ displays a list of available help
+ topics under a "Help topics" heading.
+ You can have the help system display the help text for
+ a given topic by prefacing the topic with
+ <filename>wic help</filename>:
+ <literallayout class='monospaced'>
+ $ wic help <replaceable>help_topic</replaceable>
+ </literallayout>
+ </para>
<para>
- The general form of the 'wic' command in raw mode is:
+ You can find out more about the images
+ Wic creates using the existing
+ kickstart files with the following form of the command:
<literallayout class='monospaced'>
+ $ wic list <replaceable>image</replaceable> help
+ </literallayout>
+ with <filename><replaceable>image</replaceable></filename>
+ being either <filename>directdisk</filename> or
+ <filename>mkefidisk</filename>.
+ </para>
+ </section>
+
+ <section id='operational-modes'>
+ <title>Operational Modes</title>
+
+ <para>
+ You can use Wic in two different
+ modes, depending on how much control you need for
+ specifying the Openembedded build artifacts that are
+ used for creating the image: Raw and Cooked:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Raw Mode:</emphasis>
+ You explicitly specify build artifacts through
+ command-line arguments.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Cooked Mode:</emphasis>
+ The current
+ <ulink
url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ setting and image name are used to automatically
+ locate and provide the build artifacts.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Regardless of the mode you use, you need to have the build
+ artifacts ready and available.
+ Additionally, the environment must be set up using the
+ <ulink
url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+ or
+ <ulink
url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
+ script found in the
+ <link linkend='build-directory'>Build Directory</link>.
+ </para>
+
+ <section id='raw-mode'>
+ <title>Raw Mode</title>
+
+ <para>
+ The general form of the
+ <filename>wic</filename> command in raw mode is:
+ <literallayout class='monospaced'>
$ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...]
- Where:
+ Where:
- <replaceable>image_name</replaceable>.wks
- An OpenEmbedded kickstart file. You can provide
- your own custom file or use a file from a set of
- existing files as described by further options.
+ <replaceable>image_name</replaceable>.wks
+ An OpenEmbedded kickstart file. You can provide
+ your own custom file or use a file from a set of
+ existing files as described by further options.
- -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable>
- The name of a directory in which to create image.
+ -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable>
+ The name of a directory in which to create image.
- -i <replaceable>PROPERTIES_FILE</replaceable>,
--infile=<replaceable>PROPERTIES_FILE</replaceable>
- The name of a file containing the values for image
- properties as a JSON file.
+ -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable>
+ The name of a file containing the values for image
+ properties as a JSON file.
- -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable>
- The name of the image from which to use the artifacts
- (e.g. <filename>core-image-sato</filename>).
+ -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable>
+ The name of the image from which to use the artifacts
+ (e.g. <filename>core-image-sato</filename>).
- -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable>
- The path to the <filename>/rootfs</filename> directory to use as the
- <filename>.wks</filename> rootfs source.
+ -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable>
+ The path to the <filename>/rootfs</filename> directory to use as the
+ <filename>.wks</filename> rootfs source.
- -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable>
- The path to the directory containing the boot artifacts
- (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as
the <filename>.wks</filename> bootimg
- source.
+ -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable>
+ The path to the directory containing the boot artifacts
+ (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the
<filename>.wks</filename> bootimg
+ source.
- -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable>
- The path to the directory containing the kernel to use
- in the <filename>.wks</filename> boot image.
+ -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable>
+ The path to the directory containing the kernel to use
+ in the <filename>.wks</filename> boot image.
- -n <replaceable>NATIVE_SYSROOT</replaceable>,
--native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable>
- The path to the native sysroot containing the tools to use
- to build the image.
+ -n <replaceable>NATIVE_SYSROOT</replaceable>,
--native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable>
+ The path to the native sysroot containing the tools to use
+ to build the image.
- -s, --skip-build-check
- Skips the build check.
+ -s, --skip-build-check
+ Skips the build check.
- -D, --debug
- Output debug information.
- </literallayout>
- <note>
- You do not need root privileges to run
- <filename>wic</filename>.
- In fact, you should not run as root when using the
- utility.
- </note>
- </para>
- </section>
+ -D, --debug
+ Output debug information.
+ </literallayout>
+ <note>
+ You do not need root privileges to run
+ Wic.
+ In fact, you should not run as root when using the
+ utility.
+ </note>
+ </para>
+ </section>
- <section id='cooked-mode'>
- <title>Cooked Mode</title>
+ <section id='cooked-mode'>
+ <title>Cooked Mode</title>
- <para>
- The general form of the <filename>wic</filename> command
- using Cooked Mode is:
- <literallayout class='monospaced'>
+ <para>
+ The general form of the <filename>wic</filename> command
+ using Cooked Mode is:
+ <literallayout class='monospaced'>
$ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable>
- Where:
+ Where:
- <replaceable>kickstart_file</replaceable>
- An OpenEmbedded kickstart file. You can provide your own
- custom file or supplied file.
+ <replaceable>kickstart_file</replaceable>
+ An OpenEmbedded kickstart file. You can provide your own
+ custom file or a supplied file.
- <replaceable>image_name</replaceable>
- Specifies the image built using the OpenEmbedded build
- system.
- </literallayout>
- This form is the simplest and most user-friendly, as it
- does not require specifying all individual parameters.
- All you need to provide is your own
- <filename>.wks</filename> file or one provided with the
- release.
- </para>
+ <replaceable>image_name</replaceable>
+ Specifies the image built using the OpenEmbedded build
+ system.
+ </literallayout>
+ This form is the simplest and most user-friendly, as it
+ does not require specifying all individual parameters.
+ All you need to provide is your own
+ <filename>.wks</filename> file or one provided with the
+ release.
+ </para>
+ </section>
</section>
- </section>
- <section id='using-a-provided-kickstart_file'>
- <title>Using an Existing Kickstart File</title>
+ <section id='using-a-provided-kickstart-file'>
+ <title>Using an Existing Kickstart File</title>
- <para>
- If you do not want to create your own
- <filename>.wks</filename> file, you can use an existing
- file provided by the <filename>wic</filename> installation.
- Use the following command to list the available files:
- <literallayout class='monospaced'>
+ <para>
+ If you do not want to create your own
+ <filename>.wks</filename> file, you can use an existing
+ file provided by the Wic installation.
+ Use the following command to list the available files:
+ <literallayout class='monospaced'>
$ wic list images
directdisk Create a 'pcbios' direct disk image
mkefidisk Create an EFI disk image
- </literallayout>
- When you use an existing file, you do not have to use the
- <filename>.wks</filename> extension.
- Here is an example in Raw Mode that uses the
- <filename>directdisk</filename> file:
- <literallayout class='monospaced'>
+ </literallayout>
+ When you use an existing file, you do not have to use the
+ <filename>.wks</filename> extension.
+ Here is an example in Raw Mode that uses the
+ <filename>directdisk</filename> file:
+ <literallayout class='monospaced'>
$ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b
<replaceable>bootimg_dir</replaceable> \
-k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable>
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- Here are the actual partition language commands
- used in the <filename>mkefidisk.wks</filename> file to generate
- an image:
- <literallayout class='monospaced'>
+ <para>
+ Here are the actual partition language commands
+ used in the <filename>mkefidisk.wks</filename> file to
+ generate an image:
+ <literallayout class='monospaced'>
# short-description: Create an EFI disk image
# long-description: Creates a partitioned EFI disk image that the user
# can directly dd to boot media.
@@ -4698,30 +4755,30 @@
part swap --ondisk sda --size 44 --label swap1 --fstype=swap
bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0
vmalloc=256MB snd-hda-intel.enable_msi=0"
- </literallayout>
- </para>
- </section>
+ </literallayout>
+ </para>
+ </section>
- <section id='wic-usage-examples'>
- <title>Examples</title>
+ <section id='wic-usage-examples'>
+ <title>Examples</title>
- <para>
- This section provides several examples that show how to use
- the <filename>wic</filename> utility.
- All the examples assume the list of requirements in the
- "<link linkend='wic-requirements'>Requirements</link>" section
- have been met.
- The examples assume the previously generated image is
- <filename>core-image-minimal</filename>.
- </para>
+ <para>
+ This section provides several examples that show how to use
+ the <filename>wic</filename> utility.
+ All the examples assume the list of requirements in the
+ "<link linkend='wic-requirements'>Requirements</link>"
+ section have been met.
+ The examples assume the previously generated image is
+ <filename>core-image-minimal</filename>.
+ </para>
- <section id='generate-an-image-using-a-provided-kickstart-file'>
- <title>Generate an Image using an Existing Kickstart File</title>
+ <section id='generate-an-image-using-a-provided-kickstart-file'>
+ <title>Generate an Image using an Existing Kickstart File</title>
- <para>
- This example runs in Cooked Mode and uses the
- <filename>mkefidisk</filename> kickstart file:
- <literallayout class='monospaced'>
+ <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.
@@ -4737,114 +4794,115 @@
KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel
NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
-
The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
- </literallayout>
- This example shows the easiest way to create an image
- by running in Cooked Mode and using the
- <filename>-e</filename> option with an existing kickstart
- file.
- All that is necessary is to specify the image used to
- generate the artifacts.
- Your <filename>local.conf</filename> needs to have the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- variable set to the machine you are using, which is
- "minnow" in this example.
- </para>
+ </literallayout>
+ The previous example shows the easiest way to create
+ an image by running in Cooked Mode and using the
+ <filename>-e</filename> option with an existing
+ kickstart file.
+ All that is necessary is to specify the image used to
+ generate the artifacts.
+ Your <filename>local.conf</filename> needs to have the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable set to the machine you are using, which is
+ "minnow" in this example.
+ </para>
- <para>
- The output specifies the exact image created as well as
- where it was created.
- The output also names the artifacts used and the exact
- <filename>.wks</filename> script that was used to generate
- the image.
- <note>
- You should always verify the details provided in the
- output to make sure that the image was indeed created
- exactly as expected.
- </note>
- </para>
+ <para>
+ The output specifies the exact image created as well as
+ where it was created.
+ The output also names the artifacts used and the exact
+ <filename>.wks</filename> script that was used to
+ generate the image.
+ <note>
+ You should always verify the details provided in the
+ output to make sure that the image was indeed
+ created exactly as expected.
+ </note>
+ </para>
- <para>
- Continuing with the example, you can now directly
- <filename>dd</filename> the image to a USB stick, or
- whatever media for which you built your image,
- and boot the resulting media:
- <literallayout class='monospaced'>
+ <para>
+ Continuing with the example, you can now directly
+ <filename>dd</filename> the image to a USB stick, or
+ whatever media for which you built your image,
+ and boot the resulting media:
+ <literallayout class='monospaced'>
$ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
[sudo] password for trz:
182274+0 records in
182274+0 records out
93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s
- [trz@empanada ~]$ sudo eject /dev/sdb
- </literallayout>
- </para>
- </section>
+ [trz at empanada ~]$ sudo eject /dev/sdb
+ </literallayout>
+ </para>
+ </section>
- <section id='using-a-modified-kickstart-file'>
- <title>Using a Modified Kickstart File</title>
+ <section id='using-a-modified-kickstart-file'>
+ <title>Using a Modified Kickstart File</title>
- <para>
- Because <filename>wic</filename> image creation is driven
- by the kickstart file, it is easy to affect image creation
- by changing the parameters in the file.
- This next example demonstrates that through modification
- of the <filename>directdisk</filename> kickstart file.
- </para>
+ <para>
+ Because Wic-partitioned image creation is
+ driven by the kickstart file, it is easy to affect
+ image creation by changing the parameters in the file.
+ This next example demonstrates that through modification
+ of the <filename>directdisk</filename> kickstart file.
+ </para>
- <para>
- As mentioned earlier, you can use the command
- <filename>wic list images</filename> to show the list
- of existing kickstart files.
- The directory in which these files reside is
- <filename>scripts/lib/image/canned-wks/</filename>
- located in the
- <link linkend='source-directory'>Source Directory</link>.
- Because the available files reside in this directory, you
- can create and add your own custom files to the directory.
- Subsequent use of the <filename>wic list images</filename>
- command would then include your kickstart files.
- </para>
+ <para>
+ As mentioned earlier, you can use the command
+ <filename>wic list images</filename> to show the list
+ of existing kickstart files.
+ The directory in which these files reside is
+ <filename>scripts/lib/image/canned-wks/</filename>
+ located in the
+ <link linkend='source-directory'>Source Directory</link>.
+ Because the available files reside in this directory,
+ you can create and add your own custom files to the
+ directory.
+ Subsequent use of the
+ <filename>wic list images</filename> command would then
+ include your kickstart files.
+ </para>
- <para>
- In this example, the existing
- <filename>directdisk</filename> file already does most
- of what is needed.
- However, for the hardware in this example, the image will
- need to boot from <filename>sdb</filename> instead of
- <filename>sda</filename>, which is what the
- <filename>directdisk</filename> kickstart file uses.
- </para>
+ <para>
+ In this example, the existing
+ <filename>directdisk</filename> file already does most
+ of what is needed.
+ However, for the hardware in this example, the image
+ will need to boot from <filename>sdb</filename> instead
+ of <filename>sda</filename>, which is what the
+ <filename>directdisk</filename> kickstart file uses.
+ </para>
- <para>
- The example begins by making a copy of the
- <filename>directdisk.wks</filename> file in the
- <filename>scripts/lib/image/canned-wks</filename>
- directory and then changing the lines that specify the
- target disk from which to boot.
- <literallayout class='monospaced'>
+ <para>
+ The example begins by making a copy of the
+ <filename>directdisk.wks</filename> file in the
+ <filename>scripts/lib/image/canned-wks</filename>
+ directory and then by changing the lines that specify
+ the target disk from which to boot.
+ <literallayout class='monospaced'>
$ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
- </literallayout>
- Next, the example modifies the
- <filename>directdisksdb.wks</filename> file and changes all
- instances of "<filename>--ondisk sda</filename>"
- to "<filename>--ondisk sdb</filename>".
- The example changes the following two lines and leaves the
- remaining lines untouched:
- <literallayout class='monospaced'>
+ </literallayout>
+ Next, the example modifies the
+ <filename>directdisksdb.wks</filename> file and changes
+ all instances of "<filename>--ondisk sda</filename>"
+ to "<filename>--ondisk sdb</filename>".
+ The example changes the following two lines and leaves
+ the remaining lines untouched:
+ <literallayout class='monospaced'>
part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
- </literallayout>
- Once the lines are changed, the example generates the
- <filename>directdisksdb</filename> image.
- The command points the process at the
- <filename>core-image-minimal</filename> artifacts for the
- Next Unit of Computing (nuc)
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- the <filename>local.conf</filename>.
- <literallayout class='monospaced'>
+ </literallayout>
+ Once the lines are changed, the example generates the
+ <filename>directdisksdb</filename> image.
+ The command points the process at the
+ <filename>core-image-minimal</filename> artifacts for
+ the Next Unit of Computing (nuc)
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ the <filename>local.conf</filename>.
+ <literallayout class='monospaced'>
$ wic create directdisksdb -e core-image-minimal
Checking basic build environment...
Done.
@@ -4855,39 +4913,39 @@
/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct
The following build artifacts were used to create the image(s):
+
ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs
BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share
KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel
NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
-
The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
- </literallayout>
- Continuing with the example, you can now directly
- <filename>dd</filename> the image to a USB stick, or
- whatever media for which you built your image,
- and boot the resulting media:
- <literallayout class='monospaced'>
+ </literallayout>
+ Continuing with the example, you can now directly
+ <filename>dd</filename> the image to a USB stick, or
+ whatever media for which you built your image,
+ and boot the resulting media:
+ <literallayout class='monospaced'>
$ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb
86018+0 records in
86018+0 records out
44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s
- [trz@empanada tmp]$ sudo eject /dev/sdb
- </literallayout>
- </para>
- </section>
+ [trz at empanada tmp]$ sudo eject /dev/sdb
+ </literallayout>
+ </para>
+ </section>
- <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'>
- <title>Creating an Image Based on <filename>core-image-minimal</filename> and
<filename>crownbay-noemgd</filename></title>
+ <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'>
+ <title>Creating an Image Based on <filename>core-image-minimal</filename> and
<filename>crownbay-noemgd</filename></title>
- <para>
- This example creates an image based on
- <filename>core-image-minimal</filename> and a
- <filename>crownbay-noemgd</filename>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- that works right out of the box.
- <literallayout class='monospaced'>
+ <para>
+ This example creates an image based on
+ <filename>core-image-minimal</filename> and a
+ <filename>crownbay-noemgd</filename>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ that works right out of the box.
+ <literallayout class='monospaced'>
$ wic create directdisk -e core-image-minimal
Checking basic build environment...
@@ -4907,21 +4965,21 @@
The image(s) were created using OE kickstart file:
/home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
- </literallayout>
- </para>
- </section>
+ </literallayout>
+ </para>
+ </section>
- <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'>
- <title>Using a Modified Kickstart File and Running in Raw Mode</title>
+ <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'>
+ <title>Using a Modified Kickstart File and Running in Raw Mode</title>
- <para>
- This next example manually specifies each build artifact
- (runs in Raw Mode) and uses a modified kickstart file.
- The example also uses the <filename>-o</filename> option
- to cause <filename>wic</filename> to create the output
- somewhere other than the default
- <filename>/var/tmp/wic</filename> directory:
- <literallayout class='monospaced'>
+ <para>
+ This next example manually specifies each build artifact
+ (runs in Raw Mode) and uses a modified kickstart file.
+ The example also uses the <filename>-o</filename> option
+ to cause Wic to create the output
+ somewhere other than the default
+ <filename>/var/tmp/wic</filename> directory:
+ <literallayout class='monospaced'>
$ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \
/home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \
--bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \
@@ -4942,437 +5000,477 @@
The image(s) were created using OE kickstart file:
/home/trz/test.wks
- </literallayout>
- For this example,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- did not have to be specified in the
- <filename>local.conf</filename> file since the artifact is
- manually specified.
- </para>
+ </literallayout>
+ For this example,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ did not have to be specified in the
+ <filename>local.conf</filename> file since the
+ artifact is manually specified.
+ </para>
+ </section>
</section>
- </section>
- <section id='openembedded-kickstart-plugins'>
- <title>Plug-ins</title>
+ <section id='openembedded-kickstart-plugins'>
+ <title>Plug-ins</title>
- <para>
- Plug-ins allow <filename>wic</filename> functionality to
- be extended and specialized by users.
- This section documents the plugin interface, which is
- currently restricted to source plug ins.
- </para>
+ <para>
+ Plug-ins allow Wic functionality to
+ be extended and specialized by users.
+ This section documents the plug-in interface, which is
+ currently restricted to source plug-ins.
+ </para>
- <para>
- Source plug ins provide a mechanism to customize
- various aspects of the image generation process in
- <filename>wic</filename>, mainly the contents of
- partitions.
- The plug ins provide a mechanism for mapping values
- specified in <filename>.wks</filename> files using the
- <filename>--source</filename> keyword to a
- particular plugin implementation that populates a
- corresponding partition.
- </para>
+ <para>
+ Source plug-ins provide a mechanism to customize
+ various aspects of the image generation process in
+ Wic, mainly the contents of
+ partitions.
+ The plug-ins provide a mechanism for mapping values
+ specified in <filename>.wks</filename> files using the
+ <filename>--source</filename> keyword to a
+ particular plug-in implementation that populates a
+ corresponding partition.
+ </para>
- <para>
- A source plugin is created as a subclass of
- <filename>SourcePlugin</filename>.
- The plugin file containing it is added to
- <filename>scripts/lib/wic/plugins/source/</filename> to
- make the plugin implementation available to the
- <filename>wic</filename> implementation.
- For more information, see
- <filename>scripts/lib/wic/pluginbase.py</filename>.
- </para>
+ <para>
+ A source plug-in is created as a subclass of
+ <filename>SourcePlugin</filename>.
+ The plug-in file containing it is added to
+ <filename>scripts/lib/wic/plugins/source/</filename> to
+ make the plug-in implementation available to the
+ Wic implementation.
+ For more information, see
+ <filename>scripts/lib/wic/pluginbase.py</filename>.
+ </para>
- <para>
- Source plugins can also be implemented and added by
- external layers.
- As such, any plugins found in a
- <filename>scripts/lib/wic/plugins/source/</filename>
- directory in an external layer are also made
- available.
- </para>
+ <para>
+ Source plug-ins can also be implemented and added by
+ external layers.
+ As such, any plug-ins found in a
+ <filename>scripts/lib/wic/plugins/source/</filename>
+ directory in an external layer are also made
+ available.
+ </para>
- <para>
- When the <filename>wic</filename> implementation needs
- to invoke a partition-specific implementation, it looks
- for the plugin that has the same name as the
- <filename>--source</filename> parameter given to
- that partition.
- For example, if the partition is set up as follows:
- <literallayout class='monospaced'>
+ <para>
+ When the Wic implementation needs
+ to invoke a partition-specific implementation, it looks
+ for the plug-in that has the same name as the
+ <filename>--source</filename> parameter given to
+ that partition.
+ For example, if the partition is set up as follows:
+ <literallayout class='monospaced'>
part /boot --source bootimg-pcbios ...
- </literallayout>
- The methods defined as class members of the plugin
- having the matching <filename>bootimg-pcbios.name</filename>
- class member are used.
- </para>
+ </literallayout>
+ The methods defined as class members of the plug-in
+ having the matching <filename>bootimg-pcbios.name</filename>
+ class member are used.
+ </para>
- <para>
- To be more concrete, here is the plugin definition that
- matches a
- <filename>--source bootimg-pcbios</filename> usage,
- along with an example
- method called by the <filename>wic</filename> implementation
- when it needs to invoke an implementation-specific
- partition-preparation function:
- <literallayout class='monospaced'>
+ <para>
+ To be more concrete, here is the plug-in definition that
+ matches a
+ <filename>--source bootimg-pcbios</filename> usage,
+ along with an example
+ method called by the Wic implementation
+ when it needs to invoke an implementation-specific
+ partition-preparation function:
+ <literallayout class='monospaced'>
class BootimgPcbiosPlugin(SourcePlugin):
name = 'bootimg-pcbios'
@classmethod
def do_prepare_partition(self, part, ...)
- </literallayout>
- If the subclass itself does not implement a function, a
- default version in a superclass is located and
- used, which is why all plugins must be derived from
- <filename>SourcePlugin</filename>.
- </para>
-
- <para>
- The <filename>SourcePlugin</filename> class defines the
- following methods, which is the current set of methods
- that can be implemented or overridden by
- <filename>--source</filename> plugins.
- Any methods not implemented by a
- <filename>SourcePlugin</filename> subclass inherit the
- implementations present in the
- <filename>SourcePlugin</filename> class.
- For more information, see the
- <filename>SourcePlugin</filename> source for details:
- </para>
-
- <para>
- <itemizedlist>
- <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis>
- Called to do the actual content population for a
- partition.
- In other words, the method prepares the final
- partition image that is incorporated into the
- disk image.
- </para></listitem>
- <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis>
- Called before
- <filename>do_prepare_partition()</filename>.
- This method is typically used to create custom
- configuration files for a partition (e.g. syslinux or
- grub configuration files).
- </para></listitem>
- <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis>
- Called after all partitions have been prepared and
- assembled into a disk image.
- This method provides a hook to allow finalization of a
- disk image, (e.g. writing an MBR).
- </para></listitem>
- <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis>
- Special content-staging hook called before
- <filename>do_prepare_partition()</filename>.
- This method is normally empty.</para>
- <para>Typically, a partition just uses the passed-in
- parameters (e.g. the unmodified value of
- <filename>bootimg_dir</filename>).
- However, in some cases things might need to be
- more tailored.
- As an example, certain files might additionally
- need to be taken from
- <filename>bootimg_dir + /boot</filename>.
- This hook allows those files to be staged in a
- customized fashion.
- <note>
- <filename>get_bitbake_var()</filename>
- allows you to access non-standard variables
- that you might want to use for this.
- </note>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- This scheme is extensible.
- Adding more hooks is a simple matter of adding more
- plugin methods to <filename>SourcePlugin</filename> and
- derived classes.
- The code that then needs to call the plugin methods uses
- <filename>plugin.get_source_plugin_methods()</filename>
- to find the method or methods needed by the call.
- Retrieval of those methods is accomplished
- by filling up a dict with keys
- containing the method names of interest.
- On success, these will be filled in with the actual
- methods.
- Please see the <filename>wic</filename>
- implementation for examples and details.
- </para>
- </section>
-
- <section id='openembedded-kickstart-wks-reference'>
- <title>OpenEmbedded Kickstart (.wks) Reference</title>
-
- <para>
- The current <filename>wic</filename> implementation supports
- only the basic kickstart partitioning commands:
- <filename>partition</filename> (or <filename>part</filename>
- for short) and <filename>bootloader</filename>.
- <note>
- Future updates will implement more commands and options.
- If you use anything that is not specifically
- supported, results can be unpredictable.
- </note>
- </para>
-
- <para>
- The following is a list of the commands, their syntax,
- and meanings.
- The commands are based on the Fedora
- kickstart versions but with modifications to
- reflect <filename>wic</filename> capabilities.
- You can see the original documentation for those commands
- at the following links:
- <itemizedlist>
- <listitem><para>
- <ulink
url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
- </para></listitem>
- <listitem><para>
- <ulink
url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <section id='command-part-or-partition'>
- <title>Command: part or partition</title>
-
- <para>
- Either of these commands create a partition on the system
- and uses the following syntax:
- <literallayout class='monospaced'>
- part [<replaceable>mntpoint</replaceable>]
- partition [<replaceable>mntpoint</replaceable>]
</literallayout>
- If you do not provide
- <replaceable>mntpoint</replaceable>, wic creates a partition
- but does not mount it.
- </para>
-
- <para>
- The <filename><replaceable>mntpoint</replaceable></filename>
- is where the
- partition will be mounted and must be of one of the
- following forms:
- <itemizedlist>
- <listitem><para><filename>/<replaceable>path</replaceable></filename>:
- For example, <filename>/</filename>,
- <filename>/usr</filename>, or
- <filename>/home</filename></para></listitem>
- <listitem><para><filename>swap</filename>:
- The created partition is used as swap space.
- </para></listitem>
- </itemizedlist>
+ If the subclass itself does not implement a function, a
+ default version in a superclass is located and
+ used, which is why all plug-ins must be derived from
+ <filename>SourcePlugin</filename>.
</para>
<para>
- Specifying a <replaceable>mntpoint</replaceable> causes
- the partition to automatically be mounted.
- Wic achieves this by adding entries to the filesystem
- table (fstab) during image generation.
- In order for wic to generate a valid fstab, you must
- also provide one of the <filename>--ondrive</filename>,
- <filename>--ondisk</filename>, or
- <filename>--use-uuid</filename> partition options as part
- of the command.
- Here is an example using "/" as the mountpoint.
- The command uses "--ondisk" to force the partition onto
- the <filename>sdb</filename> disk:
- <literallayout class='monospaced'>
- part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
- </literallayout>
+ The <filename>SourcePlugin</filename> class defines the
+ following methods, which is the current set of methods
+ that can be implemented or overridden by
+ <filename>--source</filename> plug-ins.
+ Any methods not implemented by a
+ <filename>SourcePlugin</filename> subclass inherit the
+ implementations present in the
+ <filename>SourcePlugin</filename> class.
+ For more information, see the
+ <filename>SourcePlugin</filename> source for details:
</para>
<para>
- Here is a list that describes other supported options you
- can use with the <filename>part</filename> and
- <filename>partition</filename> commands:
<itemizedlist>
- <listitem><para><emphasis><filename>--size</filename>:</emphasis>
- The minimum partition size in MBytes.
- Specify an integer value such as 500.
- Do not append the number with "MB".
- You do not need this option if you use
- <filename>--source</filename>.</para></listitem>
- <listitem><para><emphasis><filename>--source</filename>:</emphasis>
- This option is a
- <filename>wic</filename>-specific option that
- names the source of the data that populates
- the partition.
- The most common value for this option is
- "rootfs", but you can use any value that maps to
- a valid source plugin.
- For information on the source plugins, see the
- "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
- section.</para>
- <para>If you use
- <filename>--source rootfs</filename>,
- <filename>wic</filename> creates a partition as
- large as needed and to fill it with the contents of
- the root filesystem pointed to by the
- <filename>-r</filename> command-line option
- or the equivalent rootfs derived from the
- <filename>-e</filename> command-line
- option.
- The filesystem type used to create the
- partition is driven by the value of the
- <filename>--fstype</filename> option
- specified for the partition.
- See the entry on
- <filename>--fstype</filename> that
- follows for more information.
- </para>
- <para>If you use
- <filename>--source <replaceable>plugin-name</replaceable></filename>,
- <filename>wic</filename> creates a partition as
- large as needed and fills it with the contents of
- the partition that is generated by the
- specified plugin name using the data pointed
- to by the <filename>-r</filename> command-line
- option or the equivalent rootfs derived from the
- <filename>-e</filename> command-line
- option.
- Exactly what those contents and filesystem type end
- up being are dependent on the given plugin
- implementation.
- </para>
- <para>If you do not use the
- <filename>--source</filename> option, the
- <filename>wic</filename> command creates an empty
+ <listitem><para>
+ <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
+ Called to do the actual content population for a
partition.
- Consequently, you must use the
- <filename>--size</filename> option to specify the
- size of the empty partition.
+ In other words, the method prepares the final
+ partition image that is incorporated into the
+ disk image.
</para></listitem>
- <listitem><para><emphasis><filename>--ondisk</filename> or
<filename>--ondrive</filename>:</emphasis>
- Forces the partition to be created on a particular
- disk.</para></listitem>
- <listitem><para><emphasis><filename>--fstype</filename>:</emphasis>
- Sets the file system type for the partition.
- Valid values are:
- <itemizedlist>
- <listitem><para><filename>ext4</filename>
- </para></listitem>
- <listitem><para><filename>ext3</filename>
- </para></listitem>
- <listitem><para><filename>ext2</filename>
- </para></listitem>
- <listitem><para><filename>btrfs</filename>
- </para></listitem>
- <listitem><para><filename>squashfs</filename>
- </para></listitem>
- <listitem><para><filename>swap</filename>
- </para></listitem>
- </itemizedlist></para></listitem>
- <listitem><para><emphasis><filename>--fsoptions</filename>:</emphasis>
- Specifies a free-form string of options to be
- used when mounting the filesystem.
- This string will be copied into the
- <filename>/etc/fstab</filename> file of the
- installed system and should be enclosed in
- quotes.
- If not specified, the default string
- is "defaults".
- </para></listitem>
- <listitem><para><emphasis><filename>--label label</filename>:</emphasis>
- Specifies the label to give to the filesystem to
- be made on the partition.
- If the given label is already in use by another
- filesystem, a new label is created for the
- partition.</para></listitem>
- <listitem><para><emphasis><filename>--active</filename>:</emphasis>
- Marks the partition as active.</para></listitem>
- <listitem><para><emphasis><filename>--align (in KBytes)</filename>:</emphasis>
- This option is a <filename>wic</filename>-specific
- option that says to start a partition on an
- x KBytes boundary.</para></listitem>
- <listitem><para><emphasis><filename>--no-table</filename>:</emphasis>
- This option is a <filename>wic</filename>-specific
- option.
- Using the option reserves space for the partition
- and causes it to become populated.
- However, the partition is not added to the
- partition table.
- </para></listitem>
- <listitem><para><emphasis><filename>--extra-space</filename>:</emphasis>
- This option is a <filename>wic</filename>-specific
- option that adds extra space after the space
- filled by the content of the partition.
- The final size can go beyond the size specified
- by the <filename>--size</filename> option.
- The default value is 10 Mbytes.
- </para></listitem>
- <listitem><para><emphasis><filename>--overhead-factor</filename>:</emphasis>
- This option is a <filename>wic</filename>-specific
- option that multiplies the size of the partition by
- the option's value.
- You must supply a value greater than or equal to
- "1".
- The default value is "1.3".
- </para></listitem>
- <listitem><para><emphasis><filename>--part-type</filename>:</emphasis>
- This option is a <filename>wic</filename>-specific
- option that specifies the partition type globally
- unique identifier (GUID) for GPT partitions.
- You can find the list of partition type GUIDs
- at
- <ulink
url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>.
+ <listitem><para>
+ <emphasis><filename>do_configure_partition()</filename>:</emphasis>
+ Called before
+ <filename>do_prepare_partition()</filename>.
+ This method is typically used to create custom
+ configuration files for a partition (e.g. syslinux
+ or grub configuration files).
</para></listitem>
- <listitem><para><emphasis><filename>--use-uuid</filename>:</emphasis>
- This option is a <filename>wic</filename>-specific
- option that causes <filename>wic</filename> to
- generate a random GUID for the partition.
- The generated identifier is used in the bootloader
- configuration to specify the root partition.
+ <listitem><para>
+ <emphasis><filename>do_install_disk()</filename>:</emphasis>
+ Called after all partitions have been prepared and
+ assembled into a disk image.
+ This method provides a hook to allow finalization
+ of a disk image, (e.g. writing an MBR).
</para></listitem>
- <listitem><para><emphasis><filename>--uuid</filename>:</emphasis>
- This option is a <filename>wic</filename>-specific
- option that specifies the partition UUID.
+ <listitem><para>
+ <emphasis><filename>do_stage_partition()</filename>:</emphasis>
+ Special content-staging hook called before
+ <filename>do_prepare_partition()</filename>.
+ This method is normally empty.</para>
+ <para>Typically, a partition just uses the passed-in
+ parameters (e.g. the unmodified value of
+ <filename>bootimg_dir</filename>).
+ However, in some cases things might need to be
+ more tailored.
+ As an example, certain files might additionally
+ need to be taken from
+ <filename>bootimg_dir + /boot</filename>.
+ This hook allows those files to be staged in a
+ customized fashion.
+ <note>
+ <filename>get_bitbake_var()</filename>
+ allows you to access non-standard variables
+ that you might want to use for this.
+ </note>
</para></listitem>
</itemizedlist>
</para>
+
+ <para>
+ This scheme is extensible.
+ Adding more hooks is a simple matter of adding more
+ plug-in methods to <filename>SourcePlugin</filename> and
+ derived classes.
+ The code that then needs to call the plug-in methods uses
+ <filename>plugin.get_source_plugin_methods()</filename>
+ to find the method or methods needed by the call.
+ Retrieval of those methods is accomplished
+ by filling up a dict with keys
+ containing the method names of interest.
+ On success, these will be filled in with the actual
+ methods.
+ Please see the Wic
+ implementation for examples and details.
+ </para>
</section>
- <section id='command-bootloader'>
- <title>Command: bootloader</title>
+ <section id='openembedded-kickstart-wks-reference'>
+ <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title>
<para>
- This command specifies how the boot loader should be
- configured and supports the following options:
+ The current Wic implementation supports
+ only the basic kickstart partitioning commands:
+ <filename>partition</filename> (or <filename>part</filename>
+ for short) and <filename>bootloader</filename>.
<note>
- Bootloader functionality and boot partitions are
- implemented by the various
- <filename>--source</filename>
- plugins that implement bootloader functionality.
- The bootloader command essentially provides a means of
- modifying bootloader configuration.
+ Future updates will implement more commands and options.
+ If you use anything that is not specifically
+ supported, results can be unpredictable.
</note>
+ </para>
+
+ <para>
+ The following is a list of the commands, their syntax,
+ and meanings.
+ The commands are based on the Fedora
+ kickstart versions but with modifications to
+ reflect Wic capabilities.
+ You can see the original documentation for those commands
+ at the following links:
<itemizedlist>
- <listitem><para><emphasis><filename>--timeout</filename>:</emphasis>
- Specifies the number of seconds before the
- bootloader times out and boots the default option.
- </para></listitem>
- <listitem><para><emphasis><filename>--append</filename>:</emphasis>
- Specifies kernel parameters.
- These parameters will be added to the syslinux
- <filename>APPEND</filename> or
- <filename>grub</filename> kernel command line.
+ <listitem><para>
+ <ulink
url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
</para></listitem>
- <listitem><para><emphasis><filename>--configfile</filename>:</emphasis>
- Specifies a user-defined configuration file for
- the bootloader.
- You can provide a full pathname for the file or
- a file that exists in the
- <filename>canned-wks</filename> folder.
- This option overrides all other bootloader options.
+ <listitem><para>
+ <ulink
url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink>
</para></listitem>
</itemizedlist>
</para>
+
+ <section id='command-part-or-partition'>
+ <title>Command: part or partition</title>
+
+ <para>
+ Either of these commands create a partition on the system
+ and use the following syntax:
+ <literallayout class='monospaced'>
+ part [<replaceable>mntpoint</replaceable>]
+ partition [<replaceable>mntpoint</replaceable>]
+ </literallayout>
+ If you do not provide
+ <replaceable>mntpoint</replaceable>, Wic creates a
+ partition but does not mount it.
+ </para>
+
+ <para>
+ The
+ <filename><replaceable>mntpoint</replaceable></filename>
+ is where the partition will be mounted and must be of
+ one of the following forms:
+ <itemizedlist>
+ <listitem><para>
+ <filename>/<replaceable>path</replaceable></filename>:
+ For example, <filename>/</filename>,
+ <filename>/usr</filename>, or
+ <filename>/home</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>swap</filename>:
+ The created partition is used as swap space.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Specifying a <replaceable>mntpoint</replaceable> causes
+ the partition to automatically be mounted.
+ Wic achieves this by adding entries to the filesystem
+ table (fstab) during image generation.
+ In order for wic to generate a valid fstab, you must
+ also provide one of the <filename>--ondrive</filename>,
+ <filename>--ondisk</filename>, or
+ <filename>--use-uuid</filename> partition options as
+ part of the command.
+ Here is an example using "/" as the mountpoint.
+ The command uses "--ondisk" to force the partition onto
+ the <filename>sdb</filename> disk:
+ <literallayout class='monospaced'>
+ part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
+ </literallayout>
+ </para>
+
+ <para>
+ Here is a list that describes other supported options
+ you can use with the <filename>part</filename> and
+ <filename>partition</filename> commands:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>--size</filename>:</emphasis>
+ The minimum partition size in MBytes.
+ Specify an integer value such as 500.
+ Do not append the number with "MB".
+ You do not need this option if you use
+ <filename>--source</filename>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--source</filename>:</emphasis>
+ This option is a
+ Wic-specific option that
+ names the source of the data that populates
+ the partition.
+ The most common value for this option is
+ "rootfs", but you can use any value that maps to
+ a valid source plug-in.
+ For information on the source plug-ins, see the
+ "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>"
+ section.</para>
+ <para>If you use
+ <filename>--source rootfs</filename>,
+ Wic creates a partition as
+ large as needed and to fill it with the contents
+ of the root filesystem pointed to by the
+ <filename>-r</filename> command-line option
+ or the equivalent rootfs derived from the
+ <filename>-e</filename> command-line
+ option.
+ The filesystem type used to create the
+ partition is driven by the value of the
+ <filename>--fstype</filename> option
+ specified for the partition.
+ See the entry on
+ <filename>--fstype</filename> that
+ follows for more information.
+ </para>
+ <para>If you use
+ <filename>--source <replaceable>plugin-name</replaceable></filename>,
+ Wic creates a partition as
+ large as needed and fills it with the contents
+ of the partition that is generated by the
+ specified plug-in name using the data pointed
+ to by the <filename>-r</filename> command-line
+ option or the equivalent rootfs derived from the
+ <filename>-e</filename> command-line
+ option.
+ Exactly what those contents and filesystem type
+ end up being are dependent on the given plug-in
+ implementation.
+ </para>
+ <para>If you do not use the
+ <filename>--source</filename> option, the
+ <filename>wic</filename> command creates an
+ empty partition.
+ Consequently, you must use the
+ <filename>--size</filename> option to specify
+ the size of the empty partition.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--ondisk</filename> or
<filename>--ondrive</filename>:</emphasis>
+ Forces the partition to be created on a
+ particular disk.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--fstype</filename>:</emphasis>
+ Sets the file system type for the partition.
+ Valid values are:
+ <itemizedlist>
+ <listitem><para><filename>ext4</filename>
+ </para></listitem>
+ <listitem><para><filename>ext3</filename>
+ </para></listitem>
+ <listitem><para><filename>ext2</filename>
+ </para></listitem>
+ <listitem><para><filename>btrfs</filename>
+ </para></listitem>
+ <listitem><para><filename>squashfs</filename>
+ </para></listitem>
+ <listitem><para><filename>swap</filename>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--fsoptions</filename>:</emphasis>
+ Specifies a free-form string of options to be
+ used when mounting the filesystem.
+ This string will be copied into the
+ <filename>/etc/fstab</filename> file of the
+ installed system and should be enclosed in
+ quotes.
+ If not specified, the default string
+ is "defaults".
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--label label</filename>:</emphasis>
+ Specifies the label to give to the filesystem to
+ be made on the partition.
+ If the given label is already in use by another
+ filesystem, a new label is created for the
+ partition.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--active</filename>:</emphasis>
+ Marks the partition as active.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--align (in KBytes)</filename>:</emphasis>
+ This option is a
+ Wic-specific option that
+ says to start a partition on an
+ <replaceable>x</replaceable> KBytes
+ boundary.</para></listitem>
+ <listitem><para>
+ <emphasis><filename>--no-table</filename>:</emphasis>
+ This option is a
+ Wic-specific option.
+ Using the option reserves space for the
+ partition and causes it to become populated.
+ However, the partition is not added to the
+ partition table.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--extra-space</filename>:</emphasis>
+ This option is a
+ Wic-specific option that
+ adds extra space after the space filled by the
+ content of the partition.
+ The final size can go beyond the size specified
+ by the <filename>--size</filename> option.
+ The default value is 10 Mbytes.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--overhead-factor</filename>:</emphasis>
+ This option is a
+ Wic-specific option that
+ multiplies the size of the partition by the
+ option's value.
+ You must supply a value greater than or equal to
+ "1".
+ The default value is "1.3".
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--part-type</filename>:</emphasis>
+ This option is a
+ Wic-specific option that
+ specifies the partition type globally
+ unique identifier (GUID) for GPT partitions.
+ You can find the list of partition type GUIDs
+ at
+ <ulink
url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--use-uuid</filename>:</emphasis>
+ This option is a
+ Wic-specific option that
+ causes Wic to generate a
+ random GUID for the partition.
+ The generated identifier is used in the
+ bootloader configuration to specify the root
+ partition.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--uuid</filename>:</emphasis>
+ This option is a
+ Wic-specific
+ option that specifies the partition UUID.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='command-bootloader'>
+ <title>Command: bootloader</title>
+
+ <para>
+ This command specifies how the bootloader should be
+ configured and supports the following options:
+ <note>
+ Bootloader functionality and boot partitions are
+ implemented by the various
+ <filename>--source</filename>
+ plug-ins that implement bootloader functionality.
+ The bootloader command essentially provides a
+ means of modifying bootloader configuration.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>--timeout</filename>:</emphasis>
+ Specifies the number of seconds before the
+ bootloader times out and boots the default
+ option.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--append</filename>:</emphasis>
+ Specifies kernel parameters.
+ These parameters will be added to the syslinux
+ <filename>APPEND</filename> or
+ <filename>grub</filename> kernel command line.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--configfile</filename>:</emphasis>
+ Specifies a user-defined configuration file for
+ the bootloader.
+ You can provide a full pathname for the file or
+ a file that exists in the
+ <filename>canned-wks</filename> folder.
+ This option overrides all other bootloader
+ options.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
</section>
</section>
</section>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
