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 <tom.zanussi@linux.intel.com>
Signed-off-by: Saul Wold <sgw@linux.intel.com>

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 <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 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],
 }