From: Scott Rifenbark Date: Wed, 10 Jan 2018 19:36:56 +0000 (-0800) Subject: dev-manual, ref-manual: Moved Wic Plug-In section to dev-manual X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8097a978cef998d82cc1e35e94b090b0c8bb264f;p=thirdparty%2Fopenembedded%2Fopenembedded-core-contrib.git dev-manual, ref-manual: Moved Wic Plug-In section to dev-manual Fixes [YOCTO #12370] I had a section on Wick Plug-Ins in the ref-manual in the "technical details" chapter. This section has been combined with the section on using Wic that lives in the dev-manual. This move creates a single section on using Wic to create Wic-partitioned images. The section was moved out of the ref-manual and merged into the dev-manual Wic section. (From yocto-docs rev: 8724049141c9a793312dcf5ff5c3425948d1cbd0) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 58bb6012cea..78825c7f1ed 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -4878,16 +4878,17 @@ 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. + "Using the Wic Plug-Ins Interface" + 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. + the Wic utility, provides information on using the Wic plug-ins + interface, and provides several examples that show how to use + Wic.
@@ -5265,6 +5266,210 @@
+
+ Using the Wic Plug-Ins Interface + + + 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 contains 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. + +
+
Examples diff --git a/documentation/ref-manual/ref-kickstart.xml b/documentation/ref-manual/ref-kickstart.xml index 1dd36b242c9..ab3d1b8ef18 100644 --- a/documentation/ref-manual/ref-kickstart.xml +++ b/documentation/ref-manual/ref-kickstart.xml @@ -107,8 +107,9 @@ 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 - "Wic Plug-Ins Interface" - section. + "Using the Wic Plug-Ins Interface" + section in the Yocto Project Development Tasks Manual. + If you use --source rootfs, Wic creates a partition as large as needed and to fill it with diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index 1ac020a5cf4..5769cd619a7 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -1255,213 +1255,6 @@
-
- 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 Using Wic" - section in the Yocto Project Development Tasks 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. - -
-
Wayland