mirror of
https://git.yoctoproject.org/poky
synced 2026-04-18 03:32:13 +02:00
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. (From OE-Core rev: fa108caaa53878152e4856d32ce1ab7fe3802287) 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>
This commit is contained in:
Tom Zanussi
committed by
Richard Purdie
Richard Purdie
parent
83e5c09d2f
commit
d8b65a55d2
@@ -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'.
|
||||
"""
|
||||
|
||||
21
scripts/wic
21
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],
|
||||
}
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user