From a3dbe46dd28a6fd9e6c21f6bbb6a12578df9dff3 Mon Sep 17 00:00:00 2001 From: Tom Zanussi Date: Mon, 7 Jul 2014 16:05:44 -0500 Subject: wic: Add general 'plugins' help topic Add a category for help topics with an initial help topic discussing source plugins. Signed-off-by: Tom Zanussi Signed-off-by: Saul Wold --- scripts/lib/image/help.py | 101 +++++++++++++++++++++++++++++++++++++++++++++- scripts/wic | 15 ++++--- 2 files changed, 109 insertions(+), 7 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 ' 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. +""" diff --git a/scripts/wic b/scripts/wic index 00eddfd7bc..ac3ed160d9 100755 --- a/scripts/wic +++ b/scripts/wic @@ -240,12 +240,15 @@ wic_help_topic_usage = """ """ subcommands = { - "create": [wic_create_subcommand, - wic_create_usage, - wic_create_help], - "list": [wic_list_subcommand, - wic_list_usage, - wic_list_help], + "create": [wic_create_subcommand, + wic_create_usage, + wic_create_help], + "list": [wic_list_subcommand, + wic_list_usage, + wic_list_help], + "plugins": [wic_help_topic_subcommand, + wic_help_topic_usage, + wic_plugins_help], } -- cgit 1.2.3-korg