From 7cf82df8b09dbdf999f9b85c33a7f3be10efc5ba Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 10 Oct 2017 12:24:01 -0700 Subject: dev-manual: Updated the plug-ins section. (From yocto-docs rev: d1a4ff5ee177c7b9442d805b6e20a8ba8410d91d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 198 ++++++++++++--------- 1 file changed, 118 insertions(+), 80 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index c788a8d30a..a5fe63ac9d 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -5467,22 +5467,22 @@ 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. + 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 - 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. + 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) @@ -5494,80 +5494,119 @@ - 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 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. - Source plug-ins can also be implemented and added by - external layers. - As such, any plug-ins found in a + 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/ - directory in an external layer are also made - available. + 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 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 + 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 ... + part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024 - The methods defined as class members of the plug-in - having the matching bootimg-pcbios.name - class member are used. + 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 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: + 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: - class BootimgPcbiosPlugin(SourcePlugin): - name = 'bootimg-pcbios' + bootimg-pcbios.py + . + . + . + class BootimgPcbiosPlugin(SourcePlugin): + """ + Create MBR boot partition and install syslinux on it. + """ - @classmethod - def do_prepare_partition(self, part, ...) + 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 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. + 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 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. + 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 source for details: + 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 do the actual content population for a - 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. @@ -5575,27 +5614,27 @@ 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_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). + 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 + However, in some cases, things might need to be more tailored. As an example, certain files might additionally need to be taken from @@ -5605,27 +5644,26 @@ get_bitbake_var() allows you to access non-standard variables - that you might want to use for this. + that you might want to use for this + behavior. - 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 + 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() - 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. + 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. - Please see the Wic - implementation for examples and details. + See the Wic implementation for examples and details. -- cgit v1.2.3-54-g00ecf