diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 3202f348dc..c788a8d30a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4844,7 +4844,7 @@
contained in an Openembedded kickstart file
(.wks) specified either directly on
the command line or as one of a selection of canned
- .wks files as shown with the
+ kickstart files as shown with the
wic list images command in the
"Using an Existing Kickstart File"
section.
@@ -4869,16 +4869,14 @@
This section provides some background information on Wic,
describes what you need to have in
place to run the tool, provides instruction on how to use
- the wic utility,
- and provides several examples.
+ the Wic utility, and provides several examples.
Background
- This section provides some background on the
- wic utility.
+ This section provides some background on the Wic utility.
While none of this information is required to use
Wic, you might find it interesting.
@@ -4920,9 +4918,9 @@
Requirements
- In order to use the wic utility
- with the OpenEmbedded Build system, your system needs
- to meet the following requirements:
+ In order to use the Wic utility with the OpenEmbedded Build
+ system, your system needs to meet the following
+ requirements:
The Linux distribution on your
development host must support the Yocto Project.
@@ -4937,6 +4935,13 @@
cp, must be installed on your
development host system.
+
+ You must have sourced the build environment
+ setup script (i.e.
+ &OE_INIT_FILE;)
+ found in the
+ Build Directory.
+
You need to have the build artifacts already
available, which typically means that you must
@@ -4947,22 +4952,16 @@
in order to create an image using
Wic, the current version of
Wic requires the artifacts
- in the form generated by the build system.
+ in the form generated by the OpenEmbedded build
+ system.
- You must build several native tools, which are tools
+ You must build several native tools, which are
built to run on the build system:
$ bitbake parted-native dosfstools-native mtools-native
-
- You must have sourced the build environment
- setup script (i.e.
- &OE_INIT_FILE;)
- found in the
- Build Directory.
-
@@ -4982,13 +4981,16 @@
- Currently, Wic supports two commands:
- create and list.
- You can get help for these commands as follows:
+ Currently, Wic supports seven commands:
+ cp, create,
+ help, list,
+ ls, rm, and
+ write.
+ You can get help for these commands as follows with
+ command being one of the
+ supported commands:
$ wic help command
- with command being either
- create or list.
@@ -5007,15 +5009,29 @@
- You can find out more about the images
- Wic creates using the existing
- kickstart files with the following form of the command:
+ You can find out more about the images Wic creates using
+ the existing kickstart files with the following form of
+ the command:
$ wic list image help
- with image
- being either directdisk or
- mkefidisk.
+ For image, you can provide
+ any of the following:
+
+ beaglebone
+ mpc8315e-rdb
+ genericx86
+ edgerouter
+ qemux86-directdisk
+ directdisk-gpt
+ mkefidisk
+ directdisk
+ systemd-bootdisk
+ mkhybridiso
+ sdimage-bootpart
+ directdisk-multi-rootfs
+ directdisk-bootloader-config
+
@@ -5031,7 +5047,7 @@
Raw Mode:
You explicitly specify build artifacts through
- command-line arguments.
+ wic command-line arguments.
Cooked Mode:
@@ -5039,6 +5055,8 @@
MACHINE
setting and image name are used to automatically
locate and provide the build artifacts.
+ You just supply a kickstart file and the name
+ of the image from which to use artifacts.
@@ -5046,61 +5064,69 @@
Regardless of the mode you use, you need to have the build
artifacts ready and available.
- Additionally, the environment must be set up using the
- &OE_INIT_FILE;
- script found in the
- Build Directory.
Raw Mode
+
+ Running Wic in raw mode allows you to specify all the
+ partitions through the wic
+ command line.
+ The primary use for raw mode is if you have built
+ your kernel outside of the Yocto Project
+ Build Directory.
+ In other words, you can point to arbitrary kernel,
+ root filesystem locations, and so forth.
+ Contrast this behavior with cooked mode where Wic
+ looks in the Build Directory (e.g.
+ tmp/deploy/images/machine).
+
+
The general form of the
wic command in raw mode is:
- $ wic create image_name.wks [options] [...]
+ $ wic create wks_fileoptions ...
Where:
- image_name.wks
+ wks_file:
An OpenEmbedded kickstart file. You can provide
your own custom file or use a file from a set of
existing files as described by further options.
- -o OUTDIR, --outdir=OUTDIR
- The name of a directory in which to create image.
-
- -i PROPERTIES_FILE, --infile=PROPERTIES_FILE
- The name of a file containing the values for image
- properties as a JSON file.
-
- -e IMAGE_NAME, --image-name=IMAGE_NAME
- The name of the image from which to use the artifacts
- (e.g. core-image-sato).
-
- -r ROOTFS_DIR, --rootfs-dir=ROOTFS_DIR
- The path to the /rootfs directory to use as the
- .wks rootfs source.
-
- -b BOOTIMG_DIR, --bootimg-dir=BOOTIMG_DIR
- The path to the directory containing the boot artifacts
- (e.g. /EFI or /syslinux) to use as the .wks bootimg
- source.
-
- -k KERNEL_DIR, --kernel-dir=KERNEL_DIR
- The path to the directory containing the kernel to use
- in the .wks boot image.
-
- -n NATIVE_SYSROOT, --native-sysroot=NATIVE_SYSROOT
- The path to the native sysroot containing the tools to use
- to build the image.
-
- -s, --skip-build-check
- Skips the build check.
-
- -D, --debug
- Output debug information.
+ optional arguments:
+ -h, --help show this help message and exit
+ -o OUTDIR, --outdir OUTDIR
+ name of directory to create image in
+ -e IMAGE_NAME, --image-name IMAGE_NAME
+ name of the image to use the artifacts from e.g. core-
+ image-sato
+ -r ROOTFS_DIR, --rootfs-dir ROOTFS_DIR
+ path to the /rootfs dir to use as the .wks rootfs
+ source
+ -b BOOTIMG_DIR, --bootimg-dir BOOTIMG_DIR
+ path to the dir containing the boot artifacts (e.g.
+ /EFI or /syslinux dirs) to use as the .wks bootimg
+ source
+ -k KERNEL_DIR, --kernel-dir KERNEL_DIR
+ path to the dir containing the kernel to use in the
+ .wks bootimg
+ -n NATIVE_SYSROOT, --native-sysroot NATIVE_SYSROOT
+ path to the native sysroot containing the tools to use
+ to build the image
+ -s, --skip-build-check
+ skip the build check
+ -f, --build-rootfs build rootfs
+ -c {gzip,bzip2,xz}, --compress-with {gzip,bzip2,xz}
+ compress image with specified compressor
+ -m, --bmap generate .bmap
+ --no-fstab-update Do not change fstab file.
+ -v VARS_DIR, --vars VARS_DIR
+ directory with <image>.env files that store bitbake
+ variables
+ -D, --debug output debug information
You do not need root privileges to run
@@ -5115,26 +5141,37 @@
Cooked Mode
- The general form of the wic command
- using Cooked Mode is:
+ Running Wic in cooked mode leverages off artifacts in
+ Build Directory.
+ In other words, you do not have to specify kernel or
+ root filesystem locations as part of the command.
+ All you need to provide is a kickstart file and the
+ name of the image from which to use artifacts by using
+ the "-e" option.
+ Wic looks in the Build Directory (e.g.
+ tmp/deploy/images/machine)
+ for artifacts.
+
+
+
+ The general form of the wic
+ command using Cooked Mode is as follows:
- $ wic create kickstart_file -e image_name
+ $ wic create wks_file -e IMAGE_NAME
Where:
- kickstart_file
- An OpenEmbedded kickstart file. You can provide your own
- custom file or a supplied file.
+ wks_file:
+ An OpenEmbedded kickstart file. You can provide
+ your own custom file or use a file from a set of
+ existing files provided with the Yocto Project
+ release.
- image_name
- Specifies the image built using the OpenEmbedded build
- system.
+ required argument:
+ -e IMAGE_NAME, --image-name IMAGE_NAME
+ name of the image to use the artifacts from e.g. core-
+ image-sato
- This form is the simplest and most user-friendly, as it
- does not require specifying all individual parameters.
- All you need to provide is your own
- .wks file or one provided with the
- release.
@@ -5143,14 +5180,33 @@
Using an Existing Kickstart File
- If you do not want to create your own
- .wks file, you can use an existing
- file provided by the Wic installation.
- Use the following command to list the available files:
+ If you do not want to create your own kickstart file, you
+ can use an existing file provided by the Wic installation.
+ As shipped, kickstart files can be found in the
+ Yocto Project
+ Source Repositories
+ in the following two locations:
+
+ poky/meta-yocto-bsp/wic
+ poky/scripts/lib/wic/canned-wks
+
+ Use the following command to list the available kickstart
+ files:
$ wic list images
- directdisk Create a 'pcbios' direct disk image
- mkefidisk Create an EFI disk image
+ beaglebone Create SD card image for Beaglebone
+ mpc8315e-rdb Create SD card image for MPC8315E-RDB
+ genericx86 Create an EFI disk image for genericx86*
+ edgerouter Create SD card image for Edgerouter
+ qemux86-directdisk Create a qemu machine 'pcbios' direct disk image
+ directdisk-gpt Create a 'pcbios' direct disk image
+ mkefidisk Create an EFI disk image
+ directdisk Create a 'pcbios' direct disk image
+ systemd-bootdisk Create an EFI disk image with systemd-boot
+ mkhybridiso Create a hybrid ISO image
+ sdimage-bootpart Create SD card image with a boot partition
+ directdisk-multi-rootfs Create multi rootfs image using rootfs plugin
+ directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config
When you use an existing file, you do not have to use the
.wks extension.
@@ -5164,20 +5220,16 @@
Here are the actual partition language commands
- used in the mkefidisk.wks file to
+ used in the genericx86.wks file to
generate an image:
- # 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 --label msdos --active --align 1024
-
- part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
-
+ # short-description: Create an EFI disk image for genericx86*
+ # long-description: Creates a partitioned EFI disk image for genericx86* machines
+ part /boot --source bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos --active --align 1024
+ part / --source rootfs --ondisk sda --fstype=ext4 --label platform --align 1024 --use-uuid
part swap --ondisk sda --size 44 --label swap1 --fstype=swap
- bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0"
+ bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0"
@@ -5187,7 +5239,7 @@
This section provides several examples that show how to use
- the wic utility.
+ the Wic utility.
All the examples assume the list of requirements in the
"Requirements"
section have been met.
@@ -5203,42 +5255,36 @@
mkefidisk kickstart file:
$ wic create mkefidisk -e core-image-minimal
- Checking basic build environment...
- Done.
-
- Creating image(s)...
-
- Info: The new image(s) can be found here:
- current_directory/build/mkefidisk-201310230946-sda.direct
+ INFO: Building wic-tools...
+ .
+ .
+ .
+ INFO: The new image(s) can be found here:
+ ./mkefidisk-201710061409-sda.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg
- KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel
- NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
+ ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.r4hkds0b/rootfs_copy
+ BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
- The image(s) were created using OE kickstart file:
- /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
+ INFO: The image(s) were created using OE kickstart file:
+ /home/scottrif/poky/scripts/lib/wic/canned-wks/mkefidisk.wks
The previous example shows the easiest way to create
- an image by running in Cooked Mode and using the
- -e option with an existing
- kickstart file.
- All that is necessary is to specify the image used to
- generate the artifacts.
- Your local.conf needs to have the
+ an image by running in cooked mode and supplying
+ a kickstart file and the "-e" option to point to the
+ existing build artifacts.
+ Your local.conf file needs to have
+ the
MACHINE
variable set to the machine you are using, which is
- "minnow" in this example.
+ "qemux86" in this example.
- The output specifies the exact image created as well as
- where it was created, which is in the current
- directory by default.
- The output also names the artifacts used and the exact
- .wks script that was used to
- generate the image.
+ Once the image builds, the output provides image
+ location, artifact use, and kickstart file information.
You should always verify the details provided in the
output to make sure that the image was indeed
@@ -5249,16 +5295,16 @@
Continuing with the example, you can now write the
image to a USB stick, or whatever media for which you
- built your image, and boot the resulting media.
+ built your image, and boot from the media.
You can write the image by using
bmaptool or
dd:
- $ oe-run-native bmaptool copy build/mkefidisk-201310230946-sda.direct /dev/sdX
+ $ oe-run-native bmaptool copy build/mkefidisk-201710061409-sda.direct /dev/sdX
or
- $ sudo dd if=build/mkefidisk-201310230946-sda.direct of=/dev/sdX
+ $ sudo dd if=build/mkefidisk-201710061409-sda.direct of=/dev/sdX
For more information on how to use the
@@ -5274,22 +5320,25 @@
Using a Modified Kickstart File
- Because partitioned image creation is
- driven by the kickstart file, it is easy to affect
- image creation by changing the parameters in the file.
+ Because partitioned image creation is driven by the
+ kickstart file, it is easy to affect image creation by
+ changing the parameters in the file.
This next example demonstrates that through modification
- of the directdisk kickstart file.
+ of the directdisk-gpt kickstart
+ file.
As mentioned earlier, you can use the command
wic list images to show the list
of existing kickstart files.
- The directory in which these files reside is
- scripts/lib/image/canned-wks/
- located in the
- Source Directory.
- Because the available files reside in this directory,
+ The directory in which the
+ directdisk-gpt.wks file resides is
+ scripts/lib/image/canned-wks/,
+ which is located in the
+ Source Directory
+ (e.g. poky).
+ Because available files reside in this directory,
you can create and add your own custom files to the
directory.
Subsequent use of the
@@ -5299,104 +5348,77 @@
In this example, the existing
- directdisk file already does most
- of what is needed.
+ directdisk-gpt file already does
+ most of what is needed.
However, for the hardware in this example, the image
will need to boot from sdb instead
of sda, which is what the
- directdisk kickstart file uses.
+ directdisk-gpt kickstart file
+ uses.
The example begins by making a copy of the
- directdisk.wks file in the
+ directdisk-gpt.wks file in the
scripts/lib/image/canned-wks
directory and then by changing the lines that specify
the target disk from which to boot.
- $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \
- /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
+ $ cp /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \
+ /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
Next, the example modifies the
- directdisksdb.wks file and changes
- all instances of "--ondisk sda"
- to "--ondisk sdb".
+ directdisksdb-gpt.wks file and
+ changes all instances of
+ "--ondisk sda" to
+ "--ondisk sdb".
The example changes the following two lines and leaves
the remaining lines untouched:
part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
- part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
+ part / --source rootfs --ondisk sdb --fstype=ext4 --label platform --align 1024 --use-uuid
Once the lines are changed, the example generates the
- directdisksdb image.
+ directdisksdb-gpt image.
The command points the process at the
core-image-minimal artifacts for
the Next Unit of Computing (nuc)
MACHINE
the local.conf.
- $ wic create directdisksdb -e core-image-minimal
- Checking basic build environment...
- Done.
+ $ wic create directdisksdb-gpt -e core-image-minimal
+ INFO: Building wic-tools...
+ .
+ .
+ .
+ Initialising tasks: 100% |#######################################| Time: 0:00:01
+ NOTE: Executing SetScene Tasks
+ NOTE: Executing RunQueue Tasks
+ NOTE: Tasks Summary: Attempted 1161 tasks of which 1157 didn't need to be rerun and all succeeded.
+ INFO: Creating image(s)...
- Creating image(s)...
-
- Info: The new image(s) can be found here:
- current_directory/build/directdisksdb-201310231131-sdb.direct
+ INFO: The new image(s) can be found here:
+ ./directdisksdb-gpt-201710090938-sdb.direct
The following build artifacts were used to create the image(s):
+ ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.hk3wl6zn/rootfs_copy
+ BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
- ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share
- KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel
- NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
-
- The image(s) were created using OE kickstart file:
- /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
+ INFO: The image(s) were created using OE kickstart file:
+ /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
Continuing with the example, you can now directly
dd the image to a USB stick, or
whatever media for which you built your image,
and boot the resulting media:
- $ sudo dd if=build/directdisksdb-201310231131-sdb.direct of=/dev/sdb
- 86018+0 records in
- 86018+0 records out
- 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s
- [trz at empanada tmp]$ sudo eject /dev/sdb
-
-
-
-
-
- Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename>
-
-
- This example creates an image based on
- core-image-minimal and a
- crownbay-noemgd
- MACHINE
- that works right out of the box.
-
- $ wic create directdisk -e core-image-minimal
-
- Checking basic build environment...
- Done.
-
- Creating image(s)...
-
- Info: The new image(s) can be found here:
- current_directory/build/directdisk-201309252350-sda.direct
-
- The following build artifacts were used to create the image(s):
-
- ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share
- KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
- NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
-
- The image(s) were created using OE kickstart file:
- /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
+ $ sudo dd if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb
+ 140966+0 records in
+ 140966+0 records out
+ 72174592 bytes (72 MB, 69 MiB) copied, 78.0282 s, 925 kB/s
+ $ sudo eject /dev/sdb
@@ -5412,26 +5434,25 @@
somewhere other than the default output directory,
which is the current directory:
- $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \
- /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \
- --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \
- --kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \
- --native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
+ $ wic create /home/scottrif/my_yocto/test.wks -o /home/scottrif/testwic \
+ --rootfs-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
+ --bootimg-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
+ --kernel-dir /home/scottrif/poky/build/tmp/deploy/images/qemux86 \
+ --native-sysroot /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
- Creating image(s)...
+ INFO: Creating image(s)...
- Info: The new image(s) can be found here:
- /home/trz/testwic/build/test-201309260032-sda.direct
+ INFO: The new image(s) can be found here:
+ /home/scottrif/testwic/test-201710091445-sdb.direct
The following build artifacts were used to create the image(s):
+ ROOTFS_DIR: /home/scottrif/testwic/tmp.wic.x4wipbmb/rootfs_copy
+ BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
- ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share
- KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
- NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
-
- The image(s) were created using OE kickstart file:
- /home/trz/test.wks
+ INFO: The image(s) were created using OE kickstart file:
+ /home/scottrif/my_yocto/test.wks
For this example,
MACHINE