From 2a11e9d2944b5062638a7eb6376644a633e357a8 Mon Sep 17 00:00:00 2001 From: Tom Zanussi Date: Wed, 30 Jul 2014 09:43:40 +0300 Subject: dev-manual: Created new "Plugins" section in the wic section. Add a new section discussing plugins, taken directly from the corresponding wic help section. (From yocto-docs rev: c1b4c378a496413f2dde8ad2f043a537cba24b6e) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 153 +++++++++++++++++++++ 1 file changed, 153 insertions(+) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index be95c0f405..7f796fc037 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -4007,6 +4007,159 @@ +
+ Plugins + + + Plugins allow wic functionality to + be extended and specialized by users. + This section documents the plugin interface, which is + currently restricted to source plugins. + + + + Source plugins provide a mechanism to customize + various aspects of the image generation process in + wic, mainly the contents of + partitions. + The plugins 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/mic/plugins/source/ to + make the plugin implementation available to the + wic implementation. + For more information, see + scripts/lib/mic/pluginbase.py. + + + + Source plugins can also be implemented and added by + external layers. + As such, any plugins found in a + scripts/lib/mic/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. + Location 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. + +
+
OpenEmbedded Kickstart (.wks) Reference -- cgit v1.2.3-54-g00ecf