diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index a5fe63ac9d..3f4c2802ce 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4796,23 +4796,137 @@
- You can generate 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 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
+ kickstart 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.
+
+ For a kickstart file reference, see the
+ "OpenEmbedded Kickstart (.wks) Reference"
+ section.
+
-
- Creating Partitioned Images
+
+ 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
+ "Wic Plug-Ins Interface"
+ section in the Yocto Project Reference Manual 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
- The OpenEmbedded build system can generate
- partitioned images the same way as it generates
- any other image type.
- To generate a partitioned image, you need to modify
- two variables.
+ 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 an
+ 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 must have sourced the build environment
+ setup script (i.e.
+ &OE_INIT_FILE;)
+ found in the
+ Build Directory.
+
+
+ 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 OpenEmbedded build
+ system.
+
+
+ You must build several native tools, which are
+ built to run on the build system:
+
+ $ bitbake parted-native dosfstools-native mtools-native
+
+
Include "wic" as part of the
IMAGE_FSTYPES
@@ -4826,198 +4940,61 @@
variable
- Further steps to generate a partitioned image
- are the same as for any other image type.
- For information on image types, see the
- "Images"
- section in the Yocto Project Reference Manual.
-
- Using OpenEmbedded Image Creator Wic to Generate Partitioned Images
+
+ Getting Help
- 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
- kickstart 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 an
- 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 must have sourced the build environment
- setup script (i.e.
- &OE_INIT_FILE;)
- found in the
- Build Directory.
-
-
- 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 OpenEmbedded build
- system.
-
-
- You must build several native tools, which are
- built to run on the build system:
-
- $ bitbake parted-native dosfstools-native mtools-native
-
-
-
-
-
-
-
- Getting Help
-
-
- 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:
-
+ 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 seven commands:
- cp, create,
- help, list,
- ls, rm, and
- write.
- You can get help for these commands as follows with
- command being one of the
- supported commands:
-
+
+ Currently, Wic supports seven commands:
+ cp, create,
+ help, list,
+ ls, rm, and
+ write.
+ You can get help for these commands as follows with
+ command being one of the
+ supported commands:
+
$ 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:
-
+
+ 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:
-
+
+ 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
-
- For image, you can provide
- any of the following:
-
+
+ For image, you can provide
+ any of the following:
+
beaglebone
mpc8315e-rdb
genericx86
@@ -5031,62 +5008,62 @@
sdimage-bootpart
directdisk-multi-rootfs
directdisk-bootloader-config
-
-
-
+
+
+
-
- Operational Modes
+
+ 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
+ wic command-line arguments.
+
+
+ Cooked Mode:
+ The current
+ MACHINE
+ setting and image name are used to automatically
+ locate and provide the build artifacts.
+ You just supply a kickstart file and the name
+ of the image from which to use artifacts.
+
+
+
+
+
+ Regardless of the mode you use, you need to have the build
+ artifacts ready and available.
+
+
+
+ Raw Mode
- 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
- wic command-line arguments.
-
-
- Cooked Mode:
- The current
- MACHINE
- setting and image name are used to automatically
- locate and provide the build artifacts.
- You just supply a kickstart file and the name
- of the image from which to use artifacts.
-
-
+ Running Wic in raw mode allows you to specify all the
+ partitions through the wic
+ command line.
+ The primary use for raw mode is if you have built
+ your kernel outside of the Yocto Project
+ Build Directory.
+ In other words, you can point to arbitrary kernel,
+ root filesystem locations, and so forth.
+ Contrast this behavior with cooked mode where Wic
+ looks in the Build Directory (e.g.
+ tmp/deploy/images/machine).
- Regardless of the mode you use, you need to have the build
- artifacts ready and available.
-
-
-
- Raw Mode
-
-
- Running Wic in raw mode allows you to specify all the
- partitions through the wic
- command line.
- The primary use for raw mode is if you have built
- your kernel outside of the Yocto Project
- Build Directory.
- In other words, you can point to arbitrary kernel,
- root filesystem locations, and so forth.
- Contrast this behavior with cooked mode where Wic
- looks in the Build Directory (e.g.
- tmp/deploy/images/machine).
-
-
-
- The general form of the
- wic command in raw mode is:
-
+ The general form of the
+ wic command in raw mode is:
+
$ wic create wks_fileoptions ...
Where:
@@ -5127,36 +5104,36 @@
directory with <image>.env files that store bitbake
variables
-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.
-
-
-
+
+
+ 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
-
- Running Wic in cooked mode leverages off artifacts in
- Build Directory.
- In other words, you do not have to specify kernel or
- root filesystem locations as part of the command.
- All you need to provide is a kickstart file and the
- name of the image from which to use artifacts by using
- the "-e" option.
- Wic looks in the Build Directory (e.g.
- tmp/deploy/images/machine)
- for artifacts.
-
+
+ Running Wic in cooked mode leverages off artifacts in
+ Build Directory.
+ In other words, you do not have to specify kernel or
+ root filesystem locations as part of the command.
+ All you need to provide is a kickstart file and the
+ name of the image from which to use artifacts by using
+ the "-e" option.
+ Wic looks in the Build Directory (e.g.
+ tmp/deploy/images/machine)
+ for artifacts.
+
-
- The general form of the wic
- command using Cooked Mode is as follows:
-
+
+ The general form of the wic
+ command using Cooked Mode is as follows:
+
$ wic create wks_file -e IMAGE_NAME
Where:
@@ -5171,28 +5148,28 @@
-e IMAGE_NAME, --image-name IMAGE_NAME
name of the image to use the artifacts from e.g. core-
image-sato
-
-
-
+
+
+
-
- Using an Existing Kickstart File
+
+ Using an Existing Kickstart File
-
- If you do not want to create your own kickstart file, you
- can use an existing file provided by the Wic installation.
- As shipped, kickstart files can be found in the
- Yocto Project
- Source Repositories
- in the following two locations:
-
+
+ If you do not want to create your own kickstart file, you
+ can use an existing file provided by the Wic installation.
+ As shipped, kickstart files can be found in the
+ Yocto Project
+ Source Repositories
+ in the following two locations:
+
poky/meta-yocto-bsp/wic
poky/scripts/lib/wic/canned-wks
-
- Use the following command to list the available kickstart
- files:
-
+
+ Use the following command to list the available kickstart
+ files:
+
$ wic list images
beaglebone Create SD card image for Beaglebone
mpc8315e-rdb Create SD card image for MPC8315E-RDB
@@ -5207,22 +5184,22 @@
sdimage-bootpart Create SD card image with a boot partition
directdisk-multi-rootfs Create multi rootfs image using rootfs plugin
directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config
-
- 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 genericx86.wks file to
- generate an image:
-
+
+ Here are the actual partition language commands
+ used in the genericx86.wks file to
+ generate an image:
+
# short-description: Create an EFI disk image for genericx86*
# long-description: Creates a partitioned EFI disk image for genericx86* machines
part /boot --source bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos --active --align 1024
@@ -5230,30 +5207,30 @@
part swap --ondisk sda --size 44 --label swap1 --fstype=swap
bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0"
-
-
-
+
+
+
-
- Examples
+
+ 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
- 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:
-
+ This example runs in Cooked Mode and uses the
+ mkefidisk kickstart file:
+
$ wic create mkefidisk -e core-image-minimal
INFO: Building wic-tools...
.
@@ -5270,122 +5247,122 @@
INFO: The image(s) were created using OE kickstart file:
/home/scottrif/poky/scripts/lib/wic/canned-wks/mkefidisk.wks
-
- The previous example shows the easiest way to create
- an image by running in cooked mode and supplying
- a kickstart file and the "-e" option to point to the
- existing build artifacts.
- Your local.conf file needs to have
- the
- MACHINE
- variable set to the machine you are using, which is
- "qemux86" in this example.
-
+
+ The previous example shows the easiest way to create
+ an image by running in cooked mode and supplying
+ a kickstart file and the "-e" option to point to the
+ existing build artifacts.
+ Your local.conf file needs to have
+ the
+ MACHINE
+ variable set to the machine you are using, which is
+ "qemux86" in this example.
+
-
- Once the image builds, the output provides image
- location, artifact use, and kickstart file information.
-
- You should always verify the details provided in the
- output to make sure that the image was indeed
- created exactly as expected.
-
-
+
+ Once the image builds, the output provides image
+ location, artifact use, and kickstart file information.
+
+ 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 write the
- image to a USB stick, or whatever media for which you
- built your image, and boot from the media.
- You can write the image by using
- bmaptool or
- dd:
-
+
+ Continuing with the example, you can now write the
+ image to a USB stick, or whatever media for which you
+ built your image, and boot from the media.
+ You can write the image by using
+ bmaptool or
+ dd:
+
$ oe-run-native bmaptool copy build/mkefidisk-201710061409-sda.direct /dev/sdX
-
- or
-
+
+ or
+
$ sudo dd if=build/mkefidisk-201710061409-sda.direct of=/dev/sdX
-
-
- For more information on how to use the
- bmaptool to flash a device
- with an image, see the
- "Flashing Images Using bmaptool"
- section.
-
-
-
+
+
+ For more information on how to use the
+ bmaptool to flash a device
+ with an image, see the
+ "Flashing Images Using bmaptool"
+ section.
+
+
+
-
- Using a Modified Kickstart File
+
+ Using a Modified Kickstart File
-
- Because 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-gpt kickstart
- file.
-
+
+ Because 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-gpt 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 the
- directdisk-gpt.wks file resides is
- scripts/lib/image/canned-wks/,
- which is located in the
- Source Directory
- (e.g. poky).
- Because 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 the
+ directdisk-gpt.wks file resides is
+ scripts/lib/image/canned-wks/,
+ which is located in the
+ Source Directory
+ (e.g. poky).
+ Because 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-gpt 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-gpt kickstart file
- uses.
-
+
+ In this example, the existing
+ directdisk-gpt 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-gpt kickstart file
+ uses.
+
-
- The example begins by making a copy of the
- directdisk-gpt.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.
-
+
+ The example begins by making a copy of the
+ directdisk-gpt.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/scottrif/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \
/home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
-
- Next, the example modifies the
- directdisksdb-gpt.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-gpt.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=ext4 --label platform --align 1024 --use-uuid
-
- Once the lines are changed, the example generates the
- directdisksdb-gpt 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-gpt 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-gpt -e core-image-minimal
INFO: Building wic-tools...
.
@@ -5408,32 +5385,32 @@
INFO: The image(s) were created using OE kickstart file:
/home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.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=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb
140966+0 records in
140966+0 records out
72174592 bytes (72 MB, 69 MiB) copied, 78.0282 s, 925 kB/s
$ sudo eject /dev/sdb
-
-
-
+
+
+
-
- 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 output directory,
- which is the current 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 output directory,
+ which is the current directory:
+
$ wic create /home/scottrif/my_yocto/test.wks -o /home/scottrif/testwic \
--rootfs-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
--bootimg-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
@@ -5453,219 +5430,15 @@
INFO: The image(s) were created using OE kickstart file:
/home/scottrif/my_yocto/test.wks
-
- For this example,
- MACHINE
- did not have to be specified in the
- local.conf file since the
- artifact is manually specified.
-
-
-
-
-
- Plug-ins
-
-
- You can extend and specialize Wic functionality by using
- Wic plug-ins.
- This section explains the Wic plug-in interface.
-
- Wic plug-ins consist of "source" and "imager" plug-ins.
- Imager plug-ins are beyond the scope of this section.
-
-
-
-
- Source plug-ins provide a mechanism to customize partition
- content during the Wic image generation process.
- You can use source plug-ins to map values that you specify
- using --source commands in kickstart
- files (i.e. *.wks) to a plug-in
- implementation used to populate a given partition.
-
- If you use plug-ins that have build-time dependencies
- (e.g. native tools, bootloaders, and so forth)
- when building a Wic image, you need to specify those
- dependencies using the
- WKS_FILE_DEPENDS
- variable.
-
-
-
-
- Source plug-ins are subclasses defined in plug-in files.
- As shipped, the Yocto Project provides several plug-in
- files.
- You can see the source plug-in files that ship with the
- Yocto Project
- here.
- Each of these plug-in files contain source plug-ins that
- are designed to populate a specific Wic image partition.
-
-
-
- Source plug-ins are subclasses of the
- SourcePlugin class, which is
- defined in the
- poky/scripts/lib/wic/pluginbase.py
- file.
- For example, the BootimgEFIPlugin
- source plug-in found in the
- bootimg-efi.py file is a subclass of
- the SourcePlugin class, which is found
- in the pluginbase.py file.
-
-
-
- You can also implement source plug-ins in a layer outside
- of the Source Repositories (external layer).
- To do so, be sure that your plug-in files are located in
- a directory whose path is
- scripts/lib/wic/plugins/source/
- within your external layer.
- When the plug-in files are located there, the source
- plug-ins they contain are made available to Wic.
-
-
-
- When the Wic implementation needs to invoke a
- partition-specific implementation, it looks for the plug-in
- with the same name as the --source
- parameter used in the kickstart file given to that
- partition.
- For example, if the partition is set up using the following
- command in a kickstart file:
-
- part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
- The methods defined as class members of the matching
- source plug-in (i.e. bootimg-pcbios)
- in the bootimg-pcbios.py plug-in file
- are used.
-
-
-
- To be more concrete, here is the corresponding plug-in
- definition from the bootimg-pcbios.py
- file for the previous command along with an example
- method called by the Wic implementation when it needs to
- prepare a partition using an implementation-specific
- function:
-
- bootimg-pcbios.py
- .
- .
- .
- class BootimgPcbiosPlugin(SourcePlugin):
- """
- Create MBR boot partition and install syslinux on it.
- """
-
- name = 'bootimg-pcbios'
- .
- .
- .
- @classmethod
- def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
- oe_builddir, bootimg_dir, kernel_dir,
- rootfs_dir, native_sysroot):
- """
- Called to do the actual content population for a partition i.e. it
- 'prepares' the partition to be incorporated into the image.
- In this case, prepare content for legacy bios boot partition.
- """
- .
- .
- .
-
- If a subclass (plug-in) itself does not implement a
- particular function, Wic locates and uses the default
- version in the superclass.
- It is for this reason that all source plug-ins are derived
- from the SourcePlugin class.
-
-
-
- The SourcePlugin class defined in
- the pluginbase.py file defines
- a set of methods that source plug-ins can implement or
- override.
- Any plug-ins (subclass of
- SourcePlugin) that do not implement
- a particular method inherit the implementation of the
- method from the SourcePlugin class.
- For more information, see the
- SourcePlugin class in the
- pluginbase.py file for details:
-
-
-
- The following list describes the methods implemented in the
- SourcePlugin class:
-
-
- do_prepare_partition():
- Called to populate a partition with actual content.
- 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() 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
- behavior.
-
-
-
-
-
-
- You can extend the source plug-in mechanism.
- To add more hooks, create more source plug-in methods
- within SourcePlugin and the
- corresponding derived subclasses.
- The code that calls the plug-in methods uses the
- plugin.get_source_plugin_methods()
- function to find the method or methods needed by the call.
- Retrieval of those methods is accomplished by filling up
- a dict with keys that contain the method names of interest.
- On success, these will be filled in with the actual
- methods.
- See the Wic implementation for examples and details.
+ For this example,
+ MACHINE
+ did not have to be specified in the
+ local.conf file since the
+ artifact is manually specified.
+ OpenEmbedded Kickstart (<filename>.wks</filename>) Reference
@@ -5773,8 +5546,10 @@
"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.
+ "Wic Plug-Ins Interface"
+ section in the Yocto Project Reference
+ manual.
+
If you use
--source rootfs,
Wic creates a partition as
@@ -5792,6 +5567,7 @@
--fstype that
follows for more information.
+
If you use
--source plugin-name,
Wic creates a partition as
@@ -5806,6 +5582,7 @@
end up being are dependent on the given plug-in
implementation.
+
If you do not use the
--source option, the
wic command creates an
@@ -5824,18 +5601,24 @@
Sets the file system type for the partition.
Valid values are:
- ext4
-
- ext3
-
- ext2
-
- btrfs
-
- squashfs
-
- swap
-
+
+ ext4
+
+
+ ext3
+
+
+ ext2
+
+
+ btrfs
+
+
+ squashfs
+
+
+ swap
+
@@ -5969,7 +5752,6 @@
-
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index f566ec243a..0cfc6e675e 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -1252,6 +1252,213 @@
+
+ Wic Plug-Ins Interface
+
+
+ You can extend and specialize Wic functionality by using
+ Wic plug-ins.
+ This section explains the Wic plug-in interface.
+ For information on using Wic in general, see the
+ "Creating Partitioned Images"
+ section in the Yocto Project Development Manual.
+
+ Wic plug-ins consist of "source" and "imager" plug-ins.
+ Imager plug-ins are beyond the scope of this section.
+
+
+
+
+ Source plug-ins provide a mechanism to customize partition
+ content during the Wic image generation process.
+ You can use source plug-ins to map values that you specify
+ using --source commands in kickstart
+ files (i.e. *.wks) to a plug-in
+ implementation used to populate a given partition.
+
+ If you use plug-ins that have build-time dependencies
+ (e.g. native tools, bootloaders, and so forth)
+ when building a Wic image, you need to specify those
+ dependencies using the
+ WKS_FILE_DEPENDS
+ variable.
+
+
+
+
+ Source plug-ins are subclasses defined in plug-in files.
+ As shipped, the Yocto Project provides several plug-in
+ files.
+ You can see the source plug-in files that ship with the
+ Yocto Project
+ here.
+ Each of these plug-in files contain source plug-ins that
+ are designed to populate a specific Wic image partition.
+
+
+
+ Source plug-ins are subclasses of the
+ SourcePlugin class, which is
+ defined in the
+ poky/scripts/lib/wic/pluginbase.py
+ file.
+ For example, the BootimgEFIPlugin
+ source plug-in found in the
+ bootimg-efi.py file is a subclass of
+ the SourcePlugin class, which is found
+ in the pluginbase.py file.
+
+
+
+ You can also implement source plug-ins in a layer outside
+ of the Source Repositories (external layer).
+ To do so, be sure that your plug-in files are located in
+ a directory whose path is
+ scripts/lib/wic/plugins/source/
+ within your external layer.
+ When the plug-in files are located there, the source
+ plug-ins they contain are made available to Wic.
+
+
+
+ When the Wic implementation needs to invoke a
+ partition-specific implementation, it looks for the plug-in
+ with the same name as the --source
+ parameter used in the kickstart file given to that
+ partition.
+ For example, if the partition is set up using the following
+ command in a kickstart file:
+
+ part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
+
+ The methods defined as class members of the matching
+ source plug-in (i.e. bootimg-pcbios)
+ in the bootimg-pcbios.py plug-in file
+ are used.
+
+
+
+ To be more concrete, here is the corresponding plug-in
+ definition from the bootimg-pcbios.py
+ file for the previous command along with an example
+ method called by the Wic implementation when it needs to
+ prepare a partition using an implementation-specific
+ function:
+
+ bootimg-pcbios.py
+ .
+ .
+ .
+ class BootimgPcbiosPlugin(SourcePlugin):
+ """
+ Create MBR boot partition and install syslinux on it.
+ """
+
+ name = 'bootimg-pcbios'
+ .
+ .
+ .
+ @classmethod
+ def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
+ oe_builddir, bootimg_dir, kernel_dir,
+ rootfs_dir, native_sysroot):
+ """
+ Called to do the actual content population for a partition i.e. it
+ 'prepares' the partition to be incorporated into the image.
+ In this case, prepare content for legacy bios boot partition.
+ """
+ .
+ .
+ .
+
+ If a subclass (plug-in) itself does not implement a
+ particular function, Wic locates and uses the default
+ version in the superclass.
+ It is for this reason that all source plug-ins are derived
+ from the SourcePlugin class.
+
+
+
+ The SourcePlugin class defined in
+ the pluginbase.py file defines
+ a set of methods that source plug-ins can implement or
+ override.
+ Any plug-ins (subclass of
+ SourcePlugin) that do not implement
+ a particular method inherit the implementation of the
+ method from the SourcePlugin class.
+ For more information, see the
+ SourcePlugin class in the
+ pluginbase.py file for details:
+
+
+
+ The following list describes the methods implemented in the
+ SourcePlugin class:
+
+
+ do_prepare_partition():
+ Called to populate a partition with actual content.
+ 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() 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
+ behavior.
+
+
+
+
+
+
+ You can extend the source plug-in mechanism.
+ To add more hooks, create more source plug-in methods
+ within SourcePlugin and the
+ corresponding derived subclasses.
+ The code that calls the plug-in methods uses the
+ plugin.get_source_plugin_methods()
+ function to find the method or methods needed by the call.
+ Retrieval of those methods is accomplished by filling up
+ a dict with keys that contain the method names of interest.
+ On success, these will be filled in with the actual
+ methods.
+ See the Wic implementation for examples and details.
+
+
+
x32