blob: 163535e4318f61154009915f377a5f82fb335324 [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
Andrew Geissler82c905d2020-04-13 13:39:40 -0500344 Copy files and directories to/from the vfat or ext* partition
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500345
Andrew Geissler82c905d2020-04-13 13:39:40 -0500346 usage: wic cp <src> <dest> [--native-sysroot <path>]
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500347
Andrew Geissler82c905d2020-04-13 13:39:40 -0500348 source/destination image in format <image>:<partition>[<path>]
349
350 This command copies files or directories either
351 - from local to vfat or ext* partitions of partitioned image
352 - from vfat or ext* partitions of partitioned image to local
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500353
354 See 'wic help cp' for more detailed instructions.
355
356"""
357
358wic_cp_help = """
359
360NAME
Andrew Geissler82c905d2020-04-13 13:39:40 -0500361 wic cp - copy files and directories to/from the vfat or ext* partitions
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500362
363SYNOPSIS
Andrew Geissler82c905d2020-04-13 13:39:40 -0500364 wic cp <src> <dest>:<partition>
365 wic cp <src>:<partition> <dest>
366 wic cp <src> <dest-image>:<partition><path>
367 wic cp <src> <dest-image>:<partition><path> --native-sysroot <path>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500368
369DESCRIPTION
Andrew Geissler82c905d2020-04-13 13:39:40 -0500370 This command copies files or directories either
371 - from local to vfat or ext* partitions of partitioned image
372 - from vfat or ext* partitions of partitioned image to local
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500373
374 The first form of it copies file or directory to the root directory of
375 the partition:
376 $ wic cp test.wks tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
377 $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
378 Volume in drive : is boot
379 Volume Serial Number is DB4C-FD4C
380 Directory for ::/
381
382 efi <DIR> 2017-05-24 18:15
383 loader <DIR> 2017-05-24 18:15
384 startup nsh 26 2017-05-24 18:15
385 vmlinuz 6926384 2017-05-24 18:15
386 test wks 628 2017-05-24 21:22
387 5 files 6 927 038 bytes
388 15 677 440 bytes free
389
390 The second form of the command copies file or directory to the specified directory
391 on the partition:
392 $ wic cp test tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
393 $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
394 Volume in drive : is boot
395 Volume Serial Number is DB4C-FD4C
396 Directory for ::/efi
397
398 . <DIR> 2017-05-24 18:15
399 .. <DIR> 2017-05-24 18:15
400 boot <DIR> 2017-05-24 18:15
401 test <DIR> 2017-05-24 21:27
402 4 files 0 bytes
403 15 675 392 bytes free
404
Andrew Geissler82c905d2020-04-13 13:39:40 -0500405 The third form of the command copies file or directory from the specified directory
406 on the partition to local:
407 $ wic cp tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/vmlinuz test
408
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500409 The -n option is used to specify the path to the native sysroot
410 containing the tools(parted and mtools) to use.
411"""
412
413wic_rm_usage = """
414
415 Remove files or directories from the vfat or ext* partitions
416
417 usage: wic rm <image>:<partition><path> [--native-sysroot <path>]
418
419 This command removes files or directories from the vfat or ext* partitions of
420 the partitioned image.
421
422 See 'wic help rm' for more detailed instructions.
423
424"""
425
426wic_rm_help = """
427
428NAME
429 wic rm - remove files or directories from the vfat or ext* partitions
430
431SYNOPSIS
432 wic rm <src> <image>:<partition><path>
433 wic rm <src> <image>:<partition><path> --native-sysroot <path>
Brad Bishop6dbb3162019-11-25 09:41:34 -0500434 wic rm -r <image>:<partition><path>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500435
436DESCRIPTION
437 This command removes files or directories from the vfat or ext* partition of the
438 partitioned image:
439
440 $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
441 Volume in drive : is boot
442 Volume Serial Number is 11D0-DE21
443 Directory for ::/
444
445 libcom32 c32 186500 2017-06-02 15:15
446 libutil c32 24148 2017-06-02 15:15
447 syslinux cfg 209 2017-06-02 15:15
448 vesamenu c32 27104 2017-06-02 15:15
449 vmlinuz 6926384 2017-06-02 15:15
450 5 files 7 164 345 bytes
451 16 582 656 bytes free
452
453 $ wic rm ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/libutil.c32
454
455 $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
456 Volume in drive : is boot
457 Volume Serial Number is 11D0-DE21
458 Directory for ::/
459
460 libcom32 c32 186500 2017-06-02 15:15
461 syslinux cfg 209 2017-06-02 15:15
462 vesamenu c32 27104 2017-06-02 15:15
463 vmlinuz 6926384 2017-06-02 15:15
464 4 files 7 140 197 bytes
465 16 607 232 bytes free
466
467 The -n option is used to specify the path to the native sysroot
468 containing the tools(parted and mtools) to use.
Brad Bishop6dbb3162019-11-25 09:41:34 -0500469
470 The -r option is used to remove directories and their contents
471 recursively,this only applies to ext* partition.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500472"""
473
474wic_write_usage = """
475
476 Write image to a device
477
478 usage: wic write <image> <target device> [--expand [rules]] [--native-sysroot <path>]
479
480 This command writes partitioned image to a target device (USB stick, SD card etc).
481
482 See 'wic help write' for more detailed instructions.
483
484"""
485
486wic_write_help = """
487
488NAME
489 wic write - write an image to a device
490
491SYNOPSIS
492 wic write <image> <target>
493 wic write <image> <target> --expand auto
Brad Bishop64c979e2019-11-04 13:55:29 -0500494 wic write <image> <target> --expand 1:100M,2:300M
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500495 wic write <image> <target> --native-sysroot <path>
496
497DESCRIPTION
498 This command writes an image to a target device (USB stick, SD card etc)
499
500 $ wic write ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic /dev/sdb
501
502 The --expand option is used to resize image partitions.
503 --expand auto expands partitions to occupy all free space available on the target device.
504 It's also possible to specify expansion rules in a format
Brad Bishop64c979e2019-11-04 13:55:29 -0500505 <partition>:<size>[,<partition>:<size>...] for one or more partitions.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500506 Specifying size 0 will keep partition unmodified.
507 Note: Resizing boot partition can result in non-bootable image for non-EFI images. It is
508 recommended to use size 0 for boot partition to keep image bootable.
509
510 The --native-sysroot option is used to specify the path to the native sysroot
511 containing the tools(parted, resize2fs) to use.
512"""
513
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500514wic_plugins_help = """
515
516NAME
517 wic plugins - Overview and API
518
519DESCRIPTION
520 plugins allow wic functionality to be extended and specialized by
521 users. This section documents the plugin interface, which is
522 currently restricted to 'source' plugins.
523
524 'Source' plugins provide a mechanism to customize various aspects
525 of the image generation process in wic, mainly the contents of
526 partitions.
527
528 Source plugins provide a mechanism for mapping values specified in
529 .wks files using the --source keyword to a particular plugin
530 implementation that populates a corresponding partition.
531
532 A source plugin is created as a subclass of SourcePlugin (see
533 scripts/lib/wic/pluginbase.py) and the plugin file containing it
534 is added to scripts/lib/wic/plugins/source/ to make the plugin
535 implementation available to the wic implementation.
536
537 Source plugins can also be implemented and added by external
538 layers - any plugins found in a scripts/lib/wic/plugins/source/
Andrew Geissler82c905d2020-04-13 13:39:40 -0500539 or lib/wic/plugins/source/ directory in an external layer will
540 also be made available.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500541
542 When the wic implementation needs to invoke a partition-specific
543 implementation, it looks for the plugin that has the same name as
544 the --source param given to that partition. For example, if the
545 partition is set up like this:
546
547 part /boot --source bootimg-pcbios ...
548
549 then the methods defined as class members of the plugin having the
550 matching bootimg-pcbios .name class member would be used.
551
552 To be more concrete, here's the plugin definition that would match
553 a '--source bootimg-pcbios' usage, along with an example method
554 that would be called by the wic implementation when it needed to
555 invoke an implementation-specific partition-preparation function:
556
557 class BootimgPcbiosPlugin(SourcePlugin):
558 name = 'bootimg-pcbios'
559
560 @classmethod
561 def do_prepare_partition(self, part, ...)
562
563 If the subclass itself doesn't implement a function, a 'default'
564 version in a superclass will be located and used, which is why all
565 plugins must be derived from SourcePlugin.
566
567 The SourcePlugin class defines the following methods, which is the
568 current set of methods that can be implemented/overridden by
569 --source plugins. Any methods not implemented by a SourcePlugin
570 subclass inherit the implementations present in the SourcePlugin
571 class (see the SourcePlugin source for details):
572
573 do_prepare_partition()
574 Called to do the actual content population for a
575 partition. In other words, it 'prepares' the final partition
576 image which will be incorporated into the disk image.
577
Brad Bishop316dfdd2018-06-25 12:45:53 -0400578 do_post_partition()
579 Called after the partition is created. It is useful to add post
580 operations e.g. signing the partition.
581
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500582 do_configure_partition()
583 Called before do_prepare_partition(), typically used to
584 create custom configuration files for a partition, for
585 example syslinux or grub config files.
586
587 do_install_disk()
588 Called after all partitions have been prepared and assembled
589 into a disk image. This provides a hook to allow
590 finalization of a disk image, for example to write an MBR to
591 it.
592
593 do_stage_partition()
594 Special content-staging hook called before
595 do_prepare_partition(), normally empty.
596
597 Typically, a partition will just use the passed-in
598 parameters, for example the unmodified value of bootimg_dir.
599 In some cases however, things may need to be more tailored.
600 As an example, certain files may additionally need to be
601 take from bootimg_dir + /boot. This hook allows those files
602 to be staged in a customized fashion. Note that
603 get_bitbake_var() allows you to access non-standard
604 variables that you might want to use for these types of
605 situations.
606
607 This scheme is extensible - adding more hooks is a simple matter
608 of adding more plugin methods to SourcePlugin and derived classes.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500609 Please see the implementation for details.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500610"""
611
612wic_overview_help = """
613
614NAME
615 wic overview - General overview of wic
616
617DESCRIPTION
618 The 'wic' command generates partitioned images from existing
619 OpenEmbedded build artifacts. Image generation is driven by
620 partitioning commands contained in an 'Openembedded kickstart'
621 (.wks) file (see 'wic help kickstart') specified either directly
622 on the command-line or as one of a selection of canned .wks files
623 (see 'wic list images'). When applied to a given set of build
624 artifacts, the result is an image or set of images that can be
625 directly written onto media and used on a particular system.
626
627 The 'wic' command and the infrastructure it's based on is by
628 definition incomplete - its purpose is to allow the generation of
629 customized images, and as such was designed to be completely
630 extensible via a plugin interface (see 'wic help plugins').
631
632 Background and Motivation
633
634 wic is meant to be a completely independent standalone utility
635 that initially provides easier-to-use and more flexible
636 replacements for a couple bits of existing functionality in
637 oe-core: directdisk.bbclass and mkefidisk.sh. The difference
638 between wic and those examples is that with wic the functionality
639 of those scripts is implemented by a general-purpose partitioning
Andrew Geisslerd159c7f2021-09-02 21:05:58 -0500640 'language' based on Red Hat kickstart syntax).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500641
642 The initial motivation and design considerations that lead to the
643 current tool are described exhaustively in Yocto Bug #3847
644 (https://bugzilla.yoctoproject.org/show_bug.cgi?id=3847).
645
646 Implementation and Examples
647
648 wic can be used in two different modes, depending on how much
649 control the user needs in specifying the Openembedded build
650 artifacts that will be used in creating the image: 'raw' and
651 'cooked'.
652
653 If used in 'raw' mode, artifacts are explicitly specified via
654 command-line arguments (see example below).
655
656 The more easily usable 'cooked' mode uses the current MACHINE
657 setting and a specified image name to automatically locate the
658 artifacts used to create the image.
659
660 OE kickstart files (.wks) can of course be specified directly on
661 the command-line, but the user can also choose from a set of
662 'canned' .wks files available via the 'wic list images' command
663 (example below).
664
665 In any case, the prerequisite for generating any image is to have
666 the build artifacts already available. The below examples assume
667 the user has already build a 'core-image-minimal' for a specific
668 machine (future versions won't require this redundant step, but
669 for now that's typically how build artifacts get generated).
670
671 The other prerequisite is to source the build environment:
672
673 $ source oe-init-build-env
674
675 To start out with, we'll generate an image from one of the canned
676 .wks files. The following generates a list of availailable
677 images:
678
679 $ wic list images
680 mkefidisk Create an EFI disk image
681 directdisk Create a 'pcbios' direct disk image
682
683 You can get more information about any of the available images by
684 typing 'wic list xxx help', where 'xxx' is one of the image names:
685
686 $ wic list mkefidisk help
687
688 Creates a partitioned EFI disk image that the user can directly dd
689 to boot media.
690
691 At any time, you can get help on the 'wic' command or any
692 subcommand (currently 'list' and 'create'). For instance, to get
693 the description of 'wic create' command and its parameters:
694
695 $ wic create
696
697 Usage:
698
699 Create a new OpenEmbedded image
700
701 usage: wic create <wks file or image name> [-o <DIRNAME> | ...]
702 [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
703 [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
704 [-r, --rootfs-dir] [-b, --bootimg-dir] [-k, --kernel-dir]
705 [-n, --native-sysroot] [-f, --build-rootfs]
706
707 This command creates an OpenEmbedded image based on the 'OE
708 kickstart commands' found in the <wks file>.
709
710 The -o option can be used to place the image in a directory
711 with a different name and location.
712
713 See 'wic help create' for more detailed instructions.
714 ...
715
716 As mentioned in the command, you can get even more detailed
717 information by adding 'help' to the above:
718
719 $ wic help create
720
721 So, the easiest way to create an image is to use the -e option
722 with a canned .wks file. To use the -e option, you need to
723 specify the image used to generate the artifacts and you actually
724 need to have the MACHINE used to build them specified in your
725 local.conf (these requirements aren't necessary if you aren't
726 using the -e options.) Below, we generate a directdisk image,
727 pointing the process at the core-image-minimal artifacts for the
728 current MACHINE:
729
730 $ wic create directdisk -e core-image-minimal
731
732 Checking basic build environment...
733 Done.
734
735 Creating image(s)...
736
737 Info: The new image(s) can be found here:
738 /var/tmp/wic/build/directdisk-201309252350-sda.direct
739
740 The following build artifacts were used to create the image(s):
741
742 ROOTFS_DIR: ...
743 BOOTIMG_DIR: ...
744 KERNEL_DIR: ...
745 NATIVE_SYSROOT: ...
746
747 The image(s) were created using OE kickstart file:
748 .../scripts/lib/wic/canned-wks/directdisk.wks
749
750 The output shows the name and location of the image created, and
751 so that you know exactly what was used to generate the image, each
752 of the artifacts and the kickstart file used.
753
754 Similarly, you can create a 'mkefidisk' image in the same way
755 (notice that this example uses a different machine - because it's
756 using the -e option, you need to change the MACHINE in your
757 local.conf):
758
759 $ wic create mkefidisk -e core-image-minimal
760 Checking basic build environment...
761 Done.
762
763 Creating image(s)...
764
765 Info: The new image(s) can be found here:
766 /var/tmp/wic/build/mkefidisk-201309260027-sda.direct
767
768 ...
769
770 Here's an example that doesn't take the easy way out and manually
771 specifies each build artifact, along with a non-canned .wks file,
772 and also uses the -o option to have wic create the output
773 somewhere other than the default /var/tmp/wic:
774
775 $ wic create ./test.wks -o ./out --rootfs-dir
776 tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
777 --bootimg-dir tmp/sysroots/qemux86-64/usr/share
778 --kernel-dir tmp/deploy/images/qemux86-64
779 --native-sysroot tmp/sysroots/x86_64-linux
780
781 Creating image(s)...
782
783 Info: The new image(s) can be found here:
784 out/build/test-201507211313-sda.direct
785
786 The following build artifacts were used to create the image(s):
787 ROOTFS_DIR: tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
788 BOOTIMG_DIR: tmp/sysroots/qemux86-64/usr/share
789 KERNEL_DIR: tmp/deploy/images/qemux86-64
790 NATIVE_SYSROOT: tmp/sysroots/x86_64-linux
791
792 The image(s) were created using OE kickstart file:
793 ./test.wks
794
795 Here is a content of test.wks:
796
797 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
798 part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
799
800 bootloader --timeout=0 --append="rootwait rootfstype=ext3 video=vesafb vga=0x318 console=tty0"
801
802
803 Finally, here's an example of the actual partition language
804 commands used to generate the mkefidisk image i.e. these are the
805 contents of the mkefidisk.wks OE kickstart file:
806
807 # short-description: Create an EFI disk image
808 # long-description: Creates a partitioned EFI disk image that the user
809 # can directly dd to boot media.
810
811 part /boot --source bootimg-efi --ondisk sda --fstype=efi --active
812
813 part / --source rootfs --ondisk sda --fstype=ext3 --label platform
814
815 part swap --ondisk sda --size 44 --label swap1 --fstype=swap
816
817 bootloader --timeout=10 --append="rootwait console=ttyPCH0,115200"
818
819 You can get a complete listing and description of all the
820 kickstart commands available for use in .wks files from 'wic help
821 kickstart'.
822"""
823
824wic_kickstart_help = """
825
826NAME
827 wic kickstart - wic kickstart reference
828
829DESCRIPTION
830 This section provides the definitive reference to the wic
831 kickstart language. It also provides documentation on the list of
832 --source plugins available for use from the 'part' command (see
833 the 'Platform-specific Plugins' section below).
834
835 The current wic implementation supports only the basic kickstart
836 partitioning commands: partition (or part for short) and
837 bootloader.
838
839 The following is a listing of the commands, their syntax, and
840 meanings. The commands are based on the Fedora kickstart
841 documentation but with modifications to reflect wic capabilities.
842
Andrew Geissler595f6302022-01-24 19:11:47 +0000843 https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#part-or-partition
844 https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#bootloader
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500845
846 Commands
847
848 * 'part' or 'partition'
849
850 This command creates a partition on the system and uses the
851 following syntax:
852
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500853 part [<mountpoint>]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500854
855 The <mountpoint> is where the partition will be mounted and
856 must take of one of the following forms:
857
858 /<path>: For example: /, /usr, or /home
859
860 swap: The partition will be used as swap space.
861
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500862 If a <mountpoint> is not specified the partition will be created
863 but will not be mounted.
864
865 Partitions with a <mountpoint> specified will be automatically mounted.
866 This is achieved by wic adding entries to the fstab during image
867 generation. In order for a valid fstab to be generated one of the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800868 --ondrive, --ondisk, --use-uuid or --use-label partition options must
869 be used for each partition that specifies a mountpoint. Note that with
870 --use-{uuid,label} and non-root <mountpoint>, including swap, the mount
871 program must understand the PARTUUID or LABEL syntax. This currently
872 excludes the busybox versions of these applications.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500873
874
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500875 The following are supported 'part' options:
876
877 --size: The minimum partition size. Specify an integer value
878 such as 500. Multipliers k, M ang G can be used. If
879 not specified, the size is in MB.
880 You do not need this option if you use --source.
881
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500882 --fixed-size: Exact partition size. Value format is the same
883 as for --size option. This option cannot be
884 specified along with --size. If partition data
885 is larger than --fixed-size and error will be
886 raised when assembling disk image.
887
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500888 --source: This option is a wic-specific option that names the
889 source of the data that will populate the
890 partition. The most common value for this option
891 is 'rootfs', but can be any value which maps to a
892 valid 'source plugin' (see 'wic help plugins').
893
894 If '--source rootfs' is used, it tells the wic
895 command to create a partition as large as needed
896 and to fill it with the contents of the root
897 filesystem pointed to by the '-r' wic command-line
898 option (or the equivalent rootfs derived from the
899 '-e' command-line option). The filesystem type
900 that will be used to create the partition is driven
901 by the value of the --fstype option specified for
902 the partition (see --fstype below).
903
904 If --source <plugin-name>' is used, it tells the
905 wic command to create a partition as large as
906 needed and to fill with the contents of the
907 partition that will be generated by the specified
908 plugin name using the data pointed to by the '-r'
909 wic command-line option (or the equivalent rootfs
910 derived from the '-e' command-line option).
911 Exactly what those contents and filesystem type end
912 up being are dependent on the given plugin
913 implementation.
914
915 If --source option is not used, the wic command
916 will create empty partition. --size parameter has
917 to be used to specify size of empty partition.
918
919 --ondisk or --ondrive: Forces the partition to be created on
920 a particular disk.
921
922 --fstype: Sets the file system type for the partition. These
923 apply to partitions created using '--source rootfs' (see
924 --source above). Valid values are:
925
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500926 vfat
927 msdos
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500928 ext2
929 ext3
930 ext4
931 btrfs
932 squashfs
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700933 erofs
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500934 swap
935
936 --fsoptions: Specifies a free-form string of options to be
937 used when mounting the filesystem. This string
938 will be copied into the /etc/fstab file of the
939 installed system and should be enclosed in
940 quotes. If not specified, the default string is
941 "defaults".
942
Andrew Geisslerd5838332022-05-27 11:33:10 -0500943 --fspassno: Specifies the order in which filesystem checks are done
944 at boot time by fsck. See fs_passno parameter of
945 fstab(5). This parameter will be copied into the
946 /etc/fstab file of the installed system. If not
947 specified the default value of "0" will be used.
948
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500949 --label label: Specifies the label to give to the filesystem
950 to be made on the partition. If the given
951 label is already in use by another filesystem,
952 a new label is created for the partition.
953
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800954 --use-label: This option is specific to wic. It makes wic to use the
955 label in /etc/fstab to specify a partition. If the
956 --use-label and --use-uuid are used at the same time,
957 we prefer the uuid because it is less likely to cause
958 name confliction. We don't support using this parameter
959 on the root partition since it requires an initramfs to
960 parse this value and we do not currently support that.
961
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500962 --active: Marks the partition as active.
963
964 --align (in KBytes): This option is specific to wic and says
965 to start a partition on an x KBytes
966 boundary.
967
968 --no-table: This option is specific to wic. Space will be
969 reserved for the partition and it will be
970 populated but it will not be added to the
971 partition table. It may be useful for
972 bootloaders.
973
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500974 --exclude-path: This option is specific to wic. It excludes the given
975 relative path from the resulting image. If the path
976 ends with a slash, only the content of the directory
977 is omitted, not the directory itself. This option only
978 has an effect with the rootfs source plugin.
979
Andrew Geissler82c905d2020-04-13 13:39:40 -0500980 --include-path: This option is specific to wic. It adds the contents
981 of the given path or a rootfs to the resulting image.
982 The option contains two fields, the origin and the
983 destination. When the origin is a rootfs, it follows
984 the same logic as the rootfs-dir argument and the
985 permissions and owners are kept. When the origin is a
986 path, it is relative to the directory in which wic is
987 running not the rootfs itself so use of an absolute
988 path is recommended, and the owner and group is set to
989 root:root. If no destination is given it is
990 automatically set to the root of the rootfs. This
991 option only has an effect with the rootfs source
992 plugin.
993
994 --change-directory: This option is specific to wic. It changes to the
995 given directory before copying the files. This
996 option is useful when we want to split a rootfs in
997 multiple partitions and we want to keep the right
998 permissions and usernames in all the partitions.
999
Andrew Geisslerd159c7f2021-09-02 21:05:58 -05001000 --no-fstab-update: This option is specific to wic. It does not update the
1001 '/etc/fstab' stock file for the given partition.
1002
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001003 --extra-space: This option is specific to wic. It adds extra
1004 space after the space filled by the content
1005 of the partition. The final size can go
1006 beyond the size specified by --size.
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001007 By default, 10MB. This option cannot be used
1008 with --fixed-size option.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001009
1010 --overhead-factor: This option is specific to wic. The
1011 size of the partition is multiplied by
1012 this factor. It has to be greater than or
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001013 equal to 1. The default value is 1.3.
1014 This option cannot be used with --fixed-size
1015 option.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001016
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001017 --part-name: This option is specific to wic. It specifies name for GPT partitions.
1018
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001019 --part-type: This option is specific to wic. It specifies partition
1020 type GUID for GPT partitions.
1021 List of partition type GUIDS can be found here:
1022 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
1023
1024 --use-uuid: This option is specific to wic. It makes wic to generate
1025 random globally unique identifier (GUID) for the partition
1026 and use it in bootloader configuration to specify root partition.
1027
1028 --uuid: This option is specific to wic. It specifies partition UUID.
1029 It's useful if preconfigured partition UUID is added to kernel command line
1030 in bootloader configuration before running wic. In this case .wks file can
1031 be generated or modified to set preconfigured parition UUID using this option.
1032
Brad Bishop316dfdd2018-06-25 12:45:53 -04001033 --fsuuid: This option is specific to wic. It specifies filesystem UUID.
1034 It's useful if preconfigured filesystem UUID is added to kernel command line
1035 in bootloader configuration before running wic. In this case .wks file can
1036 be generated or modified to set preconfigured filesystem UUID using this option.
1037
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001038 --system-id: This option is specific to wic. It specifies partition system id. It's useful
1039 for the harware that requires non-default partition system ids. The parameter
1040 in one byte long hex number either with 0x prefix or without it.
1041
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001042 --mkfs-extraopts: This option specifies extra options to pass to mkfs utility.
1043 NOTE, that wic uses default options for some filesystems, for example
1044 '-S 512' for mkfs.fat or '-F -i 8192' for mkfs.ext. Those options will
1045 not take effect when --mkfs-extraopts is used. This should be taken into
1046 account when using --mkfs-extraopts.
1047
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001048 * bootloader
1049
1050 This command allows the user to specify various bootloader
1051 options. The following are supported 'bootloader' options:
1052
1053 --timeout: Specifies the number of seconds before the
1054 bootloader times out and boots the default option.
1055
1056 --append: Specifies kernel parameters. These will be added to
1057 bootloader command-line - for example, the syslinux
1058 APPEND or grub kernel command line.
1059
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001060 --configfile: Specifies a user defined configuration file for
1061 the bootloader. This file must be located in the
1062 canned-wks folder or could be the full path to the
1063 file. Using this option will override any other
1064 bootloader option.
1065
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001066 Note that bootloader functionality and boot partitions are
1067 implemented by the various --source plugins that implement
1068 bootloader functionality; the bootloader command essentially
1069 provides a means of modifying bootloader configuration.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001070
1071 * include
1072
1073 This command allows the user to include the content of .wks file
1074 into original .wks file.
1075
1076 Command uses the following syntax:
1077
1078 include <file>
1079
1080 The <file> is either path to the file or its name. If name is
1081 specified wic will try to find file in the directories with canned
1082 .wks files.
1083
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001084"""
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001085
1086wic_help_help = """
1087NAME
1088 wic help - display a help topic
1089
1090DESCRIPTION
1091 Specify a help topic to display it. Topics are shown above.
1092"""
Brad Bishop1d80a2e2019-11-15 16:35:03 -05001093
1094
1095wic_help = """
1096Creates a customized OpenEmbedded image.
1097
1098Usage: wic [--version]
1099 wic help [COMMAND or TOPIC]
1100 wic COMMAND [ARGS]
1101
1102 usage 1: Returns the current version of Wic
1103 usage 2: Returns detailed help for a COMMAND or TOPIC
1104 usage 3: Executes COMMAND
1105
1106
1107COMMAND:
1108
1109 list - List available canned images and source plugins
1110 ls - List contents of partitioned image or partition
1111 rm - Remove files or directories from the vfat or ext* partitions
1112 help - Show help for a wic COMMAND or TOPIC
1113 write - Write an image to a device
1114 cp - Copy files and directories to the vfat or ext* partitions
1115 create - Create a new OpenEmbedded image
1116
1117
1118TOPIC:
1119 overview - Presents an overall overview of Wic
1120 plugins - Presents an overview and API for Wic plugins
Andrew Geissler20137392023-10-12 04:59:14 -06001121 kickstart - Presents a Wic kickstart file reference
Brad Bishop1d80a2e2019-11-15 16:35:03 -05001122
1123
1124Examples:
1125
1126 $ wic --version
1127
1128 Returns the current version of Wic
1129
1130
1131 $ wic help cp
1132
1133 Returns the SYNOPSIS and DESCRIPTION for the Wic "cp" command.
1134
1135
1136 $ wic list images
1137
1138 Returns the list of canned images (i.e. *.wks files located in
1139 the /scripts/lib/wic/canned-wks directory.
1140
1141
1142 $ wic create mkefidisk -e core-image-minimal
1143
1144 Creates an EFI disk image from artifacts used in a previous
1145 core-image-minimal build in standard BitBake locations
1146 (e.g. Cooked Mode).
1147
1148"""