diff options
author | Tom Zanussi <tom.zanussi@linux.intel.com> | 2014-07-07 16:05:44 -0500 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-07-10 17:38:34 +0100 |
commit | d8ef35557e2ff9ac80cbfa471c675405ead9c69c (patch) | |
tree | 7813c8fecd615449a8cefcaf5effe4de7ee0c98e /scripts | |
parent | f2ab61968129c6c15b0a61968a7761ccce5a469a (diff) | |
download | ast2050-yocto-poky-d8ef35557e2ff9ac80cbfa471c675405ead9c69c.zip ast2050-yocto-poky-d8ef35557e2ff9ac80cbfa471c675405ead9c69c.tar.gz |
wic: Add general 'plugins' help topic
Add a category for help topics with an initial help topic discussing
source plugins.
(From OE-Core rev: a3dbe46dd28a6fd9e6c21f6bbb6a12578df9dff3)
Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com>
Signed-off-by: Saul Wold <sgw@linux.intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'scripts')
-rw-r--r-- | scripts/lib/image/help.py | 101 | ||||
-rwxr-xr-x | 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 6de7ab0..a4f27ab 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. +""" diff --git a/scripts/wic b/scripts/wic index 00eddfd..ac3ed16 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], } |