summaryrefslogtreecommitdiffstats
path: root/scripts/lib/wic/help.py
blob: bf658b94e34fd9136820387c90a8402a6a2d9d66 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
# ex:ts=4:sw=4:sts=4:et
# -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
#
# Copyright (c) 2013, Intel Corporation.
# All rights reserved.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License version 2 as
# published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
#
# DESCRIPTION
# This module implements some basic help invocation functions along
# with the bulk of the help topic text for the OE Core Image Tools.
#
# AUTHORS
# Tom Zanussi <tom.zanussi (at] linux.intel.com>
#

import subprocess
import logging

from wic.pluginbase import PluginMgr, PLUGIN_TYPES

logger = logging.getLogger('wic')

def subcommand_error(args):
    logger.info("invalid subcommand %s", args[0])


def display_help(subcommand, subcommands):
    """
    Display help for subcommand.
    """
    if subcommand not in subcommands:
        return False

    hlp = subcommands.get(subcommand, subcommand_error)[2]
    if callable(hlp):
        hlp = hlp()
    pager = subprocess.Popen('less', stdin=subprocess.PIPE)
    pager.communicate(hlp.encode('utf-8'))

    return True


def wic_help(args, usage_str, subcommands):
    """
    Subcommand help dispatcher.
    """
    if args.help_topic == None or not display_help(args.help_topic, subcommands):
        print(usage_str)


def get_wic_plugins_help():
    """
    Combine wic_plugins_help with the help for every known
    source plugin.
    """
    result = wic_plugins_help
    for plugin_type in PLUGIN_TYPES:
        result += '\n\n%s PLUGINS\n\n' % plugin_type.upper()
        for name, plugin in PluginMgr.get_plugins(plugin_type).items():
            result += "\n %s plugin:\n" % name
            if plugin.__doc__:
                result += plugin.__doc__
            else:
                result += "\n    %s is missing docstring\n" % plugin
    return result


def invoke_subcommand(args, parser, main_command_usage, subcommands):
    """
    Dispatch to subcommand handler borrowed from combo-layer.
    Should use argparse, but has to work in 2.6.
    """
    if not args.command:
        logger.error("No subcommand specified, exiting")
        parser.print_help()
        return 1
    elif args.command == "help":
        wic_help(args, main_command_usage, subcommands)
    elif args.command not in subcommands:
        logger.error("Unsupported subcommand %s, exiting\n", args.command)
        parser.print_help()
        return 1
    else:
        subcmd = subcommands.get(args.command, subcommand_error)
        usage = subcmd[1]
        subcmd[0](args, usage)


##
# wic help and usage strings
##

wic_usage = """

 Create a customized OpenEmbedded image

 usage: wic [--version] | [--help] | [COMMAND [ARGS]]

 Current 'wic' commands are:
    help              Show help for command or one of the topics (see below)
    create            Create a new OpenEmbedded image
    list              List available canned images and source plugins

 Help topics:
    overview          wic overview - General overview of wic
    plugins           wic plugins - Overview and API
    kickstart         wic kickstart - wic kickstart reference
"""

wic_help_usage = """

 usage: wic help <subcommand>

 This command displays detailed help for the specified subcommand.
"""

wic_create_usage = """

 Create a new OpenEmbedded image

 usage: wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>]
            [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
            [-r, --rootfs-dir] [-b, --bootimg-dir]
            [-k, --kernel-dir] [-n, --native-sysroot] [-f, --build-rootfs]
            [-c, --compress-with] [-m, --bmap]

 This command creates an OpenEmbedded image based on the 'OE kickstart
 commands' found in the <wks file>.

 The -o option can be used to place the image in a directory with a
 different name and location.

 See 'wic help create' for more detailed instructions.
"""

wic_create_help = """

NAME
    wic create - Create a new OpenEmbedded image

SYNOPSIS
    wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>]
        [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
        [-r, --rootfs-dir] [-b, --bootimg-dir]
        [-k, --kernel-dir] [-n, --native-sysroot] [-f, --build-rootfs]
        [-c, --compress-with] [-m, --bmap] [--no-fstab-update]

DESCRIPTION
    This command creates an OpenEmbedded image based on the 'OE
    kickstart commands' found in the <wks file>.

    In order to do this, wic needs to know the locations of the
    various build artifacts required to build the image.

    Users can explicitly specify the build artifact locations using
    the -r, -b, -k, and -n options.  See below for details on where
    the corresponding artifacts are typically found in a normal
    OpenEmbedded build.

    Alternatively, users can use the -e option to have 'wic' determine
    those locations for a given image.  If the -e option is used, the
    user needs to have set the appropriate MACHINE variable in
    local.conf, and have sourced the build environment.

    The -e option is used to specify the name of the image to use the
    artifacts from e.g. core-image-sato.

    The -r option is used to specify the path to the /rootfs dir to
    use as the .wks rootfs source.

    The -b option is used to specify the path to the dir containing
    the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the
    .wks bootimg source.

    The -k option is used to specify the path to the dir containing
    the kernel to use in the .wks bootimg.

    The -n option is used to specify the path to the native sysroot
    containing the tools to use to build the image.

    The -f option is used to build rootfs by running "bitbake <image>"

    The -s option is used to skip the build check.  The build check is
    a simple sanity check used to determine whether the user has
    sourced the build environment so that the -e option can operate
    correctly.  If the user has specified the build artifact locations
    explicitly, 'wic' assumes the user knows what he or she is doing
    and skips the build check.

    The -D option is used to display debug information detailing
    exactly what happens behind the scenes when a create request is
    fulfilled (or not, as the case may be).  It enumerates and
    displays the command sequence used, and should be included in any
    bug report describing unexpected results.

    When 'wic -e' is used, the locations for the build artifacts
    values are determined by 'wic -e' from the output of the 'bitbake
    -e' command given an image name e.g. 'core-image-minimal' and a
    given machine set in local.conf.  In that case, the image is
    created as if the following 'bitbake -e' variables were used:

    -r:        IMAGE_ROOTFS
    -k:        STAGING_KERNEL_DIR
    -n:        STAGING_DIR_NATIVE
    -b:        empty (plugin-specific handlers must determine this)

    If 'wic -e' is not used, the user needs to select the appropriate
    value for -b (as well as -r, -k, and -n).

    The -o option can be used to place the image in a directory with a
    different name and location.

    The -c option is used to specify compressor utility to compress
    an image. gzip, bzip2 and xz compressors are supported.

    The -m option is used to produce .bmap file for the image. This file
    can be used to flash image using bmaptool utility.

    The --no-fstab-update option is used to doesn't change fstab file. When
    using this option the final fstab file will be same that in rootfs and
    wic doesn't update file, e.g adding a new mount point. User can control
    the fstab file content in base-files recipe.
"""

wic_list_usage = """

 List available OpenEmbedded images and source plugins

 usage: wic list images
        wic list <image> help
        wic list source-plugins

 This command enumerates the set of available canned images as well as
 help for those images.  It also can be used to list of available source
 plugins.

 The first form enumerates all the available 'canned' images.

 The second form lists the detailed help information for a specific
 'canned' image.

 The third form enumerates all the available --sources (source
 plugins).

 See 'wic help list' for more details.
"""

wic_list_help = """

NAME
    wic list - List available OpenEmbedded images and source plugins

SYNOPSIS
    wic list images
    wic list <image> help
    wic list source-plugins

DESCRIPTION
    This command enumerates the set of available canned images as well
    as help for those images.  It also can be used to list available
    source plugins.

    The first form enumerates all the available 'canned' images.
    These are actually just the set of .wks files that have been moved
    into the /scripts/lib/wic/canned-wks directory).

    The second form lists the detailed help information for a specific
    'canned' image.

    The third form enumerates all the available --sources (source
    plugins).  The contents of a given partition are driven by code
    defined in 'source plugins'.  Users specify a specific plugin via
    the --source parameter of the partition .wks command.  Normally
    this is the 'rootfs' plugin but can be any of the more specialized
    sources listed by the 'list source-plugins' command.  Users can
    also add their own source plugins - see 'wic help plugins' for
    details.
"""

wic_ls_usage = """

 List content of a partitioned image

 usage: wic ls <image>[:<partition>[<path>]] [--native-sysroot <path>]

 This command  outputs either list of image partitions or directory contents
 of vfat and ext* partitions.

 See 'wic help ls' for more detailed instructions.

"""

wic_ls_help = """

NAME
    wic ls - List contents of partitioned image or partition

SYNOPSIS
    wic ls <image>
    wic ls <image>:<vfat or ext* partition>
    wic ls <image>:<vfat or ext* partition><path>
    wic ls <image>:<vfat or ext* partition><path> --native-sysroot <path>

DESCRIPTION
    This command lists either partitions of the image or directory contents
    of vfat or ext* partitions.

    The first form it lists partitions of the image.
    For example:
        $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic
        Num     Start        End          Size      Fstype
        1        1048576     24438783     23390208  fat16
        2       25165824     50315263     25149440  ext4

    Second and third form list directory content of the partition:
        $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
        Volume in drive : is boot
         Volume Serial Number is 2DF2-5F02
        Directory for ::/

        efi          <DIR>     2017-05-11  10:54
        startup  nsh        26 2017-05-11  10:54
        vmlinuz        6922288 2017-05-11  10:54
                3 files           6 922 314 bytes
                                 15 818 752 bytes free


        $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/EFI/boot/
        Volume in drive : is boot
         Volume Serial Number is 2DF2-5F02
        Directory for ::/EFI/boot

        .            <DIR>     2017-05-11  10:54
        ..           <DIR>     2017-05-11  10:54
        grub     cfg       679 2017-05-11  10:54
        bootx64  efi    571392 2017-05-11  10:54
                4 files             572 071 bytes
                                 15 818 752 bytes free

    The -n option is used to specify the path to the native sysroot
    containing the tools(parted and mtools) to use.

"""

wic_cp_usage = """

 Copy files and directories to the vfat or ext* partition

 usage: wic cp <src> <image>:<partition>[<path>] [--native-sysroot <path>]

 This command  copies local files or directories to the vfat or ext* partitions
of partitioned  image.

 See 'wic help cp' for more detailed instructions.

"""

wic_cp_help = """

NAME
    wic cp - copy files and directories to the vfat or ext* partitions

SYNOPSIS
    wic cp <src> <image>:<partition>
    wic cp <src> <image>:<partition><path>
    wic cp <src> <image>:<partition><path> --native-sysroot <path>

DESCRIPTION
    This command copies files and directories to the vfat or ext* partition of
    the partitioned image.

    The first form of it copies file or directory to the root directory of
    the partition:
        $ wic cp test.wks tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
        $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
        Volume in drive : is boot
         Volume Serial Number is DB4C-FD4C
        Directory for ::/

        efi          <DIR>     2017-05-24  18:15
        loader       <DIR>     2017-05-24  18:15
        startup  nsh        26 2017-05-24  18:15
        vmlinuz        6926384 2017-05-24  18:15
        test     wks       628 2017-05-24  21:22
                5 files           6 927 038 bytes
                                 15 677 440 bytes free

    The second form of the command copies file or directory to the specified directory
    on the partition:
       $ wic cp test tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
       $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
       Volume in drive : is boot
        Volume Serial Number is DB4C-FD4C
       Directory for ::/efi

       .            <DIR>     2017-05-24  18:15
       ..           <DIR>     2017-05-24  18:15
       boot         <DIR>     2017-05-24  18:15
       test         <DIR>     2017-05-24  21:27
               4 files                   0 bytes
                                15 675 392 bytes free

    The -n option is used to specify the path to the native sysroot
    containing the tools(parted and mtools) to use.
"""

wic_rm_usage = """

 Remove files or directories from the vfat or ext* partitions

 usage: wic rm <image>:<partition><path> [--native-sysroot <path>]

 This command  removes files or directories from the vfat or ext* partitions of
 the partitioned image.

 See 'wic help rm' for more detailed instructions.

"""

wic_rm_help = """

NAME
    wic rm - remove files or directories from the vfat or ext* partitions

SYNOPSIS
    wic rm <src> <image>:<partition><path>
    wic rm <src> <image>:<partition><path> --native-sysroot <path>

DESCRIPTION
    This command removes files or directories from the vfat or ext* partition of the
    partitioned image:

        $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
        Volume in drive : is boot
         Volume Serial Number is 11D0-DE21
        Directory for ::/

        libcom32 c32    186500 2017-06-02  15:15
        libutil  c32     24148 2017-06-02  15:15
        syslinux cfg       209 2017-06-02  15:15
        vesamenu c32     27104 2017-06-02  15:15
        vmlinuz        6926384 2017-06-02  15:15
                5 files           7 164 345 bytes
                                 16 582 656 bytes free

        $ wic rm ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/libutil.c32

        $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
        Volume in drive : is boot
         Volume Serial Number is 11D0-DE21
        Directory for ::/

        libcom32 c32    186500 2017-06-02  15:15
        syslinux cfg       209 2017-06-02  15:15
        vesamenu c32     27104 2017-06-02  15:15
        vmlinuz        6926384 2017-06-02  15:15
                4 files           7 140 197 bytes
                                 16 607 232 bytes free

    The -n option is used to specify the path to the native sysroot
    containing the tools(parted and mtools) to use.
"""

wic_write_usage = """

 Write image to a device

 usage: wic write <image> <target device> [--expand [rules]] [--native-sysroot <path>]

 This command writes partitioned image to a target device (USB stick, SD card etc).

 See 'wic help write' for more detailed instructions.

"""

wic_write_help = """

NAME
    wic write - write an image to a device

SYNOPSIS
    wic write <image> <target>
    wic write <image> <target> --expand auto
    wic write <image> <target> --expand 1:100M-2:300M
    wic write <image> <target> --native-sysroot <path>

DESCRIPTION
    This command writes an image to a target device (USB stick, SD card etc)

        $ wic write ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic /dev/sdb

    The --expand option is used to resize image partitions.
    --expand auto expands partitions to occupy all free space available on the target device.
    It's also possible to specify expansion rules in a format
    <partition>:<size>[-<partition>:<size>...] for one or more partitions.
    Specifying size 0 will keep partition unmodified.
    Note: Resizing boot partition can result in non-bootable image for non-EFI images. It is
    recommended to use size 0 for boot partition to keep image bootable.

    The --native-sysroot option is used to specify the path to the native sysroot
    containing the tools(parted, resize2fs) to use.
"""

wic_plugins_help = """

NAME
    wic plugins - Overview and API

DESCRIPTION
    plugins allow wic functionality to be extended and specialized by
    users.  This section documents the plugin interface, which is
    currently restricted to 'source' plugins.

    'Source' plugins provide a mechanism to customize various aspects
    of the image generation process in wic, mainly the contents of
    partitions.

    Source plugins provide a mechanism for mapping values specified in
    .wks files using the --source keyword to a particular plugin
    implementation that populates a corresponding partition.

    A source plugin is created as a subclass of SourcePlugin (see
    scripts/lib/wic/pluginbase.py) and the plugin file containing it
    is added to scripts/lib/wic/plugins/source/ to make the plugin
    implementation available to the wic implementation.

    Source plugins can also be implemented and added by external
    layers - any plugins found in a scripts/lib/wic/plugins/source/
    directory in an external layer will also be made available.

    When the wic implementation needs to invoke a partition-specific
    implementation, it looks for the plugin that has the same name as
    the --source param given to that partition.  For example, if the
    partition is set up like this:

      part /boot --source bootimg-pcbios   ...

    then the methods defined as class members of the plugin having the
    matching bootimg-pcbios .name class member would be used.

    To be more concrete, here's the plugin definition that would match
    a '--source bootimg-pcbios' usage, along with an example method
    that would be called by the wic implementation when it needed to
    invoke an implementation-specific partition-preparation function:

    class BootimgPcbiosPlugin(SourcePlugin):
        name = 'bootimg-pcbios'

    @classmethod
        def do_prepare_partition(self, part, ...)

    If the subclass itself doesn't implement a function, a 'default'
    version in a superclass will be located and used, which is why all
    plugins must be derived from SourcePlugin.

    The SourcePlugin class defines the following methods, which is the
    current set of methods that can be implemented/overridden by
    --source plugins.  Any methods not implemented by a SourcePlugin
    subclass inherit the implementations present in the SourcePlugin
    class (see the SourcePlugin source for details):

      do_prepare_partition()
          Called to do the actual content population for a
          partition. In other words, it 'prepares' the final partition
          image which will be incorporated into the disk image.

      do_configure_partition()
          Called before do_prepare_partition(), typically used to
          create custom configuration files for a partition, for
          example syslinux or grub config files.

      do_install_disk()
          Called after all partitions have been prepared and assembled
          into a disk image.  This provides a hook to allow
          finalization of a disk image, for example to write an MBR to
          it.

      do_stage_partition()
          Special content-staging hook called before
          do_prepare_partition(), normally empty.

          Typically, a partition will just use the passed-in
          parameters, for example the unmodified value of bootimg_dir.
          In some cases however, things may need to be more tailored.
          As an example, certain files may additionally need to be
          take from bootimg_dir + /boot.  This hook allows those files
          to be staged in a customized fashion.  Note that
          get_bitbake_var() allows you to access non-standard
          variables that you might want to use for these types of
          situations.

    This scheme is extensible - adding more hooks is a simple matter
    of adding more plugin methods to SourcePlugin and derived classes.
    Please see the implementation for details.
"""

wic_overview_help = """

NAME
    wic overview - General overview of wic

DESCRIPTION
    The 'wic' command generates partitioned images from existing
    OpenEmbedded build artifacts.  Image generation is driven by
    partitioning commands contained in an 'Openembedded kickstart'
    (.wks) file (see 'wic help kickstart') specified either directly
    on the command-line or as one of a selection of canned .wks files
    (see 'wic list images').  When applied to a given set of build
    artifacts, the result is an image or set of images that can be
    directly written onto media and used on a particular system.

    The 'wic' command and the infrastructure it's based on is by
    definition incomplete - its purpose is to allow the generation of
    customized images, and as such was designed to be completely
    extensible via a plugin interface (see 'wic help plugins').

  Background and Motivation

    wic is meant to be a completely independent standalone utility
    that initially provides easier-to-use and more flexible
    replacements for a couple bits of existing functionality in
    oe-core: directdisk.bbclass and mkefidisk.sh.  The difference
    between wic and those examples is that with wic the functionality
    of those scripts is implemented by a general-purpose partitioning
    'language' based on Redhat kickstart syntax).

    The initial motivation and design considerations that lead to the
    current tool are described exhaustively in Yocto Bug #3847
    (https://bugzilla.yoctoproject.org/show_bug.cgi?id=3847).

  Implementation and Examples

    wic can be used in two different modes, depending on how much
    control the user needs in specifying the Openembedded build
    artifacts that will be used in creating the image: 'raw' and
    'cooked'.

    If used in 'raw' mode, artifacts are explicitly specified via
    command-line arguments (see example below).

    The more easily usable 'cooked' mode uses the current MACHINE
    setting and a specified image name to automatically locate the
    artifacts used to create the image.

    OE kickstart files (.wks) can of course be specified directly on
    the command-line, but the user can also choose from a set of
    'canned' .wks files available via the 'wic list images' command
    (example below).

    In any case, the prerequisite for generating any image is to have
    the build artifacts already available.  The below examples assume
    the user has already build a 'core-image-minimal' for a specific
    machine (future versions won't require this redundant step, but
    for now that's typically how build artifacts get generated).

    The other prerequisite is to source the build environment:

      $ source oe-init-build-env

    To start out with, we'll generate an image from one of the canned
    .wks files.  The following generates a list of availailable
    images:

      $ wic list images
        mkefidisk             Create an EFI disk image
        directdisk            Create a 'pcbios' direct disk image

    You can get more information about any of the available images by
    typing 'wic list xxx help', where 'xxx' is one of the image names:

      $ wic list mkefidisk help

    Creates a partitioned EFI disk image that the user can directly dd
    to boot media.

    At any time, you can get help on the 'wic' command or any
    subcommand (currently 'list' and 'create').  For instance, to get
    the description of 'wic create' command and its parameters:

      $ wic create

       Usage:

       Create a new OpenEmbedded image

       usage: wic create <wks file or image name> [-o <DIRNAME> | ...]
            [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
            [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
            [-r, --rootfs-dir] [-b, --bootimg-dir] [-k, --kernel-dir]
            [-n, --native-sysroot] [-f, --build-rootfs]

       This command creates an OpenEmbedded image based on the 'OE
       kickstart commands' found in the <wks file>.

       The -o option can be used to place the image in a directory
       with a different name and location.

       See 'wic help create' for more detailed instructions.
       ...

    As mentioned in the command, you can get even more detailed
    information by adding 'help' to the above:

      $ wic help create

    So, the easiest way to create an image is to use the -e option
    with a canned .wks file.  To use the -e option, you need to
    specify the image used to generate the artifacts and you actually
    need to have the MACHINE used to build them specified in your
    local.conf (these requirements aren't necessary if you aren't
    using the -e options.)  Below, we generate a directdisk image,
    pointing the process at the core-image-minimal artifacts for the
    current MACHINE:

      $ wic create directdisk -e core-image-minimal

      Checking basic build environment...
      Done.

      Creating image(s)...

      Info: The new image(s) can be found here:
      /var/tmp/wic/build/directdisk-201309252350-sda.direct

      The following build artifacts were used to create the image(s):

      ROOTFS_DIR:      ...
      BOOTIMG_DIR:     ...
      KERNEL_DIR:      ...
      NATIVE_SYSROOT:  ...

      The image(s) were created using OE kickstart file:
        .../scripts/lib/wic/canned-wks/directdisk.wks

    The output shows the name and location of the image created, and
    so that you know exactly what was used to generate the image, each
    of the artifacts and the kickstart file used.

    Similarly, you can create a 'mkefidisk' image in the same way
    (notice that this example uses a different machine - because it's
    using the -e option, you need to change the MACHINE in your
    local.conf):

      $ wic create mkefidisk -e core-image-minimal
      Checking basic build environment...
      Done.

      Creating image(s)...

      Info: The new image(s) can be found here:
         /var/tmp/wic/build/mkefidisk-201309260027-sda.direct

      ...

    Here's an example that doesn't take the easy way out and manually
    specifies each build artifact, along with a non-canned .wks file,
    and also uses the -o option to have wic create the output
    somewhere other than the default /var/tmp/wic:

      $ wic create ./test.wks -o ./out --rootfs-dir
      tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
      --bootimg-dir tmp/sysroots/qemux86-64/usr/share
      --kernel-dir tmp/deploy/images/qemux86-64
      --native-sysroot tmp/sysroots/x86_64-linux

     Creating image(s)...

     Info: The new image(s) can be found here:
           out/build/test-201507211313-sda.direct

     The following build artifacts were used to create the image(s):
       ROOTFS_DIR:                   tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
       BOOTIMG_DIR:                  tmp/sysroots/qemux86-64/usr/share
       KERNEL_DIR:                   tmp/deploy/images/qemux86-64
       NATIVE_SYSROOT:               tmp/sysroots/x86_64-linux

     The image(s) were created using OE kickstart file:
     ./test.wks

     Here is a content of test.wks:

     part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
     part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024

     bootloader  --timeout=0  --append="rootwait rootfstype=ext3 video=vesafb vga=0x318 console=tty0"


    Finally, here's an example of the actual partition language
    commands used to generate the mkefidisk image i.e. these are the
    contents of the mkefidisk.wks OE kickstart file:

      # short-description: Create an EFI disk image
      # long-description: Creates a partitioned EFI disk image that the user
      # can directly dd to boot media.

      part /boot --source bootimg-efi --ondisk sda --fstype=efi --active

      part / --source rootfs --ondisk sda --fstype=ext3 --label platform

      part swap --ondisk sda --size 44 --label swap1 --fstype=swap

      bootloader  --timeout=10  --append="rootwait console=ttyPCH0,115200"

    You can get a complete listing and description of all the
    kickstart commands available for use in .wks files from 'wic help
    kickstart'.
"""

wic_kickstart_help = """

NAME
    wic kickstart - wic kickstart reference

DESCRIPTION
    This section provides the definitive reference to the wic
    kickstart language.  It also provides documentation on the list of
    --source plugins available for use from the 'part' command (see
    the 'Platform-specific Plugins' section below).

    The current wic implementation supports only the basic kickstart
    partitioning commands: partition (or part for short) and
    bootloader.

    The following is a listing of the commands, their syntax, and
    meanings. The commands are based on the Fedora kickstart
    documentation but with modifications to reflect wic capabilities.

      http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
      http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader

  Commands

    * 'part' or 'partition'

       This command creates a partition on the system and uses the
       following syntax:

         part [<mountpoint>]

       The <mountpoint> is where the partition will be mounted and
       must take of one of the following forms:

         /<path>: For example: /, /usr, or /home

         swap: The partition will be used as swap space.

       If a <mountpoint> is not specified the partition will be created
       but will not be mounted.

       Partitions with a <mountpoint> specified will be automatically mounted.
       This is achieved by wic adding entries to the fstab during image
       generation. In order for a valid fstab to be generated one of the
       --ondrive, --ondisk or --use-uuid partition options must be used for
       each partition that specifies a mountpoint.  Note that with --use-uuid
       and non-root <mountpoint>, including swap, the mount program must
       understand the PARTUUID syntax.  This currently excludes the busybox
       versions of these applications.


       The following are supported 'part' options:

         --size: The minimum partition size. Specify an integer value
                 such as 500. Multipliers k, M ang G can be used. If
                 not specified, the size is in MB.
                 You do not need this option if you use --source.

         --fixed-size: Exact partition size. Value format is the same
                       as for --size option. This option cannot be
                       specified along with --size. If partition data
                       is larger than --fixed-size and error will be
                       raised when assembling disk image.

         --source: This option is a wic-specific option that names the
                   source of the data that will populate the
                   partition.  The most common value for this option
                   is 'rootfs', but can be any value which maps to a
                   valid 'source plugin' (see 'wic help plugins').

                   If '--source rootfs' is used, it tells the wic
                   command to create a partition as large as needed
                   and to fill it with the contents of the root
                   filesystem pointed to by the '-r' wic command-line
                   option (or the equivalent rootfs derived from the
                   '-e' command-line option).  The filesystem type
                   that will be used to create the partition is driven
                   by the value of the --fstype option specified for
                   the partition (see --fstype below).

                   If --source <plugin-name>' is used, it tells the
                   wic command to create a partition as large as
                   needed and to fill with the contents of the
                   partition that will be generated by the specified
                   plugin name using the data pointed to by the '-r'
                   wic command-line option (or the equivalent rootfs
                   derived from the '-e' command-line option).
                   Exactly what those contents and filesystem type end
                   up being are dependent on the given plugin
                   implementation.

                   If --source option is not used, the wic command
                   will create empty partition. --size parameter has
                   to be used to specify size of empty partition.

         --ondisk or --ondrive: Forces the partition to be created on
                                a particular disk.

         --fstype: Sets the file system type for the partition.  These
           apply to partitions created using '--source rootfs' (see
           --source above).  Valid values are:

             vfat
             msdos
             ext2
             ext3
             ext4
             btrfs
             squashfs
             swap

         --fsoptions: Specifies a free-form string of options to be
                      used when mounting the filesystem. This string
                      will be copied into the /etc/fstab file of the
                      installed system and should be enclosed in
                      quotes.  If not specified, the default string is
                      "defaults".

         --label label: Specifies the label to give to the filesystem
                        to be made on the partition. If the given
                        label is already in use by another filesystem,
                        a new label is created for the partition.

         --active: Marks the partition as active.

         --align (in KBytes): This option is specific to wic and says
                              to start a partition on an x KBytes
                              boundary.

         --no-table: This option is specific to wic. Space will be
                     reserved for the partition and it will be
                     populated but it will not be added to the
                     partition table. It may be useful for
                     bootloaders.

         --exclude-path: This option is specific to wic. It excludes the given
                         relative path from the resulting image. If the path
                         ends with a slash, only the content of the directory
                         is omitted, not the directory itself. This option only
                         has an effect with the rootfs source plugin.

         --extra-space: This option is specific to wic. It adds extra
                        space after the space filled by the content
                        of the partition. The final size can go
                        beyond the size specified by --size.
                        By default, 10MB. This option cannot be used
                        with --fixed-size option.

         --overhead-factor: This option is specific to wic. The
                            size of the partition is multiplied by
                            this factor. It has to be greater than or
                            equal to 1. The default value is 1.3.
                            This option cannot be used with --fixed-size
                            option.

         --part-name: This option is specific to wic. It specifies name for GPT partitions.

         --part-type: This option is specific to wic. It specifies partition
                      type GUID for GPT partitions.
                      List of partition type GUIDS can be found here:
                      http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs

         --use-uuid: This option is specific to wic. It makes wic to generate
                     random globally unique identifier (GUID) for the partition
                     and use it in bootloader configuration to specify root partition.

         --uuid: This option is specific to wic. It specifies partition UUID.
                 It's useful if preconfigured partition UUID is added to kernel command line
                 in bootloader configuration before running wic. In this case .wks file can
                 be generated or modified to set preconfigured parition UUID using this option.

         --fsuuid: This option is specific to wic. It specifies filesystem UUID.
                   It's useful if preconfigured filesystem UUID is added to kernel command line
                   in bootloader configuration before running wic. In this case .wks file can
                   be generated or modified to set preconfigured filesystem UUID using this option.

         --system-id: This option is specific to wic. It specifies partition system id. It's useful
                      for the harware that requires non-default partition system ids. The parameter
                      in one byte long hex number either with 0x prefix or without it.

         --mkfs-extraopts: This option specifies extra options to pass to mkfs utility.
                           NOTE, that wic uses default options for some filesystems, for example
                           '-S 512' for mkfs.fat or '-F -i 8192' for mkfs.ext. Those options will
                           not take effect when --mkfs-extraopts is used. This should be taken into
                           account when using --mkfs-extraopts.

    * bootloader

      This command allows the user to specify various bootloader
      options.  The following are supported 'bootloader' options:

        --timeout: Specifies the number of seconds before the
                   bootloader times out and boots the default option.

        --append: Specifies kernel parameters. These will be added to
                  bootloader command-line - for example, the syslinux
                  APPEND or grub kernel command line.

        --configfile: Specifies a user defined configuration file for
                      the bootloader. This file must be located in the
                      canned-wks folder or could be the full path to the
                      file. Using this option will override any other
                      bootloader option.

      Note that bootloader functionality and boot partitions are
      implemented by the various --source plugins that implement
      bootloader functionality; the bootloader command essentially
      provides a means of modifying bootloader configuration.

    * include

      This command allows the user to include the content of .wks file
      into original .wks file.

      Command uses the following syntax:

         include <file>

      The <file> is either path to the file or its name. If name is
      specified wic will try to find file in the directories with canned
      .wks files.

"""

wic_help_help = """
NAME
    wic help - display a help topic

DESCRIPTION
    Specify a help topic to display it. Topics are shown above.
"""