From fa108caaa53878152e4856d32ce1ab7fe3802287 Mon Sep 17 00:00:00 2001 From: Tom Zanussi Date: Thu, 10 Jul 2014 20:50:31 -0500 Subject: 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 Signed-off-by: Saul Wold Signed-off-by: Richard Purdie --- scripts/lib/image/help.py | 209 ++++++++++++++++++++++++++++++++++++++++++++++ scripts/wic | 21 +++-- 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 ' 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 [-o | ...] + [-i | --infile ] + [-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 . + + 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], } -- cgit 1.2.3-korg