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