diff options
Diffstat (limited to 'scripts/lib/image')
| -rw-r--r-- | scripts/lib/image/help.py | 101 |
1 files changed, 100 insertions, 1 deletions
diff --git a/scripts/lib/image/help.py b/scripts/lib/image/help.py index 6de7ab023e..a4f27ab68e 100644 --- a/scripts/lib/image/help.py +++ b/scripts/lib/image/help.py @@ -87,7 +87,11 @@ wic_usage = """ create Create a new OpenEmbedded image list List available values for options and image properties - See 'wic help COMMAND' for more information on a specific command. + Help topics: + plugins wic plugins - Overview and API + + See 'wic help <COMMAND or HELP TOPIC>' for more information on a specific + command or help topic. """ wic_help_usage = """ @@ -323,3 +327,98 @@ DESCRIPTION ["offset", "offset of the partition within the image"] """ + +wic_plugins_help = """ + +NAME + wic plugins - Overview and API + +DESCRIPTION + 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. + + Source 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 (see + scripts/lib/mic/pluginbase.py) and the plugin file containing it + is added to scripts/lib/mic/plugins/source/ to make the plugin + implementation available to the wic implementation. + + Source plugins can also be implemented and added by external + layers - any plugins found in a scripts/lib/mic/plugins/source/ + directory in an external layer will also be 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 param given to that partition. For example, if the + partition is set up like this: + + part /boot --source bootimg-pcbios ... + + then the methods defined as class members of the plugin having the + matching bootimg-pcbios .name class member would be used. + + To be more concrete, here's the plugin definition that would match + a '--source bootimg-pcbios' usage, along with an example method + that would be called by the wic implementation when it needed 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 doesn't implement a function, a 'default' + version in a superclass will be 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/overridden by + --source plugins. Any methods not implemented by a SourcePlugin + subclass inherit the implementations present in the SourcePlugin + class (see the SourcePlugin source for details): + + do_prepare_partition() + Called to do the actual content population for a partition + i.e. it 'prepares' the final partition image which will be + incorporated into the disk image. + + do_configure_partition() + Called before do_prepare_partition(), typically used to + create custom configuration files for a partition, for + example syslinux or grub config files. + + do_install_disk() + Called after all partitions have been prepared and assembled + into a disk image. This provides a hook to allow + finalization of a disk image e.g. to write an MBR to it. + + do_stage_partition() + Special content staging hook called before + do_prepare_partition(), normally empty. + + Typically, a partition will just use the passed-in parame + e.g straight bootimg_dir, etc, but in some cases, things + need to be more tailored e.g. to use a deploy dir + /boot, + etc. This hook allows those files to be staged in a + customized fashion. Not that get_bitbake_var() allows you + to acces 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 the uses + plugin.get_source_plugin_methods() to find the method(s) needed by + the call; this is done 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 implementation for + examples and details. +""" |