blob: 664f07a212282cfdb1197239708af610a45b2a1b [file] [log] [blame]
Andrew Geissler517393d2023-01-13 08:55:19 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Creating Partitioned Images Using Wic
4*************************************
5
6Creating an image for a particular hardware target using the
7OpenEmbedded build system does not necessarily mean you can boot that
8image as is on your device. Physical devices accept and boot images in
9various ways depending on the specifics of the device. Usually,
10information about the hardware can tell you what image format the device
11requires. Should your device require multiple partitions on an SD card,
12flash, or an HDD, you can use the OpenEmbedded Image Creator, Wic, to
13create the properly partitioned image.
14
15The ``wic`` command generates partitioned images from existing
16OpenEmbedded build artifacts. Image generation is driven by partitioning
17commands contained in an OpenEmbedded kickstart file (``.wks``)
18specified either directly on the command line or as one of a selection
19of canned kickstart files as shown with the ``wic list images`` command
20in the
21":ref:`dev-manual/wic:generate an image using an existing kickstart file`"
22section. When you apply the command to a given set of build artifacts, the
23result is an image or set of images that can be directly written onto media and
24used on a particular system.
25
26.. note::
27
28 For a kickstart file reference, see the
29 ":ref:`ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference`"
30 Chapter in the Yocto Project Reference Manual.
31
32The ``wic`` command and the infrastructure it is based on is by
33definition incomplete. The purpose of the command is to allow the
34generation of customized images, and as such, was designed to be
35completely extensible through a plugin interface. See the
36":ref:`dev-manual/wic:using the wic plugin interface`" section
37for information on these plugins.
38
39This section provides some background information on Wic, describes what
40you need to have in place to run the tool, provides instruction on how
41to use the Wic utility, provides information on using the Wic plugins
42interface, and provides several examples that show how to use Wic.
43
44Background
45==========
46
47This section provides some background on the Wic utility. While none of
48this information is required to use Wic, you might find it interesting.
49
50- The name "Wic" is derived from OpenEmbedded Image Creator (oeic). The
51 "oe" diphthong in "oeic" was promoted to the letter "w", because
52 "oeic" is both difficult to remember and to pronounce.
53
54- Wic is loosely based on the Meego Image Creator (``mic``) framework.
55 The Wic implementation has been heavily modified to make direct use
56 of OpenEmbedded build artifacts instead of package installation and
57 configuration, which are already incorporated within the OpenEmbedded
58 artifacts.
59
60- Wic is a completely independent standalone utility that initially
61 provides easier-to-use and more flexible replacements for an existing
62 functionality in OE-Core's :ref:`ref-classes-image-live`
63 class. The difference between Wic and those examples is that with Wic
64 the functionality of those scripts is implemented by a
65 general-purpose partitioning language, which is based on Redhat
66 kickstart syntax.
67
68Requirements
69============
70
71In order to use the Wic utility with the OpenEmbedded Build system, your
72system needs to meet the following requirements:
73
74- The Linux distribution on your development host must support the
Patrick Williams8e7b46e2023-05-01 14:19:06 -050075 Yocto Project. See the ":ref:`system-requirements-supported-distros`"
Andrew Geissler517393d2023-01-13 08:55:19 -060076 section in the Yocto Project Reference Manual for the list of
77 distributions that support the Yocto Project.
78
79- The standard system utilities, such as ``cp``, must be installed on
80 your development host system.
81
82- You must have sourced the build environment setup script (i.e.
83 :ref:`structure-core-script`) found in the :term:`Build Directory`.
84
85- You need to have the build artifacts already available, which
86 typically means that you must have already created an image using the
87 OpenEmbedded build system (e.g. ``core-image-minimal``). While it
88 might seem redundant to generate an image in order to create an image
89 using Wic, the current version of Wic requires the artifacts in the
90 form generated by the OpenEmbedded build system.
91
92- You must build several native tools, which are built to run on the
93 build system::
94
Andrew Geissler5082cc72023-09-11 08:41:39 -040095 $ bitbake wic-tools
Andrew Geissler517393d2023-01-13 08:55:19 -060096
97- Include "wic" as part of the
98 :term:`IMAGE_FSTYPES`
99 variable.
100
101- Include the name of the :ref:`wic kickstart file <openembedded-kickstart-wks-reference>`
102 as part of the :term:`WKS_FILE` variable. If multiple candidate files can
103 be provided by different layers, specify all the possible names through the
104 :term:`WKS_FILES` variable instead.
105
106Getting Help
107============
108
109You can get general help for the ``wic`` command by entering the ``wic``
110command by itself or by entering the command with a help argument as
111follows::
112
113 $ wic -h
114 $ wic --help
115 $ wic help
116
117Currently, Wic supports seven commands: ``cp``, ``create``, ``help``,
118``list``, ``ls``, ``rm``, and ``write``. You can get help for all these
119commands except "help" by using the following form::
120
121 $ wic help command
122
123For example, the following command returns help for the ``write``
124command::
125
126 $ wic help write
127
128Wic supports help for three topics: ``overview``, ``plugins``, and
129``kickstart``. You can get help for any topic using the following form::
130
131 $ wic help topic
132
133For example, the following returns overview help for Wic::
134
135 $ wic help overview
136
137There is one additional level of help for Wic. You can get help on
138individual images through the ``list`` command. You can use the ``list``
139command to return the available Wic images as follows::
140
141 $ wic list images
142 genericx86 Create an EFI disk image for genericx86*
143 edgerouter Create SD card image for Edgerouter
144 beaglebone-yocto Create SD card image for Beaglebone
145 qemux86-directdisk Create a qemu machine 'pcbios' direct disk image
146 systemd-bootdisk Create an EFI disk image with systemd-boot
147 mkhybridiso Create a hybrid ISO image
148 mkefidisk Create an EFI disk image
149 sdimage-bootpart Create SD card image with a boot partition
150 directdisk-multi-rootfs Create multi rootfs image using rootfs plugin
151 directdisk Create a 'pcbios' direct disk image
152 directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config
153 qemuriscv Create qcow2 image for RISC-V QEMU machines
154 directdisk-gpt Create a 'pcbios' direct disk image
155 efi-bootdisk
156
157Once you know the list of available
158Wic images, you can use ``help`` with the command to get help on a
159particular image. For example, the following command returns help on the
160"beaglebone-yocto" image::
161
162 $ wic list beaglebone-yocto help
163
164 Creates a partitioned SD card image for Beaglebone.
165 Boot files are located in the first vfat partition.
166
167Operational Modes
168=================
169
170You can use Wic in two different modes, depending on how much control
171you need for specifying the OpenEmbedded build artifacts that are used
172for creating the image: Raw and Cooked:
173
174- *Raw Mode:* You explicitly specify build artifacts through Wic
175 command-line arguments.
176
177- *Cooked Mode:* The current
178 :term:`MACHINE` setting and image
179 name are used to automatically locate and provide the build
180 artifacts. You just supply a kickstart file and the name of the image
181 from which to use artifacts.
182
183Regardless of the mode you use, you need to have the build artifacts
184ready and available.
185
186Raw Mode
187--------
188
189Running Wic in raw mode allows you to specify all the partitions through
190the ``wic`` command line. The primary use for raw mode is if you have
191built your kernel outside of the Yocto Project :term:`Build Directory`.
192In other words, you can point to arbitrary kernel, root filesystem locations,
193and so forth. Contrast this behavior with cooked mode where Wic looks in the
194:term:`Build Directory` (e.g. ``tmp/deploy/images/``\ machine).
195
196The general form of the ``wic`` command in raw mode is::
197
198 $ wic create wks_file options ...
199
200 Where:
201
202 wks_file:
203 An OpenEmbedded kickstart file. You can provide
204 your own custom file or use a file from a set of
205 existing files as described by further options.
206
207 optional arguments:
208 -h, --help show this help message and exit
209 -o OUTDIR, --outdir OUTDIR
210 name of directory to create image in
211 -e IMAGE_NAME, --image-name IMAGE_NAME
212 name of the image to use the artifacts from e.g. core-
213 image-sato
214 -r ROOTFS_DIR, --rootfs-dir ROOTFS_DIR
215 path to the /rootfs dir to use as the .wks rootfs
216 source
217 -b BOOTIMG_DIR, --bootimg-dir BOOTIMG_DIR
218 path to the dir containing the boot artifacts (e.g.
219 /EFI or /syslinux dirs) to use as the .wks bootimg
220 source
221 -k KERNEL_DIR, --kernel-dir KERNEL_DIR
222 path to the dir containing the kernel to use in the
223 .wks bootimg
224 -n NATIVE_SYSROOT, --native-sysroot NATIVE_SYSROOT
225 path to the native sysroot containing the tools to use
226 to build the image
227 -s, --skip-build-check
228 skip the build check
229 -f, --build-rootfs build rootfs
230 -c {gzip,bzip2,xz}, --compress-with {gzip,bzip2,xz}
231 compress image with specified compressor
232 -m, --bmap generate .bmap
233 --no-fstab-update Do not change fstab file.
234 -v VARS_DIR, --vars VARS_DIR
235 directory with <image>.env files that store bitbake
236 variables
237 -D, --debug output debug information
238
239.. note::
240
241 You do not need root privileges to run Wic. In fact, you should not
242 run as root when using the utility.
243
244Cooked Mode
245-----------
246
247Running Wic in cooked mode leverages off artifacts in the
248:term:`Build Directory`. In other words, you do not have to specify kernel or
249root filesystem locations as part of the command. All you need to provide is
250a kickstart file and the name of the image from which to use artifacts
251by using the "-e" option. Wic looks in the :term:`Build Directory` (e.g.
252``tmp/deploy/images/``\ machine) for artifacts.
253
254The general form of the ``wic`` command using Cooked Mode is as follows::
255
256 $ wic create wks_file -e IMAGE_NAME
257
258 Where:
259
260 wks_file:
261 An OpenEmbedded kickstart file. You can provide
262 your own custom file or use a file from a set of
263 existing files provided with the Yocto Project
264 release.
265
266 required argument:
267 -e IMAGE_NAME, --image-name IMAGE_NAME
268 name of the image to use the artifacts from e.g. core-
269 image-sato
270
271Using an Existing Kickstart File
272================================
273
274If you do not want to create your own kickstart file, you can use an
275existing file provided by the Wic installation. As shipped, kickstart
276files can be found in the :ref:`overview-manual/development-environment:yocto project source repositories` in the
277following two locations::
278
279 poky/meta-yocto-bsp/wic
280 poky/scripts/lib/wic/canned-wks
281
282Use the following command to list the available kickstart files::
283
284 $ wic list images
285 genericx86 Create an EFI disk image for genericx86*
286 beaglebone-yocto Create SD card image for Beaglebone
287 edgerouter Create SD card image for Edgerouter
288 qemux86-directdisk Create a QEMU machine 'pcbios' direct disk image
289 directdisk-gpt Create a 'pcbios' direct disk image
290 mkefidisk Create an EFI disk image
291 directdisk Create a 'pcbios' direct disk image
292 systemd-bootdisk Create an EFI disk image with systemd-boot
293 mkhybridiso Create a hybrid ISO image
294 sdimage-bootpart Create SD card image with a boot partition
295 directdisk-multi-rootfs Create multi rootfs image using rootfs plugin
296 directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config
297
298When you use an existing file, you
299do not have to use the ``.wks`` extension. Here is an example in Raw
300Mode that uses the ``directdisk`` file::
301
302 $ wic create directdisk -r rootfs_dir -b bootimg_dir \
303 -k kernel_dir -n native_sysroot
304
305Here are the actual partition language commands used in the
306``genericx86.wks`` file to generate an image::
307
308 # short-description: Create an EFI disk image for genericx86*
309 # long-description: Creates a partitioned EFI disk image for genericx86* machines
310 part /boot --source bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos --active --align 1024
311 part / --source rootfs --ondisk sda --fstype=ext4 --label platform --align 1024 --use-uuid
312 part swap --ondisk sda --size 44 --label swap1 --fstype=swap
313
314 bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0"
315
316Using the Wic Plugin Interface
317==============================
318
319You can extend and specialize Wic functionality by using Wic plugins.
320This section explains the Wic plugin interface.
321
322.. note::
323
324 Wic plugins consist of "source" and "imager" plugins. Imager plugins
325 are beyond the scope of this section.
326
327Source plugins provide a mechanism to customize partition content during
328the Wic image generation process. You can use source plugins to map
329values that you specify using ``--source`` commands in kickstart files
330(i.e. ``*.wks``) to a plugin implementation used to populate a given
331partition.
332
333.. note::
334
335 If you use plugins that have build-time dependencies (e.g. native
336 tools, bootloaders, and so forth) when building a Wic image, you need
337 to specify those dependencies using the :term:`WKS_FILE_DEPENDS`
338 variable.
339
340Source plugins are subclasses defined in plugin files. As shipped, the
341Yocto Project provides several plugin files. You can see the source
342plugin files that ship with the Yocto Project
343:yocto_git:`here </poky/tree/scripts/lib/wic/plugins/source>`.
344Each of these plugin files contains source plugins that are designed to
345populate a specific Wic image partition.
346
347Source plugins are subclasses of the ``SourcePlugin`` class, which is
348defined in the ``poky/scripts/lib/wic/pluginbase.py`` file. For example,
349the ``BootimgEFIPlugin`` source plugin found in the ``bootimg-efi.py``
350file is a subclass of the ``SourcePlugin`` class, which is found in the
351``pluginbase.py`` file.
352
353You can also implement source plugins in a layer outside of the Source
354Repositories (external layer). To do so, be sure that your plugin files
355are located in a directory whose path is
356``scripts/lib/wic/plugins/source/`` within your external layer. When the
357plugin files are located there, the source plugins they contain are made
358available to Wic.
359
360When the Wic implementation needs to invoke a partition-specific
361implementation, it looks for the plugin with the same name as the
362``--source`` parameter used in the kickstart file given to that
363partition. For example, if the partition is set up using the following
364command in a kickstart file::
365
366 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
367
368The methods defined as class
369members of the matching source plugin (i.e. ``bootimg-pcbios``) in the
370``bootimg-pcbios.py`` plugin file are used.
371
372To be more concrete, here is the corresponding plugin definition from
373the ``bootimg-pcbios.py`` file for the previous command along with an
374example method called by the Wic implementation when it needs to prepare
375a partition using an implementation-specific function::
376
377 .
378 .
379 .
380 class BootimgPcbiosPlugin(SourcePlugin):
381 """
382 Create MBR boot partition and install syslinux on it.
383 """
384
385 name = 'bootimg-pcbios'
386 .
387 .
388 .
389 @classmethod
390 def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
391 oe_builddir, bootimg_dir, kernel_dir,
392 rootfs_dir, native_sysroot):
393 """
394 Called to do the actual content population for a partition i.e. it
395 'prepares' the partition to be incorporated into the image.
396 In this case, prepare content for legacy bios boot partition.
397 """
398 .
399 .
400 .
401
402If a
403subclass (plugin) itself does not implement a particular function, Wic
404locates and uses the default version in the superclass. It is for this
405reason that all source plugins are derived from the ``SourcePlugin``
406class.
407
408The ``SourcePlugin`` class defined in the ``pluginbase.py`` file defines
409a set of methods that source plugins can implement or override. Any
410plugins (subclass of ``SourcePlugin``) that do not implement a
411particular method inherit the implementation of the method from the
412``SourcePlugin`` class. For more information, see the ``SourcePlugin``
413class in the ``pluginbase.py`` file for details:
414
415The following list describes the methods implemented in the
416``SourcePlugin`` class:
417
418- ``do_prepare_partition()``: Called to populate a partition with
419 actual content. In other words, the method prepares the final
420 partition image that is incorporated into the disk image.
421
422- ``do_configure_partition()``: Called before
423 ``do_prepare_partition()`` to create custom configuration files for a
424 partition (e.g. syslinux or grub configuration files).
425
426- ``do_install_disk()``: Called after all partitions have been
427 prepared and assembled into a disk image. This method provides a hook
428 to allow finalization of a disk image (e.g. writing an MBR).
429
430- ``do_stage_partition()``: Special content-staging hook called
431 before ``do_prepare_partition()``. This method is normally empty.
432
433 Typically, a partition just uses the passed-in parameters (e.g. the
434 unmodified value of ``bootimg_dir``). However, in some cases, things
435 might need to be more tailored. As an example, certain files might
436 additionally need to be taken from ``bootimg_dir + /boot``. This hook
437 allows those files to be staged in a customized fashion.
438
439 .. note::
440
441 ``get_bitbake_var()`` allows you to access non-standard variables that
442 you might want to use for this behavior.
443
444You can extend the source plugin mechanism. To add more hooks, create
445more source plugin methods within ``SourcePlugin`` and the corresponding
446derived subclasses. The code that calls the plugin methods uses the
447``plugin.get_source_plugin_methods()`` function to find the method or
448methods needed by the call. Retrieval of those methods is accomplished
449by filling up a dict with keys that contain the method names of
450interest. On success, these will be filled in with the actual methods.
451See the Wic implementation for examples and details.
452
453Wic Examples
454============
455
456This section provides several examples that show how to use the Wic
457utility. All the examples assume the list of requirements in the
458":ref:`dev-manual/wic:requirements`" section have been met. The
459examples assume the previously generated image is
460``core-image-minimal``.
461
462Generate an Image using an Existing Kickstart File
463--------------------------------------------------
464
465This example runs in Cooked Mode and uses the ``mkefidisk`` kickstart
466file::
467
468 $ wic create mkefidisk -e core-image-minimal
469 INFO: Building wic-tools...
470 .
471 .
472 .
473 INFO: The new image(s) can be found here:
474 ./mkefidisk-201804191017-sda.direct
475
476 The following build artifacts were used to create the image(s):
477 ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
478 BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
479 KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
480 NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
481
482 INFO: The image(s) were created using OE kickstart file:
483 /home/stephano/yocto/openembedded-core/scripts/lib/wic/canned-wks/mkefidisk.wks
484
485The previous example shows the easiest way to create an image by running
486in cooked mode and supplying a kickstart file and the "-e" option to
487point to the existing build artifacts. Your ``local.conf`` file needs to
488have the :term:`MACHINE` variable set
489to the machine you are using, which is "qemux86" in this example.
490
491Once the image builds, the output provides image location, artifact use,
492and kickstart file information.
493
494.. note::
495
496 You should always verify the details provided in the output to make
497 sure that the image was indeed created exactly as expected.
498
499Continuing with the example, you can now write the image from the
500:term:`Build Directory` onto a USB stick, or whatever media for which you
501built your image, and boot from the media. You can write the image by using
502``bmaptool`` or ``dd``::
503
504 $ oe-run-native bmap-tools-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sdX
505
506or ::
507
508 $ sudo dd if=mkefidisk-201804191017-sda.direct of=/dev/sdX
509
510.. note::
511
512 For more information on how to use the ``bmaptool``
513 to flash a device with an image, see the
514 ":ref:`dev-manual/bmaptool:flashing images using \`\`bmaptool\`\``"
515 section.
516
517Using a Modified Kickstart File
518-------------------------------
519
520Because partitioned image creation is driven by the kickstart file, it
521is easy to affect image creation by changing the parameters in the file.
522This next example demonstrates that through modification of the
523``directdisk-gpt`` kickstart file.
524
525As mentioned earlier, you can use the command ``wic list images`` to
526show the list of existing kickstart files. The directory in which the
527``directdisk-gpt.wks`` file resides is
528``scripts/lib/image/canned-wks/``, which is located in the
529:term:`Source Directory` (e.g. ``poky``).
530Because available files reside in this directory, you can create and add
531your own custom files to the directory. Subsequent use of the
532``wic list images`` command would then include your kickstart files.
533
534In this example, the existing ``directdisk-gpt`` file already does most
535of what is needed. However, for the hardware in this example, the image
536will need to boot from ``sdb`` instead of ``sda``, which is what the
537``directdisk-gpt`` kickstart file uses.
538
539The example begins by making a copy of the ``directdisk-gpt.wks`` file
540in the ``scripts/lib/image/canned-wks`` directory and then by changing
541the lines that specify the target disk from which to boot::
542
543 $ cp /home/stephano/yocto/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \
544 /home/stephano/yocto/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
545
546Next, the example modifies the ``directdisksdb-gpt.wks`` file and
547changes all instances of "``--ondisk sda``" to "``--ondisk sdb``". The
548example changes the following two lines and leaves the remaining lines
549untouched::
550
551 part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
552 part / --source rootfs --ondisk sdb --fstype=ext4 --label platform --align 1024 --use-uuid
553
554Once the lines are changed, the
555example generates the ``directdisksdb-gpt`` image. The command points
556the process at the ``core-image-minimal`` artifacts for the Next Unit of
557Computing (nuc) :term:`MACHINE` the
558``local.conf``::
559
560 $ wic create directdisksdb-gpt -e core-image-minimal
561 INFO: Building wic-tools...
562 .
563 .
564 .
565 Initialising tasks: 100% |#######################################| Time: 0:00:01
566 NOTE: Executing SetScene Tasks
567 NOTE: Executing RunQueue Tasks
568 NOTE: Tasks Summary: Attempted 1161 tasks of which 1157 didn't need to be rerun and all succeeded.
569 INFO: Creating image(s)...
570
571 INFO: The new image(s) can be found here:
572 ./directdisksdb-gpt-201710090938-sdb.direct
573
574 The following build artifacts were used to create the image(s):
575 ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
576 BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
577 KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
578 NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
579
580 INFO: The image(s) were created using OE kickstart file:
581 /home/stephano/yocto/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
582
583Continuing with the example, you can now directly ``dd`` the image to a
584USB stick, or whatever media for which you built your image, and boot
585the resulting media::
586
587 $ sudo dd if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb
588 140966+0 records in
589 140966+0 records out
590 72174592 bytes (72 MB, 69 MiB) copied, 78.0282 s, 925 kB/s
591 $ sudo eject /dev/sdb
592
593Using a Modified Kickstart File and Running in Raw Mode
594-------------------------------------------------------
595
596This next example manually specifies each build artifact (runs in Raw
597Mode) and uses a modified kickstart file. The example also uses the
598``-o`` option to cause Wic to create the output somewhere other than the
599default output directory, which is the current directory::
600
601 $ wic create test.wks -o /home/stephano/testwic \
602 --rootfs-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
603 --bootimg-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
604 --kernel-dir /home/stephano/yocto/build/tmp/deploy/images/qemux86 \
605 --native-sysroot /home/stephano/yocto/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
606
607 INFO: Creating image(s)...
608
609 INFO: The new image(s) can be found here:
610 /home/stephano/testwic/test-201710091445-sdb.direct
611
612 The following build artifacts were used to create the image(s):
613 ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
614 BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
615 KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
616 NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
617
618 INFO: The image(s) were created using OE kickstart file:
619 test.wks
620
621For this example,
622:term:`MACHINE` did not have to be
623specified in the ``local.conf`` file since the artifact is manually
624specified.
625
626Using Wic to Manipulate an Image
627--------------------------------
628
629Wic image manipulation allows you to shorten turnaround time during
630image development. For example, you can use Wic to delete the kernel
631partition of a Wic image and then insert a newly built kernel. This
632saves you time from having to rebuild the entire image each time you
633modify the kernel.
634
635.. note::
636
637 In order to use Wic to manipulate a Wic image as in this example,
638 your development machine must have the ``mtools`` package installed.
639
640The following example examines the contents of the Wic image, deletes
641the existing kernel, and then inserts a new kernel:
642
643#. *List the Partitions:* Use the ``wic ls`` command to list all the
644 partitions in the Wic image::
645
646 $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic
647 Num Start End Size Fstype
648 1 1048576 25041919 23993344 fat16
649 2 25165824 72157183 46991360 ext4
650
651 The previous output shows two partitions in the
652 ``core-image-minimal-qemux86.wic`` image.
653
654#. *Examine a Particular Partition:* Use the ``wic ls`` command again
655 but in a different form to examine a particular partition.
656
657 .. note::
658
659 You can get command usage on any Wic command using the following
660 form::
661
662 $ wic help command
663
664
665 For example, the following command shows you the various ways to
666 use the
667 wic ls
668 command::
669
670 $ wic help ls
671
672
673 The following command shows what is in partition one::
674
675 $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1
676 Volume in drive : is boot
677 Volume Serial Number is E894-1809
678 Directory for ::/
679
680 libcom32 c32 186500 2017-10-09 16:06
681 libutil c32 24148 2017-10-09 16:06
682 syslinux cfg 220 2017-10-09 16:06
683 vesamenu c32 27104 2017-10-09 16:06
684 vmlinuz 6904608 2017-10-09 16:06
685 5 files 7 142 580 bytes
686 16 582 656 bytes free
687
688 The previous output shows five files, with the
689 ``vmlinuz`` being the kernel.
690
691 .. note::
692
693 If you see the following error, you need to update or create a
694 ``~/.mtoolsrc`` file and be sure to have the line "mtools_skip_check=1"
695 in the file. Then, run the Wic command again::
696
697 ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0
698 output: Total number of sectors (47824) not a multiple of sectors per track (32)!
699 Add mtools_skip_check=1 to your .mtoolsrc file to skip this test
700
701
702#. *Remove the Old Kernel:* Use the ``wic rm`` command to remove the
703 ``vmlinuz`` file (kernel)::
704
705 $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz
706
707#. *Add In the New Kernel:* Use the ``wic cp`` command to add the
708 updated kernel to the Wic image. Depending on how you built your
709 kernel, it could be in different places. If you used ``devtool`` and
710 an SDK to build your kernel, it resides in the ``tmp/work`` directory
711 of the extensible SDK. If you used ``make`` to build the kernel, the
712 kernel will be in the ``workspace/sources`` area.
713
714 The following example assumes ``devtool`` was used to build the
715 kernel::
716
717 $ 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 \
718 poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz
719
720 Once the new kernel is added back into the image, you can use the
721 ``dd`` command or :ref:`bmaptool
722 <dev-manual/bmaptool:flashing images using \`\`bmaptool\`\`>`
723 to flash your wic image onto an SD card or USB stick and test your
724 target.
725
726 .. note::
727
728 Using ``bmaptool`` is generally 10 to 20 times faster than using ``dd``.
729