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