1# Copyright (c) 2013, Intel Corporation. 2# 3# SPDX-License-Identifier: GPL-2.0-only 4# 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 16from wic.pluginbase import PluginMgr, PLUGIN_TYPES 17 18logger = logging.getLogger('wic') 19 20def subcommand_error(args): 21 logger.info("invalid subcommand %s", args[0]) 22 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) 35 pager.communicate(hlp.encode('utf-8')) 36 37 return True 38 39 40def wic_help(args, usage_str, subcommands): 41 """ 42 Subcommand help dispatcher. 43 """ 44 if args.help_topic == None or not display_help(args.help_topic, subcommands): 45 print(usage_str) 46 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() 56 for name, plugin in PluginMgr.get_plugins(plugin_type).items(): 57 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 """ 70 if not args.command: 71 logger.error("No subcommand specified, exiting") 72 parser.print_help() 73 return 1 74 elif args.command == "help": 75 wic_help(args, main_command_usage, subcommands) 76 elif args.command not in subcommands: 77 logger.error("Unsupported subcommand %s, exiting\n", args.command) 78 parser.print_help() 79 return 1 80 else: 81 subcmd = subcommands.get(args.command, subcommand_error) 82 usage = subcmd[1] 83 subcmd[0](args, usage) 84 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>] 119 [-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] 122 [-c, --compress-with] [-m, --bmap] 123 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] 143 [-c, --compress-with] [-m, --bmap] [--no-fstab-update] 144 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. 212 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. 215 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. 220""" 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 277wic_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/from the vfat or ext* partition 345 346 usage: wic cp <src> <dest> [--native-sysroot <path>] 347 348 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 353 354 See 'wic help cp' for more detailed instructions. 355 356""" 357 358wic_cp_help = """ 359 360NAME 361 wic cp - copy files and directories to/from the vfat or ext* partitions 362 363SYNOPSIS 364 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> 368 369DESCRIPTION 370 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 373 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 405 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 409 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> 434 wic rm -r <image>:<partition><path> 435 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. 469 470 The -r option is used to remove directories and their contents 471 recursively,this only applies to ext* partition. 472""" 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 494 wic write <image> <target> --expand 1:100M,2:300M 495 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 505 <partition>:<size>[,<partition>:<size>...] for one or more partitions. 506 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 514wic_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/ 539 or lib/wic/plugins/source/ directory in an external layer will 540 also be made available. 541 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 578 do_post_partition() 579 Called after the partition is created. It is useful to add post 580 operations e.g. signing the partition. 581 582 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. 609 Please see the implementation for details. 610""" 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 640 'language' based on Red Hat kickstart syntax). 641 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 843 https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#part-or-partition 844 https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#bootloader 845 846 Commands 847 848 * 'part' or 'partition' 849 850 This command creates a partition on the system and uses the 851 following syntax: 852 853 part [<mountpoint>] 854 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 862 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 868 --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. 873 874 875 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 882 --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 888 --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 --sourceparams: This option is specific to wic. Supply additional 920 parameters to the source plugin in 921 key1=value1,key2 format. 922 923 --ondisk or --ondrive: Forces the partition to be created on 924 a particular disk. 925 926 --fstype: Sets the file system type for the partition. These 927 apply to partitions created using '--source rootfs' (see 928 --source above). Valid values are: 929 930 vfat 931 msdos 932 ext2 933 ext3 934 ext4 935 btrfs 936 squashfs 937 erofs 938 swap 939 none 940 941 --fsoptions: Specifies a free-form string of options to be 942 used when mounting the filesystem. This string 943 will be copied into the /etc/fstab file of the 944 installed system and should be enclosed in 945 quotes. If not specified, the default string is 946 "defaults". 947 948 --fspassno: Specifies the order in which filesystem checks are done 949 at boot time by fsck. See fs_passno parameter of 950 fstab(5). This parameter will be copied into the 951 /etc/fstab file of the installed system. If not 952 specified the default value of "0" will be used. 953 954 --label label: Specifies the label to give to the filesystem 955 to be made on the partition. If the given 956 label is already in use by another filesystem, 957 a new label is created for the partition. 958 959 --use-label: This option is specific to wic. It makes wic to use the 960 label in /etc/fstab to specify a partition. If the 961 --use-label and --use-uuid are used at the same time, 962 we prefer the uuid because it is less likely to cause 963 name confliction. We don't support using this parameter 964 on the root partition since it requires an initramfs to 965 parse this value and we do not currently support that. 966 967 --active: Marks the partition as active. 968 969 --align (in KBytes): This option is specific to wic and says 970 to start a partition on an x KBytes 971 boundary. 972 973 --offset: This option is specific to wic that says to place a partition 974 at exactly the specified offset. If the partition cannot be 975 placed at the specified offset, the image build will fail. 976 Specify as an integer value optionally followed by one of the 977 units s/S for 512 byte sector, k/K for kibibyte, M for 978 mebibyte and G for gibibyte. The default unit if none is 979 given is k. 980 981 --no-table: This option is specific to wic. Space will be 982 reserved for the partition and it will be 983 populated but it will not be added to the 984 partition table. It may be useful for 985 bootloaders. 986 987 --exclude-path: This option is specific to wic. It excludes the given 988 relative path from the resulting image. If the path 989 ends with a slash, only the content of the directory 990 is omitted, not the directory itself. This option only 991 has an effect with the rootfs source plugin. 992 993 --include-path: This option is specific to wic. It adds the contents 994 of the given path or a rootfs to the resulting image. 995 The option contains two fields, the origin and the 996 destination. When the origin is a rootfs, it follows 997 the same logic as the rootfs-dir argument and the 998 permissions and owners are kept. When the origin is a 999 path, it is relative to the directory in which wic is 1000 running not the rootfs itself so use of an absolute 1001 path is recommended, and the owner and group is set to 1002 root:root. If no destination is given it is 1003 automatically set to the root of the rootfs. This 1004 option only has an effect with the rootfs source 1005 plugin. 1006 1007 --change-directory: This option is specific to wic. It changes to the 1008 given directory before copying the files. This 1009 option is useful when we want to split a rootfs in 1010 multiple partitions and we want to keep the right 1011 permissions and usernames in all the partitions. 1012 1013 --no-fstab-update: This option is specific to wic. It does not update the 1014 '/etc/fstab' stock file for the given partition. 1015 1016 --extra-space: This option is specific to wic. It adds extra 1017 space after the space filled by the content 1018 of the partition. The final size can go 1019 beyond the size specified by --size. 1020 By default, 10MB. This option cannot be used 1021 with --fixed-size option. 1022 1023 --overhead-factor: This option is specific to wic. The 1024 size of the partition is multiplied by 1025 this factor. It has to be greater than or 1026 equal to 1. The default value is 1.3. 1027 This option cannot be used with --fixed-size 1028 option. 1029 1030 --part-name: This option is specific to wic. It specifies name for GPT partitions. 1031 1032 --part-type: This option is specific to wic. It specifies partition 1033 type GUID for GPT partitions. 1034 List of partition type GUIDS can be found here: 1035 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs 1036 1037 --use-uuid: This option is specific to wic. It makes wic to generate 1038 random globally unique identifier (GUID) for the partition 1039 and use it in bootloader configuration to specify root partition. 1040 1041 --uuid: This option is specific to wic. It specifies partition UUID. 1042 It's useful if preconfigured partition UUID is added to kernel command line 1043 in bootloader configuration before running wic. In this case .wks file can 1044 be generated or modified to set preconfigured parition UUID using this option. 1045 1046 --fsuuid: This option is specific to wic. It specifies filesystem UUID. 1047 It's useful if preconfigured filesystem UUID is added to kernel command line 1048 in bootloader configuration before running wic. In this case .wks file can 1049 be generated or modified to set preconfigured filesystem UUID using this option. 1050 1051 --system-id: This option is specific to wic. It specifies partition system id. It's useful 1052 for the harware that requires non-default partition system ids. The parameter 1053 in one byte long hex number either with 0x prefix or without it. 1054 1055 --mkfs-extraopts: This option specifies extra options to pass to mkfs utility. 1056 NOTE, that wic uses default options for some filesystems, for example 1057 '-S 512' for mkfs.fat or '-F -i 8192' for mkfs.ext. Those options will 1058 not take effect when --mkfs-extraopts is used. This should be taken into 1059 account when using --mkfs-extraopts. 1060 1061 --type: This option is specific to wic. Valid values are 'primary', 1062 'logical'. For msdos partition tables, this option specifies 1063 the partition type. 1064 1065 --hidden: This option is specific to wic. This option sets the 1066 RequiredPartition bit (bit 0) on GPT partitions. 1067 1068 --mbr: This option is specific to wic. This option is used with the 1069 gpt-hybrid partition type that uses both a GPT partition and 1070 an MBR header. Partitions with this flag will be included in 1071 this MBR header. 1072 1073 * bootloader 1074 1075 This command allows the user to specify various bootloader 1076 options. The following are supported 'bootloader' options: 1077 1078 --timeout: Specifies the number of seconds before the 1079 bootloader times out and boots the default option. 1080 1081 --append: Specifies kernel parameters. These will be added to 1082 bootloader command-line - for example, the syslinux 1083 APPEND or grub kernel command line. 1084 1085 --configfile: Specifies a user defined configuration file for 1086 the bootloader. This file must be located in the 1087 canned-wks folder or could be the full path to the 1088 file. Using this option will override any other 1089 bootloader option. 1090 1091 --ptable: Specifies the partition table format. Valid values are 1092 'msdos', 'gpt', 'gpt-hybrid'. 1093 1094 --source: Specifies the source plugin. If not specified, the 1095 --source value will be copied from the partition that has 1096 /boot as mountpoint. 1097 1098 Note that bootloader functionality and boot partitions are 1099 implemented by the various --source plugins that implement 1100 bootloader functionality; the bootloader command essentially 1101 provides a means of modifying bootloader configuration. 1102 1103 * include 1104 1105 This command allows the user to include the content of .wks file 1106 into original .wks file. 1107 1108 Command uses the following syntax: 1109 1110 include <file> 1111 1112 The <file> is either path to the file or its name. If name is 1113 specified wic will try to find file in the directories with canned 1114 .wks files. 1115 1116""" 1117 1118wic_help_help = """ 1119NAME 1120 wic help - display a help topic 1121 1122DESCRIPTION 1123 Specify a help topic to display it. Topics are shown above. 1124""" 1125 1126 1127wic_help = """ 1128Creates a customized OpenEmbedded image. 1129 1130Usage: wic [--version] 1131 wic help [COMMAND or TOPIC] 1132 wic COMMAND [ARGS] 1133 1134 usage 1: Returns the current version of Wic 1135 usage 2: Returns detailed help for a COMMAND or TOPIC 1136 usage 3: Executes COMMAND 1137 1138 1139COMMAND: 1140 1141 list - List available canned images and source plugins 1142 ls - List contents of partitioned image or partition 1143 rm - Remove files or directories from the vfat or ext* partitions 1144 help - Show help for a wic COMMAND or TOPIC 1145 write - Write an image to a device 1146 cp - Copy files and directories to the vfat or ext* partitions 1147 create - Create a new OpenEmbedded image 1148 1149 1150TOPIC: 1151 overview - Presents an overall overview of Wic 1152 plugins - Presents an overview and API for Wic plugins 1153 kickstart - Presents a Wic kickstart file reference 1154 1155 1156Examples: 1157 1158 $ wic --version 1159 1160 Returns the current version of Wic 1161 1162 1163 $ wic help cp 1164 1165 Returns the SYNOPSIS and DESCRIPTION for the Wic "cp" command. 1166 1167 1168 $ wic list images 1169 1170 Returns the list of canned images (i.e. *.wks files located in 1171 the /scripts/lib/wic/canned-wks directory. 1172 1173 1174 $ wic create mkefidisk -e core-image-minimal 1175 1176 Creates an EFI disk image from artifacts used in a previous 1177 core-image-minimal build in standard BitBake locations 1178 (e.g. Cooked Mode). 1179 1180""" 1181