wic: Add wic overview to help system

Add a general overview of wic to the help system as 'wic overview',
along with some introductory examples.

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>

2 files changed, 221 insertions, 9 deletions

diff --git a/scripts/lib/image/help.py b/scripts/lib/image/help.py
index a4f27ab68e..bf2f773266 100644
--- a/scripts/lib/image/help.py
+++ b/scripts/lib/image/help.py
@@ -88,6 +88,7 @@ wic_usage = """
     list              List available values for options and image properties
 
  Help topics:
+    overview           wic overview - General overview of wic
     plugins            wic plugins - Overview and API
 
  See 'wic help <COMMAND or HELP TOPIC>' for more information on a specific
@@ -422,3 +423,211 @@ DESCRIPTION
     with the actual methods. Please see the implementation for
     examples and details.
 """
+
+wic_overview_help = """
+
+NAME
+    wic overview - General overview of wic
+
+DESCRIPTION
+    The 'wic' command generates partitioned images from existing
+    OpenEmbedded build artifacts.  Image generation is driven by
+    partitioning commands contained in an 'Openembedded kickstart'
+    (.wks) file (see 'wic help kickstart') specified either directly
+    on the command-line or as one of a selection of canned .wks files
+    (see 'wic list images').  When applied to a given set of build
+    artifacts, the result is an image or set of images that can be
+    directly written onto media and used on a particular system.
+
+    The 'wic' command and the infrastructure it's based is by
+    definition incomplete - it's designed to allow the generation of
+    customized images, and as such was designed to be completely
+    extensible via a plugin interface (see 'wic help plugins').
+
+  Background and Motivation
+
+    wic is meant to be a completely independent standalone utility
+    that initially provides easier-to-use and more flexible
+    replacements for a couple bits of existing functionality in
+    oe-core: directdisk.bbclass and mkefidisk.sh.  The difference
+    between wic and those examples is that with wic the functionality
+    of those scripts is implemented by a general-purpose partitioning
+    'language' based on Redhat kickstart syntax (with the underlying
+    code borrowed from Tizen mic, which in turn was borrowed from
+    Meego mic, in turn borrowed from Fedora livecd, etc.).
+
+    The initial motivation and design considerations that lead to the
+    current tool are described exhaustively in Yocto Bug #3847
+    (https://bugzilla.yoctoproject.org/show_bug.cgi?id=3847).
+
+    Though the current wic tool only uses the kickstart syntax related
+    to partitioning and bootloaders and only for creating images,
+    because the code is based on the mic/pykickstart code, future
+    deployment efforts such as those partially described by Yocto Bug
+    #4106 (https://bugzilla.yoctoproject.org/show_bug.cgi?id=4106),
+    but also others including package selection (from e.g. binary
+    feeds) and deployment configuration of users/network/services,
+    etc, could be implemented under this framework, considering that
+    all of those are implemented in some form by the base system.
+
+  Implementation and Examples
+
+    wic can be used in two different modes, depending on how much
+    control the user needs in specifying the Openembedded build
+    artifacts that will be used in creating the image: 'raw' and
+    'cooked'.
+
+    If used in 'raw' mode, artifacts are explicitly specified via
+    command-line arguments (see example below).
+
+    The more easily usable 'cooked' mode uses the current MACHINE
+    setting and a specified image name to automatically locate the
+    artifacts used to create the image.
+
+    OE kickstart files (.wks) can of course be specified directly on
+    the command-line, but the user can also choose from a set of
+    'canned' .wks files available via the 'wic list images' command
+    (example below).
+
+    In any case, the prerequisite for generating any image is to have
+    the build artifacts already available.  The below examples assume
+    the user has already build a 'core-image-minimal' for a specific
+    machine (future versions won't require this redundant step, but
+    for now that's typically how build artifacts get generated).
+
+    The other prerequisite is to source the build environment:
+
+      $ source oe-init-build-env
+
+    To start out with, we'll generate an image from one of the canned
+    .wks files.  The following generates a list of availailable
+    images:
+
+      $ wic list images
+        mkefidisk             Create an EFI disk image
+        directdisk            Create a 'pcbios' direct disk image
+
+    You can get more information about any of the available images by
+    typing 'wic list xxx help', where 'xxx' is one of the image names:
+
+      $ wic list mkefidisk help
+
+    Creates a partitioned EFI disk image that the user can directly dd
+    to boot media.
+
+    At any time, you can get help on the 'wic' command or any
+    subcommand (currently 'list' and 'create').  For instance, to get
+    the description of 'wic create' command and its parameters:
+
+      $ wic create
+
+       Usage:
+
+       Create a new OpenEmbedded image
+
+       usage: wic create <wks file or image name> [-o <DIRNAME> | ...]
+            [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
+            [-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir]
+            [-k, --kernel-dir] [-n, --native-sysroot] [-s, --skip-build-check]
+
+       This command creates an OpenEmbedded image based on the 'OE
+       kickstart commands' found in the <wks file>.
+
+       The -o option can be used to place the image in a directory
+       with a different name and location.
+
+       See 'wic help create' for more detailed instructions.
+       ...
+
+    As mentioned in the command, you can get even more detailed
+    information by adding 'help' to the above:
+
+      $ wic help create
+
+    So, the easiest way to create an image is to use the -e option
+    with a canned .wks file.  To use the -e option, you need to
+    specify the image used to generate the artifacts and you actually
+    need to have the MACHINE used to build them specified in your
+    local.conf (these requirements aren't necessary if you aren't
+    using the -e options.)  Below, we generate a directdisk image,
+    pointing the process at the core-image-minimal artifacts for the
+    current MACHINE:
+
+      $ wic create directdisk -e core-image-minimal
+
+      Checking basic build environment...
+      Done.
+
+      Creating image(s)...
+
+      Info: The new image(s) can be found here:
+      /var/tmp/wic/build/directdisk-201309252350-sda.direct
+
+      The following build artifacts were used to create the image(s):
+
+      ROOTFS_DIR:      ...
+      BOOTIMG_DIR:     ...
+      KERNEL_DIR:      ...
+      NATIVE_SYSROOT:  ...
+
+      The image(s) were created using OE kickstart file:
+        .../scripts/lib/image/canned-wks/directdisk.wks
+
+    The output shows the name and location of the image created, and
+    so that you know exactly what was used to generate the image, each
+    of the artifacts and the kickstart file used.
+
+    Similarly, you can create a 'mkefidisk' image in the same way
+    (notice that this example uses a different machine - because it's
+    using the -e option, you need to change the MACHINE in your
+    local.conf):
+
+      $ wic create mkefidisk -e core-image-minimal
+      Checking basic build environment...
+      Done.
+
+      Creating image(s)...
+
+      Info: The new image(s) can be found here:
+         /var/tmp/wic/build/mkefidisk-201309260027-sda.direct
+
+      ...
+
+    Here's an example that doesn't take the easy way out and manually
+    specifies each build artifact, along with a non-canned .wks file,
+    and also uses the -o option to have wic create the output
+    somewhere other than the default /var/tmp/wic:
+
+      $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir
+      /home/trz/yocto/build/tmp/work/crownbay/core-image-minimal/1.0-r0/rootfs
+      --bootimg-dir /home/trz/yocto/build/tmp/sysroots/crownbay/usr/share
+      --kernel-dir /home/trz/yocto/build/tmp/sysroots/crownbay/usr/src/kernel
+      --native-sysroot /home/trz/yocto/build/tmp/sysroots/x86_64-linux
+
+      Creating image(s)...
+
+      Info: The new image(s) can be found here:
+        /home/trz/testwic/build/test-201309260032-sda.direct
+
+      ...
+
+    Finally, here's an example of the actual partition language
+    commands used to generate the mkefidisk image i.e. these are the
+    contents of the mkefidisk.wks OE kickstart file:
+
+      # short-description: Create an EFI disk image
+      # long-description: Creates a partitioned EFI disk image that the user
+      # can directly dd to boot media.
+
+      part /boot --source bootimg-efi --ondisk sda --fstype=efi --active
+
+      part / --source rootfs --ondisk sda --fstype=ext3 --label platform
+
+      part swap --ondisk sda --size 44 --label swap1 --fstype=swap
+
+      bootloader  --timeout=10  --append="rootwait console=ttyPCH0,115200"
+
+    You can get a complete listing and description of all the
+    kickstart commands available for use in .wks files from 'wic help
+    kickstart'.
+"""
diff --git a/scripts/wic b/scripts/wic
index ac3ed160d9..5453750703 100755
--- a/scripts/wic
+++ b/scripts/wic
@@ -240,15 +240,18 @@ 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],
-    "plugins": [wic_help_topic_subcommand,
-                wic_help_topic_usage,
-                wic_plugins_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],
+    "overview":  [wic_help_topic_subcommand,
+                 wic_help_topic_usage,
+                 wic_overview_help],
 }