blob: af7d0576e28c09b8315d822c041ebc5ed28360ad [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001# Copyright (c) 2013, Intel Corporation.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002#
Brad Bishopc342db32019-05-15 21:57:59 -04003# SPDX-License-Identifier: GPL-2.0-only
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004#
5# DESCRIPTION
6# This module implements some basic help invocation functions along
7# with the bulk of the help topic text for the OE Core Image Tools.
8#
9# AUTHORS
10# Tom Zanussi <tom.zanussi (at] linux.intel.com>
11#
12
13import subprocess
14import logging
15
Brad Bishop6e60e8b2018-02-01 10:27:11 -050016from wic.pluginbase import PluginMgr, PLUGIN_TYPES
17
18logger = logging.getLogger('wic')
Patrick Williamsc124f4f2015-09-15 14:41:29 -050019
20def subcommand_error(args):
Brad Bishop6e60e8b2018-02-01 10:27:11 -050021 logger.info("invalid subcommand %s", args[0])
Patrick Williamsc124f4f2015-09-15 14:41:29 -050022
23
24def display_help(subcommand, subcommands):
25 """
26 Display help for subcommand.
27 """
28 if subcommand not in subcommands:
29 return False
30
31 hlp = subcommands.get(subcommand, subcommand_error)[2]
32 if callable(hlp):
33 hlp = hlp()
34 pager = subprocess.Popen('less', stdin=subprocess.PIPE)
Patrick Williamsc0f7c042017-02-23 20:41:17 -060035 pager.communicate(hlp.encode('utf-8'))
Patrick Williamsc124f4f2015-09-15 14:41:29 -050036
37 return True
38
39
40def wic_help(args, usage_str, subcommands):
41 """
42 Subcommand help dispatcher.
43 """
Brad Bishopd7bf8c12018-02-25 22:55:05 -050044 if args.help_topic == None or not display_help(args.help_topic, subcommands):
Patrick Williamsc0f7c042017-02-23 20:41:17 -060045 print(usage_str)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050046
47
48def get_wic_plugins_help():
49 """
50 Combine wic_plugins_help with the help for every known
51 source plugin.
52 """
53 result = wic_plugins_help
54 for plugin_type in PLUGIN_TYPES:
55 result += '\n\n%s PLUGINS\n\n' % plugin_type.upper()
Brad Bishop6e60e8b2018-02-01 10:27:11 -050056 for name, plugin in PluginMgr.get_plugins(plugin_type).items():
Patrick Williamsc124f4f2015-09-15 14:41:29 -050057 result += "\n %s plugin:\n" % name
58 if plugin.__doc__:
59 result += plugin.__doc__
60 else:
61 result += "\n %s is missing docstring\n" % plugin
62 return result
63
64
65def invoke_subcommand(args, parser, main_command_usage, subcommands):
66 """
67 Dispatch to subcommand handler borrowed from combo-layer.
68 Should use argparse, but has to work in 2.6.
69 """
Brad Bishopd7bf8c12018-02-25 22:55:05 -050070 if not args.command:
Brad Bishop6e60e8b2018-02-01 10:27:11 -050071 logger.error("No subcommand specified, exiting")
Patrick Williamsc124f4f2015-09-15 14:41:29 -050072 parser.print_help()
73 return 1
Brad Bishopd7bf8c12018-02-25 22:55:05 -050074 elif args.command == "help":
Patrick Williamsc124f4f2015-09-15 14:41:29 -050075 wic_help(args, main_command_usage, subcommands)
Brad Bishopd7bf8c12018-02-25 22:55:05 -050076 elif args.command not in subcommands:
77 logger.error("Unsupported subcommand %s, exiting\n", args.command)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050078 parser.print_help()
79 return 1
80 else:
Brad Bishopd7bf8c12018-02-25 22:55:05 -050081 subcmd = subcommands.get(args.command, subcommand_error)
82 usage = subcmd[1]
83 subcmd[0](args, usage)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050084
85
86##
87# wic help and usage strings
88##
89
90wic_usage = """
91
92 Create a customized OpenEmbedded image
93
94 usage: wic [--version] | [--help] | [COMMAND [ARGS]]
95
96 Current 'wic' commands are:
97 help Show help for command or one of the topics (see below)
98 create Create a new OpenEmbedded image
99 list List available canned images and source plugins
100
101 Help topics:
102 overview wic overview - General overview of wic
103 plugins wic plugins - Overview and API
104 kickstart wic kickstart - wic kickstart reference
105"""
106
107wic_help_usage = """
108
109 usage: wic help <subcommand>
110
111 This command displays detailed help for the specified subcommand.
112"""
113
114wic_create_usage = """
115
116 Create a new OpenEmbedded image
117
118 usage: wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500119 [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
120 [-r, --rootfs-dir] [-b, --bootimg-dir]
121 [-k, --kernel-dir] [-n, --native-sysroot] [-f, --build-rootfs]
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500122 [-c, --compress-with] [-m, --bmap]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500123
124 This command creates an OpenEmbedded image based on the 'OE kickstart
125 commands' found in the <wks file>.
126
127 The -o option can be used to place the image in a directory with a
128 different name and location.
129
130 See 'wic help create' for more detailed instructions.
131"""
132
133wic_create_help = """
134
135NAME
136 wic create - Create a new OpenEmbedded image
137
138SYNOPSIS
139 wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>]
140 [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
141 [-r, --rootfs-dir] [-b, --bootimg-dir]
142 [-k, --kernel-dir] [-n, --native-sysroot] [-f, --build-rootfs]
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500143 [-c, --compress-with] [-m, --bmap] [--no-fstab-update]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500144
145DESCRIPTION
146 This command creates an OpenEmbedded image based on the 'OE
147 kickstart commands' found in the <wks file>.
148
149 In order to do this, wic needs to know the locations of the
150 various build artifacts required to build the image.
151
152 Users can explicitly specify the build artifact locations using
153 the -r, -b, -k, and -n options. See below for details on where
154 the corresponding artifacts are typically found in a normal
155 OpenEmbedded build.
156
157 Alternatively, users can use the -e option to have 'wic' determine
158 those locations for a given image. If the -e option is used, the
159 user needs to have set the appropriate MACHINE variable in
160 local.conf, and have sourced the build environment.
161
162 The -e option is used to specify the name of the image to use the
163 artifacts from e.g. core-image-sato.
164
165 The -r option is used to specify the path to the /rootfs dir to
166 use as the .wks rootfs source.
167
168 The -b option is used to specify the path to the dir containing
169 the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the
170 .wks bootimg source.
171
172 The -k option is used to specify the path to the dir containing
173 the kernel to use in the .wks bootimg.
174
175 The -n option is used to specify the path to the native sysroot
176 containing the tools to use to build the image.
177
178 The -f option is used to build rootfs by running "bitbake <image>"
179
180 The -s option is used to skip the build check. The build check is
181 a simple sanity check used to determine whether the user has
182 sourced the build environment so that the -e option can operate
183 correctly. If the user has specified the build artifact locations
184 explicitly, 'wic' assumes the user knows what he or she is doing
185 and skips the build check.
186
187 The -D option is used to display debug information detailing
188 exactly what happens behind the scenes when a create request is
189 fulfilled (or not, as the case may be). It enumerates and
190 displays the command sequence used, and should be included in any
191 bug report describing unexpected results.
192
193 When 'wic -e' is used, the locations for the build artifacts
194 values are determined by 'wic -e' from the output of the 'bitbake
195 -e' command given an image name e.g. 'core-image-minimal' and a
196 given machine set in local.conf. In that case, the image is
197 created as if the following 'bitbake -e' variables were used:
198
199 -r: IMAGE_ROOTFS
200 -k: STAGING_KERNEL_DIR
201 -n: STAGING_DIR_NATIVE
202 -b: empty (plugin-specific handlers must determine this)
203
204 If 'wic -e' is not used, the user needs to select the appropriate
205 value for -b (as well as -r, -k, and -n).
206
207 The -o option can be used to place the image in a directory with a
208 different name and location.
209
210 The -c option is used to specify compressor utility to compress
211 an image. gzip, bzip2 and xz compressors are supported.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600212
213 The -m option is used to produce .bmap file for the image. This file
214 can be used to flash image using bmaptool utility.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500215
216 The --no-fstab-update option is used to doesn't change fstab file. When
217 using this option the final fstab file will be same that in rootfs and
218 wic doesn't update file, e.g adding a new mount point. User can control
219 the fstab file content in base-files recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500220"""
221
222wic_list_usage = """
223
224 List available OpenEmbedded images and source plugins
225
226 usage: wic list images
227 wic list <image> help
228 wic list source-plugins
229
230 This command enumerates the set of available canned images as well as
231 help for those images. It also can be used to list of available source
232 plugins.
233
234 The first form enumerates all the available 'canned' images.
235
236 The second form lists the detailed help information for a specific
237 'canned' image.
238
239 The third form enumerates all the available --sources (source
240 plugins).
241
242 See 'wic help list' for more details.
243"""
244
245wic_list_help = """
246
247NAME
248 wic list - List available OpenEmbedded images and source plugins
249
250SYNOPSIS
251 wic list images
252 wic list <image> help
253 wic list source-plugins
254
255DESCRIPTION
256 This command enumerates the set of available canned images as well
257 as help for those images. It also can be used to list available
258 source plugins.
259
260 The first form enumerates all the available 'canned' images.
261 These are actually just the set of .wks files that have been moved
262 into the /scripts/lib/wic/canned-wks directory).
263
264 The second form lists the detailed help information for a specific
265 'canned' image.
266
267 The third form enumerates all the available --sources (source
268 plugins). The contents of a given partition are driven by code
269 defined in 'source plugins'. Users specify a specific plugin via
270 the --source parameter of the partition .wks command. Normally
271 this is the 'rootfs' plugin but can be any of the more specialized
272 sources listed by the 'list source-plugins' command. Users can
273 also add their own source plugins - see 'wic help plugins' for
274 details.
275"""
276
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500277wic_ls_usage = """
278
279 List content of a partitioned image
280
281 usage: wic ls <image>[:<partition>[<path>]] [--native-sysroot <path>]
282
283 This command outputs either list of image partitions or directory contents
284 of vfat and ext* partitions.
285
286 See 'wic help ls' for more detailed instructions.
287
288"""
289
290wic_ls_help = """
291
292NAME
293 wic ls - List contents of partitioned image or partition
294
295SYNOPSIS
296 wic ls <image>
297 wic ls <image>:<vfat or ext* partition>
298 wic ls <image>:<vfat or ext* partition><path>
299 wic ls <image>:<vfat or ext* partition><path> --native-sysroot <path>
300
301DESCRIPTION
302 This command lists either partitions of the image or directory contents
303 of vfat or ext* partitions.
304
305 The first form it lists partitions of the image.
306 For example:
307 $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic
308 Num Start End Size Fstype
309 1 1048576 24438783 23390208 fat16
310 2 25165824 50315263 25149440 ext4
311
312 Second and third form list directory content of the partition:
313 $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
314 Volume in drive : is boot
315 Volume Serial Number is 2DF2-5F02
316 Directory for ::/
317
318 efi <DIR> 2017-05-11 10:54
319 startup nsh 26 2017-05-11 10:54
320 vmlinuz 6922288 2017-05-11 10:54
321 3 files 6 922 314 bytes
322 15 818 752 bytes free
323
324
325 $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/EFI/boot/
326 Volume in drive : is boot
327 Volume Serial Number is 2DF2-5F02
328 Directory for ::/EFI/boot
329
330 . <DIR> 2017-05-11 10:54
331 .. <DIR> 2017-05-11 10:54
332 grub cfg 679 2017-05-11 10:54
333 bootx64 efi 571392 2017-05-11 10:54
334 4 files 572 071 bytes
335 15 818 752 bytes free
336
337 The -n option is used to specify the path to the native sysroot
338 containing the tools(parted and mtools) to use.
339
340"""
341
342wic_cp_usage = """
343
344 Copy files and directories to the vfat or ext* partition
345
346 usage: wic cp <src> <image>:<partition>[<path>] [--native-sysroot <path>]
347
348 This command copies local files or directories to the vfat or ext* partitions
349of partitioned image.
350
351 See 'wic help cp' for more detailed instructions.
352
353"""
354
355wic_cp_help = """
356
357NAME
358 wic cp - copy files and directories to the vfat or ext* partitions
359
360SYNOPSIS
361 wic cp <src> <image>:<partition>
362 wic cp <src> <image>:<partition><path>
363 wic cp <src> <image>:<partition><path> --native-sysroot <path>
364
365DESCRIPTION
366 This command copies files and directories to the vfat or ext* partition of
367 the partitioned image.
368
369 The first form of it copies file or directory to the root directory of
370 the partition:
371 $ wic cp test.wks tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
372 $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
373 Volume in drive : is boot
374 Volume Serial Number is DB4C-FD4C
375 Directory for ::/
376
377 efi <DIR> 2017-05-24 18:15
378 loader <DIR> 2017-05-24 18:15
379 startup nsh 26 2017-05-24 18:15
380 vmlinuz 6926384 2017-05-24 18:15
381 test wks 628 2017-05-24 21:22
382 5 files 6 927 038 bytes
383 15 677 440 bytes free
384
385 The second form of the command copies file or directory to the specified directory
386 on the partition:
387 $ wic cp test tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
388 $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
389 Volume in drive : is boot
390 Volume Serial Number is DB4C-FD4C
391 Directory for ::/efi
392
393 . <DIR> 2017-05-24 18:15
394 .. <DIR> 2017-05-24 18:15
395 boot <DIR> 2017-05-24 18:15
396 test <DIR> 2017-05-24 21:27
397 4 files 0 bytes
398 15 675 392 bytes free
399
400 The -n option is used to specify the path to the native sysroot
401 containing the tools(parted and mtools) to use.
402"""
403
404wic_rm_usage = """
405
406 Remove files or directories from the vfat or ext* partitions
407
408 usage: wic rm <image>:<partition><path> [--native-sysroot <path>]
409
410 This command removes files or directories from the vfat or ext* partitions of
411 the partitioned image.
412
413 See 'wic help rm' for more detailed instructions.
414
415"""
416
417wic_rm_help = """
418
419NAME
420 wic rm - remove files or directories from the vfat or ext* partitions
421
422SYNOPSIS
423 wic rm <src> <image>:<partition><path>
424 wic rm <src> <image>:<partition><path> --native-sysroot <path>
425
426DESCRIPTION
427 This command removes files or directories from the vfat or ext* partition of the
428 partitioned image:
429
430 $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
431 Volume in drive : is boot
432 Volume Serial Number is 11D0-DE21
433 Directory for ::/
434
435 libcom32 c32 186500 2017-06-02 15:15
436 libutil c32 24148 2017-06-02 15:15
437 syslinux cfg 209 2017-06-02 15:15
438 vesamenu c32 27104 2017-06-02 15:15
439 vmlinuz 6926384 2017-06-02 15:15
440 5 files 7 164 345 bytes
441 16 582 656 bytes free
442
443 $ wic rm ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/libutil.c32
444
445 $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
446 Volume in drive : is boot
447 Volume Serial Number is 11D0-DE21
448 Directory for ::/
449
450 libcom32 c32 186500 2017-06-02 15:15
451 syslinux cfg 209 2017-06-02 15:15
452 vesamenu c32 27104 2017-06-02 15:15
453 vmlinuz 6926384 2017-06-02 15:15
454 4 files 7 140 197 bytes
455 16 607 232 bytes free
456
457 The -n option is used to specify the path to the native sysroot
458 containing the tools(parted and mtools) to use.
459"""
460
461wic_write_usage = """
462
463 Write image to a device
464
465 usage: wic write <image> <target device> [--expand [rules]] [--native-sysroot <path>]
466
467 This command writes partitioned image to a target device (USB stick, SD card etc).
468
469 See 'wic help write' for more detailed instructions.
470
471"""
472
473wic_write_help = """
474
475NAME
476 wic write - write an image to a device
477
478SYNOPSIS
479 wic write <image> <target>
480 wic write <image> <target> --expand auto
Brad Bishop64c979e2019-11-04 13:55:29 -0500481 wic write <image> <target> --expand 1:100M,2:300M
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500482 wic write <image> <target> --native-sysroot <path>
483
484DESCRIPTION
485 This command writes an image to a target device (USB stick, SD card etc)
486
487 $ wic write ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic /dev/sdb
488
489 The --expand option is used to resize image partitions.
490 --expand auto expands partitions to occupy all free space available on the target device.
491 It's also possible to specify expansion rules in a format
Brad Bishop64c979e2019-11-04 13:55:29 -0500492 <partition>:<size>[,<partition>:<size>...] for one or more partitions.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500493 Specifying size 0 will keep partition unmodified.
494 Note: Resizing boot partition can result in non-bootable image for non-EFI images. It is
495 recommended to use size 0 for boot partition to keep image bootable.
496
497 The --native-sysroot option is used to specify the path to the native sysroot
498 containing the tools(parted, resize2fs) to use.
499"""
500
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500501wic_plugins_help = """
502
503NAME
504 wic plugins - Overview and API
505
506DESCRIPTION
507 plugins allow wic functionality to be extended and specialized by
508 users. This section documents the plugin interface, which is
509 currently restricted to 'source' plugins.
510
511 'Source' plugins provide a mechanism to customize various aspects
512 of the image generation process in wic, mainly the contents of
513 partitions.
514
515 Source plugins provide a mechanism for mapping values specified in
516 .wks files using the --source keyword to a particular plugin
517 implementation that populates a corresponding partition.
518
519 A source plugin is created as a subclass of SourcePlugin (see
520 scripts/lib/wic/pluginbase.py) and the plugin file containing it
521 is added to scripts/lib/wic/plugins/source/ to make the plugin
522 implementation available to the wic implementation.
523
524 Source plugins can also be implemented and added by external
525 layers - any plugins found in a scripts/lib/wic/plugins/source/
526 directory in an external layer will also be made available.
527
528 When the wic implementation needs to invoke a partition-specific
529 implementation, it looks for the plugin that has the same name as
530 the --source param given to that partition. For example, if the
531 partition is set up like this:
532
533 part /boot --source bootimg-pcbios ...
534
535 then the methods defined as class members of the plugin having the
536 matching bootimg-pcbios .name class member would be used.
537
538 To be more concrete, here's the plugin definition that would match
539 a '--source bootimg-pcbios' usage, along with an example method
540 that would be called by the wic implementation when it needed to
541 invoke an implementation-specific partition-preparation function:
542
543 class BootimgPcbiosPlugin(SourcePlugin):
544 name = 'bootimg-pcbios'
545
546 @classmethod
547 def do_prepare_partition(self, part, ...)
548
549 If the subclass itself doesn't implement a function, a 'default'
550 version in a superclass will be located and used, which is why all
551 plugins must be derived from SourcePlugin.
552
553 The SourcePlugin class defines the following methods, which is the
554 current set of methods that can be implemented/overridden by
555 --source plugins. Any methods not implemented by a SourcePlugin
556 subclass inherit the implementations present in the SourcePlugin
557 class (see the SourcePlugin source for details):
558
559 do_prepare_partition()
560 Called to do the actual content population for a
561 partition. In other words, it 'prepares' the final partition
562 image which will be incorporated into the disk image.
563
Brad Bishop316dfdd2018-06-25 12:45:53 -0400564 do_post_partition()
565 Called after the partition is created. It is useful to add post
566 operations e.g. signing the partition.
567
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500568 do_configure_partition()
569 Called before do_prepare_partition(), typically used to
570 create custom configuration files for a partition, for
571 example syslinux or grub config files.
572
573 do_install_disk()
574 Called after all partitions have been prepared and assembled
575 into a disk image. This provides a hook to allow
576 finalization of a disk image, for example to write an MBR to
577 it.
578
579 do_stage_partition()
580 Special content-staging hook called before
581 do_prepare_partition(), normally empty.
582
583 Typically, a partition will just use the passed-in
584 parameters, for example the unmodified value of bootimg_dir.
585 In some cases however, things may need to be more tailored.
586 As an example, certain files may additionally need to be
587 take from bootimg_dir + /boot. This hook allows those files
588 to be staged in a customized fashion. Note that
589 get_bitbake_var() allows you to access non-standard
590 variables that you might want to use for these types of
591 situations.
592
593 This scheme is extensible - adding more hooks is a simple matter
594 of adding more plugin methods to SourcePlugin and derived classes.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500595 Please see the implementation for details.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500596"""
597
598wic_overview_help = """
599
600NAME
601 wic overview - General overview of wic
602
603DESCRIPTION
604 The 'wic' command generates partitioned images from existing
605 OpenEmbedded build artifacts. Image generation is driven by
606 partitioning commands contained in an 'Openembedded kickstart'
607 (.wks) file (see 'wic help kickstart') specified either directly
608 on the command-line or as one of a selection of canned .wks files
609 (see 'wic list images'). When applied to a given set of build
610 artifacts, the result is an image or set of images that can be
611 directly written onto media and used on a particular system.
612
613 The 'wic' command and the infrastructure it's based on is by
614 definition incomplete - its purpose is to allow the generation of
615 customized images, and as such was designed to be completely
616 extensible via a plugin interface (see 'wic help plugins').
617
618 Background and Motivation
619
620 wic is meant to be a completely independent standalone utility
621 that initially provides easier-to-use and more flexible
622 replacements for a couple bits of existing functionality in
623 oe-core: directdisk.bbclass and mkefidisk.sh. The difference
624 between wic and those examples is that with wic the functionality
625 of those scripts is implemented by a general-purpose partitioning
626 'language' based on Redhat kickstart syntax).
627
628 The initial motivation and design considerations that lead to the
629 current tool are described exhaustively in Yocto Bug #3847
630 (https://bugzilla.yoctoproject.org/show_bug.cgi?id=3847).
631
632 Implementation and Examples
633
634 wic can be used in two different modes, depending on how much
635 control the user needs in specifying the Openembedded build
636 artifacts that will be used in creating the image: 'raw' and
637 'cooked'.
638
639 If used in 'raw' mode, artifacts are explicitly specified via
640 command-line arguments (see example below).
641
642 The more easily usable 'cooked' mode uses the current MACHINE
643 setting and a specified image name to automatically locate the
644 artifacts used to create the image.
645
646 OE kickstart files (.wks) can of course be specified directly on
647 the command-line, but the user can also choose from a set of
648 'canned' .wks files available via the 'wic list images' command
649 (example below).
650
651 In any case, the prerequisite for generating any image is to have
652 the build artifacts already available. The below examples assume
653 the user has already build a 'core-image-minimal' for a specific
654 machine (future versions won't require this redundant step, but
655 for now that's typically how build artifacts get generated).
656
657 The other prerequisite is to source the build environment:
658
659 $ source oe-init-build-env
660
661 To start out with, we'll generate an image from one of the canned
662 .wks files. The following generates a list of availailable
663 images:
664
665 $ wic list images
666 mkefidisk Create an EFI disk image
667 directdisk Create a 'pcbios' direct disk image
668
669 You can get more information about any of the available images by
670 typing 'wic list xxx help', where 'xxx' is one of the image names:
671
672 $ wic list mkefidisk help
673
674 Creates a partitioned EFI disk image that the user can directly dd
675 to boot media.
676
677 At any time, you can get help on the 'wic' command or any
678 subcommand (currently 'list' and 'create'). For instance, to get
679 the description of 'wic create' command and its parameters:
680
681 $ wic create
682
683 Usage:
684
685 Create a new OpenEmbedded image
686
687 usage: wic create <wks file or image name> [-o <DIRNAME> | ...]
688 [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
689 [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
690 [-r, --rootfs-dir] [-b, --bootimg-dir] [-k, --kernel-dir]
691 [-n, --native-sysroot] [-f, --build-rootfs]
692
693 This command creates an OpenEmbedded image based on the 'OE
694 kickstart commands' found in the <wks file>.
695
696 The -o option can be used to place the image in a directory
697 with a different name and location.
698
699 See 'wic help create' for more detailed instructions.
700 ...
701
702 As mentioned in the command, you can get even more detailed
703 information by adding 'help' to the above:
704
705 $ wic help create
706
707 So, the easiest way to create an image is to use the -e option
708 with a canned .wks file. To use the -e option, you need to
709 specify the image used to generate the artifacts and you actually
710 need to have the MACHINE used to build them specified in your
711 local.conf (these requirements aren't necessary if you aren't
712 using the -e options.) Below, we generate a directdisk image,
713 pointing the process at the core-image-minimal artifacts for the
714 current MACHINE:
715
716 $ wic create directdisk -e core-image-minimal
717
718 Checking basic build environment...
719 Done.
720
721 Creating image(s)...
722
723 Info: The new image(s) can be found here:
724 /var/tmp/wic/build/directdisk-201309252350-sda.direct
725
726 The following build artifacts were used to create the image(s):
727
728 ROOTFS_DIR: ...
729 BOOTIMG_DIR: ...
730 KERNEL_DIR: ...
731 NATIVE_SYSROOT: ...
732
733 The image(s) were created using OE kickstart file:
734 .../scripts/lib/wic/canned-wks/directdisk.wks
735
736 The output shows the name and location of the image created, and
737 so that you know exactly what was used to generate the image, each
738 of the artifacts and the kickstart file used.
739
740 Similarly, you can create a 'mkefidisk' image in the same way
741 (notice that this example uses a different machine - because it's
742 using the -e option, you need to change the MACHINE in your
743 local.conf):
744
745 $ wic create mkefidisk -e core-image-minimal
746 Checking basic build environment...
747 Done.
748
749 Creating image(s)...
750
751 Info: The new image(s) can be found here:
752 /var/tmp/wic/build/mkefidisk-201309260027-sda.direct
753
754 ...
755
756 Here's an example that doesn't take the easy way out and manually
757 specifies each build artifact, along with a non-canned .wks file,
758 and also uses the -o option to have wic create the output
759 somewhere other than the default /var/tmp/wic:
760
761 $ wic create ./test.wks -o ./out --rootfs-dir
762 tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
763 --bootimg-dir tmp/sysroots/qemux86-64/usr/share
764 --kernel-dir tmp/deploy/images/qemux86-64
765 --native-sysroot tmp/sysroots/x86_64-linux
766
767 Creating image(s)...
768
769 Info: The new image(s) can be found here:
770 out/build/test-201507211313-sda.direct
771
772 The following build artifacts were used to create the image(s):
773 ROOTFS_DIR: tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
774 BOOTIMG_DIR: tmp/sysroots/qemux86-64/usr/share
775 KERNEL_DIR: tmp/deploy/images/qemux86-64
776 NATIVE_SYSROOT: tmp/sysroots/x86_64-linux
777
778 The image(s) were created using OE kickstart file:
779 ./test.wks
780
781 Here is a content of test.wks:
782
783 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
784 part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
785
786 bootloader --timeout=0 --append="rootwait rootfstype=ext3 video=vesafb vga=0x318 console=tty0"
787
788
789 Finally, here's an example of the actual partition language
790 commands used to generate the mkefidisk image i.e. these are the
791 contents of the mkefidisk.wks OE kickstart file:
792
793 # short-description: Create an EFI disk image
794 # long-description: Creates a partitioned EFI disk image that the user
795 # can directly dd to boot media.
796
797 part /boot --source bootimg-efi --ondisk sda --fstype=efi --active
798
799 part / --source rootfs --ondisk sda --fstype=ext3 --label platform
800
801 part swap --ondisk sda --size 44 --label swap1 --fstype=swap
802
803 bootloader --timeout=10 --append="rootwait console=ttyPCH0,115200"
804
805 You can get a complete listing and description of all the
806 kickstart commands available for use in .wks files from 'wic help
807 kickstart'.
808"""
809
810wic_kickstart_help = """
811
812NAME
813 wic kickstart - wic kickstart reference
814
815DESCRIPTION
816 This section provides the definitive reference to the wic
817 kickstart language. It also provides documentation on the list of
818 --source plugins available for use from the 'part' command (see
819 the 'Platform-specific Plugins' section below).
820
821 The current wic implementation supports only the basic kickstart
822 partitioning commands: partition (or part for short) and
823 bootloader.
824
825 The following is a listing of the commands, their syntax, and
826 meanings. The commands are based on the Fedora kickstart
827 documentation but with modifications to reflect wic capabilities.
828
829 http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
830 http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader
831
832 Commands
833
834 * 'part' or 'partition'
835
836 This command creates a partition on the system and uses the
837 following syntax:
838
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500839 part [<mountpoint>]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500840
841 The <mountpoint> is where the partition will be mounted and
842 must take of one of the following forms:
843
844 /<path>: For example: /, /usr, or /home
845
846 swap: The partition will be used as swap space.
847
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500848 If a <mountpoint> is not specified the partition will be created
849 but will not be mounted.
850
851 Partitions with a <mountpoint> specified will be automatically mounted.
852 This is achieved by wic adding entries to the fstab during image
853 generation. In order for a valid fstab to be generated one of the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800854 --ondrive, --ondisk, --use-uuid or --use-label partition options must
855 be used for each partition that specifies a mountpoint. Note that with
856 --use-{uuid,label} and non-root <mountpoint>, including swap, the mount
857 program must understand the PARTUUID or LABEL syntax. This currently
858 excludes the busybox versions of these applications.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500859
860
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500861 The following are supported 'part' options:
862
863 --size: The minimum partition size. Specify an integer value
864 such as 500. Multipliers k, M ang G can be used. If
865 not specified, the size is in MB.
866 You do not need this option if you use --source.
867
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500868 --fixed-size: Exact partition size. Value format is the same
869 as for --size option. This option cannot be
870 specified along with --size. If partition data
871 is larger than --fixed-size and error will be
872 raised when assembling disk image.
873
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500874 --source: This option is a wic-specific option that names the
875 source of the data that will populate the
876 partition. The most common value for this option
877 is 'rootfs', but can be any value which maps to a
878 valid 'source plugin' (see 'wic help plugins').
879
880 If '--source rootfs' is used, it tells the wic
881 command to create a partition as large as needed
882 and to fill it with the contents of the root
883 filesystem pointed to by the '-r' wic command-line
884 option (or the equivalent rootfs derived from the
885 '-e' command-line option). The filesystem type
886 that will be used to create the partition is driven
887 by the value of the --fstype option specified for
888 the partition (see --fstype below).
889
890 If --source <plugin-name>' is used, it tells the
891 wic command to create a partition as large as
892 needed and to fill with the contents of the
893 partition that will be generated by the specified
894 plugin name using the data pointed to by the '-r'
895 wic command-line option (or the equivalent rootfs
896 derived from the '-e' command-line option).
897 Exactly what those contents and filesystem type end
898 up being are dependent on the given plugin
899 implementation.
900
901 If --source option is not used, the wic command
902 will create empty partition. --size parameter has
903 to be used to specify size of empty partition.
904
905 --ondisk or --ondrive: Forces the partition to be created on
906 a particular disk.
907
908 --fstype: Sets the file system type for the partition. These
909 apply to partitions created using '--source rootfs' (see
910 --source above). Valid values are:
911
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500912 vfat
913 msdos
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500914 ext2
915 ext3
916 ext4
917 btrfs
918 squashfs
919 swap
920
921 --fsoptions: Specifies a free-form string of options to be
922 used when mounting the filesystem. This string
923 will be copied into the /etc/fstab file of the
924 installed system and should be enclosed in
925 quotes. If not specified, the default string is
926 "defaults".
927
928 --label label: Specifies the label to give to the filesystem
929 to be made on the partition. If the given
930 label is already in use by another filesystem,
931 a new label is created for the partition.
932
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800933 --use-label: This option is specific to wic. It makes wic to use the
934 label in /etc/fstab to specify a partition. If the
935 --use-label and --use-uuid are used at the same time,
936 we prefer the uuid because it is less likely to cause
937 name confliction. We don't support using this parameter
938 on the root partition since it requires an initramfs to
939 parse this value and we do not currently support that.
940
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500941 --active: Marks the partition as active.
942
943 --align (in KBytes): This option is specific to wic and says
944 to start a partition on an x KBytes
945 boundary.
946
947 --no-table: This option is specific to wic. Space will be
948 reserved for the partition and it will be
949 populated but it will not be added to the
950 partition table. It may be useful for
951 bootloaders.
952
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500953 --exclude-path: This option is specific to wic. It excludes the given
954 relative path from the resulting image. If the path
955 ends with a slash, only the content of the directory
956 is omitted, not the directory itself. This option only
957 has an effect with the rootfs source plugin.
958
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500959 --extra-space: This option is specific to wic. It adds extra
960 space after the space filled by the content
961 of the partition. The final size can go
962 beyond the size specified by --size.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500963 By default, 10MB. This option cannot be used
964 with --fixed-size option.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500965
966 --overhead-factor: This option is specific to wic. The
967 size of the partition is multiplied by
968 this factor. It has to be greater than or
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500969 equal to 1. The default value is 1.3.
970 This option cannot be used with --fixed-size
971 option.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500972
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500973 --part-name: This option is specific to wic. It specifies name for GPT partitions.
974
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500975 --part-type: This option is specific to wic. It specifies partition
976 type GUID for GPT partitions.
977 List of partition type GUIDS can be found here:
978 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
979
980 --use-uuid: This option is specific to wic. It makes wic to generate
981 random globally unique identifier (GUID) for the partition
982 and use it in bootloader configuration to specify root partition.
983
984 --uuid: This option is specific to wic. It specifies partition UUID.
985 It's useful if preconfigured partition UUID is added to kernel command line
986 in bootloader configuration before running wic. In this case .wks file can
987 be generated or modified to set preconfigured parition UUID using this option.
988
Brad Bishop316dfdd2018-06-25 12:45:53 -0400989 --fsuuid: This option is specific to wic. It specifies filesystem UUID.
990 It's useful if preconfigured filesystem UUID is added to kernel command line
991 in bootloader configuration before running wic. In this case .wks file can
992 be generated or modified to set preconfigured filesystem UUID using this option.
993
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600994 --system-id: This option is specific to wic. It specifies partition system id. It's useful
995 for the harware that requires non-default partition system ids. The parameter
996 in one byte long hex number either with 0x prefix or without it.
997
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500998 --mkfs-extraopts: This option specifies extra options to pass to mkfs utility.
999 NOTE, that wic uses default options for some filesystems, for example
1000 '-S 512' for mkfs.fat or '-F -i 8192' for mkfs.ext. Those options will
1001 not take effect when --mkfs-extraopts is used. This should be taken into
1002 account when using --mkfs-extraopts.
1003
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001004 * bootloader
1005
1006 This command allows the user to specify various bootloader
1007 options. The following are supported 'bootloader' options:
1008
1009 --timeout: Specifies the number of seconds before the
1010 bootloader times out and boots the default option.
1011
1012 --append: Specifies kernel parameters. These will be added to
1013 bootloader command-line - for example, the syslinux
1014 APPEND or grub kernel command line.
1015
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001016 --configfile: Specifies a user defined configuration file for
1017 the bootloader. This file must be located in the
1018 canned-wks folder or could be the full path to the
1019 file. Using this option will override any other
1020 bootloader option.
1021
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001022 Note that bootloader functionality and boot partitions are
1023 implemented by the various --source plugins that implement
1024 bootloader functionality; the bootloader command essentially
1025 provides a means of modifying bootloader configuration.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001026
1027 * include
1028
1029 This command allows the user to include the content of .wks file
1030 into original .wks file.
1031
1032 Command uses the following syntax:
1033
1034 include <file>
1035
1036 The <file> is either path to the file or its name. If name is
1037 specified wic will try to find file in the directories with canned
1038 .wks files.
1039
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001040"""
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001041
1042wic_help_help = """
1043NAME
1044 wic help - display a help topic
1045
1046DESCRIPTION
1047 Specify a help topic to display it. Topics are shown above.
1048"""