Plug-ins allow wic
functionality to
be extended and specialized by users.
This section documents the plugin 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 plugin implementation that populates a
corresponding partition.
A source plugin is created as a subclass of
SourcePlugin
.
The plugin file containing it is added to
scripts/lib/wic/plugins/source/
to
make the plugin implementation available to the
wic
implementation.
For more information, see
scripts/lib/wic/pluginbase.py
.
Source plugins can also be implemented and added by
external layers.
As such, any plugins 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 plugin 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 plugin
having the matching bootimg-pcbios.name
class member are used.
To be more concrete, here is the plugin 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 plugins 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
plugins.
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:
do_prepare_partition()
:
Called to do the actual content population for a
partition.
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()
.
This method is typically used 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.
This scheme is extensible.
Adding more hooks is a simple matter of adding more
plugin methods to SourcePlugin
and
derived classes.
The code that then needs to call the plugin 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.