path: root/scripts/lib/wic/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

from wic.pluginbase import PluginMgr, PLUGIN_TYPES

logger = logging.getLogger('wic')

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


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

    hlp = subcommands.get(subcommand, subcommand_error)[2]
    if callable(hlp):
        hlp = hlp()
    pager = subprocess.Popen('less', stdin=subprocess.PIPE)
    pager.communicate(hlp.encode('utf-8'))

    return True


def wic_help(args, usage_str, subcommands):
    """
    Subcommand help dispatcher.
    """
    if args.help_topic == None or not display_help(args.help_topic, subcommands):
        print(usage_str)


def get_wic_plugins_help():
    """
    Combine wic_plugins_help with the help for every known
    source plugin.
    """
    result = wic_plugins_help
    for plugin_type in PLUGIN_TYPES:
        result += '\n\n%s PLUGINS\n\n' % plugin_type.upper()
        for name, plugin in PluginMgr.get_plugins(plugin_type).items():
            result += "\n %s plugin:\n" % name
            if plugin.__doc__:
                result += plugin.__doc__
            else:
                result += "\n    %s is missing docstring\n" % plugin
    return result


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.command:
        logger.error("No subcommand specified, exiting")
        parser.print_help()
        return 1
    elif args.command == "help":
        wic_help(args, main_command_usage, subcommands)
    elif args.command not in subcommands:
        logger.error("Unsupported subcommand %s, exiting\n", args.command)
        parser.print_help()
        return 1
    else:
        subcmd = subcommands.get(args.command, subcommand_error)
        usage = subcmd[1]
        subcmd[0](args, usage)


##
# wic help and usage strings
##

wic_usage = """

 Create a customized OpenEmbedded image

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

 Current 'wic' commands are:
    help              Show help for command or one of the topics (see below)
    create            Create a new OpenEmbedded image
    list              List available canned images and source plugins

 Help topics:
    overview          wic overview - General overview of wic
    plugins           wic plugins - Overview and API
    kickstart         wic kickstart - wic kickstart reference
"""

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>]
            [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
            [-r, --rootfs-dir] [-b, --bootimg-dir]
            [-k, --kernel-dir] [-n, --native-sysroot] [-f, --build-rootfs]
            [-c, --compress-with] [-m, --bmap]

 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>]
        [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
        [-r, --rootfs-dir] [-b, --bootimg-dir]
        [-k, --kernel-dir] [-n, --native-sysroot] [-f, --build-rootfs]
        [-c, --compress-with] [-m, --bmap] [--no-fstab-update]

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 'wic' 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 -f option is used to build rootfs by running "bitbake <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.

    The -D option is used to display debug information detailing
    exactly what happens behind the scenes when a create request is
    fulfilled (or not, as the case may be).  It enumerates and
    displays the command sequence used, and should be included in any
    bug report describing unexpected results.

    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:        empty (plugin-specific handlers must determine this)

    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.

    The -c option is used to specify compressor utility to compress
    an image. gzip, bzip2 and xz compressors are supported.

    The -m option is used to produce .bmap file for the image. This file
    can be used to flash image using bmaptool utility.

    The --no-fstab-update option is used to doesn't change fstab file. When
    using this option the final fstab file will be same that in rootfs and
    wic doesn't update file, e.g adding a new mount point. User can control
    the fstab file content in base-files recipe.
"""

wic_list_usage = """

 List available OpenEmbedded images and source plugins

 usage: wic list images
        wic list <image> help
        wic list source-plugins

 This command enumerates the set of available canned images as well as
 help for those images.  It also can be used to list of available source
 plugins.

 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).

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

wic_list_help = """

NAME
    wic list - List available OpenEmbedded images and source plugins

SYNOPSIS
    wic list images
    wic list <image> help
    wic list source-plugins

DESCRIPTION
    This command enumerates the set of available canned images as well
    as help for those images.  It also can be used to list available
    source plugins.

    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/wic/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.
"""

wic_ls_usage = """

 List content of a partitioned image

 usage: wic ls <image>[:<partition>[<path>]] [--native-sysroot <path>]

 This command  outputs either list of image partitions or directory contents
 of vfat and ext* partitions.

 See 'wic help ls' for more detailed instructions.

"""

wic_ls_help = """

NAME
    wic ls - List contents of partitioned image or partition

SYNOPSIS
    wic ls <image>
    wic ls <image>:<vfat or ext* partition>
    wic ls <image>:<vfat or ext* partition><path>
    wic ls <image>:<vfat or ext* partition><path> --native-sysroot <path>

DESCRIPTION
    This command lists either partitions of the image or directory contents
    of vfat or ext* partitions.

    The first form it lists partitions of the image.
    For example:
        $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic
        Num     Start        End          Size      Fstype
        1        1048576     24438783     23390208  fat16
        2       25165824     50315263     25149440  ext4

    Second and third form list directory content of the partition:
        $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
        Volume in drive : is boot
         Volume Serial Number is 2DF2-5F02
        Directory for ::/

        efi          <DIR>     2017-05-11  10:54
        startup  nsh