summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml1692
1 files changed, 895 insertions, 797 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 2c95ecbc99..d48724c82c 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3984,7 +3984,7 @@
3984 </para></listitem> 3984 </para></listitem>
3985 </itemizedlist> 3985 </itemizedlist>
3986 </para> 3986 </para>
3987' 3987
3988 <para> 3988 <para>
3989 For the RPM Package Management System, the following implementation details 3989 For the RPM Package Management System, the following implementation details
3990 exist: 3990 exist:
@@ -4365,328 +4365,385 @@
4365 format the device requires. 4365 format the device requires.
4366 Should your device require multiple partitions on an SD card, flash, 4366 Should your device require multiple partitions on an SD card, flash,
4367 or an HDD, you can use the OpenEmbedded Image Creator, 4367 or an HDD, you can use the OpenEmbedded Image Creator,
4368 <filename>wic</filename>, to create the properly partitioned image. 4368 Wic, to create the properly partitioned image.
4369 </para>
4370
4371 <para>
4372 The <filename>wic</filename> command generates partitioned images
4373 from existing OpenEmbedded build artifacts.
4374 Image generation is driven by partitioning commands contained
4375 in an Openembedded kickstart file (<filename>.wks</filename>)
4376 specified either directly on the command line or as one of a
4377 selection of canned <filename>.wks</filename> files as shown
4378 with the <filename>wic list images</filename> command in the
4379 "<link linkend='using-a-provided-kickstart_file'>Using an Existing Kickstart File</link>"
4380 section.
4381 When applied to a given set of build artifacts, the result is an
4382 image or set of images that can be directly written onto media and
4383 used on a particular system.
4384 </para> 4369 </para>
4385 4370
4386 <para> 4371 <para>
4387 The <filename>wic</filename> command and the infrastructure 4372 You can generate Wic-partitioned images
4388 it is based on is by definition incomplete. 4373 (<replaceable>image</replaceable><filename>.wic</filename>)
4389 Its purpose is to allow the generation of customized images, 4374 two ways: using the OpenEmbedded build system and by running
4390 and as such was designed to be completely extensible through a 4375 the OpenEmbedded Image Creator Wic directly.
4391 plug-in interface. 4376 The former way is preferable as it is easier to use and understand.
4392 See the
4393 "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>"
4394 section for information on these plug-ins.
4395 </para>
4396
4397 <para>
4398 This section provides some background information on
4399 <filename>wic</filename>, describes what you need to have in
4400 place to run the tool, provides instruction on how to use
4401 <filename>wic</filename>, and provides several examples.
4402 </para> 4377 </para>
4403 4378
4404 <section id='wic-background'> 4379 <section id='creating-wic-images-oe'>
4405 <title>Background</title> 4380 <title>Creating Wic-Partitioned Images</title>
4406 4381
4407 <para> 4382 <para>
4408 This section provides some background on the 4383 The OpenEmbedded build system can generate
4409 <filename>wic</filename> utility. 4384 Wic-partitioned images the same way as it generates
4410 While none of this information is required to use 4385 any other image type.
4411 <filename>wic</filename>, you might find it interesting. 4386 To generate a Wic-partitioned image, you need to modify
4387 two variables.
4412 <itemizedlist> 4388 <itemizedlist>
4413 <listitem><para> 4389 <listitem><para>
4414 The name "wic" is derived from OpenEmbedded 4390 Include "wic" as part of the
4415 Image Creator (oeic). 4391 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
4416 The "oe" diphthong in "oeic" was promoted to the 4392 variable.
4417 letter "w", because "oeic" is both difficult to remember and
4418 pronounce.</para></listitem>
4419 <listitem><para>
4420 <filename>wic</filename> is loosely based on the
4421 Meego Image Creator (<filename>mic</filename>)
4422 framework.
4423 The <filename>wic</filename> implementation has been
4424 heavily modified to make direct use of OpenEmbedded
4425 build artifacts instead of package installation and
4426 configuration, which are already incorporated within
4427 the OpenEmbedded artifacts.</para></listitem>
4428 <listitem><para>
4429 <filename>wic</filename> is a completely independent
4430 standalone utility that initially provides
4431 easier-to-use and more flexible replacements for a
4432 couple bits of existing functionality in OE Core's
4433 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
4434 class and <filename>mkefidisk.sh</filename> script.
4435 The difference between
4436 <filename>wic</filename> and those examples is
4437 that with <filename>wic</filename> the
4438 functionality of those scripts is implemented
4439 by a general-purpose partitioning language, which is
4440 based on Redhat kickstart syntax.</para></listitem>
4441 </itemizedlist>
4442 </para>
4443 </section>
4444
4445 <section id='wic-requirements'>
4446 <title>Requirements</title>
4447
4448 <para>
4449 In order to use the <filename>wic</filename> utility
4450 with the OpenEmbedded Build system, your system needs
4451 to meet the following requirements:
4452 <itemizedlist>
4453 <listitem><para>The Linux distribution on your
4454 development host must support the Yocto Project.
4455 See the
4456 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
4457 section in the Yocto Project Reference Manual for this
4458 list of distributions.</para></listitem>
4459 <listitem><para>
4460 The standard system utilities, such as
4461 <filename>cp</filename>, must be installed on your
4462 development host system.
4463 </para></listitem>
4464 <listitem><para>
4465 You need to have the build artifacts already
4466 available, which typically means that you must
4467 have already created an image using the
4468 Openembedded build system (e.g.
4469 <filename>core-image-minimal</filename>).
4470 While it might seem redundant to generate an image in
4471 order to create an image using
4472 <filename>wic</filename>, the current version of
4473 <filename>wic</filename> requires the artifacts
4474 in the form generated by the build system.
4475 </para></listitem>
4476 <listitem><para>
4477 You must build several native tools, which are tools
4478 built to run on the build system:
4479 <literallayout class='monospaced'>
4480 $ bitbake parted-native dosfstools-native mtools-native
4481 </literallayout>
4482 </para></listitem> 4393 </para></listitem>
4483 <listitem><para> 4394 <listitem><para>
4484 You must have sourced one of the build environment 4395 Include the name of the
4485 setup scripts (i.e. 4396 <link linkend='openembedded-kickstart-wks-reference'>wic kickstart file</link>
4486 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> 4397 as part of the
4487 or 4398 <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>
4488 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) 4399 variable
4489 found in the
4490 <link linkend='build-directory'>Build Directory</link>.
4491 </para></listitem> 4400 </para></listitem>
4492 </itemizedlist> 4401 </itemizedlist>
4402 Further steps to generate a Wic-partitioned image
4403 are the same as for any other image type.
4404 For information on image types, see the
4405 "<link linkend='building-images'>Building Images</link>"
4406 section.
4493 </para> 4407 </para>
4494 </section> 4408 </section>
4495 4409
4496 <section id='wic-getting-help'> 4410 <section id='create-wic-images-wic'>
4497 <title>Getting Help</title> 4411 <title>Using OpenEmbedded Image Creator Wic to Generate Partitioned Images</title>
4498 4412
4499 <para> 4413 <para>
4500 You can get general help for the <filename>wic</filename> 4414 The <filename>wic</filename> command generates partitioned
4501 by entering the <filename>wic</filename> command by itself 4415 images from existing OpenEmbedded build artifacts.
4502 or by entering the command with a help argument as follows: 4416 Image generation is driven by partitioning commands
4503 <literallayout class='monospaced'> 4417 contained in an Openembedded kickstart file
4504 $ wic -h 4418 (<filename>.wks</filename>) specified either directly on
4505 $ wic --help 4419 the command line or as one of a selection of canned
4506 </literallayout> 4420 <filename>.wks</filename> files as shown with the
4421 <filename>wic list images</filename> command in the
4422 "<link linkend='using-a-provided-kickstart-file'>Using an Existing Kickstart File</link>"
4423 section.
4424 When you apply the command to a given set of build
4425 artifacts, the result is an image or set of images that
4426 can be directly written onto media and used on a particular
4427 system.
4507 </para> 4428 </para>
4508 4429
4509 <para> 4430 <para>
4510 Currently, <filename>wic</filename> supports two commands: 4431 The <filename>wic</filename> command and the infrastructure
4511 <filename>create</filename> and <filename>list</filename>. 4432 it is based on is by definition incomplete.
4512 You can get help for these commands as follows: 4433 The purpose of the command is to allow the generation of
4513 <literallayout class='monospaced'> 4434 customized images, and as such, was designed to be
4514 $ wic help <replaceable>command</replaceable> 4435 completely extensible through a plug-in interface.
4515 </literallayout> 4436 See the
4437 "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>"
4438 section for information on these plug-ins.
4516 </para> 4439 </para>
4517 4440
4518 <para> 4441 <para>
4519 You can also get detailed help on a number of topics 4442 This section provides some background information on Wic,
4520 from the help system. 4443 describes what you need to have in
4521 The output of <filename>wic --help</filename> 4444 place to run the tool, provides instruction on how to use
4522 displays a list of available help 4445 the <filename>wic</filename> utility,
4523 topics under a "Help topics" heading. 4446 and provides several examples.
4524 You can have the help system display the help text for
4525 a given topic by prefacing the topic with
4526 <filename>wic help</filename>:
4527 <literallayout class='monospaced'>
4528 $ wic help <replaceable>help_topic</replaceable>
4529 </literallayout>
4530 </para> 4447 </para>
4531 4448
4532 <para> 4449 <section id='wic-background'>
4533 You can find out more about the images 4450 <title>Background</title>
4534 <filename>wic</filename> creates using the existing
4535 kickstart files with the following form of the command:
4536 <literallayout class='monospaced'>
4537 $ wic list <replaceable>image</replaceable> help
4538 </literallayout>
4539 where <filename><replaceable>image</replaceable></filename> is either
4540 <filename>directdisk</filename> or
4541 <filename>mkefidisk</filename>.
4542 </para>
4543 </section>
4544 4451
4545 <section id='operational-modes'> 4452 <para>
4546 <title>Operational Modes</title> 4453 This section provides some background on the
4454 <filename>wic</filename> utility.
4455 While none of this information is required to use
4456 Wic, you might find it interesting.
4457 <itemizedlist>
4458 <listitem><para>
4459 The name "Wic" is derived from OpenEmbedded
4460 Image Creator (oeic).
4461 The "oe" diphthong in "oeic" was promoted to the
4462 letter "w", because "oeic" is both difficult to
4463 remember and to pronounce.
4464 </para></listitem>
4465 <listitem><para>
4466 Wic is loosely based on the
4467 Meego Image Creator (<filename>mic</filename>)
4468 framework.
4469 The Wic implementation has been
4470 heavily modified to make direct use of OpenEmbedded
4471 build artifacts instead of package installation and
4472 configuration, which are already incorporated within
4473 the OpenEmbedded artifacts.
4474 </para></listitem>
4475 <listitem><para>
4476 Wic is a completely independent
4477 standalone utility that initially provides
4478 easier-to-use and more flexible replacements for a
4479 existing functionality in OE Core's
4480 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
4481 class and <filename>mkefidisk.sh</filename> script.
4482 The difference between
4483 Wic and those examples is
4484 that with Wic the
4485 functionality of those scripts is implemented
4486 by a general-purpose partitioning language, which is
4487 based on Redhat kickstart syntax.</para></listitem>
4488 </itemizedlist>
4489 </para>
4490 </section>
4547 4491
4548 <para> 4492 <section id='wic-requirements'>
4549 You can use <filename>wic</filename> in two different 4493 <title>Requirements</title>
4550 modes, depending on how much control you need for
4551 specifying the Openembedded build artifacts that are
4552 used for creating the image: Raw and Cooked:
4553 <itemizedlist>
4554 <listitem><para><emphasis>Raw Mode:</emphasis>
4555 You explicitly specify build artifacts through
4556 command-line arguments.</para></listitem>
4557 <listitem><para><emphasis>Cooked Mode:</emphasis>
4558 The current
4559 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4560 setting and image name are used to automatically locate
4561 and provide the build artifacts.</para></listitem>
4562 </itemizedlist>
4563 </para>
4564 4494
4565 <para> 4495 <para>
4566 Regardless of the mode you use, you need to have the build 4496 In order to use the <filename>wic</filename> utility
4567 artifacts ready and available. 4497 with the OpenEmbedded Build system, your system needs
4568 Additionally, the environment must be set up using the 4498 to meet the following requirements:
4569 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> 4499 <itemizedlist>
4570 or 4500 <listitem><para>The Linux distribution on your
4571 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> 4501 development host must support the Yocto Project.
4572 script found in the 4502 See the
4573 <link linkend='build-directory'>Build Directory</link>. 4503 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
4574 </para> 4504 section in the Yocto Project Reference Manual for
4505 the list of distributions that support the
4506 Yocto Project.
4507 </para></listitem>
4508 <listitem><para>
4509 The standard system utilities, such as
4510 <filename>cp</filename>, must be installed on your
4511 development host system.
4512 </para></listitem>
4513 <listitem><para>
4514 You need to have the build artifacts already
4515 available, which typically means that you must
4516 have already created an image using the
4517 Openembedded build system (e.g.
4518 <filename>core-image-minimal</filename>).
4519 While it might seem redundant to generate an image
4520 in order to create an image using
4521 Wic, the current version of
4522 Wic requires the artifacts
4523 in the form generated by the build system.
4524 </para></listitem>
4525 <listitem><para>
4526 You must build several native tools, which are tools
4527 built to run on the build system:
4528 <literallayout class='monospaced'>
4529 $ bitbake parted-native dosfstools-native mtools-native
4530 </literallayout>
4531 </para></listitem>
4532 <listitem><para>
4533 You must have sourced one of the build environment
4534 setup scripts (i.e.
4535 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
4536 or
4537 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
4538 found in the
4539 <link linkend='build-directory'>Build Directory</link>.
4540 </para></listitem>
4541 </itemizedlist>
4542 </para>
4543 </section>
4544
4545 <section id='wic-getting-help'>
4546 <title>Getting Help</title>
4547
4548 <para>
4549 You can get general help for the <filename>wic</filename>
4550 command by entering the <filename>wic</filename> command
4551 by itself or by entering the command with a help argument
4552 as follows:
4553 <literallayout class='monospaced'>
4554 $ wic -h
4555 $ wic --help
4556 </literallayout>
4557 </para>
4558
4559 <para>
4560 Currently, Wic supports two commands:
4561 <filename>create</filename> and <filename>list</filename>.
4562 You can get help for these commands as follows:
4563 <literallayout class='monospaced'>
4564 $ wic help <replaceable>command</replaceable>
4565 with <replaceable>command</replaceable> being either
4566 <filename>create</filename> or <filename>list</filename>.
4567 </literallayout>
4568 </para>
4575 4569
4576 <section id='raw-mode'> 4570 <para>
4577 <title>Raw Mode</title> 4571 You can also get detailed help on a number of topics
4572 from the help system.
4573 The output of <filename>wic --help</filename>
4574 displays a list of available help
4575 topics under a "Help topics" heading.
4576 You can have the help system display the help text for
4577 a given topic by prefacing the topic with
4578 <filename>wic help</filename>:
4579 <literallayout class='monospaced'>
4580 $ wic help <replaceable>help_topic</replaceable>
4581 </literallayout>
4582 </para>
4578 4583
4579 <para> 4584 <para>
4580 The general form of the 'wic' command in raw mode is: 4585 You can find out more about the images
4586 Wic creates using the existing
4587 kickstart files with the following form of the command:
4581 <literallayout class='monospaced'> 4588 <literallayout class='monospaced'>
4589 $ wic list <replaceable>image</replaceable> help
4590 </literallayout>
4591 with <filename><replaceable>image</replaceable></filename>
4592 being either <filename>directdisk</filename> or
4593 <filename>mkefidisk</filename>.
4594 </para>
4595 </section>
4596
4597 <section id='operational-modes'>
4598 <title>Operational Modes</title>
4599
4600 <para>
4601 You can use Wic in two different
4602 modes, depending on how much control you need for
4603 specifying the Openembedded build artifacts that are
4604 used for creating the image: Raw and Cooked:
4605 <itemizedlist>
4606 <listitem><para>
4607 <emphasis>Raw Mode:</emphasis>
4608 You explicitly specify build artifacts through
4609 command-line arguments.
4610 </para></listitem>
4611 <listitem><para>
4612 <emphasis>Cooked Mode:</emphasis>
4613 The current
4614 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4615 setting and image name are used to automatically
4616 locate and provide the build artifacts.
4617 </para></listitem>
4618 </itemizedlist>
4619 </para>
4620
4621 <para>
4622 Regardless of the mode you use, you need to have the build
4623 artifacts ready and available.
4624 Additionally, the environment must be set up using the
4625 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
4626 or
4627 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
4628 script found in the
4629 <link linkend='build-directory'>Build Directory</link>.
4630 </para>
4631
4632 <section id='raw-mode'>
4633 <title>Raw Mode</title>
4634
4635 <para>
4636 The general form of the
4637 <filename>wic</filename> command in raw mode is:
4638 <literallayout class='monospaced'>
4582 $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...] 4639 $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...]
4583 4640
4584 Where: 4641 Where:
4585 4642
4586 <replaceable>image_name</replaceable>.wks 4643 <replaceable>image_name</replaceable>.wks
4587 An OpenEmbedded kickstart file. You can provide 4644 An OpenEmbedded kickstart file. You can provide
4588 your own custom file or use a file from a set of 4645 your own custom file or use a file from a set of
4589 existing files as described by further options. 4646 existing files as described by further options.
4590 4647
4591 -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable> 4648 -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable>
4592 The name of a directory in which to create image. 4649 The name of a directory in which to create image.
4593 4650
4594 -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable> 4651 -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable>
4595 The name of a file containing the values for image 4652 The name of a file containing the values for image
4596 properties as a JSON file. 4653 properties as a JSON file.
4597 4654
4598 -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable> 4655 -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable>
4599 The name of the image from which to use the artifacts 4656 The name of the image from which to use the artifacts
4600 (e.g. <filename>core-image-sato</filename>). 4657 (e.g. <filename>core-image-sato</filename>).
4601 4658
4602 -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> 4659 -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable>
4603 The path to the <filename>/rootfs</filename> directory to use as the 4660 The path to the <filename>/rootfs</filename> directory to use as the
4604 <filename>.wks</filename> rootfs source. 4661 <filename>.wks</filename> rootfs source.
4605 4662
4606 -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> 4663 -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable>
4607 The path to the directory containing the boot artifacts 4664 The path to the directory containing the boot artifacts
4608 (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg 4665 (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg
4609 source. 4666 source.
4610 4667
4611 -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable> 4668 -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable>
4612 The path to the directory containing the kernel to use 4669 The path to the directory containing the kernel to use
4613 in the <filename>.wks</filename> boot image. 4670 in the <filename>.wks</filename> boot image.
4614 4671
4615 -n <replaceable>NATIVE_SYSROOT</replaceable>, --native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> 4672 -n <replaceable>NATIVE_SYSROOT</replaceable>, --native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable>
4616 The path to the native sysroot containing the tools to use 4673 The path to the native sysroot containing the tools to use
4617 to build the image. 4674 to build the image.
4618 4675
4619 -s, --skip-build-check 4676 -s, --skip-build-check
4620 Skips the build check. 4677 Skips the build check.
4621 4678
4622 -D, --debug 4679 -D, --debug
4623 Output debug information. 4680 Output debug information.
4624 </literallayout> 4681 </literallayout>
4625 <note> 4682 <note>
4626 You do not need root privileges to run 4683 You do not need root privileges to run
4627 <filename>wic</filename>. 4684 Wic.
4628 In fact, you should not run as root when using the 4685 In fact, you should not run as root when using the
4629 utility. 4686 utility.
4630 </note> 4687 </note>
4631 </para> 4688 </para>
4632 </section> 4689 </section>
4633 4690
4634 <section id='cooked-mode'> 4691 <section id='cooked-mode'>
4635 <title>Cooked Mode</title> 4692 <title>Cooked Mode</title>
4636 4693
4637 <para> 4694 <para>
4638 The general form of the <filename>wic</filename> command 4695 The general form of the <filename>wic</filename> command
4639 using Cooked Mode is: 4696 using Cooked Mode is:
4640 <literallayout class='monospaced'> 4697 <literallayout class='monospaced'>
4641 $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable> 4698 $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable>
4642 4699
4643 Where: 4700 Where:
4644 4701
4645 <replaceable>kickstart_file</replaceable> 4702 <replaceable>kickstart_file</replaceable>
4646 An OpenEmbedded kickstart file. You can provide your own 4703 An OpenEmbedded kickstart file. You can provide your own
4647 custom file or supplied file. 4704 custom file or a supplied file.
4648 4705
4649 <replaceable>image_name</replaceable> 4706 <replaceable>image_name</replaceable>
4650 Specifies the image built using the OpenEmbedded build 4707 Specifies the image built using the OpenEmbedded build
4651 system. 4708 system.
4652 </literallayout> 4709 </literallayout>
4653 This form is the simplest and most user-friendly, as it 4710 This form is the simplest and most user-friendly, as it
4654 does not require specifying all individual parameters. 4711 does not require specifying all individual parameters.
4655 All you need to provide is your own 4712 All you need to provide is your own
4656 <filename>.wks</filename> file or one provided with the 4713 <filename>.wks</filename> file or one provided with the
4657 release. 4714 release.
4658 </para> 4715 </para>
4716 </section>
4659 </section> 4717 </section>
4660 </section>
4661 4718
4662 <section id='using-a-provided-kickstart_file'> 4719 <section id='using-a-provided-kickstart-file'>
4663 <title>Using an Existing Kickstart File</title> 4720 <title>Using an Existing Kickstart File</title>
4664 4721
4665 <para> 4722 <para>
4666 If you do not want to create your own 4723 If you do not want to create your own
4667 <filename>.wks</filename> file, you can use an existing 4724 <filename>.wks</filename> file, you can use an existing
4668 file provided by the <filename>wic</filename> installation. 4725 file provided by the Wic installation.
4669 Use the following command to list the available files: 4726 Use the following command to list the available files:
4670 <literallayout class='monospaced'> 4727 <literallayout class='monospaced'>
4671 $ wic list images 4728 $ wic list images
4672 directdisk Create a 'pcbios' direct disk image 4729 directdisk Create a 'pcbios' direct disk image
4673 mkefidisk Create an EFI disk image 4730 mkefidisk Create an EFI disk image
4674 </literallayout> 4731 </literallayout>
4675 When you use an existing file, you do not have to use the 4732 When you use an existing file, you do not have to use the
4676 <filename>.wks</filename> extension. 4733 <filename>.wks</filename> extension.
4677 Here is an example in Raw Mode that uses the 4734 Here is an example in Raw Mode that uses the
4678 <filename>directdisk</filename> file: 4735 <filename>directdisk</filename> file:
4679 <literallayout class='monospaced'> 4736 <literallayout class='monospaced'>
4680 $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \ 4737 $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \
4681 -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable> 4738 -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable>
4682 </literallayout> 4739 </literallayout>
4683 </para> 4740 </para>
4684 4741
4685 <para> 4742 <para>
4686 Here are the actual partition language commands 4743 Here are the actual partition language commands
4687 used in the <filename>mkefidisk.wks</filename> file to generate 4744 used in the <filename>mkefidisk.wks</filename> file to
4688 an image: 4745 generate an image:
4689 <literallayout class='monospaced'> 4746 <literallayout class='monospaced'>
4690 # short-description: Create an EFI disk image 4747 # short-description: Create an EFI disk image
4691 # long-description: Creates a partitioned EFI disk image that the user 4748 # long-description: Creates a partitioned EFI disk image that the user
4692 # can directly dd to boot media. 4749 # can directly dd to boot media.
@@ -4698,30 +4755,30 @@
4698 part swap --ondisk sda --size 44 --label swap1 --fstype=swap 4755 part swap --ondisk sda --size 44 --label swap1 --fstype=swap
4699 4756
4700 bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0" 4757 bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0"
4701 </literallayout> 4758 </literallayout>
4702 </para> 4759 </para>
4703 </section> 4760 </section>
4704 4761
4705 <section id='wic-usage-examples'> 4762 <section id='wic-usage-examples'>
4706 <title>Examples</title> 4763 <title>Examples</title>
4707 4764
4708 <para> 4765 <para>
4709 This section provides several examples that show how to use 4766 This section provides several examples that show how to use
4710 the <filename>wic</filename> utility. 4767 the <filename>wic</filename> utility.
4711 All the examples assume the list of requirements in the 4768 All the examples assume the list of requirements in the
4712 "<link linkend='wic-requirements'>Requirements</link>" section 4769 "<link linkend='wic-requirements'>Requirements</link>"
4713 have been met. 4770 section have been met.
4714 The examples assume the previously generated image is 4771 The examples assume the previously generated image is
4715 <filename>core-image-minimal</filename>. 4772 <filename>core-image-minimal</filename>.
4716 </para> 4773 </para>
4717 4774
4718 <section id='generate-an-image-using-a-provided-kickstart-file'> 4775 <section id='generate-an-image-using-a-provided-kickstart-file'>
4719 <title>Generate an Image using an Existing Kickstart File</title> 4776 <title>Generate an Image using an Existing Kickstart File</title>
4720 4777
4721 <para> 4778 <para>
4722 This example runs in Cooked Mode and uses the 4779 This example runs in Cooked Mode and uses the
4723 <filename>mkefidisk</filename> kickstart file: 4780 <filename>mkefidisk</filename> kickstart file:
4724 <literallayout class='monospaced'> 4781 <literallayout class='monospaced'>
4725 $ wic create mkefidisk -e core-image-minimal 4782 $ wic create mkefidisk -e core-image-minimal
4726 Checking basic build environment... 4783 Checking basic build environment...
4727 Done. 4784 Done.
@@ -4737,114 +4794,115 @@
4737 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel 4794 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel
4738 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux 4795 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
4739 4796
4740
4741 The image(s) were created using OE kickstart file: 4797 The image(s) were created using OE kickstart file:
4742 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks 4798 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
4743 </literallayout> 4799 </literallayout>
4744 This example shows the easiest way to create an image 4800 The previous example shows the easiest way to create
4745 by running in Cooked Mode and using the 4801 an image by running in Cooked Mode and using the
4746 <filename>-e</filename> option with an existing kickstart 4802 <filename>-e</filename> option with an existing
4747 file. 4803 kickstart file.
4748 All that is necessary is to specify the image used to 4804 All that is necessary is to specify the image used to
4749 generate the artifacts. 4805 generate the artifacts.
4750 Your <filename>local.conf</filename> needs to have the 4806 Your <filename>local.conf</filename> needs to have the
4751 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 4807 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4752 variable set to the machine you are using, which is 4808 variable set to the machine you are using, which is
4753 "minnow" in this example. 4809 "minnow" in this example.
4754 </para> 4810 </para>
4755 4811
4756 <para> 4812 <para>
4757 The output specifies the exact image created as well as 4813 The output specifies the exact image created as well as
4758 where it was created. 4814 where it was created.
4759 The output also names the artifacts used and the exact 4815 The output also names the artifacts used and the exact
4760 <filename>.wks</filename> script that was used to generate 4816 <filename>.wks</filename> script that was used to
4761 the image. 4817 generate the image.
4762 <note> 4818 <note>
4763 You should always verify the details provided in the 4819 You should always verify the details provided in the
4764 output to make sure that the image was indeed created 4820 output to make sure that the image was indeed
4765 exactly as expected. 4821 created exactly as expected.
4766 </note> 4822 </note>
4767 </para> 4823 </para>
4768 4824
4769 <para> 4825 <para>
4770 Continuing with the example, you can now directly 4826 Continuing with the example, you can now directly
4771 <filename>dd</filename> the image to a USB stick, or 4827 <filename>dd</filename> the image to a USB stick, or
4772 whatever media for which you built your image, 4828 whatever media for which you built your image,
4773 and boot the resulting media: 4829 and boot the resulting media:
4774 <literallayout class='monospaced'> 4830 <literallayout class='monospaced'>
4775 $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb 4831 $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
4776 [sudo] password for trz: 4832 [sudo] password for trz:
4777 182274+0 records in 4833 182274+0 records in
4778 182274+0 records out 4834 182274+0 records out
4779 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s 4835 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s
4780 [trz@empanada ~]$ sudo eject /dev/sdb 4836 [trz at empanada ~]$ sudo eject /dev/sdb
4781 </literallayout> 4837 </literallayout>
4782 </para> 4838 </para>
4783 </section> 4839 </section>
4784 4840
4785 <section id='using-a-modified-kickstart-file'> 4841 <section id='using-a-modified-kickstart-file'>
4786 <title>Using a Modified Kickstart File</title> 4842 <title>Using a Modified Kickstart File</title>
4787 4843
4788 <para> 4844 <para>
4789 Because <filename>wic</filename> image creation is driven 4845 Because Wic-partitioned image creation is
4790 by the kickstart file, it is easy to affect image creation 4846 driven by the kickstart file, it is easy to affect
4791 by changing the parameters in the file. 4847 image creation by changing the parameters in the file.
4792 This next example demonstrates that through modification 4848 This next example demonstrates that through modification
4793 of the <filename>directdisk</filename> kickstart file. 4849 of the <filename>directdisk</filename> kickstart file.
4794 </para> 4850 </para>
4795 4851
4796 <para> 4852 <para>
4797 As mentioned earlier, you can use the command 4853 As mentioned earlier, you can use the command
4798 <filename>wic list images</filename> to show the list 4854 <filename>wic list images</filename> to show the list
4799 of existing kickstart files. 4855 of existing kickstart files.
4800 The directory in which these files reside is 4856 The directory in which these files reside is
4801 <filename>scripts/lib/image/canned-wks/</filename> 4857 <filename>scripts/lib/image/canned-wks/</filename>
4802 located in the 4858 located in the
4803 <link linkend='source-directory'>Source Directory</link>. 4859 <link linkend='source-directory'>Source Directory</link>.
4804 Because the available files reside in this directory, you 4860 Because the available files reside in this directory,
4805 can create and add your own custom files to the directory. 4861 you can create and add your own custom files to the
4806 Subsequent use of the <filename>wic list images</filename> 4862 directory.
4807 command would then include your kickstart files. 4863 Subsequent use of the
4808 </para> 4864 <filename>wic list images</filename> command would then
4865 include your kickstart files.
4866 </para>
4809 4867
4810 <para> 4868 <para>
4811 In this example, the existing 4869 In this example, the existing
4812 <filename>directdisk</filename> file already does most 4870 <filename>directdisk</filename> file already does most
4813 of what is needed. 4871 of what is needed.
4814 However, for the hardware in this example, the image will 4872 However, for the hardware in this example, the image
4815 need to boot from <filename>sdb</filename> instead of 4873 will need to boot from <filename>sdb</filename> instead
4816 <filename>sda</filename>, which is what the 4874 of <filename>sda</filename>, which is what the
4817 <filename>directdisk</filename> kickstart file uses. 4875 <filename>directdisk</filename> kickstart file uses.
4818 </para> 4876 </para>
4819 4877
4820 <para> 4878 <para>
4821 The example begins by making a copy of the 4879 The example begins by making a copy of the
4822 <filename>directdisk.wks</filename> file in the 4880 <filename>directdisk.wks</filename> file in the
4823 <filename>scripts/lib/image/canned-wks</filename> 4881 <filename>scripts/lib/image/canned-wks</filename>
4824 directory and then changing the lines that specify the 4882 directory and then by changing the lines that specify
4825 target disk from which to boot. 4883 the target disk from which to boot.
4826 <literallayout class='monospaced'> 4884 <literallayout class='monospaced'>
4827 $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \ 4885 $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \
4828 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks 4886 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
4829 </literallayout> 4887 </literallayout>
4830 Next, the example modifies the 4888 Next, the example modifies the
4831 <filename>directdisksdb.wks</filename> file and changes all 4889 <filename>directdisksdb.wks</filename> file and changes
4832 instances of "<filename>--ondisk sda</filename>" 4890 all instances of "<filename>--ondisk sda</filename>"
4833 to "<filename>--ondisk sdb</filename>". 4891 to "<filename>--ondisk sdb</filename>".
4834 The example changes the following two lines and leaves the 4892 The example changes the following two lines and leaves
4835 remaining lines untouched: 4893 the remaining lines untouched:
4836 <literallayout class='monospaced'> 4894 <literallayout class='monospaced'>
4837 part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 4895 part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
4838 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 4896 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
4839 </literallayout> 4897 </literallayout>
4840 Once the lines are changed, the example generates the 4898 Once the lines are changed, the example generates the
4841 <filename>directdisksdb</filename> image. 4899 <filename>directdisksdb</filename> image.
4842 The command points the process at the 4900 The command points the process at the
4843 <filename>core-image-minimal</filename> artifacts for the 4901 <filename>core-image-minimal</filename> artifacts for
4844 Next Unit of Computing (nuc) 4902 the Next Unit of Computing (nuc)
4845 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 4903 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4846 the <filename>local.conf</filename>. 4904 the <filename>local.conf</filename>.
4847 <literallayout class='monospaced'> 4905 <literallayout class='monospaced'>
4848 $ wic create directdisksdb -e core-image-minimal 4906 $ wic create directdisksdb -e core-image-minimal
4849 Checking basic build environment... 4907 Checking basic build environment...
4850 Done. 4908 Done.
@@ -4855,39 +4913,39 @@
4855 /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct 4913 /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct
4856 4914
4857 The following build artifacts were used to create the image(s): 4915 The following build artifacts were used to create the image(s):
4916
4858 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs 4917 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs
4859 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share 4918 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share
4860 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel 4919 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel
4861 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux 4920 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
4862 4921
4863
4864 The image(s) were created using OE kickstart file: 4922 The image(s) were created using OE kickstart file:
4865 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks 4923 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
4866 </literallayout> 4924 </literallayout>
4867 Continuing with the example, you can now directly 4925 Continuing with the example, you can now directly
4868 <filename>dd</filename> the image to a USB stick, or 4926 <filename>dd</filename> the image to a USB stick, or
4869 whatever media for which you built your image, 4927 whatever media for which you built your image,
4870 and boot the resulting media: 4928 and boot the resulting media:
4871 <literallayout class='monospaced'> 4929 <literallayout class='monospaced'>
4872 $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb 4930 $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb
4873 86018+0 records in 4931 86018+0 records in
4874 86018+0 records out 4932 86018+0 records out
4875 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s 4933 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s
4876 [trz@empanada tmp]$ sudo eject /dev/sdb 4934 [trz at empanada tmp]$ sudo eject /dev/sdb
4877 </literallayout> 4935 </literallayout>
4878 </para> 4936 </para>
4879 </section> 4937 </section>
4880 4938
4881 <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'> 4939 <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'>
4882 <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title> 4940 <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title>
4883 4941
4884 <para> 4942 <para>
4885 This example creates an image based on 4943 This example creates an image based on
4886 <filename>core-image-minimal</filename> and a 4944 <filename>core-image-minimal</filename> and a
4887 <filename>crownbay-noemgd</filename> 4945 <filename>crownbay-noemgd</filename>
4888 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 4946 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4889 that works right out of the box. 4947 that works right out of the box.
4890 <literallayout class='monospaced'> 4948 <literallayout class='monospaced'>
4891 $ wic create directdisk -e core-image-minimal 4949 $ wic create directdisk -e core-image-minimal
4892 4950
4893 Checking basic build environment... 4951 Checking basic build environment...
@@ -4907,21 +4965,21 @@
4907 4965
4908 The image(s) were created using OE kickstart file: 4966 The image(s) were created using OE kickstart file:
4909 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks 4967 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
4910 </literallayout> 4968 </literallayout>
4911 </para> 4969 </para>
4912 </section> 4970 </section>
4913 4971
4914 <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'> 4972 <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'>
4915 <title>Using a Modified Kickstart File and Running in Raw Mode</title> 4973 <title>Using a Modified Kickstart File and Running in Raw Mode</title>
4916 4974
4917 <para> 4975 <para>
4918 This next example manually specifies each build artifact 4976 This next example manually specifies each build artifact
4919 (runs in Raw Mode) and uses a modified kickstart file. 4977 (runs in Raw Mode) and uses a modified kickstart file.
4920 The example also uses the <filename>-o</filename> option 4978 The example also uses the <filename>-o</filename> option
4921 to cause <filename>wic</filename> to create the output 4979 to cause Wic to create the output
4922 somewhere other than the default 4980 somewhere other than the default
4923 <filename>/var/tmp/wic</filename> directory: 4981 <filename>/var/tmp/wic</filename> directory:
4924 <literallayout class='monospaced'> 4982 <literallayout class='monospaced'>
4925 $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \ 4983 $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \
4926 /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ 4984 /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \
4927 --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ 4985 --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \
@@ -4942,437 +5000,477 @@
4942 5000
4943 The image(s) were created using OE kickstart file: 5001 The image(s) were created using OE kickstart file:
4944 /home/trz/test.wks 5002 /home/trz/test.wks
4945 </literallayout> 5003 </literallayout>
4946 For this example, 5004 For this example,
4947 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 5005 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4948 did not have to be specified in the 5006 did not have to be specified in the
4949 <filename>local.conf</filename> file since the artifact is 5007 <filename>local.conf</filename> file since the
4950 manually specified. 5008 artifact is manually specified.
4951 </para> 5009 </para>
5010 </section>
4952 </section> 5011 </section>
4953 </section>
4954 5012
4955 <section id='openembedded-kickstart-plugins'> 5013 <section id='openembedded-kickstart-plugins'>
4956 <title>Plug-ins</title> 5014 <title>Plug-ins</title>
4957 5015
4958 <para> 5016 <para>
4959 Plug-ins allow <filename>wic</filename> functionality to 5017 Plug-ins allow Wic functionality to
4960 be extended and specialized by users. 5018 be extended and specialized by users.
4961 This section documents the plugin interface, which is 5019 This section documents the plug-in interface, which is
4962 currently restricted to source plug ins. 5020 currently restricted to source plug-ins.
4963 </para> 5021 </para>
4964 5022
4965 <para> 5023 <para>
4966 Source plug ins provide a mechanism to customize 5024 Source plug-ins provide a mechanism to customize
4967 various aspects of the image generation process in 5025 various aspects of the image generation process in
4968 <filename>wic</filename>, mainly the contents of 5026 Wic, mainly the contents of
4969 partitions. 5027 partitions.
4970 The plug ins provide a mechanism for mapping values 5028 The plug-ins provide a mechanism for mapping values
4971 specified in <filename>.wks</filename> files using the 5029 specified in <filename>.wks</filename> files using the
4972 <filename>--source</filename> keyword to a 5030 <filename>--source</filename> keyword to a
4973 particular plugin implementation that populates a 5031 particular plug-in implementation that populates a
4974 corresponding partition. 5032 corresponding partition.
4975 </para> 5033 </para>
4976 5034
4977 <para> 5035 <para>
4978 A source plugin is created as a subclass of 5036 A source plug-in is created as a subclass of
4979 <filename>SourcePlugin</filename>. 5037 <filename>SourcePlugin</filename>.
4980 The plugin file containing it is added to 5038 The plug-in file containing it is added to
4981 <filename>scripts/lib/wic/plugins/source/</filename> to 5039 <filename>scripts/lib/wic/plugins/source/</filename> to
4982 make the plugin implementation available to the 5040 make the plug-in implementation available to the
4983 <filename>wic</filename> implementation. 5041 Wic implementation.
4984 For more information, see 5042 For more information, see
4985 <filename>scripts/lib/wic/pluginbase.py</filename>. 5043 <filename>scripts/lib/wic/pluginbase.py</filename>.
4986 </para> 5044 </para>
4987 5045
4988 <para> 5046 <para>
4989 Source plugins can also be implemented and added by 5047 Source plug-ins can also be implemented and added by
4990 external layers. 5048 external layers.
4991 As such, any plugins found in a 5049 As such, any plug-ins found in a
4992 <filename>scripts/lib/wic/plugins/source/</filename> 5050 <filename>scripts/lib/wic/plugins/source/</filename>
4993 directory in an external layer are also made 5051 directory in an external layer are also made
4994 available. 5052 available.
4995 </para> 5053 </para>
4996 5054
4997 <para> 5055 <para>
4998 When the <filename>wic</filename> implementation needs 5056 When the Wic implementation needs
4999 to invoke a partition-specific implementation, it looks 5057 to invoke a partition-specific implementation, it looks
5000 for the plugin that has the same name as the 5058 for the plug-in that has the same name as the
5001 <filename>--source</filename> parameter given to 5059 <filename>--source</filename> parameter given to
5002 that partition. 5060 that partition.
5003 For example, if the partition is set up as follows: 5061 For example, if the partition is set up as follows:
5004 <literallayout class='monospaced'> 5062 <literallayout class='monospaced'>
5005 part /boot --source bootimg-pcbios ... 5063 part /boot --source bootimg-pcbios ...
5006 </literallayout> 5064 </literallayout>
5007 The methods defined as class members of the plugin 5065 The methods defined as class members of the plug-in
5008 having the matching <filename>bootimg-pcbios.name</filename> 5066 having the matching <filename>bootimg-pcbios.name</filename>
5009 class member are used. 5067 class member are used.
5010 </para> 5068 </para>
5011 5069
5012 <para> 5070 <para>
5013 To be more concrete, here is the plugin definition that 5071 To be more concrete, here is the plug-in definition that
5014 matches a 5072 matches a
5015 <filename>--source bootimg-pcbios</filename> usage, 5073 <filename>--source bootimg-pcbios</filename> usage,
5016 along with an example 5074 along with an example
5017 method called by the <filename>wic</filename> implementation 5075 method called by the Wic implementation
5018 when it needs to invoke an implementation-specific 5076 when it needs to invoke an implementation-specific
5019 partition-preparation function: 5077 partition-preparation function:
5020 <literallayout class='monospaced'> 5078 <literallayout class='monospaced'>
5021 class BootimgPcbiosPlugin(SourcePlugin): 5079 class BootimgPcbiosPlugin(SourcePlugin):
5022 name = 'bootimg-pcbios' 5080 name = 'bootimg-pcbios'
5023 5081
5024 @classmethod 5082 @classmethod
5025 def do_prepare_partition(self, part, ...) 5083 def do_prepare_partition(self, part, ...)
5026 </literallayout>
5027 If the subclass itself does not implement a function, a
5028 default version in a superclass is located and
5029 used, which is why all plugins must be derived from
5030 <filename>SourcePlugin</filename>.
5031 </para>
5032
5033 <para>
5034 The <filename>SourcePlugin</filename> class defines the
5035 following methods, which is the current set of methods
5036 that can be implemented or overridden by
5037 <filename>--source</filename> plugins.
5038 Any methods not implemented by a
5039 <filename>SourcePlugin</filename> subclass inherit the
5040 implementations present in the
5041 <filename>SourcePlugin</filename> class.
5042 For more information, see the
5043 <filename>SourcePlugin</filename> source for details:
5044 </para>
5045
5046 <para>
5047 <itemizedlist>
5048 <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis>
5049 Called to do the actual content population for a
5050 partition.
5051 In other words, the method prepares the final
5052 partition image that is incorporated into the
5053 disk image.
5054 </para></listitem>
5055 <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis>
5056 Called before
5057 <filename>do_prepare_partition()</filename>.
5058 This method is typically used to create custom
5059 configuration files for a partition (e.g. syslinux or
5060 grub configuration files).
5061 </para></listitem>
5062 <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis>
5063 Called after all partitions have been prepared and
5064 assembled into a disk image.
5065 This method provides a hook to allow finalization of a
5066 disk image, (e.g. writing an MBR).
5067 </para></listitem>
5068 <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis>
5069 Special content-staging hook called before
5070 <filename>do_prepare_partition()</filename>.
5071 This method is normally empty.</para>
5072 <para>Typically, a partition just uses the passed-in
5073 parameters (e.g. the unmodified value of
5074 <filename>bootimg_dir</filename>).
5075 However, in some cases things might need to be
5076 more tailored.
5077 As an example, certain files might additionally
5078 need to be taken from
5079 <filename>bootimg_dir + /boot</filename>.
5080 This hook allows those files to be staged in a
5081 customized fashion.
5082 <note>
5083 <filename>get_bitbake_var()</filename>
5084 allows you to access non-standard variables
5085 that you might want to use for this.
5086 </note>
5087 </para></listitem>
5088 </itemizedlist>
5089 </para>
5090
5091 <para>
5092 This scheme is extensible.
5093 Adding more hooks is a simple matter of adding more
5094 plugin methods to <filename>SourcePlugin</filename> and
5095 derived classes.
5096 The code that then needs to call the plugin methods uses
5097 <filename>plugin.get_source_plugin_methods()</filename>
5098 to find the method or methods needed by the call.
5099 Retrieval of those methods is accomplished
5100 by filling up a dict with keys
5101 containing the method names of interest.
5102 On success, these will be filled in with the actual
5103 methods.
5104 Please see the <filename>wic</filename>
5105 implementation for examples and details.
5106 </para>
5107 </section>
5108
5109 <section id='openembedded-kickstart-wks-reference'>
5110 <title>OpenEmbedded Kickstart (.wks) Reference</title>
5111
5112 <para>
5113 The current <filename>wic</filename> implementation supports
5114 only the basic kickstart partitioning commands:
5115 <filename>partition</filename> (or <filename>part</filename>
5116 for short) and <filename>bootloader</filename>.
5117 <note>
5118 Future updates will implement more commands and options.
5119 If you use anything that is not specifically
5120 supported, results can be unpredictable.
5121 </note>
5122 </para>
5123
5124 <para>
5125 The following is a list of the commands, their syntax,
5126 and meanings.
5127 The commands are based on the Fedora
5128 kickstart versions but with modifications to
5129 reflect <filename>wic</filename> capabilities.
5130 You can see the original documentation for those commands
5131 at the following links:
5132 <itemizedlist>
5133 <listitem><para>
5134 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
5135 </para></listitem>
5136 <listitem><para>
5137 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink>
5138 </para></listitem>
5139 </itemizedlist>
5140 </para>
5141
5142 <section id='command-part-or-partition'>
5143 <title>Command: part or partition</title>
5144
5145 <para>
5146 Either of these commands create a partition on the system
5147 and uses the following syntax:
5148 <literallayout class='monospaced'>
5149 part [<replaceable>mntpoint</replaceable>]
5150 partition [<replaceable>mntpoint</replaceable>]
5151 </literallayout> 5084 </literallayout>
5152 If you do not provide 5085 If the subclass itself does not implement a function, a
5153 <replaceable>mntpoint</replaceable>, wic creates a partition 5086 default version in a superclass is located and
5154 but does not mount it. 5087 used, which is why all plug-ins must be derived from
5155 </para> 5088 <filename>SourcePlugin</filename>.
5156
5157 <para>
5158 The <filename><replaceable>mntpoint</replaceable></filename>
5159 is where the
5160 partition will be mounted and must be of one of the
5161 following forms:
5162 <itemizedlist>
5163 <listitem><para><filename>/<replaceable>path</replaceable></filename>:
5164 For example, <filename>/</filename>,
5165 <filename>/usr</filename>, or
5166 <filename>/home</filename></para></listitem>
5167 <listitem><para><filename>swap</filename>:
5168 The created partition is used as swap space.
5169 </para></listitem>
5170 </itemizedlist>
5171 </para> 5089 </para>
5172 5090
5173 <para> 5091 <para>
5174 Specifying a <replaceable>mntpoint</replaceable> causes 5092 The <filename>SourcePlugin</filename> class defines the
5175 the partition to automatically be mounted. 5093 following methods, which is the current set of methods
5176 Wic achieves this by adding entries to the filesystem 5094 that can be implemented or overridden by
5177 table (fstab) during image generation. 5095 <filename>--source</filename> plug-ins.
5178 In order for wic to generate a valid fstab, you must 5096 Any methods not implemented by a
5179 also provide one of the <filename>--ondrive</filename>, 5097 <filename>SourcePlugin</filename> subclass inherit the
5180 <filename>--ondisk</filename>, or 5098 implementations present in the
5181 <filename>--use-uuid</filename> partition options as part 5099 <filename>SourcePlugin</filename> class.
5182 of the command. 5100 For more information, see the
5183 Here is an example using "/" as the mountpoint. 5101 <filename>SourcePlugin</filename> source for details:
5184 The command uses "--ondisk" to force the partition onto
5185 the <filename>sdb</filename> disk:
5186 <literallayout class='monospaced'>
5187 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
5188 </literallayout>
5189 </para> 5102 </para>
5190 5103
5191 <para> 5104 <para>
5192 Here is a list that describes other supported options you
5193 can use with the <filename>part</filename> and
5194 <filename>partition</filename> commands:
5195 <itemizedlist> 5105 <itemizedlist>
5196 <listitem><para><emphasis><filename>--size</filename>:</emphasis> 5106 <listitem><para>
5197 The minimum partition size in MBytes. 5107 <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
5198 Specify an integer value such as 500. 5108 Called to do the actual content population for a
5199 Do not append the number with "MB".
5200 You do not need this option if you use
5201 <filename>--source</filename>.</para></listitem>
5202 <listitem><para><emphasis><filename>--source</filename>:</emphasis>
5203 This option is a
5204 <filename>wic</filename>-specific option that
5205 names the source of the data that populates
5206 the partition.
5207 The most common value for this option is
5208 "rootfs", but you can use any value that maps to
5209 a valid source plugin.
5210 For information on the source plugins, see the
5211 "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
5212 section.</para>
5213 <para>If you use
5214 <filename>--source rootfs</filename>,
5215 <filename>wic</filename> creates a partition as
5216 large as needed and to fill it with the contents of
5217 the root filesystem pointed to by the
5218 <filename>-r</filename> command-line option
5219 or the equivalent rootfs derived from the
5220 <filename>-e</filename> command-line
5221 option.
5222 The filesystem type used to create the
5223 partition is driven by the value of the
5224 <filename>--fstype</filename> option
5225 specified for the partition.
5226 See the entry on
5227 <filename>--fstype</filename> that
5228 follows for more information.
5229 </para>
5230 <para>If you use
5231 <filename>--source <replaceable>plugin-name</replaceable></filename>,
5232 <filename>wic</filename> creates a partition as
5233 large as needed and fills it with the contents of
5234 the partition that is generated by the
5235 specified plugin name using the data pointed
5236 to by the <filename>-r</filename> command-line
5237 option or the equivalent rootfs derived from the
5238 <filename>-e</filename> command-line
5239 option.
5240 Exactly what those contents and filesystem type end
5241 up being are dependent on the given plugin
5242 implementation.
5243 </para>
5244 <para>If you do not use the
5245 <filename>--source</filename> option, the
5246 <filename>wic</filename> command creates an empty
5247 partition. 5109 partition.
5248 Consequently, you must use the 5110 In other words, the method prepares the final
5249 <filename>--size</filename> option to specify the 5111 partition image that is incorporated into the
5250 size of the empty partition. 5112 disk image.
5251 </para></listitem> 5113 </para></listitem>
5252 <listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> 5114 <listitem><para>
5253 Forces the partition to be created on a particular 5115 <emphasis><filename>do_configure_partition()</filename>:</emphasis>
5254 disk.</para></listitem> 5116 Called before
5255 <listitem><para><emphasis><filename>--fstype</filename>:</emphasis> 5117 <filename>do_prepare_partition()</filename>.
5256 Sets the file system type for the partition. 5118 This method is typically used to create custom
5257 Valid values are: 5119 configuration files for a partition (e.g. syslinux
5258 <itemizedlist> 5120 or grub configuration files).
5259 <listitem><para><filename>ext4</filename>
5260 </para></listitem>
5261 <listitem><para><filename>ext3</filename>
5262 </para></listitem>
5263 <listitem><para><filename>ext2</filename>
5264 </para></listitem>
5265 <listitem><para><filename>btrfs</filename>
5266 </para></listitem>
5267 <listitem><para><filename>squashfs</filename>
5268 </para></listitem>
5269 <listitem><para><filename>swap</filename>
5270 </para></listitem>
5271 </itemizedlist></para></listitem>
5272 <listitem><para><emphasis><filename>--fsoptions</filename>:</emphasis>
5273 Specifies a free-form string of options to be
5274 used when mounting the filesystem.
5275 This string will be copied into the
5276 <filename>/etc/fstab</filename> file of the
5277 installed system and should be enclosed in
5278 quotes.
5279 If not specified, the default string
5280 is "defaults".
5281 </para></listitem>
5282 <listitem><para><emphasis><filename>--label label</filename>:</emphasis>
5283 Specifies the label to give to the filesystem to
5284 be made on the partition.
5285 If the given label is already in use by another
5286 filesystem, a new label is created for the
5287 partition.</para></listitem>
5288 <listitem><para><emphasis><filename>--active</filename>:</emphasis>
5289 Marks the partition as active.</para></listitem>
5290 <listitem><para><emphasis><filename>--align (in KBytes)</filename>:</emphasis>
5291 This option is a <filename>wic</filename>-specific
5292 option that says to start a partition on an
5293 x KBytes boundary.</para></listitem>
5294 <listitem><para><emphasis><filename>--no-table</filename>:</emphasis>
5295 This option is a <filename>wic</filename>-specific
5296 option.
5297 Using the option reserves space for the partition
5298 and causes it to become populated.
5299 However, the partition is not added to the
5300 partition table.
5301 </para></listitem>
5302 <listitem><para><emphasis><filename>--extra-space</filename>:</emphasis>
5303 This option is a <filename>wic</filename>-specific
5304 option that adds extra space after the space
5305 filled by the content of the partition.
5306 The final size can go beyond the size specified
5307 by the <filename>--size</filename> option.
5308 The default value is 10 Mbytes.
5309 </para></listitem>
5310 <listitem><para><emphasis><filename>--overhead-factor</filename>:</emphasis>
5311 This option is a <filename>wic</filename>-specific
5312 option that multiplies the size of the partition by
5313 the option's value.
5314 You must supply a value greater than or equal to
5315 "1".
5316 The default value is "1.3".
5317 </para></listitem>
5318 <listitem><para><emphasis><filename>--part-type</filename>:</emphasis>
5319 This option is a <filename>wic</filename>-specific
5320 option that specifies the partition type globally
5321 unique identifier (GUID) for GPT partitions.
5322 You can find the list of partition type GUIDs
5323 at
5324 <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>.
5325 </para></listitem> 5121 </para></listitem>
5326 <listitem><para><emphasis><filename>--use-uuid</filename>:</emphasis> 5122 <listitem><para>
5327 This option is a <filename>wic</filename>-specific 5123 <emphasis><filename>do_install_disk()</filename>:</emphasis>
5328 option that causes <filename>wic</filename> to 5124 Called after all partitions have been prepared and
5329 generate a random GUID for the partition. 5125 assembled into a disk image.
5330 The generated identifier is used in the bootloader 5126 This method provides a hook to allow finalization
5331 configuration to specify the root partition. 5127 of a disk image, (e.g. writing an MBR).
5332 </para></listitem> 5128 </para></listitem>
5333 <listitem><para><emphasis><filename>--uuid</filename>:</emphasis> 5129 <listitem><para>
5334 This option is a <filename>wic</filename>-specific 5130 <emphasis><filename>do_stage_partition()</filename>:</emphasis>
5335 option that specifies the partition UUID. 5131 Special content-staging hook called before
5132 <filename>do_prepare_partition()</filename>.
5133 This method is normally empty.</para>
5134 <para>Typically, a partition just uses the passed-in
5135 parameters (e.g. the unmodified value of
5136 <filename>bootimg_dir</filename>).
5137 However, in some cases things might need to be
5138 more tailored.
5139 As an example, certain files might additionally
5140 need to be taken from
5141 <filename>bootimg_dir + /boot</filename>.
5142 This hook allows those files to be staged in a
5143 customized fashion.
5144 <note>
5145 <filename>get_bitbake_var()</filename>
5146 allows you to access non-standard variables
5147 that you might want to use for this.
5148 </note>
5336 </para></listitem> 5149 </para></listitem>
5337 </itemizedlist> 5150 </itemizedlist>
5338 </para> 5151 </para>
5152
5153 <para>
5154 This scheme is extensible.
5155 Adding more hooks is a simple matter of adding more
5156 plug-in methods to <filename>SourcePlugin</filename> and
5157 derived classes.
5158 The code that then needs to call the plug-in methods uses
5159 <filename>plugin.get_source_plugin_methods()</filename>
5160 to find the method or methods needed by the call.
5161 Retrieval of those methods is accomplished
5162 by filling up a dict with keys
5163 containing the method names of interest.
5164 On success, these will be filled in with the actual
5165 methods.
5166 Please see the Wic
5167 implementation for examples and details.
5168 </para>
5339 </section> 5169 </section>
5340 5170
5341 <section id='command-bootloader'> 5171 <section id='openembedded-kickstart-wks-reference'>
5342 <title>Command: bootloader</title> 5172 <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title>
5343 5173
5344 <para> 5174 <para>
5345 This command specifies how the boot loader should be 5175 The current Wic implementation supports
5346 configured and supports the following options: 5176 only the basic kickstart partitioning commands:
5177 <filename>partition</filename> (or <filename>part</filename>
5178 for short) and <filename>bootloader</filename>.
5347 <note> 5179 <note>
5348 Bootloader functionality and boot partitions are 5180 Future updates will implement more commands and options.
5349 implemented by the various 5181 If you use anything that is not specifically
5350 <filename>--source</filename> 5182 supported, results can be unpredictable.
5351 plugins that implement bootloader functionality.
5352 The bootloader command essentially provides a means of
5353 modifying bootloader configuration.
5354 </note> 5183 </note>
5184 </para>
5185
5186 <para>
5187 The following is a list of the commands, their syntax,
5188 and meanings.
5189 The commands are based on the Fedora
5190 kickstart versions but with modifications to
5191 reflect Wic capabilities.
5192 You can see the original documentation for those commands
5193 at the following links:
5355 <itemizedlist> 5194 <itemizedlist>
5356 <listitem><para><emphasis><filename>--timeout</filename>:</emphasis> 5195 <listitem><para>
5357 Specifies the number of seconds before the 5196 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
5358 bootloader times out and boots the default option.
5359 </para></listitem>
5360 <listitem><para><emphasis><filename>--append</filename>:</emphasis>
5361 Specifies kernel parameters.
5362 These parameters will be added to the syslinux
5363 <filename>APPEND</filename> or
5364 <filename>grub</filename> kernel command line.
5365 </para></listitem> 5197 </para></listitem>
5366 <listitem><para><emphasis><filename>--configfile</filename>:</emphasis> 5198 <listitem><para>
5367 Specifies a user-defined configuration file for 5199 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink>
5368 the bootloader.
5369 You can provide a full pathname for the file or
5370 a file that exists in the
5371 <filename>canned-wks</filename> folder.
5372 This option overrides all other bootloader options.
5373 </para></listitem> 5200 </para></listitem>
5374 </itemizedlist> 5201 </itemizedlist>
5375 </para> 5202 </para>
5203
5204 <section id='command-part-or-partition'>
5205 <title>Command: part or partition</title>
5206
5207 <para>
5208 Either of these commands create a partition on the system
5209 and use the following syntax:
5210 <literallayout class='monospaced'>
5211 part [<replaceable>mntpoint</replaceable>]
5212 partition [<replaceable>mntpoint</replaceable>]
5213 </literallayout>
5214 If you do not provide
5215 <replaceable>mntpoint</replaceable>, Wic creates a
5216 partition but does not mount it.
5217 </para>
5218
5219 <para>
5220 The
5221 <filename><replaceable>mntpoint</replaceable></filename>
5222 is where the partition will be mounted and must be of
5223 one of the following forms:
5224 <itemizedlist>
5225 <listitem><para>
5226 <filename>/<replaceable>path</replaceable></filename>:
5227 For example, <filename>/</filename>,
5228 <filename>/usr</filename>, or
5229 <filename>/home</filename>
5230 </para></listitem>
5231 <listitem><para>
5232 <filename>swap</filename>:
5233 The created partition is used as swap space.
5234 </para></listitem>
5235 </itemizedlist>
5236 </para>
5237
5238 <para>
5239 Specifying a <replaceable>mntpoint</replaceable> causes
5240 the partition to automatically be mounted.
5241 Wic achieves this by adding entries to the filesystem
5242 table (fstab) during image generation.
5243 In order for wic to generate a valid fstab, you must
5244 also provide one of the <filename>--ondrive</filename>,
5245 <filename>--ondisk</filename>, or
5246 <filename>--use-uuid</filename> partition options as
5247 part of the command.
5248 Here is an example using "/" as the mountpoint.
5249 The command uses "--ondisk" to force the partition onto
5250 the <filename>sdb</filename> disk:
5251 <literallayout class='monospaced'>
5252 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
5253 </literallayout>
5254 </para>
5255
5256 <para>
5257 Here is a list that describes other supported options
5258 you can use with the <filename>part</filename> and
5259 <filename>partition</filename> commands:
5260 <itemizedlist>
5261 <listitem><para>
5262 <emphasis><filename>--size</filename>:</emphasis>
5263 The minimum partition size in MBytes.
5264 Specify an integer value such as 500.
5265 Do not append the number with "MB".
5266 You do not need this option if you use
5267 <filename>--source</filename>.
5268 </para></listitem>
5269 <listitem><para>
5270 <emphasis><filename>--source</filename>:</emphasis>
5271 This option is a
5272 Wic-specific option that
5273 names the source of the data that populates
5274 the partition.
5275 The most common value for this option is
5276 "rootfs", but you can use any value that maps to
5277 a valid source plug-in.
5278 For information on the source plug-ins, see the
5279 "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>"
5280 section.</para>
5281 <para>If you use
5282 <filename>--source rootfs</filename>,
5283 Wic creates a partition as
5284 large as needed and to fill it with the contents
5285 of the root filesystem pointed to by the
5286 <filename>-r</filename> command-line option
5287 or the equivalent rootfs derived from the
5288 <filename>-e</filename> command-line
5289 option.
5290 The filesystem type used to create the
5291 partition is driven by the value of the
5292 <filename>--fstype</filename> option
5293 specified for the partition.
5294 See the entry on
5295 <filename>--fstype</filename> that
5296 follows for more information.
5297 </para>
5298 <para>If you use
5299 <filename>--source <replaceable>plugin-name</replaceable></filename>,
5300 Wic creates a partition as
5301 large as needed and fills it with the contents
5302 of the partition that is generated by the
5303 specified plug-in name using the data pointed
5304 to by the <filename>-r</filename> command-line
5305 option or the equivalent rootfs derived from the
5306 <filename>-e</filename> command-line
5307 option.
5308 Exactly what those contents and filesystem type
5309 end up being are dependent on the given plug-in
5310 implementation.
5311 </para>
5312 <para>If you do not use the
5313 <filename>--source</filename> option, the
5314 <filename>wic</filename> command creates an
5315 empty partition.
5316 Consequently, you must use the
5317 <filename>--size</filename> option to specify
5318 the size of the empty partition.
5319 </para></listitem>
5320 <listitem><para>
5321 <emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis>
5322 Forces the partition to be created on a
5323 particular disk.
5324 </para></listitem>
5325 <listitem><para>
5326 <emphasis><filename>--fstype</filename>:</emphasis>
5327 Sets the file system type for the partition.
5328 Valid values are:
5329 <itemizedlist>
5330 <listitem><para><filename>ext4</filename>
5331 </para></listitem>
5332 <listitem><para><filename>ext3</filename>
5333 </para></listitem>
5334 <listitem><para><filename>ext2</filename>
5335 </para></listitem>
5336 <listitem><para><filename>btrfs</filename>
5337 </para></listitem>
5338 <listitem><para><filename>squashfs</filename>
5339 </para></listitem>
5340 <listitem><para><filename>swap</filename>
5341 </para></listitem>
5342 </itemizedlist>
5343 </para></listitem>
5344 <listitem><para>
5345 <emphasis><filename>--fsoptions</filename>:</emphasis>
5346 Specifies a free-form string of options to be
5347 used when mounting the filesystem.
5348 This string will be copied into the
5349 <filename>/etc/fstab</filename> file of the
5350 installed system and should be enclosed in
5351 quotes.
5352 If not specified, the default string
5353 is "defaults".
5354 </para></listitem>
5355 <listitem><para>
5356 <emphasis><filename>--label label</filename>:</emphasis>
5357 Specifies the label to give to the filesystem to
5358 be made on the partition.
5359 If the given label is already in use by another
5360 filesystem, a new label is created for the
5361 partition.
5362 </para></listitem>
5363 <listitem><para>
5364 <emphasis><filename>--active</filename>:</emphasis>
5365 Marks the partition as active.
5366 </para></listitem>
5367 <listitem><para>
5368 <emphasis><filename>--align (in KBytes)</filename>:</emphasis>
5369 This option is a
5370 Wic-specific option that
5371 says to start a partition on an
5372 <replaceable>x</replaceable> KBytes
5373 boundary.</para></listitem>
5374 <listitem><para>
5375 <emphasis><filename>--no-table</filename>:</emphasis>
5376 This option is a
5377 Wic-specific option.
5378 Using the option reserves space for the
5379 partition and causes it to become populated.
5380 However, the partition is not added to the
5381 partition table.
5382 </para></listitem>
5383 <listitem><para>
5384 <emphasis><filename>--extra-space</filename>:</emphasis>
5385 This option is a
5386 Wic-specific option that
5387 adds extra space after the space filled by the
5388 content of the partition.
5389 The final size can go beyond the size specified
5390 by the <filename>--size</filename> option.
5391 The default value is 10 Mbytes.
5392 </para></listitem>
5393 <listitem><para>
5394 <emphasis><filename>--overhead-factor</filename>:</emphasis>
5395 This option is a
5396 Wic-specific option that
5397 multiplies the size of the partition by the
5398 option's value.
5399 You must supply a value greater than or equal to
5400 "1".
5401 The default value is "1.3".
5402 </para></listitem>
5403 <listitem><para>
5404 <emphasis><filename>--part-type</filename>:</emphasis>
5405 This option is a
5406 Wic-specific option that
5407 specifies the partition type globally
5408 unique identifier (GUID) for GPT partitions.
5409 You can find the list of partition type GUIDs
5410 at
5411 <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>.
5412 </para></listitem>
5413 <listitem><para>
5414 <emphasis><filename>--use-uuid</filename>:</emphasis>
5415 This option is a
5416 Wic-specific option that
5417 causes Wic to generate a
5418 random GUID for the partition.
5419 The generated identifier is used in the
5420 bootloader configuration to specify the root
5421 partition.
5422 </para></listitem>
5423 <listitem><para>
5424 <emphasis><filename>--uuid</filename>:</emphasis>
5425 This option is a
5426 Wic-specific
5427 option that specifies the partition UUID.
5428 </para></listitem>
5429 </itemizedlist>
5430 </para>
5431 </section>
5432
5433 <section id='command-bootloader'>
5434 <title>Command: bootloader</title>
5435
5436 <para>
5437 This command specifies how the bootloader should be
5438 configured and supports the following options:
5439 <note>
5440 Bootloader functionality and boot partitions are
5441 implemented by the various
5442 <filename>--source</filename>
5443 plug-ins that implement bootloader functionality.
5444 The bootloader command essentially provides a
5445 means of modifying bootloader configuration.
5446 </note>
5447 <itemizedlist>
5448 <listitem><para>
5449 <emphasis><filename>--timeout</filename>:</emphasis>
5450 Specifies the number of seconds before the
5451 bootloader times out and boots the default
5452 option.
5453 </para></listitem>
5454 <listitem><para>
5455 <emphasis><filename>--append</filename>:</emphasis>
5456 Specifies kernel parameters.
5457 These parameters will be added to the syslinux
5458 <filename>APPEND</filename> or
5459 <filename>grub</filename> kernel command line.
5460 </para></listitem>
5461 <listitem><para>
5462 <emphasis><filename>--configfile</filename>:</emphasis>
5463 Specifies a user-defined configuration file for
5464 the bootloader.
5465 You can provide a full pathname for the file or
5466 a file that exists in the
5467 <filename>canned-wks</filename> folder.
5468 This option overrides all other bootloader
5469 options.
5470 </para></listitem>
5471 </itemizedlist>
5472 </para>
5473 </section>
5376 </section> 5474 </section>
5377 </section> 5475 </section>
5378 </section> 5476 </section>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-13 15:15:19 +0000