From e746cc1c65bc4c4e3ce06e9a63b6897d82a6bb64 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 9 Oct 2017 12:31:18 -0700 Subject: dev-manual: Updated Wic Kicstart examples. (From yocto-docs rev: b5393e416c779aa9d4f5116cdea8d5fd09c21bd1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 453 +++++++++++---------- 1 file changed, 237 insertions(+), 216 deletions(-) (limited to 'documentation') 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_file options ... 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. - - Creating image(s)... - - Info: The new image(s) can be found here: - current_directory/build/directdisksdb-201310231131-sdb.direct + $ 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)... + + 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 -- cgit v1.2.3-54-g00ecf