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

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.

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.

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 can also be implemented and added by external layers. As such, any plug-ins found in a scripts/lib/wic/plugins/source/ directory in an external layer are also made available.

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:

     part /boot --source bootimg-pcbios   ...
                    

The methods defined as class members of the plug-in having the matching bootimg-pcbios.name class member 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:

    class BootimgPcbiosPlugin(SourcePlugin):
        name = 'bootimg-pcbios'

    @classmethod
        def do_prepare_partition(self, part, ...)
                    

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.

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. For more information, see the SourcePlugin source for details:

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 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. On success, these will be filled in with the actual methods. Please see the Wic implementation for examples and details.