3.16.6. 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.

Note

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.

Note

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:

                  .
                  .
                  .
     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:

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.