diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 2c95ecbc99..d48724c82c 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3984,7 +3984,7 @@
-'
+
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,
- wic, to create the properly partitioned image.
+ Wic, to create the properly partitioned image.
- The wic command generates partitioned images
- from existing OpenEmbedded build artifacts.
- Image generation is driven by partitioning commands contained
- in an Openembedded kickstart file (.wks)
- specified either directly on the command line or as one of a
- selection of canned .wks files as shown
- with the wic list images command in the
- "Using an Existing Kickstart File"
- section.
- When applied to a given set of build artifacts, the result is an
- image or set of images that can be directly written onto media and
- used on a particular system.
+ You can generate Wic-partitioned images
+ (image.wic)
+ 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.
-
- The wic 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
- "Plug-ins"
- section for information on these plug-ins.
-
-
-
- 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
- wic, and provides several examples.
-
-
-
- Background
+
+ Creating Wic-Partitioned Images
- This section provides some background on the
- wic utility.
- While none of this information is required to use
- wic, 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.
- 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.
+ Include "wic" as part of the
+ IMAGE_FSTYPES
+ variable.
+
- wic is loosely based on the
- Meego Image Creator (mic)
- 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.
-
- wic 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
- image-live
- class and mkefidisk.sh 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.
+ Include the name of the
+ wic kickstart file
+ as part of the
+ WKS_FILE
+ variable
+
+ Further steps to generate a Wic-partitioned image
+ are the same as for any other image type.
+ For information on image types, see the
+ "Building Images"
+ section.
-
- Requirements
+
+ Using OpenEmbedded Image Creator Wic to Generate Partitioned Images
- In order to use the wic utility
- with the OpenEmbedded Build system, your system needs
- to meet the following requirements:
-
- The Linux distribution on your
- development host must support the Yocto Project.
- See the
- "Supported Linux Distributions"
- section in the Yocto Project Reference Manual for this
- list of distributions.
-
- The standard system utilities, such as
- cp, must be installed on your
- development host system.
-
-
- 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.
- core-image-minimal).
- 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.
-
-
- You must build several native tools, which are tools
- built to run on the build system:
-
+ The wic command generates partitioned
+ images from existing OpenEmbedded build artifacts.
+ Image generation is driven by partitioning commands
+ contained in an Openembedded kickstart file
+ (.wks) specified either directly on
+ the command line or as one of a selection of canned
+ .wks files as shown with the
+ wic list images command in the
+ "Using an Existing Kickstart File"
+ 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.
+
+
+
+ The wic 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
+ "Plug-ins"
+ section for information on these plug-ins.
+
+
+
+ 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 wic utility,
+ and provides several examples.
+
+
+
+ Background
+
+
+ This section provides some background on the
+ wic utility.
+ While none of this information is required to use
+ Wic, you might find it interesting.
+
+
+ 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.
+
+
+ Wic is loosely based on the
+ Meego Image Creator (mic)
+ 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.
+
+
+ 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
+ image-live
+ class and mkefidisk.sh 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.
+
+
+
+
+
+ Requirements
+
+
+ In order to use the wic utility
+ with the OpenEmbedded Build system, your system needs
+ to meet the following requirements:
+
+ The Linux distribution on your
+ development host must support the Yocto Project.
+ See the
+ "Supported Linux Distributions"
+ section in the Yocto Project Reference Manual for
+ the list of distributions that support the
+ Yocto Project.
+
+
+ The standard system utilities, such as
+ cp, must be installed on your
+ development host system.
+
+
+ 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.
+ core-image-minimal).
+ 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.
+
+
+ You must build several native tools, which are tools
+ built to run on the build system:
+
$ bitbake parted-native dosfstools-native mtools-native
-
-
-
- You must have sourced one of the build environment
- setup scripts (i.e.
- &OE_INIT_FILE;
- or
- oe-init-build-env-memres)
- found in the
- Build Directory.
-
-
-
-
+
+
+
+ You must have sourced one of the build environment
+ setup scripts (i.e.
+ &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres)
+ found in the
+ Build Directory.
+
+
+
+
-
- Getting Help
+
+ Getting Help
-
- You can get general help for the wic
- by entering the wic command by itself
- or by entering the command with a help argument as follows:
-
+
+ You can get general help for the wic
+ command by entering the wic command
+ by itself or by entering the command with a help argument
+ as follows:
+
$ wic -h
$ wic --help
-
-
-
-
- Currently, wic supports two commands:
- create and list.
- You can get help for these commands as follows:
-
- $ wic help command
-
-
-
-
- You can also get detailed help on a number of topics
- from the help system.
- The output of wic --help
- 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
- wic help:
-
- $ wic help help_topic
-
-
-
-
- You can find out more about the images
- wic creates using the existing
- kickstart files with the following form of the command:
-
- $ wic list image help
-
- where image is either
- directdisk or
- mkefidisk.
-
-
-
-
- Operational Modes
-
-
- 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:
-
- Raw Mode:
- You explicitly specify build artifacts through
- command-line arguments.
- Cooked Mode:
- The current
- MACHINE
- setting and image name are used to automatically locate
- and provide the build artifacts.
-
-
-
-
- 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
- &OE_INIT_FILE;
- or
- oe-init-build-env-memres
- script found in the
- Build Directory.
-
-
-
- Raw Mode
+
+
- The general form of the 'wic' command in raw mode is:
+ Currently, Wic supports two commands:
+ create and list.
+ You can get help for these commands as follows:
+ $ wic help command
+ with command being either
+ create or list.
+
+
+
+
+ You can also get detailed help on a number of topics
+ from the help system.
+ The output of wic --help
+ 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
+ wic help:
+
+ $ wic help help_topic
+
+
+
+
+ You can find out more about the images
+ Wic creates using the existing
+ kickstart files with the following form of the command:
+
+ $ wic list image help
+
+ with image
+ being either directdisk or
+ mkefidisk.
+
+
+
+
+ Operational Modes
+
+
+ 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:
+
+
+ Raw Mode:
+ You explicitly specify build artifacts through
+ command-line arguments.
+
+
+ Cooked Mode:
+ The current
+ MACHINE
+ setting and image name are used to automatically
+ locate and provide the build artifacts.
+
+
+
+
+
+ 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
+ &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres
+ script found in the
+ Build Directory.
+
+
+
+ Raw Mode
+
+
+ The general form of the
+ wic command in raw mode is:
+
$ wic create image_name.wks [options] [...]
- Where:
+ Where:
- image_name.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.
+ image_name.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 OUTDIR, --outdir=OUTDIR
- The name of a directory in which to create image.
+ -o OUTDIR, --outdir=OUTDIR
+ The name of a directory in which to create image.
- -i PROPERTIES_FILE, --infile=PROPERTIES_FILE
- The name of a file containing the values for image
- properties as a JSON file.
+ -i PROPERTIES_FILE, --infile=PROPERTIES_FILE
+ The name of a file containing the values for image
+ properties as a JSON file.
- -e IMAGE_NAME, --image-name=IMAGE_NAME
- The name of the image from which to use the artifacts
- (e.g. core-image-sato).
+ -e IMAGE_NAME, --image-name=IMAGE_NAME
+ The name of the image from which to use the artifacts
+ (e.g. core-image-sato).
- -r ROOTFS_DIR, --rootfs-dir=ROOTFS_DIR
- The path to the /rootfs directory to use as the
- .wks rootfs source.
+ -r ROOTFS_DIR, --rootfs-dir=ROOTFS_DIR
+ The path to the /rootfs directory to use as the
+ .wks rootfs source.
- -b BOOTIMG_DIR, --bootimg-dir=BOOTIMG_DIR
- The path to the directory containing the boot artifacts
- (e.g. /EFI or /syslinux) to use as the .wks bootimg
- source.
+ -b BOOTIMG_DIR, --bootimg-dir=BOOTIMG_DIR
+ The path to the directory containing the boot artifacts
+ (e.g. /EFI or /syslinux) to use as the .wks bootimg
+ source.
- -k KERNEL_DIR, --kernel-dir=KERNEL_DIR
- The path to the directory containing the kernel to use
- in the .wks boot image.
+ -k KERNEL_DIR, --kernel-dir=KERNEL_DIR
+ The path to the directory containing the kernel to use
+ in the .wks boot image.
- -n NATIVE_SYSROOT, --native-sysroot=NATIVE_SYSROOT
- The path to the native sysroot containing the tools to use
- to build the image.
+ -n NATIVE_SYSROOT, --native-sysroot=NATIVE_SYSROOT
+ 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.
-
-
- You do not need root privileges to run
- wic.
- In fact, you should not run as root when using the
- utility.
-
-
-
+ -D, --debug
+ Output debug information.
+
+
+ You do not need root privileges to run
+ Wic.
+ In fact, you should not run as root when using the
+ utility.
+
+
+
-
- Cooked Mode
+
+ Cooked Mode
-
- The general form of the wic command
- using Cooked Mode is:
-
+
+ The general form of the wic command
+ using Cooked Mode is:
+
$ wic create kickstart_file -e image_name
- Where:
+ Where:
- kickstart_file
- An OpenEmbedded kickstart file. You can provide your own
- custom file or supplied file.
+ kickstart_file
+ An OpenEmbedded kickstart file. You can provide your own
+ custom file or a supplied file.
- image_name
- Specifies the image built using the OpenEmbedded build
- system.
-
- 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
- .wks file or one provided with the
- release.
-
+ image_name
+ Specifies the image built using the OpenEmbedded build
+ system.
+
+ 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
+ .wks file or one provided with the
+ release.
+
+
-
-
- Using an Existing Kickstart File
+
+ Using an Existing Kickstart File
-
- If you do not want to create your own
- .wks file, you can use an existing
- file provided by the wic installation.
- Use the following command to list the available files:
-
+
+ If you do not want to create your own
+ .wks file, you can use an existing
+ file provided by the Wic installation.
+ Use the following command to list the available files:
+
$ wic list images
directdisk Create a 'pcbios' direct disk image
mkefidisk Create an EFI disk image
-
- When you use an existing file, you do not have to use the
- .wks extension.
- Here is an example in Raw Mode that uses the
- directdisk file:
-
+
+ When you use an existing file, you do not have to use the
+ .wks extension.
+ Here is an example in Raw Mode that uses the
+ directdisk file:
+
$ wic create directdisk -r rootfs_dir -b bootimg_dir \
-k kernel_dir -n native_sysroot
-
-
+
+
-
- Here are the actual partition language commands
- used in the mkefidisk.wks file to generate
- an image:
-
+
+ Here are the actual partition language commands
+ used in the mkefidisk.wks file to
+ generate an image:
+
# 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"
-
-
-
+
+
+
-
- Examples
-
-
- This section provides several examples that show how to use
- the wic utility.
- All the examples assume the list of requirements in the
- "Requirements" section
- have been met.
- The examples assume the previously generated image is
- core-image-minimal.
-
-
-
- Generate an Image using an Existing Kickstart File
+
+ Examples
- This example runs in Cooked Mode and uses the
- mkefidisk kickstart file:
-
+ This section provides several examples that show how to use
+ the wic utility.
+ All the examples assume the list of requirements in the
+ "Requirements"
+ section have been met.
+ The examples assume the previously generated image is
+ core-image-minimal.
+
+
+
+ Generate an Image using an Existing Kickstart File
+
+
+ This example runs in Cooked Mode and uses the
+ mkefidisk kickstart file:
+
$ 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
-
- This example shows the easiest way to create an image
- by running in Cooked Mode and using the
- -e option with an existing kickstart
- file.
- All that is necessary is to specify the image used to
- generate the artifacts.
- Your local.conf needs to have the
- MACHINE
- variable set to the machine you are using, which is
- "minnow" in this example.
-
+
+ The previous example shows the easiest way to create
+ an image by running in Cooked Mode and using the
+ -e option with an existing
+ kickstart file.
+ All that is necessary is to specify the image used to
+ generate the artifacts.
+ Your local.conf needs to have the
+ MACHINE
+ variable set to the machine you are using, which is
+ "minnow" in this example.
+
-
- The output specifies the exact image created as well as
- where it was created.
- The output also names the artifacts used and the exact
- .wks script that was used to generate
- the image.
-
- You should always verify the details provided in the
- output to make sure that the image was indeed created
- exactly as expected.
-
-
+
+ The output specifies the exact image created as well as
+ where it was created.
+ The output also names the artifacts used and the exact
+ .wks script that was used to
+ generate the image.
+
+ You should always verify the details provided in the
+ output to make sure that the image was indeed
+ created exactly as expected.
+
+
-
- Continuing with the example, you can now directly
- dd the image to a USB stick, or
- whatever media for which you built your image,
- and boot the resulting media:
-
+
+ Continuing with the example, you can now directly
+ dd the image to a USB stick, or
+ whatever media for which you built your image,
+ and boot the resulting media:
+
$ 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
-
-
-
+ [trz at empanada ~]$ sudo eject /dev/sdb
+
+
+
-
- Using a Modified Kickstart File
+
+ Using a Modified Kickstart File
-
- Because wic 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 directdisk kickstart file.
-
+
+ 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 directdisk kickstart file.
+
-
- As mentioned earlier, you can use the command
- wic list images to show the list
- of existing kickstart files.
- The directory in which these files reside is
- scripts/lib/image/canned-wks/
- located in the
- Source Directory.
- Because the available files reside in this directory, you
- can create and add your own custom files to the directory.
- Subsequent use of the wic list images
- command would then include your kickstart files.
-
+
+ As mentioned earlier, you can use the command
+ wic list images to show the list
+ of existing kickstart files.
+ The directory in which these files reside is
+ scripts/lib/image/canned-wks/
+ located in the
+ Source Directory.
+ Because the available files reside in this directory,
+ you can create and add your own custom files to the
+ directory.
+ Subsequent use of the
+ wic list images command would then
+ include your kickstart files.
+
-
- In this example, the existing
- directdisk file already does most
- of what is needed.
- However, for the hardware in this example, the image will
- need to boot from sdb instead of
- sda, which is what the
- directdisk kickstart file uses.
-
+
+ In this example, the existing
+ directdisk file already does most
+ of what is needed.
+ However, for the hardware in this example, the image
+ will need to boot from sdb instead
+ of sda, which is what the
+ directdisk kickstart file uses.
+
-
- The example begins by making a copy of the
- directdisk.wks file in the
- scripts/lib/image/canned-wks
- directory and then changing the lines that specify the
- target disk from which to boot.
-
+
+ The example begins by making a copy of the
+ directdisk.wks file in the
+ scripts/lib/image/canned-wks
+ directory and then by changing the lines that specify
+ the target disk from which to boot.
+
$ 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
-
- Next, the example modifies the
- directdisksdb.wks file and changes all
- instances of "--ondisk sda"
- to "--ondisk sdb".
- The example changes the following two lines and leaves the
- remaining lines untouched:
-
+
+ Next, the example modifies the
+ directdisksdb.wks file and changes
+ all instances of "--ondisk sda"
+ to "--ondisk sdb".
+ The example changes the following two lines and leaves
+ the remaining lines untouched:
+
part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
-
- Once the lines are changed, the example generates the
- directdisksdb image.
- The command points the process at the
- core-image-minimal artifacts for the
- Next Unit of Computing (nuc)
- MACHINE
- the local.conf.
-
+
+ Once the lines are changed, the example generates the
+ directdisksdb image.
+ The command points the process at the
+ core-image-minimal artifacts for
+ the Next Unit of Computing (nuc)
+ MACHINE
+ the local.conf.
+
$ 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
-
- Continuing with the example, you can now directly
- dd the image to a USB stick, or
- whatever media for which you built your image,
- and boot the resulting media:
-
+
+ Continuing with the example, you can now directly
+ dd the image to a USB stick, or
+ whatever media for which you built your image,
+ and boot the resulting media:
+
$ 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
-
-
-
+ [trz at empanada tmp]$ sudo eject /dev/sdb
+
+
+
-
- Creating an Image Based on core-image-minimal and crownbay-noemgd
+
+ Creating an Image Based on core-image-minimal and crownbay-noemgd
-
- This example creates an image based on
- core-image-minimal and a
- crownbay-noemgd
- MACHINE
- that works right out of the box.
-
+
+ This example creates an image based on
+ core-image-minimal and a
+ crownbay-noemgd
+ MACHINE
+ that works right out of the box.
+
$ 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
-
-
-
+
+
+
-
- Using a Modified Kickstart File and Running in Raw Mode
+
+ Using a Modified Kickstart File and Running in Raw Mode
-
- This next example manually specifies each build artifact
- (runs in Raw Mode) and uses a modified kickstart file.
- The example also uses the -o option
- to cause wic to create the output
- somewhere other than the default
- /var/tmp/wic directory:
-
+
+ This next example manually specifies each build artifact
+ (runs in Raw Mode) and uses a modified kickstart file.
+ The example also uses the -o option
+ to cause Wic to create the output
+ somewhere other than the default
+ /var/tmp/wic directory:
+
$ 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
-
- For this example,
- MACHINE
- did not have to be specified in the
- local.conf file since the artifact is
- manually specified.
-
+
+ For this example,
+ MACHINE
+ did not have to be specified in the
+ local.conf file since the
+ artifact is manually specified.
+
+
-
-
- Plug-ins
+
+ Plug-ins
-
- Plug-ins allow wic functionality to
- be extended and specialized by users.
- This section documents the plugin interface, which is
- currently restricted to source plug ins.
-
+
+ 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.
+
-
- 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 .wks files using the
- --source keyword to a
- particular plugin implementation that populates a
- corresponding partition.
-
+
+ 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 .wks files using the
+ --source keyword to a
+ particular plug-in implementation that populates a
+ corresponding partition.
+
-
- A source plugin is created as a subclass of
- SourcePlugin.
- The plugin file containing it is added to
- scripts/lib/wic/plugins/source/ to
- make the plugin implementation available to the
- wic implementation.
- For more information, see
- scripts/lib/wic/pluginbase.py.
-
+
+ A source plug-in is created as a subclass of
+ SourcePlugin.
+ The plug-in file containing it is added to
+ scripts/lib/wic/plugins/source/ to
+ make the plug-in implementation available to the
+ Wic implementation.
+ For more information, see
+ scripts/lib/wic/pluginbase.py.
+
-
- Source plugins can also be implemented and added by
- external layers.
- As such, any plugins found in a
- scripts/lib/wic/plugins/source/
- directory in an external layer are also made
- available.
-
+
+ Source plug-ins can also be implemented and added by
+ external layers.
+ As such, any plug-ins found in a
+ scripts/lib/wic/plugins/source/
+ directory in an external layer are also made
+ available.
+
-
- When the wic implementation needs
- to invoke a partition-specific implementation, it looks
- for the plugin that has the same name as the
- --source parameter given to
- that partition.
- For example, if the partition is set up as follows:
-
+
+ When the Wic implementation needs
+ to invoke a partition-specific implementation, it looks
+ for the plug-in that has the same name as the
+ --source parameter given to
+ that partition.
+ For example, if the partition is set up as follows:
+
part /boot --source bootimg-pcbios ...
-
- The methods defined as class members of the plugin
- having the matching bootimg-pcbios.name
- class member are used.
-
+
+ The methods defined as class members of the plug-in
+ having the matching bootimg-pcbios.name
+ class member are used.
+
-
- To be more concrete, here is the plugin definition that
- matches a
- --source bootimg-pcbios usage,
- along with an example
- method called by the wic implementation
- when it needs to invoke an implementation-specific
- partition-preparation function:
-
+
+ To be more concrete, here is the plug-in definition that
+ matches a
+ --source bootimg-pcbios usage,
+ along with an example
+ method called by the Wic implementation
+ when it needs to invoke an implementation-specific
+ partition-preparation function:
+
class BootimgPcbiosPlugin(SourcePlugin):
name = 'bootimg-pcbios'
@classmethod
def do_prepare_partition(self, part, ...)
-
- 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
- SourcePlugin.
-
-
-
- The SourcePlugin class defines the
- following methods, which is the current set of methods
- that can be implemented or overridden by
- --source plugins.
- Any methods not implemented by a
- SourcePlugin subclass inherit the
- implementations present in the
- SourcePlugin class.
- For more information, see the
- SourcePlugin source for details:
-
-
-
-
- do_prepare_partition():
- 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.
-
- do_configure_partition():
- Called before
- do_prepare_partition().
- This method is typically used to create custom
- configuration files for a partition (e.g. syslinux or
- grub configuration files).
-
- do_install_disk():
- 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).
-
- do_stage_partition():
- Special content-staging hook called before
- do_prepare_partition().
- This method is normally empty.
- Typically, a partition just uses the passed-in
- parameters (e.g. the unmodified value of
- bootimg_dir).
- However, in some cases things might need to be
- more tailored.
- As an example, certain files might additionally
- need to be taken from
- bootimg_dir + /boot.
- This hook allows those files to be staged in a
- customized fashion.
-
- get_bitbake_var()
- allows you to access non-standard variables
- that you might want to use for this.
-
-
-
-
-
-
- This scheme is extensible.
- Adding more hooks is a simple matter of adding more
- plugin methods to SourcePlugin and
- derived classes.
- The code that then needs to call the plugin methods uses
- plugin.get_source_plugin_methods()
- 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.
-
-
-
-
- OpenEmbedded Kickstart (.wks) Reference
-
-
- The current wic implementation supports
- only the basic kickstart partitioning commands:
- partition (or part
- for short) and bootloader.
-
- Future updates will implement more commands and options.
- If you use anything that is not specifically
- supported, results can be unpredictable.
-
-
-
-
- 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:
-
-
- http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
-
-
- http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader
-
-
-
-
-
- Command: part or partition
-
-
- Either of these commands create a partition on the system
- and uses the following syntax:
-
- part [mntpoint]
- partition [mntpoint]
- If you do not provide
- mntpoint, wic creates a partition
- but does not mount it.
+ 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
+ SourcePlugin.
+
+
+
+ The SourcePlugin class defines the
+ following methods, which is the current set of methods
+ that can be implemented or overridden by
+ --source plug-ins.
+ Any methods not implemented by a
+ SourcePlugin subclass inherit the
+ implementations present in the
+ SourcePlugin class.
+ For more information, see the
+ SourcePlugin source for details:
- The mntpoint
- is where the
- partition will be mounted and must be of one of the
- following forms:
- /path:
- For example, /,
- /usr, or
- /home
- swap:
- The created partition is used as swap space.
-
-
-
-
-
- Specifying a mntpoint 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 --ondrive,
- --ondisk, or
- --use-uuid 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 sdb disk:
-
- part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
-
-
-
-
- Here is a list that describes other supported options you
- can use with the part and
- partition commands:
-
- --size:
- 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
- --source.
- --source:
- 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 plugin.
- For information on the source plugins, see the
- "Plugins"
- section.
- If you use
- --source rootfs,
- wic creates a partition as
- large as needed and to fill it with the contents of
- the root filesystem pointed to by the
- -r command-line option
- or the equivalent rootfs derived from the
- -e command-line
- option.
- The filesystem type used to create the
- partition is driven by the value of the
- --fstype option
- specified for the partition.
- See the entry on
- --fstype that
- follows for more information.
-
- If you use
- --source plugin-name,
- wic 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 -r command-line
- option or the equivalent rootfs derived from the
- -e command-line
- option.
- Exactly what those contents and filesystem type end
- up being are dependent on the given plugin
- implementation.
-
- If you do not use the
- --source option, the
- wic command creates an empty
+
+ do_prepare_partition():
+ Called to do the actual content population for a
partition.
- Consequently, you must use the
- --size 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.
- --ondisk or --ondrive:
- Forces the partition to be created on a particular
- disk.
- --fstype:
- Sets the file system type for the partition.
- Valid values are:
-
- ext4
-
- ext3
-
- ext2
-
- btrfs
-
- squashfs
-
- swap
-
-
- --fsoptions:
- Specifies a free-form string of options to be
- used when mounting the filesystem.
- This string will be copied into the
- /etc/fstab file of the
- installed system and should be enclosed in
- quotes.
- If not specified, the default string
- is "defaults".
+
+ do_configure_partition():
+ Called before
+ do_prepare_partition().
+ This method is typically used to create custom
+ configuration files for a partition (e.g. syslinux
+ or grub configuration files).
- --label label:
- 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.
- --active:
- Marks the partition as active.
- --align (in KBytes):
- This option is a wic-specific
- option that says to start a partition on an
- x KBytes boundary.
- --no-table:
- 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.
+
+ do_install_disk():
+ 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).
- --extra-space:
- 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 --size option.
- The default value is 10 Mbytes.
-
- --overhead-factor:
- 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".
-
- --part-type:
- 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
- .
-
- --use-uuid:
- 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.
-
- --uuid:
- This option is a wic-specific
- option that specifies the partition UUID.
+
+ do_stage_partition():
+ Special content-staging hook called before
+ do_prepare_partition().
+ This method is normally empty.
+ Typically, a partition just uses the passed-in
+ parameters (e.g. the unmodified value of
+ bootimg_dir).
+ However, in some cases things might need to be
+ more tailored.
+ As an example, certain files might additionally
+ need to be taken from
+ bootimg_dir + /boot.
+ This hook allows those files to be staged in a
+ customized fashion.
+
+ get_bitbake_var()
+ allows you to access non-standard variables
+ that you might want to use for this.
+
+
+
+ This scheme is extensible.
+ Adding more hooks is a simple matter of adding more
+ plug-in methods to SourcePlugin and
+ derived classes.
+ The code that then needs to call the plug-in methods uses
+ plugin.get_source_plugin_methods()
+ 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.
+
-
- Command: bootloader
+
+ OpenEmbedded Kickstart (.wks) Reference
- 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:
+ partition (or part
+ for short) and bootloader.
- Bootloader functionality and boot partitions are
- implemented by the various
- --source
- 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.
+
+
+
+ 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:
- --timeout:
- Specifies the number of seconds before the
- bootloader times out and boots the default option.
+
+ http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
- --append:
- Specifies kernel parameters.
- These parameters will be added to the syslinux
- APPEND or
- grub kernel command line.
-
- --configfile:
- 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
- canned-wks folder.
- This option overrides all other bootloader options.
+
+ http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader
+
+
+ Command: part or partition
+
+
+ Either of these commands create a partition on the system
+ and use the following syntax:
+
+ part [mntpoint]
+ partition [mntpoint]
+
+ If you do not provide
+ mntpoint, Wic creates a
+ partition but does not mount it.
+
+
+
+ The
+ mntpoint
+ is where the partition will be mounted and must be of
+ one of the following forms:
+
+
+ /path:
+ For example, /,
+ /usr, or
+ /home
+
+
+ swap:
+ The created partition is used as swap space.
+
+
+
+
+
+ Specifying a mntpoint 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 --ondrive,
+ --ondisk, or
+ --use-uuid 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 sdb disk:
+
+ part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
+
+
+
+
+ Here is a list that describes other supported options
+ you can use with the part and
+ partition commands:
+
+
+ --size:
+ 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
+ --source.
+
+
+ --source:
+ 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
+ "Plug-ins"
+ section.
+ If you use
+ --source rootfs,
+ Wic creates a partition as
+ large as needed and to fill it with the contents
+ of the root filesystem pointed to by the
+ -r command-line option
+ or the equivalent rootfs derived from the
+ -e command-line
+ option.
+ The filesystem type used to create the
+ partition is driven by the value of the
+ --fstype option
+ specified for the partition.
+ See the entry on
+ --fstype that
+ follows for more information.
+
+ If you use
+ --source plugin-name,
+ 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 -r command-line
+ option or the equivalent rootfs derived from the
+ -e command-line
+ option.
+ Exactly what those contents and filesystem type
+ end up being are dependent on the given plug-in
+ implementation.
+
+ If you do not use the
+ --source option, the
+ wic command creates an
+ empty partition.
+ Consequently, you must use the
+ --size option to specify
+ the size of the empty partition.
+
+
+ --ondisk or --ondrive:
+ Forces the partition to be created on a
+ particular disk.
+
+
+ --fstype:
+ Sets the file system type for the partition.
+ Valid values are:
+
+ ext4
+
+ ext3
+
+ ext2
+
+ btrfs
+
+ squashfs
+
+ swap
+
+
+
+
+ --fsoptions:
+ Specifies a free-form string of options to be
+ used when mounting the filesystem.
+ This string will be copied into the
+ /etc/fstab file of the
+ installed system and should be enclosed in
+ quotes.
+ If not specified, the default string
+ is "defaults".
+
+
+ --label label:
+ 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.
+
+
+ --active:
+ Marks the partition as active.
+
+
+ --align (in KBytes):
+ This option is a
+ Wic-specific option that
+ says to start a partition on an
+ x KBytes
+ boundary.
+
+ --no-table:
+ 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.
+
+
+ --extra-space:
+ 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 --size option.
+ The default value is 10 Mbytes.
+
+
+ --overhead-factor:
+ 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".
+
+
+ --part-type:
+ 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
+ .
+
+
+ --use-uuid:
+ 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.
+
+
+ --uuid:
+ This option is a
+ Wic-specific
+ option that specifies the partition UUID.
+
+
+
+
+
+
+ Command: bootloader
+
+
+ This command specifies how the bootloader should be
+ configured and supports the following options:
+
+ Bootloader functionality and boot partitions are
+ implemented by the various
+ --source
+ plug-ins that implement bootloader functionality.
+ The bootloader command essentially provides a
+ means of modifying bootloader configuration.
+
+
+
+ --timeout:
+ Specifies the number of seconds before the
+ bootloader times out and boots the default
+ option.
+
+
+ --append:
+ Specifies kernel parameters.
+ These parameters will be added to the syslinux
+ APPEND or
+ grub kernel command line.
+
+
+ --configfile:
+ 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
+ canned-wks folder.
+ This option overrides all other bootloader
+ options.
+
+
+
+