| .. SPDX-License-Identifier: CC-BY-SA-2.0-UK |
| |
| Creating Partitioned Images Using Wic |
| ************************************* |
| |
| Creating an image for a particular hardware target using the |
| OpenEmbedded build system does not necessarily mean you can boot that |
| image as is on your device. Physical devices accept and boot images in |
| various ways depending on the specifics of the device. Usually, |
| information about the hardware can tell you what image format the device |
| requires. Should your device require multiple partitions on an SD card, |
| flash, or an HDD, you can use the OpenEmbedded Image Creator, Wic, to |
| create the properly partitioned image. |
| |
| The ``wic`` command generates partitioned images from existing |
| OpenEmbedded build artifacts. Image generation is driven by partitioning |
| commands contained in an OpenEmbedded kickstart file (``.wks``) |
| specified either directly on the command line or as one of a selection |
| of canned kickstart files as shown with the ``wic list images`` command |
| in the |
| ":ref:`dev-manual/wic:generate an image using an existing kickstart file`" |
| section. When you apply the command 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. |
| |
| .. note:: |
| |
| For a kickstart file reference, see the |
| ":ref:`ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference`" |
| Chapter in the Yocto Project Reference Manual. |
| |
| The ``wic`` command and the infrastructure it is based on is by |
| definition incomplete. The purpose of the command is to allow the |
| generation of customized images, and as such, was designed to be |
| completely extensible through a plugin interface. See the |
| ":ref:`dev-manual/wic:using the wic plugin interface`" section |
| for information on these plugins. |
| |
| 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, provides information on using the Wic plugins |
| interface, and provides several examples that show how to use Wic. |
| |
| Background |
| ========== |
| |
| This section provides some background on the Wic utility. While none of |
| this information is required to use Wic, you might find it interesting. |
| |
| - The name "Wic" is derived from OpenEmbedded Image Creator (oeic). The |
| "oe" diphthong in "oeic" was promoted to the letter "w", because |
| "oeic" is both difficult to remember and to pronounce. |
| |
| - Wic is loosely based on the Meego Image Creator (``mic``) framework. |
| The Wic implementation has been heavily modified to make direct use |
| of OpenEmbedded build artifacts instead of package installation and |
| configuration, which are already incorporated within the OpenEmbedded |
| artifacts. |
| |
| - Wic is a completely independent standalone utility that initially |
| provides easier-to-use and more flexible replacements for an existing |
| functionality in OE-Core's :ref:`ref-classes-image-live` |
| class. The difference between Wic and those examples is that with Wic |
| the functionality of those scripts is implemented by a |
| general-purpose partitioning language, which is based on Redhat |
| kickstart syntax. |
| |
| 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. See the ":ref:`system-requirements-supported-distros`" |
| section in the Yocto Project Reference Manual for the list of |
| distributions that support the Yocto Project. |
| |
| - The standard system utilities, such as ``cp``, must be installed on |
| your development host system. |
| |
| - You must have sourced the build environment setup script (i.e. |
| :ref:`structure-core-script`) found in the :term:`Build Directory`. |
| |
| - You need to have the build artifacts already available, which |
| typically means that you must have already created an image using the |
| OpenEmbedded build system (e.g. ``core-image-minimal``). While it |
| might seem redundant to generate an image in order to create an image |
| using Wic, the current version of Wic requires the artifacts in the |
| form generated by the OpenEmbedded build system. |
| |
| - You must build several native tools, which are built to run on the |
| build system:: |
| |
| $ bitbake wic-tools |
| |
| - Include "wic" as part of the |
| :term:`IMAGE_FSTYPES` |
| variable. |
| |
| - Include the name of the :ref:`wic kickstart file <openembedded-kickstart-wks-reference>` |
| as part of the :term:`WKS_FILE` variable. If multiple candidate files can |
| be provided by different layers, specify all the possible names through the |
| :term:`WKS_FILES` variable instead. |
| |
| Getting Help |
| ============ |
| |
| You can get general help for the ``wic`` command by entering the ``wic`` |
| command by itself or by entering the command with a help argument as |
| follows:: |
| |
| $ wic -h |
| $ wic --help |
| $ wic help |
| |
| Currently, Wic supports seven commands: ``cp``, ``create``, ``help``, |
| ``list``, ``ls``, ``rm``, and ``write``. You can get help for all these |
| commands except "help" by using the following form:: |
| |
| $ wic help command |
| |
| For example, the following command returns help for the ``write`` |
| command:: |
| |
| $ wic help write |
| |
| Wic supports help for three topics: ``overview``, ``plugins``, and |
| ``kickstart``. You can get help for any topic using the following form:: |
| |
| $ wic help topic |
| |
| For example, the following returns overview help for Wic:: |
| |
| $ wic help overview |
| |
| There is one additional level of help for Wic. You can get help on |
| individual images through the ``list`` command. You can use the ``list`` |
| command to return the available Wic images as follows:: |
| |
| $ wic list images |
| genericx86 Create an EFI disk image for genericx86* |
| beaglebone-yocto Create SD card image for Beaglebone |
| qemuriscv Create qcow2 image for RISC-V QEMU machines |
| mkefidisk Create an EFI disk image |
| qemuloongarch Create qcow2 image for LoongArch QEMU machines |
| directdisk-multi-rootfs Create multi rootfs image using rootfs plugin |
| directdisk Create a 'pcbios' direct disk image |
| efi-bootdisk |
| mkhybridiso Create a hybrid ISO image |
| directdisk-gpt Create a 'pcbios' direct disk image |
| systemd-bootdisk Create an EFI disk image with systemd-boot |
| sdimage-bootpart Create SD card image with a boot partition |
| qemux86-directdisk Create a qemu machine 'pcbios' direct disk image |
| directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config |
| |
| Once you know the list of available |
| Wic images, you can use ``help`` with the command to get help on a |
| particular image. For example, the following command returns help on the |
| "beaglebone-yocto" image:: |
| |
| $ wic list beaglebone-yocto help |
| |
| Creates a partitioned SD card image for Beaglebone. |
| Boot files are located in the first vfat partition. |
| |
| Operational Modes |
| ================= |
| |
| You can use Wic in two different modes, depending on how much control |
| you need for specifying the OpenEmbedded build artifacts that are used |
| for creating the image: Raw and Cooked: |
| |
| - *Raw Mode:* You explicitly specify build artifacts through Wic |
| command-line arguments. |
| |
| - *Cooked Mode:* The current |
| :term:`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. |
| |
| Regardless of the mode you use, you need to have the build artifacts |
| ready and available. |
| |
| 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 :term:`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 |
| :term:`Build Directory` (e.g. ``tmp/deploy/images/``\ machine). |
| |
| The general form of the ``wic`` command in raw mode is:: |
| |
| $ wic create wks_file options ... |
| |
| Where: |
| |
| 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. |
| |
| 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 |
| |
| .. note:: |
| |
| You do not need root privileges to run Wic. In fact, you should not |
| run as root when using the utility. |
| |
| Cooked Mode |
| ----------- |
| |
| Running Wic in cooked mode leverages off artifacts in the |
| :term:`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 :term:`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 wks_file -e IMAGE_NAME |
| |
| Where: |
| |
| 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. |
| |
| required argument: |
| -e IMAGE_NAME, --image-name IMAGE_NAME |
| name of the image to use the artifacts from e.g. core- |
| image-sato |
| |
| Using an Existing Kickstart File |
| ================================ |
| |
| 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 :ref:`overview-manual/development-environment: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 |
| genericx86 Create an EFI disk image for genericx86* |
| beaglebone-yocto Create SD card image for Beaglebone |
| qemuriscv Create qcow2 image for RISC-V QEMU machines |
| mkefidisk Create an EFI disk image |
| qemuloongarch Create qcow2 image for LoongArch QEMU machines |
| directdisk-multi-rootfs Create multi rootfs image using rootfs plugin |
| directdisk Create a 'pcbios' direct disk image |
| efi-bootdisk |
| mkhybridiso Create a hybrid ISO image |
| directdisk-gpt Create a 'pcbios' direct disk image |
| systemd-bootdisk Create an EFI disk image with systemd-boot |
| sdimage-bootpart Create SD card image with a boot partition |
| qemux86-directdisk Create a qemu machine 'pcbios' direct disk image |
| 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. Here is an example in Raw |
| Mode that uses the ``directdisk`` file:: |
| |
| $ wic create directdisk -r rootfs_dir -b bootimg_dir \ |
| -k kernel_dir -n native_sysroot |
| |
| Here are the actual partition language commands used in the |
| ``genericx86.wks`` file to generate an image:: |
| |
| # 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 --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0" |
| |
| Using the Wic Plugin Interface |
| ============================== |
| |
| You can extend and specialize Wic functionality by using Wic plugins. |
| This section explains the Wic plugin interface. |
| |
| .. note:: |
| |
| Wic plugins consist of "source" and "imager" plugins. Imager plugins |
| are beyond the scope of this section. |
| |
| Source plugins provide a mechanism to customize partition content during |
| the Wic image generation process. You can use source plugins to map |
| values that you specify using ``--source`` commands in kickstart files |
| (i.e. ``*.wks``) to a plugin implementation used to populate a given |
| partition. |
| |
| .. note:: |
| |
| If you use plugins that have build-time dependencies (e.g. native |
| tools, bootloaders, and so forth) when building a Wic image, you need |
| to specify those dependencies using the :term:`WKS_FILE_DEPENDS` |
| variable. |
| |
| Source plugins are subclasses defined in plugin files. As shipped, the |
| Yocto Project provides several plugin files. You can see the source |
| plugin files that ship with the Yocto Project |
| :yocto_git:`here </poky/tree/scripts/lib/wic/plugins/source>`. |
| Each of these plugin files contains source plugins that are designed to |
| populate a specific Wic image partition. |
| |
| Source plugins are subclasses of the ``SourcePlugin`` class, which is |
| defined in the ``poky/scripts/lib/wic/pluginbase.py`` file. For example, |
| the ``BootimgEFIPlugin`` source plugin found in the ``bootimg-efi.py`` |
| file is a subclass of the ``SourcePlugin`` class, which is found in the |
| ``pluginbase.py`` file. |
| |
| You can also implement source plugins in a layer outside of the Source |
| Repositories (external layer). To do so, be sure that your plugin files |
| are located in a directory whose path is |
| ``scripts/lib/wic/plugins/source/`` within your external layer. When the |
| plugin files are located there, the source plugins they contain are made |
| available to Wic. |
| |
| When the Wic implementation needs to invoke a partition-specific |
| implementation, it looks for the plugin with the same name as the |
| ``--source`` parameter used in the kickstart file given to that |
| partition. For example, if the partition is set up using the following |
| command in a kickstart file:: |
| |
| part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024 |
| |
| The methods defined as class |
| members of the matching source plugin (i.e. ``bootimg-pcbios``) in the |
| ``bootimg-pcbios.py`` plugin file are used. |
| |
| To be more concrete, here is the corresponding plugin definition from |
| the ``bootimg-pcbios.py`` file for the previous command along with an |
| example method called by the Wic implementation when it needs to prepare |
| a partition using an implementation-specific function:: |
| |
| . |
| . |
| . |
| class BootimgPcbiosPlugin(SourcePlugin): |
| """ |
| Create MBR boot partition and install syslinux on it. |
| """ |
| |
| name = 'bootimg-pcbios' |
| . |
| . |
| . |
| @classmethod |
| def do_prepare_partition(cls, part, source_params, creator, cr_workdir, |
| oe_builddir, bootimg_dir, kernel_dir, |
| rootfs_dir, native_sysroot): |
| """ |
| Called to do the actual content population for a partition i.e. it |
| 'prepares' the partition to be incorporated into the image. |
| In this case, prepare content for legacy bios boot partition. |
| """ |
| . |
| . |
| . |
| |
| If a |
| subclass (plugin) itself does not implement a particular function, Wic |
| locates and uses the default version in the superclass. It is for this |
| reason that all source plugins are derived from the ``SourcePlugin`` |
| class. |
| |
| The ``SourcePlugin`` class defined in the ``pluginbase.py`` file defines |
| a set of methods that source plugins can implement or override. Any |
| plugins (subclass of ``SourcePlugin``) that do not implement a |
| particular method inherit the implementation of the method from the |
| ``SourcePlugin`` class. For more information, see the ``SourcePlugin`` |
| class in the ``pluginbase.py`` file for details: |
| |
| The following list describes the methods implemented in the |
| ``SourcePlugin`` class: |
| |
| - ``do_prepare_partition()``: Called to populate a partition with |
| actual content. In other words, the method prepares the final |
| partition image that is incorporated into the disk image. |
| |
| - ``do_configure_partition()``: Called before |
| ``do_prepare_partition()`` to create custom configuration files for a |
| partition (e.g. syslinux or grub configuration files). |
| |
| - ``do_install_disk()``: Called after all partitions have been |
| prepared and assembled into a disk image. This method provides a hook |
| to allow finalization of a disk image (e.g. writing an MBR). |
| |
| - ``do_stage_partition()``: Special content-staging hook called |
| before ``do_prepare_partition()``. This method is normally empty. |
| |
| Typically, a partition just uses the passed-in parameters (e.g. the |
| unmodified value of ``bootimg_dir``). However, in some cases, things |
| might need to be more tailored. As an example, certain files might |
| additionally need to be taken from ``bootimg_dir + /boot``. This hook |
| allows those files to be staged in a customized fashion. |
| |
| .. note:: |
| |
| ``get_bitbake_var()`` allows you to access non-standard variables that |
| you might want to use for this behavior. |
| |
| You can extend the source plugin mechanism. To add more hooks, create |
| more source plugin methods within ``SourcePlugin`` and the corresponding |
| derived subclasses. The code that calls the plugin methods uses the |
| ``plugin.get_source_plugin_methods()`` function to find the method or |
| methods needed by the call. Retrieval of those methods is accomplished |
| by filling up a dict with keys that contain the method names of |
| interest. On success, these will be filled in with the actual methods. |
| See the Wic implementation for examples and details. |
| |
| Wic Examples |
| ============ |
| |
| This section provides several examples that show how to use the Wic |
| utility. All the examples assume the list of requirements in the |
| ":ref:`dev-manual/wic:requirements`" section have been met. The |
| examples assume the previously generated image is |
| ``core-image-minimal``. |
| |
| Generate an Image using an Existing Kickstart File |
| -------------------------------------------------- |
| |
| This example runs in Cooked Mode and uses the ``mkefidisk`` kickstart |
| file:: |
| |
| $ wic create mkefidisk -e core-image-minimal |
| INFO: Building wic-tools... |
| . |
| . |
| . |
| INFO: The new image(s) can be found here: |
| ./mkefidisk-201804191017-sda.direct |
| |
| The following build artifacts were used to create the image(s): |
| ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs |
| BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share |
| KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86 |
| NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native |
| |
| INFO: The image(s) were created using OE kickstart file: |
| /home/stephano/yocto/openembedded-core/scripts/lib/wic/canned-wks/mkefidisk.wks |
| |
| The previous example shows the easiest way to create 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 :term:`MACHINE` variable set |
| to the machine you are using, which is "qemux86" in this example. |
| |
| Once the image builds, the output provides image location, artifact use, |
| and kickstart file information. |
| |
| .. note:: |
| |
| You should always verify the details provided in the output to make |
| sure that the image was indeed created exactly as expected. |
| |
| Continuing with the example, you can now write the image from the |
| :term:`Build Directory` onto a USB stick, or whatever media for which you |
| built your image, and boot from the media. You can write the image by using |
| ``bmaptool`` or ``dd``:: |
| |
| $ oe-run-native bmaptool-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sdX |
| |
| or :: |
| |
| $ sudo dd if=mkefidisk-201804191017-sda.direct of=/dev/sdX |
| |
| .. note:: |
| |
| For more information on how to use the ``bmaptool`` |
| to flash a device with an image, see the |
| ":ref:`dev-manual/bmaptool:flashing images using \`\`bmaptool\`\``" |
| section. |
| |
| 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. |
| This next example demonstrates that through modification 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 the |
| ``directdisk-gpt.wks`` file resides is |
| ``scripts/lib/image/canned-wks/``, which is located in the |
| :term:`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 |
| ``wic list images`` command would then include your kickstart files. |
| |
| In this example, the existing ``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-gpt`` kickstart file uses. |
| |
| The example begins by making a copy of 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/stephano/yocto/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \ |
| /home/stephano/yocto/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks |
| |
| Next, the example modifies the ``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=ext4 --label platform --align 1024 --use-uuid |
| |
| Once the lines are changed, the |
| example generates the ``directdisksdb-gpt`` image. The command points |
| the process at the ``core-image-minimal`` artifacts for the Next Unit of |
| Computing (nuc) :term:`MACHINE` the |
| ``local.conf``:: |
| |
| $ 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/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs |
| BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share |
| KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86 |
| NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native |
| |
| INFO: The image(s) were created using OE kickstart file: |
| /home/stephano/yocto/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=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 |
| |
| Using a Modified Kickstart File and Running in Raw Mode |
| ------------------------------------------------------- |
| |
| This next example manually specifies each build artifact (runs in Raw |
| Mode) and uses a modified kickstart file. The example also uses the |
| ``-o`` option to cause Wic to create the output somewhere other than the |
| default output directory, which is the current directory:: |
| |
| $ wic create test.wks -o /home/stephano/testwic \ |
| --rootfs-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \ |
| --bootimg-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \ |
| --kernel-dir /home/stephano/yocto/build/tmp/deploy/images/qemux86 \ |
| --native-sysroot /home/stephano/yocto/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native |
| |
| INFO: Creating image(s)... |
| |
| INFO: The new image(s) can be found here: |
| /home/stephano/testwic/test-201710091445-sdb.direct |
| |
| The following build artifacts were used to create the image(s): |
| ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs |
| BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share |
| KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86 |
| NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native |
| |
| INFO: The image(s) were created using OE kickstart file: |
| test.wks |
| |
| For this example, |
| :term:`MACHINE` did not have to be |
| specified in the ``local.conf`` file since the artifact is manually |
| specified. |
| |
| Using Wic to Manipulate an Image |
| -------------------------------- |
| |
| Wic image manipulation allows you to shorten turnaround time during |
| image development. For example, you can use Wic to delete the kernel |
| partition of a Wic image and then insert a newly built kernel. This |
| saves you time from having to rebuild the entire image each time you |
| modify the kernel. |
| |
| .. note:: |
| |
| In order to use Wic to manipulate a Wic image as in this example, |
| your development machine must have the ``mtools`` package installed. |
| |
| The following example examines the contents of the Wic image, deletes |
| the existing kernel, and then inserts a new kernel: |
| |
| #. *List the Partitions:* Use the ``wic ls`` command to list all the |
| partitions in the Wic image:: |
| |
| $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic |
| Num Start End Size Fstype |
| 1 1048576 25041919 23993344 fat16 |
| 2 25165824 72157183 46991360 ext4 |
| |
| The previous output shows two partitions in the |
| ``core-image-minimal-qemux86.wic`` image. |
| |
| #. *Examine a Particular Partition:* Use the ``wic ls`` command again |
| but in a different form to examine a particular partition. |
| |
| .. note:: |
| |
| You can get command usage on any Wic command using the following |
| form:: |
| |
| $ wic help command |
| |
| |
| For example, the following command shows you the various ways to |
| use the |
| wic ls |
| command:: |
| |
| $ wic help ls |
| |
| |
| The following command shows what is in partition one:: |
| |
| $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1 |
| Volume in drive : is boot |
| Volume Serial Number is E894-1809 |
| Directory for ::/ |
| |
| libcom32 c32 186500 2017-10-09 16:06 |
| libutil c32 24148 2017-10-09 16:06 |
| syslinux cfg 220 2017-10-09 16:06 |
| vesamenu c32 27104 2017-10-09 16:06 |
| vmlinuz 6904608 2017-10-09 16:06 |
| 5 files 7 142 580 bytes |
| 16 582 656 bytes free |
| |
| The previous output shows five files, with the |
| ``vmlinuz`` being the kernel. |
| |
| .. note:: |
| |
| If you see the following error, you need to update or create a |
| ``~/.mtoolsrc`` file and be sure to have the line "mtools_skip_check=1" |
| in the file. Then, run the Wic command again:: |
| |
| ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0 |
| output: Total number of sectors (47824) not a multiple of sectors per track (32)! |
| Add mtools_skip_check=1 to your .mtoolsrc file to skip this test |
| |
| |
| #. *Remove the Old Kernel:* Use the ``wic rm`` command to remove the |
| ``vmlinuz`` file (kernel):: |
| |
| $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz |
| |
| #. *Add In the New Kernel:* Use the ``wic cp`` command to add the |
| updated kernel to the Wic image. Depending on how you built your |
| kernel, it could be in different places. If you used ``devtool`` and |
| an SDK to build your kernel, it resides in the ``tmp/work`` directory |
| of the extensible SDK. If you used ``make`` to build the kernel, the |
| kernel will be in the ``workspace/sources`` area. |
| |
| The following example assumes ``devtool`` was used to build the |
| kernel:: |
| |
| $ wic cp poky_sdk/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+git999-r0/linux-yocto-4.12.12+git999/arch/x86/boot/bzImage \ |
| poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz |
| |
| Once the new kernel is added back into the image, you can use the |
| ``dd`` command or :ref:`bmaptool |
| <dev-manual/bmaptool:flashing images using \`\`bmaptool\`\`>` |
| to flash your wic image onto an SD card or USB stick and test your |
| target. |
| |
| .. note:: |
| |
| Using ``bmaptool`` is generally 10 to 20 times faster than using ``dd``. |
| |