diff options
Diffstat (limited to 'scripts/lib/image/help.py')
-rw-r--r-- | scripts/lib/image/help.py | 756 |
1 files changed, 756 insertions, 0 deletions
diff --git a/scripts/lib/image/help.py b/scripts/lib/image/help.py new file mode 100644 index 0000000000..6b74f57662 --- /dev/null +++ b/scripts/lib/image/help.py | |||
@@ -0,0 +1,756 @@ | |||
1 | # 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 | |||
28 | import subprocess | ||
29 | import logging | ||
30 | |||
31 | |||
32 | def subcommand_error(args): | ||
33 | logging.info("invalid subcommand %s" % args[0]) | ||
34 | |||
35 | |||
36 | def display_help(subcommand, subcommands): | ||
37 | """ | ||
38 | Display help for subcommand. | ||
39 | """ | ||
40 | if subcommand not in subcommands: | ||
41 | return False | ||
42 | |||
43 | help = subcommands.get(subcommand, subcommand_error)[2] | ||
44 | pager = subprocess.Popen('less', stdin=subprocess.PIPE) | ||
45 | pager.communicate(help) | ||
46 | |||
47 | return True | ||
48 | |||
49 | |||
50 | def wic_help(args, usage_str, subcommands): | ||
51 | """ | ||
52 | Subcommand help dispatcher. | ||
53 | """ | ||
54 | if len(args) == 1 or not display_help(args[1], subcommands): | ||
55 | print(usage_str) | ||
56 | |||
57 | |||
58 | def invoke_subcommand(args, parser, main_command_usage, subcommands): | ||
59 | """ | ||
60 | Dispatch to subcommand handler borrowed from combo-layer. | ||
61 | Should use argparse, but has to work in 2.6. | ||
62 | """ | ||
63 | if not args: | ||
64 | logging.error("No subcommand specified, exiting") | ||
65 | parser.print_help() | ||
66 | elif args[0] == "help": | ||
67 | wic_help(args, main_command_usage, subcommands) | ||
68 | elif args[0] not in subcommands: | ||
69 | logging.error("Unsupported subcommand %s, exiting\n" % (args[0])) | ||
70 | parser.print_help() | ||
71 | else: | ||
72 | usage = subcommands.get(args[0], subcommand_error)[1] | ||
73 | subcommands.get(args[0], subcommand_error)[0](args[1:], usage) | ||
74 | |||
75 | |||
76 | ## | ||
77 | # wic help and usage strings | ||
78 | ## | ||
79 | |||
80 | wic_usage = """ | ||
81 | |||
82 | Create a customized OpenEmbedded image | ||
83 | |||
84 | usage: wic [--version] [--help] COMMAND [ARGS] | ||
85 | |||
86 | Current 'wic' commands are: | ||
87 | create Create a new OpenEmbedded image | ||
88 | list List available values for options and image properties | ||
89 | |||
90 | Help topics: | ||
91 | overview wic overview - General overview of wic | ||
92 | plugins wic plugins - Overview and API | ||
93 | kickstart wic kickstart - wic kickstart reference | ||
94 | |||
95 | See 'wic help <COMMAND or HELP TOPIC>' for more information on a specific | ||
96 | command or help topic. | ||
97 | """ | ||
98 | |||
99 | wic_help_usage = """ | ||
100 | |||
101 | usage: wic help <subcommand> | ||
102 | |||
103 | This command displays detailed help for the specified subcommand. | ||
104 | """ | ||
105 | |||
106 | wic_create_usage = """ | ||
107 | |||
108 | Create a new OpenEmbedded image | ||
109 | |||
110 | usage: wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>] | ||
111 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] | ||
112 | [-e | --image-name] [-s, --skip-build-check] [-D, --debug] | ||
113 | [-r, --rootfs-dir] [-b, --bootimg-dir] | ||
114 | [-k, --kernel-dir] [-n, --native-sysroot] | ||
115 | |||
116 | This command creates an OpenEmbedded image based on the 'OE kickstart | ||
117 | commands' found in the <wks file>. | ||
118 | |||
119 | The -o option can be used to place the image in a directory with a | ||
120 | different name and location. | ||
121 | |||
122 | See 'wic help create' for more detailed instructions. | ||
123 | """ | ||
124 | |||
125 | wic_create_help = """ | ||
126 | |||
127 | NAME | ||
128 | wic create - Create a new OpenEmbedded image | ||
129 | |||
130 | SYNOPSIS | ||
131 | wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>] | ||
132 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] | ||
133 | [-e | --image-name] [-s, --skip-build-check] [-D, --debug] | ||
134 | [-r, --rootfs-dir] [-b, --bootimg-dir] | ||
135 | [-k, --kernel-dir] [-n, --native-sysroot] | ||
136 | |||
137 | DESCRIPTION | ||
138 | This command creates an OpenEmbedded image based on the 'OE | ||
139 | kickstart commands' found in the <wks file>. | ||
140 | |||
141 | In order to do this, wic needs to know the locations of the | ||
142 | various build artifacts required to build the image. | ||
143 | |||
144 | Users can explicitly specify the build artifact locations using | ||
145 | the -r, -b, -k, and -n options. See below for details on where | ||
146 | the corresponding artifacts are typically found in a normal | ||
147 | OpenEmbedded build. | ||
148 | |||
149 | Alternatively, users can use the -e option to have 'wic' determine | ||
150 | those locations for a given image. If the -e option is used, the | ||
151 | user needs to have set the appropriate MACHINE variable in | ||
152 | local.conf, and have sourced the build environment. | ||
153 | |||
154 | The -e option is used to specify the name of the image to use the | ||
155 | artifacts from e.g. core-image-sato. | ||
156 | |||
157 | The -r option is used to specify the path to the /rootfs dir to | ||
158 | use as the .wks rootfs source. | ||
159 | |||
160 | The -b option is used to specify the path to the dir containing | ||
161 | the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the | ||
162 | .wks bootimg source. | ||
163 | |||
164 | The -k option is used to specify the path to the dir containing | ||
165 | the kernel to use in the .wks bootimg. | ||
166 | |||
167 | The -n option is used to specify the path to the native sysroot | ||
168 | containing the tools to use to build the image. | ||
169 | |||
170 | The -s option is used to skip the build check. The build check is | ||
171 | a simple sanity check used to determine whether the user has | ||
172 | sourced the build environment so that the -e option can operate | ||
173 | correctly. If the user has specified the build artifact locations | ||
174 | explicitly, 'wic' assumes the user knows what he or she is doing | ||
175 | and skips the build check. | ||
176 | |||
177 | The -D option is used to display debug information detailing | ||
178 | exactly what happens behind the scenes when a create request is | ||
179 | fulfilled (or not, as the case may be). It enumerates and | ||
180 | displays the command sequence used, and should be included in any | ||
181 | bug report describing unexpected results. | ||
182 | |||
183 | When 'wic -e' is used, the locations for the build artifacts | ||
184 | values are determined by 'wic -e' from the output of the 'bitbake | ||
185 | -e' command given an image name e.g. 'core-image-minimal' and a | ||
186 | given machine set in local.conf. In that case, the image is | ||
187 | created as if the following 'bitbake -e' variables were used: | ||
188 | |||
189 | -r: IMAGE_ROOTFS | ||
190 | -k: STAGING_KERNEL_DIR | ||
191 | -n: STAGING_DIR_NATIVE | ||
192 | -b: empty (plugin-specific handlers must determine this) | ||
193 | |||
194 | If 'wic -e' is not used, the user needs to select the appropriate | ||
195 | value for -b (as well as -r, -k, and -n). | ||
196 | |||
197 | The -o option can be used to place the image in a directory with a | ||
198 | different name and location. | ||
199 | |||
200 | As an alternative to the wks file, the image-specific properties | ||
201 | that define the values that will be used to generate a particular | ||
202 | image can be specified on the command-line using the -i option and | ||
203 | supplying a JSON object consisting of the set of name:value pairs | ||
204 | needed by image creation. | ||
205 | |||
206 | The set of properties available for a given image type can be | ||
207 | listed using the 'wic list' command. | ||
208 | """ | ||
209 | |||
210 | wic_list_usage = """ | ||
211 | |||
212 | List available OpenEmbedded image properties and values | ||
213 | |||
214 | usage: wic list images | ||
215 | wic list <image> help | ||
216 | wic list source-plugins | ||
217 | wic list properties | ||
218 | wic list properties <wks file> | ||
219 | wic list property <property> | ||
220 | [-o <JSON PROPERTY FILE> | --outfile <JSON PROPERTY_FILE>] | ||
221 | |||
222 | This command enumerates the set of available canned images as well as | ||
223 | help for those images. It also can be used to enumerate the complete | ||
224 | set of possible values for a specified option or property needed by | ||
225 | the image creation process. | ||
226 | |||
227 | The first form enumerates all the available 'canned' images. | ||
228 | |||
229 | The second form lists the detailed help information for a specific | ||
230 | 'canned' image. | ||
231 | |||
232 | The third form enumerates all the available --sources (source | ||
233 | plugins). | ||
234 | |||
235 | The fourth form enumerates all the possible values that exist and can | ||
236 | be specified in an OE kickstart (wks) file. | ||
237 | |||
238 | The fifth form enumerates all the possible options that exist for the | ||
239 | set of properties specified in a given OE kickstart (ks) file. | ||
240 | |||
241 | The final form enumerates all the possible values that exist and can | ||
242 | be specified for any given OE kickstart (wks) property. | ||
243 | |||
244 | See 'wic help list' for more details. | ||
245 | """ | ||
246 | |||
247 | wic_list_help = """ | ||
248 | |||
249 | NAME | ||
250 | wic list - List available OpenEmbedded image properties and values | ||
251 | |||
252 | SYNOPSIS | ||
253 | wic list images | ||
254 | wic list <image> help | ||
255 | wic list source-plugins | ||
256 | wic list properties | ||
257 | wic list properties <wks file> | ||
258 | wic list property <property> | ||
259 | [-o <JSON PROPERTY FILE> | --outfile <JSON PROPERTY_FILE>] | ||
260 | |||
261 | DESCRIPTION | ||
262 | This command enumerates the complete set of possible values for a | ||
263 | specified option or property needed by the image creation process. | ||
264 | |||
265 | This command enumerates the set of available canned images as well | ||
266 | as help for those images. It also can be used to enumerate the | ||
267 | complete set of possible values for a specified option or property | ||
268 | needed by the image creation process. | ||
269 | |||
270 | The first form enumerates all the available 'canned' images. | ||
271 | These are actually just the set of .wks files that have been moved | ||
272 | into the /scripts/lib/image/canned-wks directory). | ||
273 | |||
274 | The second form lists the detailed help information for a specific | ||
275 | 'canned' image. | ||
276 | |||
277 | The third form enumerates all the available --sources (source | ||
278 | plugins). The contents of a given partition are driven by code | ||
279 | defined in 'source plugins'. Users specify a specific plugin via | ||
280 | the --source parameter of the partition .wks command. Normally | ||
281 | this is the 'rootfs' plugin but can be any of the more specialized | ||
282 | sources listed by the 'list source-plugins' command. Users can | ||
283 | also add their own source plugins - see 'wic help plugins' for | ||
284 | details. | ||
285 | |||
286 | The third form enumerates all the possible values that exist and | ||
287 | can be specified in a OE kickstart (wks) file. The output of this | ||
288 | can be used by the third form to print the description and | ||
289 | possible values of a specific property. | ||
290 | |||
291 | The fourth form enumerates all the possible options that exist for | ||
292 | the set of properties specified in a given OE kickstart (wks) | ||
293 | file. If the -o option is specified, the list of properties, in | ||
294 | addition to being displayed, will be written to the specified file | ||
295 | as a JSON object. In this case, the object will consist of the | ||
296 | set of name:value pairs corresponding to the (possibly nested) | ||
297 | dictionary of properties defined by the input statements used by | ||
298 | the image. Some example output for the 'list <wks file>' command: | ||
299 | |||
300 | $ wic list test.ks | ||
301 | "part" : { | ||
302 | "mountpoint" : "/" | ||
303 | "fstype" : "ext3" | ||
304 | } | ||
305 | "part" : { | ||
306 | "mountpoint" : "/home" | ||
307 | "fstype" : "ext3" | ||
308 | "offset" : "10000" | ||
309 | } | ||
310 | "bootloader" : { | ||
311 | "type" : "efi" | ||
312 | } | ||
313 | . | ||
314 | . | ||
315 | . | ||
316 | |||
317 | Each entry in the output consists of the name of the input element | ||
318 | e.g. "part", followed by the properties defined for that | ||
319 | element enclosed in braces. This information should provide | ||
320 | sufficient information to create a complete user interface with. | ||
321 | |||
322 | The final form enumerates all the possible values that exist and | ||
323 | can be specified for any given OE kickstart (wks) property. If | ||
324 | the -o option is specified, the list of values for the given | ||
325 | property, in addition to being displayed, will be written to the | ||
326 | specified file as a JSON object. In this case, the object will | ||
327 | consist of the set of name:value pairs corresponding to the array | ||
328 | of property values associated with the property. | ||
329 | |||
330 | $ wic list property part | ||
331 | ["mountpoint", "where the partition should be mounted"] | ||
332 | ["fstype", "filesytem type of the partition"] | ||
333 | ["ext3"] | ||
334 | ["ext4"] | ||
335 | ["btrfs"] | ||
336 | ["swap"] | ||
337 | ["offset", "offset of the partition within the image"] | ||
338 | |||
339 | """ | ||
340 | |||
341 | wic_plugins_help = """ | ||
342 | |||
343 | NAME | ||
344 | wic plugins - Overview and API | ||
345 | |||
346 | DESCRIPTION | ||
347 | plugins allow wic functionality to be extended and specialized by | ||
348 | users. This section documents the plugin interface, which is | ||
349 | currently restricted to 'source' plugins. | ||
350 | |||
351 | 'Source' plugins provide a mechanism to customize various aspects | ||
352 | of the image generation process in wic, mainly the contents of | ||
353 | partitions. | ||
354 | |||
355 | Source plugins provide a mechanism for mapping values specified in | ||
356 | .wks files using the --source keyword to a particular plugin | ||
357 | implementation that populates a corresponding partition. | ||
358 | |||
359 | A source plugin is created as a subclass of SourcePlugin (see | ||
360 | scripts/lib/wic/pluginbase.py) and the plugin file containing it | ||
361 | is added to scripts/lib/wic/plugins/source/ to make the plugin | ||
362 | implementation available to the wic implementation. | ||
363 | |||
364 | Source plugins can also be implemented and added by external | ||
365 | layers - any plugins found in a scripts/lib/wic/plugins/source/ | ||
366 | directory in an external layer will also be made available. | ||
367 | |||
368 | When the wic implementation needs to invoke a partition-specific | ||
369 | implementation, it looks for the plugin that has the same name as | ||
370 | the --source param given to that partition. For example, if the | ||
371 | partition is set up like this: | ||
372 | |||
373 | part /boot --source bootimg-pcbios ... | ||
374 | |||
375 | then the methods defined as class members of the plugin having the | ||
376 | matching bootimg-pcbios .name class member would be used. | ||
377 | |||
378 | To be more concrete, here's the plugin definition that would match | ||
379 | a '--source bootimg-pcbios' usage, along with an example method | ||
380 | that would be called by the wic implementation when it needed to | ||
381 | invoke an implementation-specific partition-preparation function: | ||
382 | |||
383 | class BootimgPcbiosPlugin(SourcePlugin): | ||
384 | name = 'bootimg-pcbios' | ||
385 | |||
386 | @classmethod | ||
387 | def do_prepare_partition(self, part, ...) | ||
388 | |||
389 | If the subclass itself doesn't implement a function, a 'default' | ||
390 | version in a superclass will be located and used, which is why all | ||
391 | plugins must be derived from SourcePlugin. | ||
392 | |||
393 | The SourcePlugin class defines the following methods, which is the | ||
394 | current set of methods that can be implemented/overridden by | ||
395 | --source plugins. Any methods not implemented by a SourcePlugin | ||
396 | subclass inherit the implementations present in the SourcePlugin | ||
397 | class (see the SourcePlugin source for details): | ||
398 | |||
399 | do_prepare_partition() | ||
400 | Called to do the actual content population for a | ||
401 | partition. In other words, it 'prepares' the final partition | ||
402 | image which will be incorporated into the disk image. | ||
403 | |||
404 | do_configure_partition() | ||
405 | Called before do_prepare_partition(), typically used to | ||
406 | create custom configuration files for a partition, for | ||
407 | example syslinux or grub config files. | ||
408 | |||
409 | do_install_disk() | ||
410 | Called after all partitions have been prepared and assembled | ||
411 | into a disk image. This provides a hook to allow | ||
412 | finalization of a disk image, for example to write an MBR to | ||
413 | it. | ||
414 | |||
415 | do_stage_partition() | ||
416 | Special content-staging hook called before | ||
417 | do_prepare_partition(), normally empty. | ||
418 | |||
419 | Typically, a partition will just use the passed-in | ||
420 | parameters, for example the unmodified value of bootimg_dir. | ||
421 | In some cases however, things may need to be more tailored. | ||
422 | As an example, certain files may additionally need to be | ||
423 | take from bootimg_dir + /boot. This hook allows those files | ||
424 | to be staged in a customized fashion. Note that | ||
425 | get_bitbake_var() allows you to access non-standard | ||
426 | variables that you might want to use for these types of | ||
427 | situations. | ||
428 | |||
429 | This scheme is extensible - adding more hooks is a simple matter | ||
430 | of adding more plugin methods to SourcePlugin and derived classes. | ||
431 | The code that then needs to call the plugin methods uses | ||
432 | plugin.get_source_plugin_methods() to find the method(s) needed by | ||
433 | the call; this is done by filling up a dict with keys containing | ||
434 | the method names of interest - on success, these will be filled in | ||
435 | with the actual methods. Please see the implementation for | ||
436 | examples and details. | ||
437 | """ | ||
438 | |||
439 | wic_overview_help = """ | ||
440 | |||
441 | NAME | ||
442 | wic overview - General overview of wic | ||
443 | |||
444 | DESCRIPTION | ||
445 | The 'wic' command generates partitioned images from existing | ||
446 | OpenEmbedded build artifacts. Image generation is driven by | ||
447 | partitioning commands contained in an 'Openembedded kickstart' | ||
448 | (.wks) file (see 'wic help kickstart') specified either directly | ||
449 | on the command-line or as one of a selection of canned .wks files | ||
450 | (see 'wic list images'). When applied to a given set of build | ||
451 | artifacts, the result is an image or set of images that can be | ||
452 | directly written onto media and used on a particular system. | ||
453 | |||
454 | The 'wic' command and the infrastructure it's based on is by | ||
455 | definition incomplete - its purpose is to allow the generation of | ||
456 | customized images, and as such was designed to be completely | ||
457 | extensible via a plugin interface (see 'wic help plugins'). | ||
458 | |||
459 | Background and Motivation | ||
460 | |||
461 | wic is meant to be a completely independent standalone utility | ||
462 | that initially provides easier-to-use and more flexible | ||
463 | replacements for a couple bits of existing functionality in | ||
464 | oe-core: directdisk.bbclass and mkefidisk.sh. The difference | ||
465 | between wic and those examples is that with wic the functionality | ||
466 | of those scripts is implemented by a general-purpose partitioning | ||
467 | 'language' based on Redhat kickstart syntax). | ||
468 | |||
469 | The initial motivation and design considerations that lead to the | ||
470 | current tool are described exhaustively in Yocto Bug #3847 | ||
471 | (https://bugzilla.yoctoproject.org/show_bug.cgi?id=3847). | ||
472 | |||
473 | Implementation and Examples | ||
474 | |||
475 | wic can be used in two different modes, depending on how much | ||
476 | control the user needs in specifying the Openembedded build | ||
477 | artifacts that will be used in creating the image: 'raw' and | ||
478 | 'cooked'. | ||
479 | |||
480 | If used in 'raw' mode, artifacts are explicitly specified via | ||
481 | command-line arguments (see example below). | ||
482 | |||
483 | The more easily usable 'cooked' mode uses the current MACHINE | ||
484 | setting and a specified image name to automatically locate the | ||
485 | artifacts used to create the image. | ||
486 | |||
487 | OE kickstart files (.wks) can of course be specified directly on | ||
488 | the command-line, but the user can also choose from a set of | ||
489 | 'canned' .wks files available via the 'wic list images' command | ||
490 | (example below). | ||
491 | |||
492 | In any case, the prerequisite for generating any image is to have | ||
493 | the build artifacts already available. The below examples assume | ||
494 | the user has already build a 'core-image-minimal' for a specific | ||
495 | machine (future versions won't require this redundant step, but | ||
496 | for now that's typically how build artifacts get generated). | ||
497 | |||
498 | The other prerequisite is to source the build environment: | ||
499 | |||
500 | $ source oe-init-build-env | ||
501 | |||
502 | To start out with, we'll generate an image from one of the canned | ||
503 | .wks files. The following generates a list of availailable | ||
504 | images: | ||
505 | |||
506 | $ wic list images | ||
507 | mkefidisk Create an EFI disk image | ||
508 | directdisk Create a 'pcbios' direct disk image | ||
509 | |||
510 | You can get more information about any of the available images by | ||
511 | typing 'wic list xxx help', where 'xxx' is one of the image names: | ||
512 | |||
513 | $ wic list mkefidisk help | ||
514 | |||
515 | Creates a partitioned EFI disk image that the user can directly dd | ||
516 | to boot media. | ||
517 | |||
518 | At any time, you can get help on the 'wic' command or any | ||
519 | subcommand (currently 'list' and 'create'). For instance, to get | ||
520 | the description of 'wic create' command and its parameters: | ||
521 | |||
522 | $ wic create | ||
523 | |||
524 | Usage: | ||
525 | |||
526 | Create a new OpenEmbedded image | ||
527 | |||
528 | usage: wic create <wks file or image name> [-o <DIRNAME> | ...] | ||
529 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] | ||
530 | [-e | --image-name] [-s, --skip-build-check] [-D, --debug] | ||
531 | [-r, --rootfs-dir] [-b, --bootimg-dir] | ||
532 | [-k, --kernel-dir] [-n, --native-sysroot] | ||
533 | |||
534 | This command creates an OpenEmbedded image based on the 'OE | ||
535 | kickstart commands' found in the <wks file>. | ||
536 | |||
537 | The -o option can be used to place the image in a directory | ||
538 | with a different name and location. | ||
539 | |||
540 | See 'wic help create' for more detailed instructions. | ||
541 | ... | ||
542 | |||
543 | As mentioned in the command, you can get even more detailed | ||
544 | information by adding 'help' to the above: | ||
545 | |||
546 | $ wic help create | ||
547 | |||
548 | So, the easiest way to create an image is to use the -e option | ||
549 | with a canned .wks file. To use the -e option, you need to | ||
550 | specify the image used to generate the artifacts and you actually | ||
551 | need to have the MACHINE used to build them specified in your | ||
552 | local.conf (these requirements aren't necessary if you aren't | ||
553 | using the -e options.) Below, we generate a directdisk image, | ||
554 | pointing the process at the core-image-minimal artifacts for the | ||
555 | current MACHINE: | ||
556 | |||
557 | $ wic create directdisk -e core-image-minimal | ||
558 | |||
559 | Checking basic build environment... | ||
560 | Done. | ||
561 | |||
562 | Creating image(s)... | ||
563 | |||
564 | Info: The new image(s) can be found here: | ||
565 | /var/tmp/wic/build/directdisk-201309252350-sda.direct | ||
566 | |||
567 | The following build artifacts were used to create the image(s): | ||
568 | |||
569 | ROOTFS_DIR: ... | ||
570 | BOOTIMG_DIR: ... | ||
571 | KERNEL_DIR: ... | ||
572 | NATIVE_SYSROOT: ... | ||
573 | |||
574 | The image(s) were created using OE kickstart file: | ||
575 | .../scripts/lib/image/canned-wks/directdisk.wks | ||
576 | |||
577 | The output shows the name and location of the image created, and | ||
578 | so that you know exactly what was used to generate the image, each | ||
579 | of the artifacts and the kickstart file used. | ||
580 | |||
581 | Similarly, you can create a 'mkefidisk' image in the same way | ||
582 | (notice that this example uses a different machine - because it's | ||
583 | using the -e option, you need to change the MACHINE in your | ||
584 | local.conf): | ||
585 | |||
586 | $ wic create mkefidisk -e core-image-minimal | ||
587 | Checking basic build environment... | ||
588 | Done. | ||
589 | |||
590 | Creating image(s)... | ||
591 | |||
592 | Info: The new image(s) can be found here: | ||
593 | /var/tmp/wic/build/mkefidisk-201309260027-sda.direct | ||
594 | |||
595 | ... | ||
596 | |||
597 | Here's an example that doesn't take the easy way out and manually | ||
598 | specifies each build artifact, along with a non-canned .wks file, | ||
599 | and also uses the -o option to have wic create the output | ||
600 | somewhere other than the default /var/tmp/wic: | ||
601 | |||
602 | $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir | ||
603 | /home/trz/yocto/build/tmp/work/crownbay/core-image-minimal/1.0-r0/rootfs | ||
604 | --bootimg-dir /home/trz/yocto/build/tmp/sysroots/crownbay/usr/share | ||
605 | --kernel-dir /home/trz/yocto/build/tmp/sysroots/crownbay/usr/src/kernel | ||
606 | --native-sysroot /home/trz/yocto/build/tmp/sysroots/x86_64-linux | ||
607 | |||
608 | Creating image(s)... | ||
609 | |||
610 | Info: The new image(s) can be found here: | ||
611 | /home/trz/testwic/build/test-201309260032-sda.direct | ||
612 | |||
613 | ... | ||
614 | |||
615 | Finally, here's an example of the actual partition language | ||
616 | commands used to generate the mkefidisk image i.e. these are the | ||
617 | contents of the mkefidisk.wks OE kickstart file: | ||
618 | |||
619 | # short-description: Create an EFI disk image | ||
620 | # long-description: Creates a partitioned EFI disk image that the user | ||
621 | # can directly dd to boot media. | ||
622 | |||
623 | part /boot --source bootimg-efi --ondisk sda --fstype=efi --active | ||
624 | |||
625 | part / --source rootfs --ondisk sda --fstype=ext3 --label platform | ||
626 | |||
627 | part swap --ondisk sda --size 44 --label swap1 --fstype=swap | ||
628 | |||
629 | bootloader --timeout=10 --append="rootwait console=ttyPCH0,115200" | ||
630 | |||
631 | You can get a complete listing and description of all the | ||
632 | kickstart commands available for use in .wks files from 'wic help | ||
633 | kickstart'. | ||
634 | """ | ||
635 | |||
636 | wic_kickstart_help = """ | ||
637 | |||
638 | NAME | ||
639 | wic kickstart - wic kickstart reference | ||
640 | |||
641 | DESCRIPTION | ||
642 | This section provides the definitive reference to the wic | ||
643 | kickstart language. It also provides documentation on the list of | ||
644 | --source plugins available for use from the 'part' command (see | ||
645 | the 'Platform-specific Plugins' section below). | ||
646 | |||
647 | The current wic implementation supports only the basic kickstart | ||
648 | partitioning commands: partition (or part for short) and | ||
649 | bootloader. | ||
650 | |||
651 | The following is a listing of the commands, their syntax, and | ||
652 | meanings. The commands are based on the Fedora kickstart | ||
653 | documentation but with modifications to reflect wic capabilities. | ||
654 | |||
655 | http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition | ||
656 | http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader | ||
657 | |||
658 | Commands | ||
659 | |||
660 | * 'part' or 'partition' | ||
661 | |||
662 | This command creates a partition on the system and uses the | ||
663 | following syntax: | ||
664 | |||
665 | part <mountpoint> | ||
666 | |||
667 | The <mountpoint> is where the partition will be mounted and | ||
668 | must take of one of the following forms: | ||
669 | |||
670 | /<path>: For example: /, /usr, or /home | ||
671 | |||
672 | swap: The partition will be used as swap space. | ||
673 | |||
674 | The following are supported 'part' options: | ||
675 | |||
676 | --size: The minimum partition size in MBytes. Specify an | ||
677 | integer value such as 500. Do not append the number | ||
678 | with "MB". You do not need this option if you use | ||
679 | --source. | ||
680 | |||
681 | --source: This option is a wic-specific option that names the | ||
682 | source of the data that will populate the | ||
683 | partition. The most common value for this option | ||
684 | is 'rootfs', but can be any value which maps to a | ||
685 | valid 'source plugin' (see 'wic help plugins'). | ||
686 | |||
687 | If '--source rootfs' is used, it tells the wic | ||
688 | command to create a partition as large as needed | ||
689 | and to fill it with the contents of the root | ||
690 | filesystem pointed to by the '-r' wic command-line | ||
691 | option (or the equivalent rootfs derived from the | ||
692 | '-e' command-line option). The filesystem type | ||
693 | that will be used to create the partition is driven | ||
694 | by the value of the --fstype option specified for | ||
695 | the partition (see --fstype below). | ||
696 | |||
697 | If --source <plugin-name>' is used, it tells the | ||
698 | wic command to create a partition as large as | ||
699 | needed and to fill with the contents of the | ||
700 | partition that will be generated by the specified | ||
701 | plugin name using the data pointed to by the '-r' | ||
702 | wic command-line option (or the equivalent rootfs | ||
703 | derived from the '-e' command-line option). | ||
704 | Exactly what those contents and filesystem type end | ||
705 | up being are dependent on the given plugin | ||
706 | implementation. | ||
707 | |||
708 | --ondisk or --ondrive: Forces the partition to be created on | ||
709 | a particular disk. | ||
710 | |||
711 | --fstype: Sets the file system type for the partition. These | ||
712 | apply to partitions created using '--source rootfs' (see | ||
713 | --source above). Valid values are: | ||
714 | |||
715 | ext2 | ||
716 | ext3 | ||
717 | ext4 | ||
718 | btrfs | ||
719 | squashfs | ||
720 | swap | ||
721 | |||
722 | --fsoptions: Specifies a free-form string of options to be | ||
723 | used when mounting the filesystem. This string | ||
724 | will be copied into the /etc/fstab file of the | ||
725 | installed system and should be enclosed in | ||
726 | quotes. If not specified, the default string is | ||
727 | "defaults". | ||
728 | |||
729 | --label label: Specifies the label to give to the filesystem | ||
730 | to be made on the partition. If the given | ||
731 | label is already in use by another filesystem, | ||
732 | a new label is created for the partition. | ||
733 | |||
734 | --active: Marks the partition as active. | ||
735 | |||
736 | --align (in KBytes): This option is specific to wic and says | ||
737 | to start a partition on an x KBytes | ||
738 | boundary. | ||
739 | |||
740 | * bootloader | ||
741 | |||
742 | This command allows the user to specify various bootloader | ||
743 | options. The following are supported 'bootloader' options: | ||
744 | |||
745 | --timeout: Specifies the number of seconds before the | ||
746 | bootloader times out and boots the default option. | ||
747 | |||
748 | --append: Specifies kernel parameters. These will be added to | ||
749 | bootloader command-line - for example, the syslinux | ||
750 | APPEND or grub kernel command line. | ||
751 | |||
752 | Note that bootloader functionality and boot partitions are | ||
753 | implemented by the various --source plugins that implement | ||
754 | bootloader functionality; the bootloader command essentially | ||
755 | provides a means of modifying bootloader configuration. | ||
756 | """ | ||