From 6077ebbe806bb232e3d96b0f138e1f4748e5ef5b Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 11 Oct 2017 13:29:14 -0700 Subject: ref-manual, dev-manual: Moved plug-in section for wic to ref-manual Fixed links affected by the move. (From yocto-docs rev: 250d312274788b0eebf3ae9143f2f89eafd4ab90) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 1110 ++++++++------------ documentation/ref-manual/technical-details.xml | 207 ++++ 2 files changed, 653 insertions(+), 664 deletions(-) (limited to 'documentation') 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. + + + + + 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. -
- Creating Partitioned Images +
+ 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. + 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 + - 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. + 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 + - 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: - - $ 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: - - $ 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. - - - + + 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. - + + Regardless of the mode you use, you need to have the build + artifacts ready and available. + -
- Raw Mode +
+ 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). - + + 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_file options ... 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. - + + 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 +
+ 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 -- cgit v1.2.3-54-g00ecf