poky/scripts/lib/image/help.py

# ex:ts=4:sw=4:sts=4:et
# -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
#
# Copyright (c) 2013, Intel Corporation.
# All rights reserved.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License version 2 as
# published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
#
# DESCRIPTION
# This module implements some basic help invocation functions along
# with the bulk of the help topic text for the OE Core Image Tools.
#
# AUTHORS
# Tom Zanussi <tom.zanussi (at] linux.intel.com>
#

import subprocess
import logging


def subcommand_error(args):
    logging.info("invalid subcommand %s" % args[0])


def display_help(subcommand, subcommands):
    """
    Display help for subcommand.
    """
    if subcommand not in subcommands:
        return False

    help = subcommands.get(subcommand, subcommand_error)[2]
    pager = subprocess.Popen('less', stdin=subprocess.PIPE)
    pager.communicate(help)

    return True


def wic_help(args, usage_str, subcommands):
    """
    Subcommand help dispatcher.
    """
    if len(args) == 1 or not display_help(args[1], subcommands):
        print(usage_str)


def invoke_subcommand(args, parser, main_command_usage, subcommands):
    """
    Dispatch to subcommand handler borrowed from combo-layer.
    Should use argparse, but has to work in 2.6.
    """
    if not args:
        logging.error("No subcommand specified, exiting")
        parser.print_help()
    elif args[0] == "help":
        wic_help(args, main_command_usage, subcommands)
    elif args[0] not in subcommands:
        logging.error("Unsupported subcommand %s, exiting\n" % (args[0]))
        parser.print_help()
    else:
        usage = subcommands.get(args[0], subcommand_error)[1]
        subcommands.get(args[0], subcommand_error)[0](args[1:], usage)


##
# wic help and usage strings
##

wic_usage = """

 Create a customized OpenEmbedded image

 usage: wic [--version] [--help] COMMAND [ARGS]

 Current 'wic' commands are:
    create            Create a new OpenEmbedded image
    list              List available values for options and image properties

 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 = """

 usage: wic help <subcommand>

 This command displays detailed help for the specified subcommand.
"""

wic_create_usage = """

 Create a new OpenEmbedded image

 usage: wic create <wks file or image name> [-o <DIRNAME> | --outdir <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.
"""

wic_create_help = """

NAME
    wic create - Create a new OpenEmbedded image

SYNOPSIS
    wic create <wks file or image name> [-o <DIRNAME> | --outdir <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]

DESCRIPTION
    This command creates an OpenEmbedded image based on the 'OE
    kickstart commands' found in the <wks file>.

    In order to do this, wic needs to know the locations of the
    various build artifacts required to build the image.

    Users can explicitly specify the build artifact locations using
    the -r, -b, -k, and -n options.  See below for details on where
    the corresponding artifacts are typically found in a normal
    OpenEmbedded build.

    Alternatively, users can use the -e option to have 'mic' determine
    those locations for a given image.  If the -e option is used, the
    user needs to have set the appropriate MACHINE variable in
    local.conf, and have sourced the build environment.

    The -e option is used to specify the name of the image to use the
    artifacts from e.g. core-image-sato.

    The -r option is used to specify the path to the /rootfs dir to
    use as the .wks rootfs source.

    The -b option is used to specify the path to the dir containing
    the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the
    .wks bootimg source.

    The -k option is used to specify the path to the dir containing
    the kernel to use in the .wks bootimg.

    The -n option is used to specify the path to the native sysroot
    containing the tools to use to build the image.

    The -s option is used to skip the build check.  The build check is
    a simple sanity check used to determine whether the user has
    sourced the build environment so that the -e option can operate
    correctly.  If the user has specified the build artifact locations
    explicitly, 'wic' assumes the user knows what he or she is doing
    and skips the build check.

    When 'wic -e' is used, the locations for the build artifacts
    values are determined by 'wic -e' from the output of the 'bitbake
    -e' command given an image name e.g. 'core-image-minimal' and a
    given machine set in local.conf.  In that case, the image is
    created as if the following 'bitbake -e' variables were used:

    -r:        IMAGE_ROOTFS
    -k:        STAGING_KERNEL_DIR
    -n:        STAGING_DIR_NATIVE
    -b:        HDDDIR and STAGING_DATA_DIR (handlers decide which to use)

    If 'wic -e' is not used, the user needs to select the appropriate
    value for -b (as well as -r, -k, and -n).

    The -o option can be used to place the image in a directory with a
    different name and location.

    As an alternative to the wks file, the image-specific properties
    that define the values that will be used to generate a particular
    image can be specified on the command-line using the -i option and
    supplying a JSON object consisting of the set of name:value pairs
    needed by image creation.

    The set of properties available for a given image type can be
    listed using the 'wic list' command.
"""

wic_list_usage = """

 List available OpenEmbedded image properties and values

 usage: wic list images
        wic list <image> help
        wic list source-plugins
        wic list properties
        wic list properties <wks file>
        wic list property <property>
                [-o <JSON PROPERTY FILE> | --outfile <JSON PROPERTY_FILE>]

 This command enumerates the set of available canned images as well as
 help for those images.  It also can be used to enumerate the complete
 set of possible values for a specified option or property needed by
 the image creation process.

 The first form enumerates all the available 'canned' images.

 The second form lists the detailed help information for a specific
 'canned' image.

 The third form enumerates all the available --sources (source
 plugins).

 The fourth form enumerates all the possible values that exist and can
 be specified in an OE kickstart (wks) file.

 The fifth form enumerates all the possible options that exist for the
 set of properties specified in a given OE kickstart (ks) file.

 The final form enumerates all the possible values that exist and can
 be specified for any given OE kickstart (wks) property.

 See 'wic help list' for more details.
"""

wic_list_help = """

NAME
    wic list - List available OpenEmbedded image properties and values

SYNOPSIS
    wic list images
    wic list <image> help
    wic list source-plugins
    wic list properties
    wic list properties <wks file>
    wic list property <property>
            [-o <JSON PROPERTY FILE> | --outfile <JSON PROPERTY_FILE>]

DESCRIPTION
    This command enumerates the complete set of possible values for a
    specified option or property needed by the image creation process.

    This command enumerates the set of available canned images as well
    as help for those images.  It also can be used to enumerate the
    complete set of possible values for a specified option or property
    needed by the image creation process.

    The first form enumerates all the available 'canned' images.
    These are actually just the set of .wks files that have been moved
    into the /scripts/lib/image/canned-wks directory).

    The second form lists the detailed help information for a specific
    'canned' image.

    The third form enumerates all the available --sources (source
    plugins).  The contents of a given partition are driven by code
    defined in 'source plugins'.  Users specify a specific plugin via
    the --source parameter of the partition .wks command.  Normally
    this is the 'rootfs' plugin but can be any of the more specialized
    sources listed by the 'list source-plugins' command.  Users can
    also add their own source plugins - see 'wic help plugins' for
    details.

    The third form enumerates all the possible values that exist and
    can be specified in a OE kickstart (wks) file.  The output of this
    can be used by the third form to print the description and
    possible values of a specific property.

    The fourth form enumerates all the possible options that exist for
    the set of properties specified in a given OE kickstart (wks)
    file.  If the -o option is specified, the list of properties, in
    addition to being displayed, will be written to the specified file
    as a JSON object.  In this case, the object will consist of the
    set of name:value pairs corresponding to the (possibly nested)
    dictionary of properties defined by the input statements used by
    the image.  Some example output for the 'list <wks file>' command:

    $ wic list test.ks
    "part" : {
        "mountpoint" : "/"
        "fstype" : "ext3"
    }
    "part" : {
        "mountpoint" : "/home"
        "fstype" : "ext3"
        "offset" : "10000"
    }
    "bootloader" : {
        "type" : "efi"
    }
    .
    .
    .

    Each entry in the output consists of the name of the input element
    e.g. "part", followed by the properties defined for that
    element enclosed in braces.  This information should provide
    sufficient information to create a complete user interface with.

    The final form enumerates all the possible values that exist and
    can be specified for any given OE kickstart (wks) property.  If
    the -o option is specified, the list of values for the given
    property, in addition to being displayed, will be written to the
    specified file as a JSON object.  In this case, the object will
    consist of the set of name:value pairs corresponding to the array
    of property values associated with the property.

    $ wic list property part
        ["mountpoint", "where the partition should be mounted"]
        ["fstype", "filesytem type of the partition"]
            ["ext3"]
            ["ext4"]
            ["btrfs"]
            ["swap"]
        ["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.
"""