diff options
| author |   Scott Rifenbark <srifenbark@gmail.com> | 2016-12-12 17:04:46 -0800 |
|---|---|---|
| committer |   Richard Purdie <richard.purdie@linuxfoundation.org> | 2017-01-11 17:23:10 +0000 |
| commit | ba8fc212de04491a7a9b5f0113117e8c508629b7 (patch) | |
| tree | abdb29f051612828d171fba8b86b812995a8911a | |
| parent | ac6773117afa6fef5383b7d1c23d139f32568c5d (diff) | |
| download | openembedded-core-contrib-ba8fc212de04491a7a9b5f0113117e8c508629b7.tar.gz | |
dev-manual: Updated to the "Creating Partitioned Images" section
new information on how wic works
(From yocto-docs rev: c5bfbba2bc810eb1ff8825b66aa1397cfeed8ce1)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
| -rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 1692 |
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 @@ </para></listitem> </itemizedlist> </para> -' + <para> For the RPM Package Management System, the following implementation details exist: @@ -4365,328 +4365,385 @@ format the device requires. Should your device require multiple partitions on an SD card, flash, or an HDD, you can use the OpenEmbedded Image Creator, - <filename>wic</filename>, to create the properly partitioned image. - </para> - - <para> - The <filename>wic</filename> command generates partitioned images - from existing OpenEmbedded build artifacts. - Image generation is driven by partitioning commands contained - in an Openembedded kickstart file (<filename>.wks</filename>) - specified either directly on the command line or as one of a - selection of canned <filename>.wks</filename> files as shown - with the <filename>wic list images</filename> command in the - "<link linkend='using-a-provided-kickstart_file'>Using an Existing Kickstart File</link>" - section. - When applied to a given set of build artifacts, the result is an - image or set of images that can be directly written onto media and - used on a particular system. + Wic, to create the properly partitioned image. </para> <para> - The <filename>wic</filename> command and the infrastructure - it is based on is by definition incomplete. - Its purpose is to allow the generation of customized images, - and as such was designed to be completely extensible through a - plug-in interface. - See the - "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" - section for information on these plug-ins. - </para> - - <para> - This section provides some background information on - <filename>wic</filename>, describes what you need to have in - place to run the tool, provides instruction on how to use - <filename>wic</filename>, and provides several examples. + You can generate Wic-partitioned images + (<replaceable>image</replaceable><filename>.wic</filename>) + two ways: using the OpenEmbedded build system and by running + the OpenEmbedded Image Creator Wic directly. + The former way is preferable as it is easier to use and understand. </para> - <section id='wic-background'> - <title>Background</title> + <section id='creating-wic-images-oe'> + <title>Creating Wic-Partitioned Images</title> <para> - This section provides some background on the - <filename>wic</filename> utility. - While none of this information is required to use - <filename>wic</filename>, you might find it interesting. + The OpenEmbedded build system can generate + Wic-partitioned images the same way as it generates + any other image type. + To generate a Wic-partitioned image, you need to modify + two variables. <itemizedlist> <listitem><para> - The name "wic" is derived from OpenEmbedded - Image Creator (oeic). - The "oe" diphthong in "oeic" was promoted to the - letter "w", because "oeic" is both difficult to remember and - pronounce.</para></listitem> - <listitem><para> - <filename>wic</filename> is loosely based on the - Meego Image Creator (<filename>mic</filename>) - framework. - The <filename>wic</filename> implementation has been - heavily modified to make direct use of OpenEmbedded - build artifacts instead of package installation and - configuration, which are already incorporated within - the OpenEmbedded artifacts.</para></listitem> - <listitem><para> - <filename>wic</filename> is a completely independent - standalone utility that initially provides - easier-to-use and more flexible replacements for a - couple bits of existing functionality in OE Core's - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink> - class and <filename>mkefidisk.sh</filename> script. - The difference between - <filename>wic</filename> and those examples is - that with <filename>wic</filename> the - functionality of those scripts is implemented - by a general-purpose partitioning language, which is - based on Redhat kickstart syntax.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='wic-requirements'> - <title>Requirements</title> - - <para> - In order to use the <filename>wic</filename> utility - with the OpenEmbedded Build system, your system needs - to meet the following requirements: - <itemizedlist> - <listitem><para>The Linux distribution on your - development host must support the Yocto Project. - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" - section in the Yocto Project Reference Manual for this - list of distributions.</para></listitem> - <listitem><para> - The standard system utilities, such as - <filename>cp</filename>, must be installed on your - development host system. - </para></listitem> - <listitem><para> - You need to have the build artifacts already - available, which typically means that you must - have already created an image using the - Openembedded build system (e.g. - <filename>core-image-minimal</filename>). - While it might seem redundant to generate an image in - order to create an image using - <filename>wic</filename>, the current version of - <filename>wic</filename> requires the artifacts - in the form generated by the build system. - </para></listitem> - <listitem><para> - You must build several native tools, which are tools - built to run on the build system: - <literallayout class='monospaced'> - $ bitbake parted-native dosfstools-native mtools-native - </literallayout> + Include "wic" as part of the + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink> + variable. </para></listitem> <listitem><para> - You must have sourced one of the build environment - setup scripts (i.e. - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) - found in the - <link linkend='build-directory'>Build Directory</link>. + Include the name of the + <link linkend='openembedded-kickstart-wks-reference'>wic kickstart file</link> + as part of the + <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink> + variable </para></listitem> </itemizedlist> + Further steps to generate a Wic-partitioned image + are the same as for any other image type. + For information on image types, see the + "<link linkend='building-images'>Building Images</link>" + section. </para> </section> - <section id='wic-getting-help'> - <title>Getting Help</title> + <section id='create-wic-images-wic'> + <title>Using OpenEmbedded Image Creator Wic to Generate Partitioned Images</title> <para> - You can get general help for the <filename>wic</filename> - by entering the <filename>wic</filename> command by itself - or by entering the command with a help argument as follows: - <literallayout class='monospaced'> - $ wic -h - $ wic --help - </literallayout> + The <filename>wic</filename> command generates partitioned + images from existing OpenEmbedded build artifacts. + Image generation is driven by partitioning commands + contained in an Openembedded kickstart file + (<filename>.wks</filename>) specified either directly on + the command line or as one of a selection of canned + <filename>.wks</filename> files as shown with the + <filename>wic list images</filename> command in the + "<link linkend='using-a-provided-kickstart-file'>Using an Existing Kickstart File</link>" + section. + When you apply the command to a given set of build + artifacts, the result is an image or set of images that + can be directly written onto media and used on a particular + system. </para> <para> - Currently, <filename>wic</filename> supports two commands: - <filename>create</filename> and <filename>list</filename>. - You can get help for these commands as follows: - <literallayout class='monospaced'> - $ wic help <replaceable>command</replaceable> - </literallayout> + The <filename>wic</filename> command and the infrastructure + it is based on is by definition incomplete. + The purpose of the command is to allow the generation of + customized images, and as such, was designed to be + completely extensible through a plug-in interface. + See the + "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" + section for information on these plug-ins. </para> <para> - You can also get detailed help on a number of topics - from the help system. - The output of <filename>wic --help</filename> - displays a list of available help - topics under a "Help topics" heading. - You can have the help system display the help text for - a given topic by prefacing the topic with - <filename>wic help</filename>: - <literallayout class='monospaced'> - $ wic help <replaceable>help_topic</replaceable> - </literallayout> + This section provides some background information on Wic, + describes what you need to have in + place to run the tool, provides instruction on how to use + the <filename>wic</filename> utility, + and provides several examples. </para> - <para> - You can find out more about the images - <filename>wic</filename> creates using the existing - kickstart files with the following form of the command: - <literallayout class='monospaced'> - $ wic list <replaceable>image</replaceable> help - </literallayout> - where <filename><replaceable>image</replaceable></filename> is either - <filename>directdisk</filename> or - <filename>mkefidisk</filename>. - </para> - </section> + <section id='wic-background'> + <title>Background</title> - <section id='operational-modes'> - <title>Operational Modes</title> + <para> + This section provides some background on the + <filename>wic</filename> utility. + While none of this information is required to use + Wic, you might find it interesting. + <itemizedlist> + <listitem><para> + The name "Wic" is derived from OpenEmbedded + Image Creator (oeic). + The "oe" diphthong in "oeic" was promoted to the + letter "w", because "oeic" is both difficult to + remember and to pronounce. + </para></listitem> + <listitem><para> + Wic is loosely based on the + Meego Image Creator (<filename>mic</filename>) + framework. + The Wic implementation has been + heavily modified to make direct use of OpenEmbedded + build artifacts instead of package installation and + configuration, which are already incorporated within + the OpenEmbedded artifacts. + </para></listitem> + <listitem><para> + Wic is a completely independent + standalone utility that initially provides + easier-to-use and more flexible replacements for a + existing functionality in OE Core's + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink> + class and <filename>mkefidisk.sh</filename> script. + The difference between + Wic and those examples is + that with Wic the + functionality of those scripts is implemented + by a general-purpose partitioning language, which is + based on Redhat kickstart syntax.</para></listitem> + </itemizedlist> + </para> + </section> - <para> - You can use <filename>wic</filename> in two different - modes, depending on how much control you need for - specifying the Openembedded build artifacts that are - used for creating the image: Raw and Cooked: - <itemizedlist> - <listitem><para><emphasis>Raw Mode:</emphasis> - You explicitly specify build artifacts through - command-line arguments.</para></listitem> - <listitem><para><emphasis>Cooked Mode:</emphasis> - The current - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - setting and image name are used to automatically locate - and provide the build artifacts.</para></listitem> - </itemizedlist> - </para> + <section id='wic-requirements'> + <title>Requirements</title> - <para> - Regardless of the mode you use, you need to have the build - artifacts ready and available. - Additionally, the environment must be set up using the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> - script found in the - <link linkend='build-directory'>Build Directory</link>. - </para> + <para> + In order to use the <filename>wic</filename> utility + with the OpenEmbedded Build system, your system needs + to meet the following requirements: + <itemizedlist> + <listitem><para>The Linux distribution on your + development host must support the Yocto Project. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" + section in the Yocto Project Reference Manual for + the list of distributions that support the + Yocto Project. + </para></listitem> + <listitem><para> + The standard system utilities, such as + <filename>cp</filename>, must be installed on your + development host system. + </para></listitem> + <listitem><para> + You need to have the build artifacts already + available, which typically means that you must + have already created an image using the + Openembedded build system (e.g. + <filename>core-image-minimal</filename>). + While it might seem redundant to generate an image + in order to create an image using + Wic, the current version of + Wic requires the artifacts + in the form generated by the build system. + </para></listitem> + <listitem><para> + You must build several native tools, which are tools + built to run on the build system: + <literallayout class='monospaced'> + $ bitbake parted-native dosfstools-native mtools-native + </literallayout> + </para></listitem> + <listitem><para> + You must have sourced one of the build environment + setup scripts (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) + found in the + <link linkend='build-directory'>Build Directory</link>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='wic-getting-help'> + <title>Getting Help</title> + + <para> + You can get general help for the <filename>wic</filename> + command by entering the <filename>wic</filename> command + by itself or by entering the command with a help argument + as follows: + <literallayout class='monospaced'> + $ wic -h + $ wic --help + </literallayout> + </para> + + <para> + Currently, Wic supports two commands: + <filename>create</filename> and <filename>list</filename>. + You can get help for these commands as follows: + <literallayout class='monospaced'> + $ wic help <replaceable>command</replaceable> + with <replaceable>command</replaceable> being either + <filename>create</filename> or <filename>list</filename>. + </literallayout> + </para> - <section id='raw-mode'> - <title>Raw Mode</title> + <para> + You can also get detailed help on a number of topics + from the help system. + The output of <filename>wic --help</filename> + displays a list of available help + topics under a "Help topics" heading. + You can have the help system display the help text for + a given topic by prefacing the topic with + <filename>wic help</filename>: + <literallayout class='monospaced'> + $ wic help <replaceable>help_topic</replaceable> + </literallayout> + </para> <para> - The general form of the 'wic' command in raw mode is: + You can find out more about the images + Wic creates using the existing + kickstart files with the following form of the command: <literallayout class='monospaced'> + $ wic list <replaceable>image</replaceable> help + </literallayout> + with <filename><replaceable>image</replaceable></filename> + being either <filename>directdisk</filename> or + <filename>mkefidisk</filename>. + </para> + </section> + + <section id='operational-modes'> + <title>Operational Modes</title> + + <para> + You can use Wic in two different + modes, depending on how much control you need for + specifying the Openembedded build artifacts that are + used for creating the image: Raw and Cooked: + <itemizedlist> + <listitem><para> + <emphasis>Raw Mode:</emphasis> + You explicitly specify build artifacts through + command-line arguments. + </para></listitem> + <listitem><para> + <emphasis>Cooked Mode:</emphasis> + The current + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + setting and image name are used to automatically + locate and provide the build artifacts. + </para></listitem> + </itemizedlist> + </para> + + <para> + Regardless of the mode you use, you need to have the build + artifacts ready and available. + Additionally, the environment must be set up using the + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> + script found in the + <link linkend='build-directory'>Build Directory</link>. + </para> + + <section id='raw-mode'> + <title>Raw Mode</title> + + <para> + The general form of the + <filename>wic</filename> command in raw mode is: + <literallayout class='monospaced'> $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...] - Where: + Where: - <replaceable>image_name</replaceable>.wks - An OpenEmbedded kickstart file. You can provide - your own custom file or use a file from a set of - existing files as described by further options. + <replaceable>image_name</replaceable>.wks + An OpenEmbedded kickstart file. You can provide + your own custom file or use a file from a set of + existing files as described by further options. - -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable> - The name of a directory in which to create image. + -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable> + The name of a directory in which to create image. - -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable> - The name of a file containing the values for image - properties as a JSON file. + -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable> + The name of a file containing the values for image + properties as a JSON file. - -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable> - The name of the image from which to use the artifacts - (e.g. <filename>core-image-sato</filename>). + -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable> + The name of the image from which to use the artifacts + (e.g. <filename>core-image-sato</filename>). - -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> - The path to the <filename>/rootfs</filename> directory to use as the - <filename>.wks</filename> rootfs source. + -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> + The path to the <filename>/rootfs</filename> directory to use as the + <filename>.wks</filename> rootfs source. - -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> - The path to the directory containing the boot artifacts - (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg - source. + -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> + The path to the directory containing the boot artifacts + (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg + source. - -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable> - The path to the directory containing the kernel to use - in the <filename>.wks</filename> boot image. + -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable> + The path to the directory containing the kernel to use + in the <filename>.wks</filename> boot image. - -n <replaceable>NATIVE_SYSROOT</replaceable>, --native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> - The path to the native sysroot containing the tools to use - to build the image. + -n <replaceable>NATIVE_SYSROOT</replaceable>, --native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> + The path to the native sysroot containing the tools to use + to build the image. - -s, --skip-build-check - Skips the build check. + -s, --skip-build-check + Skips the build check. - -D, --debug - Output debug information. - </literallayout> - <note> - You do not need root privileges to run - <filename>wic</filename>. - In fact, you should not run as root when using the - utility. - </note> - </para> - </section> + -D, --debug + Output debug information. + </literallayout> + <note> + You do not need root privileges to run + Wic. + In fact, you should not run as root when using the + utility. + </note> + </para> + </section> - <section id='cooked-mode'> - <title>Cooked Mode</title> + <section id='cooked-mode'> + <title>Cooked Mode</title> - <para> - The general form of the <filename>wic</filename> command - using Cooked Mode is: - <literallayout class='monospaced'> + <para> + The general form of the <filename>wic</filename> command + using Cooked Mode is: + <literallayout class='monospaced'> $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable> - Where: + Where: - <replaceable>kickstart_file</replaceable> - An OpenEmbedded kickstart file. You can provide your own - custom file or supplied file. + <replaceable>kickstart_file</replaceable> + An OpenEmbedded kickstart file. You can provide your own + custom file or a supplied file. - <replaceable>image_name</replaceable> - Specifies the image built using the OpenEmbedded build - system. - </literallayout> - This form is the simplest and most user-friendly, as it - does not require specifying all individual parameters. - All you need to provide is your own - <filename>.wks</filename> file or one provided with the - release. - </para> + <replaceable>image_name</replaceable> + Specifies the image built using the OpenEmbedded build + system. + </literallayout> + This form is the simplest and most user-friendly, as it + does not require specifying all individual parameters. + All you need to provide is your own + <filename>.wks</filename> file or one provided with the + release. + </para> + </section> </section> - </section> - <section id='using-a-provided-kickstart_file'> - <title>Using an Existing Kickstart File</title> + <section id='using-a-provided-kickstart-file'> + <title>Using an Existing Kickstart File</title> - <para> - If you do not want to create your own - <filename>.wks</filename> file, you can use an existing - file provided by the <filename>wic</filename> installation. - Use the following command to list the available files: - <literallayout class='monospaced'> + <para> + If you do not want to create your own + <filename>.wks</filename> file, you can use an existing + file provided by the Wic installation. + Use the following command to list the available files: + <literallayout class='monospaced'> $ wic list images directdisk Create a 'pcbios' direct disk image mkefidisk Create an EFI disk image - </literallayout> - When you use an existing file, you do not have to use the - <filename>.wks</filename> extension. - Here is an example in Raw Mode that uses the - <filename>directdisk</filename> file: - <literallayout class='monospaced'> + </literallayout> + When you use an existing file, you do not have to use the + <filename>.wks</filename> extension. + Here is an example in Raw Mode that uses the + <filename>directdisk</filename> file: + <literallayout class='monospaced'> $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \ -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable> - </literallayout> - </para> + </literallayout> + </para> - <para> - Here are the actual partition language commands - used in the <filename>mkefidisk.wks</filename> file to generate - an image: - <literallayout class='monospaced'> + <para> + Here are the actual partition language commands + used in the <filename>mkefidisk.wks</filename> file to + generate an image: + <literallayout class='monospaced'> # short-description: Create an EFI disk image # long-description: Creates a partitioned EFI disk image that the user # can directly dd to boot media. @@ -4698,30 +4755,30 @@ part swap --ondisk sda --size 44 --label swap1 --fstype=swap bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0" - </literallayout> - </para> - </section> + </literallayout> + </para> + </section> - <section id='wic-usage-examples'> - <title>Examples</title> + <section id='wic-usage-examples'> + <title>Examples</title> - <para> - This section provides several examples that show how to use - the <filename>wic</filename> utility. - All the examples assume the list of requirements in the - "<link linkend='wic-requirements'>Requirements</link>" section - have been met. - The examples assume the previously generated image is - <filename>core-image-minimal</filename>. - </para> + <para> + This section provides several examples that show how to use + the <filename>wic</filename> utility. + All the examples assume the list of requirements in the + "<link linkend='wic-requirements'>Requirements</link>" + section have been met. + The examples assume the previously generated image is + <filename>core-image-minimal</filename>. + </para> - <section id='generate-an-image-using-a-provided-kickstart-file'> - <title>Generate an Image using an Existing Kickstart File</title> + <section id='generate-an-image-using-a-provided-kickstart-file'> + <title>Generate an Image using an Existing Kickstart File</title> - <para> - This example runs in Cooked Mode and uses the - <filename>mkefidisk</filename> kickstart file: - <literallayout class='monospaced'> + <para> + This example runs in Cooked Mode and uses the + <filename>mkefidisk</filename> kickstart file: + <literallayout class='monospaced'> $ wic create mkefidisk -e core-image-minimal Checking basic build environment... Done. @@ -4737,114 +4794,115 @@ KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux - The image(s) were created using OE kickstart file: /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks - </literallayout> - This example shows the easiest way to create an image - by running in Cooked Mode and using the - <filename>-e</filename> option with an existing kickstart - file. - All that is necessary is to specify the image used to - generate the artifacts. - Your <filename>local.conf</filename> needs to have the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable set to the machine you are using, which is - "minnow" in this example. - </para> + </literallayout> + The previous example shows the easiest way to create + an image by running in Cooked Mode and using the + <filename>-e</filename> option with an existing + kickstart file. + All that is necessary is to specify the image used to + generate the artifacts. + Your <filename>local.conf</filename> needs to have the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable set to the machine you are using, which is + "minnow" in this example. + </para> - <para> - The output specifies the exact image created as well as - where it was created. - The output also names the artifacts used and the exact - <filename>.wks</filename> script that was used to generate - the image. - <note> - You should always verify the details provided in the - output to make sure that the image was indeed created - exactly as expected. - </note> - </para> + <para> + The output specifies the exact image created as well as + where it was created. + The output also names the artifacts used and the exact + <filename>.wks</filename> script that was used to + generate the image. + <note> + You should always verify the details provided in the + output to make sure that the image was indeed + created exactly as expected. + </note> + </para> - <para> - Continuing with the example, you can now directly - <filename>dd</filename> the image to a USB stick, or - whatever media for which you built your image, - and boot the resulting media: - <literallayout class='monospaced'> + <para> + Continuing with the example, you can now directly + <filename>dd</filename> the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: + <literallayout class='monospaced'> $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb [sudo] password for trz: 182274+0 records in 182274+0 records out 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s - [trz@empanada ~]$ sudo eject /dev/sdb - </literallayout> - </para> - </section> + [trz at empanada ~]$ sudo eject /dev/sdb + </literallayout> + </para> + </section> - <section id='using-a-modified-kickstart-file'> - <title>Using a Modified Kickstart File</title> + <section id='using-a-modified-kickstart-file'> + <title>Using a Modified Kickstart File</title> - <para> - Because <filename>wic</filename> image creation is driven - by the kickstart file, it is easy to affect image creation - by changing the parameters in the file. - This next example demonstrates that through modification - of the <filename>directdisk</filename> kickstart file. - </para> + <para> + Because Wic-partitioned image creation is + driven by the kickstart file, it is easy to affect + image creation by changing the parameters in the file. + This next example demonstrates that through modification + of the <filename>directdisk</filename> kickstart file. + </para> - <para> - As mentioned earlier, you can use the command - <filename>wic list images</filename> to show the list - of existing kickstart files. - The directory in which these files reside is - <filename>scripts/lib/image/canned-wks/</filename> - located in the - <link linkend='source-directory'>Source Directory</link>. - Because the available files reside in this directory, you - can create and add your own custom files to the directory. - Subsequent use of the <filename>wic list images</filename> - command would then include your kickstart files. - </para> + <para> + As mentioned earlier, you can use the command + <filename>wic list images</filename> to show the list + of existing kickstart files. + The directory in which these files reside is + <filename>scripts/lib/image/canned-wks/</filename> + located in the + <link linkend='source-directory'>Source Directory</link>. + Because the available files reside in this directory, + you can create and add your own custom files to the + directory. + Subsequent use of the + <filename>wic list images</filename> command would then + include your kickstart files. + </para> - <para> - In this example, the existing - <filename>directdisk</filename> file already does most - of what is needed. - However, for the hardware in this example, the image will - need to boot from <filename>sdb</filename> instead of - <filename>sda</filename>, which is what the - <filename>directdisk</filename> kickstart file uses. - </para> + <para> + In this example, the existing + <filename>directdisk</filename> file already does most + of what is needed. + However, for the hardware in this example, the image + will need to boot from <filename>sdb</filename> instead + of <filename>sda</filename>, which is what the + <filename>directdisk</filename> kickstart file uses. + </para> - <para> - The example begins by making a copy of the - <filename>directdisk.wks</filename> file in the - <filename>scripts/lib/image/canned-wks</filename> - directory and then changing the lines that specify the - target disk from which to boot. - <literallayout class='monospaced'> + <para> + The example begins by making a copy of the + <filename>directdisk.wks</filename> file in the + <filename>scripts/lib/image/canned-wks</filename> + directory and then by changing the lines that specify + the target disk from which to boot. + <literallayout class='monospaced'> $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \ /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks - </literallayout> - Next, the example modifies the - <filename>directdisksdb.wks</filename> file and changes all - instances of "<filename>--ondisk sda</filename>" - to "<filename>--ondisk sdb</filename>". - The example changes the following two lines and leaves the - remaining lines untouched: - <literallayout class='monospaced'> + </literallayout> + Next, the example modifies the + <filename>directdisksdb.wks</filename> file and changes + all instances of "<filename>--ondisk sda</filename>" + to "<filename>--ondisk sdb</filename>". + The example changes the following two lines and leaves + the remaining lines untouched: + <literallayout class='monospaced'> part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 - </literallayout> - Once the lines are changed, the example generates the - <filename>directdisksdb</filename> image. - The command points the process at the - <filename>core-image-minimal</filename> artifacts for the - Next Unit of Computing (nuc) - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - the <filename>local.conf</filename>. - <literallayout class='monospaced'> + </literallayout> + Once the lines are changed, the example generates the + <filename>directdisksdb</filename> image. + The command points the process at the + <filename>core-image-minimal</filename> artifacts for + the Next Unit of Computing (nuc) + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + the <filename>local.conf</filename>. + <literallayout class='monospaced'> $ wic create directdisksdb -e core-image-minimal Checking basic build environment... Done. @@ -4855,39 +4913,39 @@ /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct The following build artifacts were used to create the image(s): + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux - The image(s) were created using OE kickstart file: /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks - </literallayout> - Continuing with the example, you can now directly - <filename>dd</filename> the image to a USB stick, or - whatever media for which you built your image, - and boot the resulting media: - <literallayout class='monospaced'> + </literallayout> + Continuing with the example, you can now directly + <filename>dd</filename> the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: + <literallayout class='monospaced'> $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb 86018+0 records in 86018+0 records out 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s - [trz@empanada tmp]$ sudo eject /dev/sdb - </literallayout> - </para> - </section> + [trz at empanada tmp]$ sudo eject /dev/sdb + </literallayout> + </para> + </section> - <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'> - <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title> + <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'> + <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title> - <para> - This example creates an image based on - <filename>core-image-minimal</filename> and a - <filename>crownbay-noemgd</filename> - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - that works right out of the box. - <literallayout class='monospaced'> + <para> + This example creates an image based on + <filename>core-image-minimal</filename> and a + <filename>crownbay-noemgd</filename> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + that works right out of the box. + <literallayout class='monospaced'> $ wic create directdisk -e core-image-minimal Checking basic build environment... @@ -4907,21 +4965,21 @@ The image(s) were created using OE kickstart file: /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks - </literallayout> - </para> - </section> + </literallayout> + </para> + </section> - <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'> - <title>Using a Modified Kickstart File and Running in Raw Mode</title> + <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'> + <title>Using a Modified Kickstart File and Running in Raw Mode</title> - <para> - This next example manually specifies each build artifact - (runs in Raw Mode) and uses a modified kickstart file. - The example also uses the <filename>-o</filename> option - to cause <filename>wic</filename> to create the output - somewhere other than the default - <filename>/var/tmp/wic</filename> directory: - <literallayout class='monospaced'> + <para> + This next example manually specifies each build artifact + (runs in Raw Mode) and uses a modified kickstart file. + The example also uses the <filename>-o</filename> option + to cause Wic to create the output + somewhere other than the default + <filename>/var/tmp/wic</filename> directory: + <literallayout class='monospaced'> $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \ /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ @@ -4942,437 +5000,477 @@ The image(s) were created using OE kickstart file: /home/trz/test.wks - </literallayout> - For this example, - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - did not have to be specified in the - <filename>local.conf</filename> file since the artifact is - manually specified. - </para> + </literallayout> + For this example, + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + did not have to be specified in the + <filename>local.conf</filename> file since the + artifact is manually specified. + </para> + </section> </section> - </section> - <section id='openembedded-kickstart-plugins'> - <title>Plug-ins</title> + <section id='openembedded-kickstart-plugins'> + <title>Plug-ins</title> - <para> - Plug-ins allow <filename>wic</filename> functionality to - be extended and specialized by users. - This section documents the plugin interface, which is - currently restricted to source plug ins. - </para> + <para> + Plug-ins allow Wic functionality to + be extended and specialized by users. + This section documents the plug-in interface, which is + currently restricted to source plug-ins. + </para> - <para> - Source plug ins provide a mechanism to customize - various aspects of the image generation process in - <filename>wic</filename>, mainly the contents of - partitions. - The plug ins provide a mechanism for mapping values - specified in <filename>.wks</filename> files using the - <filename>--source</filename> keyword to a - particular plugin implementation that populates a - corresponding partition. - </para> + <para> + Source plug-ins provide a mechanism to customize + various aspects of the image generation process in + Wic, mainly the contents of + partitions. + The plug-ins provide a mechanism for mapping values + specified in <filename>.wks</filename> files using the + <filename>--source</filename> keyword to a + particular plug-in implementation that populates a + corresponding partition. + </para> - <para> - A source plugin is created as a subclass of - <filename>SourcePlugin</filename>. - The plugin file containing it is added to - <filename>scripts/lib/wic/plugins/source/</filename> to - make the plugin implementation available to the - <filename>wic</filename> implementation. - For more information, see - <filename>scripts/lib/wic/pluginbase.py</filename>. - </para> + <para> + A source plug-in is created as a subclass of + <filename>SourcePlugin</filename>. + The plug-in file containing it is added to + <filename>scripts/lib/wic/plugins/source/</filename> to + make the plug-in implementation available to the + Wic implementation. + For more information, see + <filename>scripts/lib/wic/pluginbase.py</filename>. + </para> - <para> - Source plugins can also be implemented and added by - external layers. - As such, any plugins found in a - <filename>scripts/lib/wic/plugins/source/</filename> - directory in an external layer are also made - available. - </para> + <para> + Source plug-ins can also be implemented and added by + external layers. + As such, any plug-ins found in a + <filename>scripts/lib/wic/plugins/source/</filename> + directory in an external layer are also made + available. + </para> - <para> - When the <filename>wic</filename> implementation needs - to invoke a partition-specific implementation, it looks - for the plugin that has the same name as the - <filename>--source</filename> parameter given to - that partition. - For example, if the partition is set up as follows: - <literallayout class='monospaced'> + <para> + When the Wic implementation needs + to invoke a partition-specific implementation, it looks + for the plug-in that has the same name as the + <filename>--source</filename> parameter given to + that partition. + For example, if the partition is set up as follows: + <literallayout class='monospaced'> part /boot --source bootimg-pcbios ... - </literallayout> - The methods defined as class members of the plugin - having the matching <filename>bootimg-pcbios.name</filename> - class member are used. - </para> + </literallayout> + The methods defined as class members of the plug-in + having the matching <filename>bootimg-pcbios.name</filename> + class member are used. + </para> - <para> - To be more concrete, here is the plugin definition that - matches a - <filename>--source bootimg-pcbios</filename> usage, - along with an example - method called by the <filename>wic</filename> implementation - when it needs to invoke an implementation-specific - partition-preparation function: - <literallayout class='monospaced'> + <para> + To be more concrete, here is the plug-in definition that + matches a + <filename>--source bootimg-pcbios</filename> usage, + along with an example + method called by the Wic implementation + when it needs to invoke an implementation-specific + partition-preparation function: + <literallayout class='monospaced'> class BootimgPcbiosPlugin(SourcePlugin): name = 'bootimg-pcbios' @classmethod def do_prepare_partition(self, part, ...) - </literallayout> - If the subclass itself does not implement a function, a - default version in a superclass is located and - used, which is why all plugins must be derived from - <filename>SourcePlugin</filename>. - </para> - - <para> - The <filename>SourcePlugin</filename> class defines the - following methods, which is the current set of methods - that can be implemented or overridden by - <filename>--source</filename> plugins. - Any methods not implemented by a - <filename>SourcePlugin</filename> subclass inherit the - implementations present in the - <filename>SourcePlugin</filename> class. - For more information, see the - <filename>SourcePlugin</filename> source for details: - </para> - - <para> - <itemizedlist> - <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis> - Called to do the actual content population for a - partition. - In other words, the method prepares the final - partition image that is incorporated into the - disk image. - </para></listitem> - <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis> - Called before - <filename>do_prepare_partition()</filename>. - This method is typically used to create custom - configuration files for a partition (e.g. syslinux or - grub configuration files). - </para></listitem> - <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis> - Called after all partitions have been prepared and - assembled into a disk image. - This method provides a hook to allow finalization of a - disk image, (e.g. writing an MBR). - </para></listitem> - <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis> - Special content-staging hook called before - <filename>do_prepare_partition()</filename>. - This method is normally empty.</para> - <para>Typically, a partition just uses the passed-in - parameters (e.g. the unmodified value of - <filename>bootimg_dir</filename>). - However, in some cases things might need to be - more tailored. - As an example, certain files might additionally - need to be taken from - <filename>bootimg_dir + /boot</filename>. - This hook allows those files to be staged in a - customized fashion. - <note> - <filename>get_bitbake_var()</filename> - allows you to access non-standard variables - that you might want to use for this. - </note> - </para></listitem> - </itemizedlist> - </para> - - <para> - This scheme is extensible. - Adding more hooks is a simple matter of adding more - plugin methods to <filename>SourcePlugin</filename> and - derived classes. - The code that then needs to call the plugin methods uses - <filename>plugin.get_source_plugin_methods()</filename> - to find the method or methods needed by the call. - Retrieval of those methods is accomplished - by filling up a dict with keys - containing the method names of interest. - On success, these will be filled in with the actual - methods. - Please see the <filename>wic</filename> - implementation for examples and details. - </para> - </section> - - <section id='openembedded-kickstart-wks-reference'> - <title>OpenEmbedded Kickstart (.wks) Reference</title> - - <para> - The current <filename>wic</filename> implementation supports - only the basic kickstart partitioning commands: - <filename>partition</filename> (or <filename>part</filename> - for short) and <filename>bootloader</filename>. - <note> - Future updates will implement more commands and options. - If you use anything that is not specifically - supported, results can be unpredictable. - </note> - </para> - - <para> - The following is a list of the commands, their syntax, - and meanings. - The commands are based on the Fedora - kickstart versions but with modifications to - reflect <filename>wic</filename> capabilities. - You can see the original documentation for those commands - at the following links: - <itemizedlist> - <listitem><para> - <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink> - </para></listitem> - <listitem><para> - <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink> - </para></listitem> - </itemizedlist> - </para> - - <section id='command-part-or-partition'> - <title>Command: part or partition</title> - - <para> - Either of these commands create a partition on the system - and uses the following syntax: - <literallayout class='monospaced'> - part [<replaceable>mntpoint</replaceable>] - partition [<replaceable>mntpoint</replaceable>] </literallayout> - If you do not provide - <replaceable>mntpoint</replaceable>, wic creates a partition - but does not mount it. - </para> - - <para> - The <filename><replaceable>mntpoint</replaceable></filename> - is where the - partition will be mounted and must be of one of the - following forms: - <itemizedlist> - <listitem><para><filename>/<replaceable>path</replaceable></filename>: - For example, <filename>/</filename>, - <filename>/usr</filename>, or - <filename>/home</filename></para></listitem> - <listitem><para><filename>swap</filename>: - The created partition is used as swap space. - </para></listitem> - </itemizedlist> + If the subclass itself does not implement a function, a + default version in a superclass is located and + used, which is why all plug-ins must be derived from + <filename>SourcePlugin</filename>. </para> <para> - Specifying a <replaceable>mntpoint</replaceable> causes - the partition to automatically be mounted. - Wic achieves this by adding entries to the filesystem - table (fstab) during image generation. - In order for wic to generate a valid fstab, you must - also provide one of the <filename>--ondrive</filename>, - <filename>--ondisk</filename>, or - <filename>--use-uuid</filename> partition options as part - of the command. - Here is an example using "/" as the mountpoint. - The command uses "--ondisk" to force the partition onto - the <filename>sdb</filename> disk: - <literallayout class='monospaced'> - part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 - </literallayout> + The <filename>SourcePlugin</filename> class defines the + following methods, which is the current set of methods + that can be implemented or overridden by + <filename>--source</filename> plug-ins. + Any methods not implemented by a + <filename>SourcePlugin</filename> subclass inherit the + implementations present in the + <filename>SourcePlugin</filename> class. + For more information, see the + <filename>SourcePlugin</filename> source for details: </para> <para> - Here is a list that describes other supported options you - can use with the <filename>part</filename> and - <filename>partition</filename> commands: <itemizedlist> - <listitem><para><emphasis><filename>--size</filename>:</emphasis> - The minimum partition size in MBytes. - Specify an integer value such as 500. - Do not append the number with "MB". - You do not need this option if you use - <filename>--source</filename>.</para></listitem> - <listitem><para><emphasis><filename>--source</filename>:</emphasis> - This option is a - <filename>wic</filename>-specific option that - names the source of the data that populates - the partition. - The most common value for this option is - "rootfs", but you can use any value that maps to - a valid source plugin. - For information on the source plugins, see the - "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" - section.</para> - <para>If you use - <filename>--source rootfs</filename>, - <filename>wic</filename> creates a partition as - large as needed and to fill it with the contents of - the root filesystem pointed to by the - <filename>-r</filename> command-line option - or the equivalent rootfs derived from the - <filename>-e</filename> command-line - option. - The filesystem type used to create the - partition is driven by the value of the - <filename>--fstype</filename> option - specified for the partition. - See the entry on - <filename>--fstype</filename> that - follows for more information. - </para> - <para>If you use - <filename>--source <replaceable>plugin-name</replaceable></filename>, - <filename>wic</filename> creates a partition as - large as needed and fills it with the contents of - the partition that is generated by the - specified plugin name using the data pointed - to by the <filename>-r</filename> command-line - option or the equivalent rootfs derived from the - <filename>-e</filename> command-line - option. - Exactly what those contents and filesystem type end - up being are dependent on the given plugin - implementation. - </para> - <para>If you do not use the - <filename>--source</filename> option, the - <filename>wic</filename> command creates an empty + <listitem><para> + <emphasis><filename>do_prepare_partition()</filename>:</emphasis> + Called to do the actual content population for a partition. - Consequently, you must use the - <filename>--size</filename> option to specify the - size of the empty partition. + In other words, the method prepares the final + partition image that is incorporated into the + disk image. </para></listitem> - <listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> - Forces the partition to be created on a particular - disk.</para></listitem> - <listitem><para><emphasis><filename>--fstype</filename>:</emphasis> - Sets the file system type for the partition. - Valid values are: - <itemizedlist> - <listitem><para><filename>ext4</filename> - </para></listitem> - <listitem><para><filename>ext3</filename> - </para></listitem> - <listitem><para><filename>ext2</filename> - </para></listitem> - <listitem><para><filename>btrfs</filename> - </para></listitem> - <listitem><para><filename>squashfs</filename> - </para></listitem> - <listitem><para><filename>swap</filename> - </para></listitem> - </itemizedlist></para></listitem> - <listitem><para><emphasis><filename>--fsoptions</filename>:</emphasis> - Specifies a free-form string of options to be - used when mounting the filesystem. - This string will be copied into the - <filename>/etc/fstab</filename> file of the - installed system and should be enclosed in - quotes. - If not specified, the default string - is "defaults". - </para></listitem> - <listitem><para><emphasis><filename>--label label</filename>:</emphasis> - Specifies the label to give to the filesystem to - be made on the partition. - If the given label is already in use by another - filesystem, a new label is created for the - partition.</para></listitem> - <listitem><para><emphasis><filename>--active</filename>:</emphasis> - Marks the partition as active.</para></listitem> - <listitem><para><emphasis><filename>--align (in KBytes)</filename>:</emphasis> - This option is a <filename>wic</filename>-specific - option that says to start a partition on an - x KBytes boundary.</para></listitem> - <listitem><para><emphasis><filename>--no-table</filename>:</emphasis> - This option is a <filename>wic</filename>-specific - option. - Using the option reserves space for the partition - and causes it to become populated. - However, the partition is not added to the - partition table. - </para></listitem> - <listitem><para><emphasis><filename>--extra-space</filename>:</emphasis> - This option is a <filename>wic</filename>-specific - option that adds extra space after the space - filled by the content of the partition. - The final size can go beyond the size specified - by the <filename>--size</filename> option. - The default value is 10 Mbytes. - </para></listitem> - <listitem><para><emphasis><filename>--overhead-factor</filename>:</emphasis> - This option is a <filename>wic</filename>-specific - option that multiplies the size of the partition by - the option's value. - You must supply a value greater than or equal to - "1". - The default value is "1.3". - </para></listitem> - <listitem><para><emphasis><filename>--part-type</filename>:</emphasis> - This option is a <filename>wic</filename>-specific - option that specifies the partition type globally - unique identifier (GUID) for GPT partitions. - You can find the list of partition type GUIDs - at - <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>. + <listitem><para> + <emphasis><filename>do_configure_partition()</filename>:</emphasis> + Called before + <filename>do_prepare_partition()</filename>. + This method is typically used to create custom + configuration files for a partition (e.g. syslinux + or grub configuration files). </para></listitem> - <listitem><para><emphasis><filename>--use-uuid</filename>:</emphasis> - This option is a <filename>wic</filename>-specific - option that causes <filename>wic</filename> to - generate a random GUID for the partition. - The generated identifier is used in the bootloader - configuration to specify the root partition. + <listitem><para> + <emphasis><filename>do_install_disk()</filename>:</emphasis> + Called after all partitions have been prepared and + assembled into a disk image. + This method provides a hook to allow finalization + of a disk image, (e.g. writing an MBR). </para></listitem> - <listitem><para><emphasis><filename>--uuid</filename>:</emphasis> - This option is a <filename>wic</filename>-specific - option that specifies the partition UUID. + <listitem><para> + <emphasis><filename>do_stage_partition()</filename>:</emphasis> + Special content-staging hook called before + <filename>do_prepare_partition()</filename>. + This method is normally empty.</para> + <para>Typically, a partition just uses the passed-in + parameters (e.g. the unmodified value of + <filename>bootimg_dir</filename>). + However, in some cases things might need to be + more tailored. + As an example, certain files might additionally + need to be taken from + <filename>bootimg_dir + /boot</filename>. + This hook allows those files to be staged in a + customized fashion. + <note> + <filename>get_bitbake_var()</filename> + allows you to access non-standard variables + that you might want to use for this. + </note> </para></listitem> </itemizedlist> </para> + + <para> + This scheme is extensible. + Adding more hooks is a simple matter of adding more + plug-in methods to <filename>SourcePlugin</filename> and + derived classes. + The code that then needs to call the plug-in methods uses + <filename>plugin.get_source_plugin_methods()</filename> + to find the method or methods needed by the call. + Retrieval of those methods is accomplished + by filling up a dict with keys + containing the method names of interest. + On success, these will be filled in with the actual + methods. + Please see the Wic + implementation for examples and details. + </para> </section> - <section id='command-bootloader'> - <title>Command: bootloader</title> + <section id='openembedded-kickstart-wks-reference'> + <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title> <para> - This command specifies how the boot loader should be - configured and supports the following options: + The current Wic implementation supports + only the basic kickstart partitioning commands: + <filename>partition</filename> (or <filename>part</filename> + for short) and <filename>bootloader</filename>. <note> - Bootloader functionality and boot partitions are - implemented by the various - <filename>--source</filename> - plugins that implement bootloader functionality. - The bootloader command essentially provides a means of - modifying bootloader configuration. + Future updates will implement more commands and options. + If you use anything that is not specifically + supported, results can be unpredictable. </note> + </para> + + <para> + The following is a list of the commands, their syntax, + and meanings. + The commands are based on the Fedora + kickstart versions but with modifications to + reflect Wic capabilities. + You can see the original documentation for those commands + at the following links: <itemizedlist> - <listitem><para><emphasis><filename>--timeout</filename>:</emphasis> - Specifies the number of seconds before the - bootloader times out and boots the default option. - </para></listitem> - <listitem><para><emphasis><filename>--append</filename>:</emphasis> - Specifies kernel parameters. - These parameters will be added to the syslinux - <filename>APPEND</filename> or - <filename>grub</filename> kernel command line. + <listitem><para> + <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink> </para></listitem> - <listitem><para><emphasis><filename>--configfile</filename>:</emphasis> - Specifies a user-defined configuration file for - the bootloader. - You can provide a full pathname for the file or - a file that exists in the - <filename>canned-wks</filename> folder. - This option overrides all other bootloader options. + <listitem><para> + <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink> </para></listitem> </itemizedlist> </para> + + <section id='command-part-or-partition'> + <title>Command: part or partition</title> + + <para> + Either of these commands create a partition on the system + and use the following syntax: + <literallayout class='monospaced'> + part [<replaceable>mntpoint</replaceable>] + partition [<replaceable>mntpoint</replaceable>] + </literallayout> + If you do not provide + <replaceable>mntpoint</replaceable>, Wic creates a + partition but does not mount it. + </para> + + <para> + The + <filename><replaceable>mntpoint</replaceable></filename> + is where the partition will be mounted and must be of + one of the following forms: + <itemizedlist> + <listitem><para> + <filename>/<replaceable>path</replaceable></filename>: + For example, <filename>/</filename>, + <filename>/usr</filename>, or + <filename>/home</filename> + </para></listitem> + <listitem><para> + <filename>swap</filename>: + The created partition is used as swap space. + </para></listitem> + </itemizedlist> + </para> + + <para> + Specifying a <replaceable>mntpoint</replaceable> causes + the partition to automatically be mounted. + Wic achieves this by adding entries to the filesystem + table (fstab) during image generation. + In order for wic to generate a valid fstab, you must + also provide one of the <filename>--ondrive</filename>, + <filename>--ondisk</filename>, or + <filename>--use-uuid</filename> partition options as + part of the command. + Here is an example using "/" as the mountpoint. + The command uses "--ondisk" to force the partition onto + the <filename>sdb</filename> disk: + <literallayout class='monospaced'> + part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 + </literallayout> + </para> + + <para> + Here is a list that describes other supported options + you can use with the <filename>part</filename> and + <filename>partition</filename> commands: + <itemizedlist> + <listitem><para> + <emphasis><filename>--size</filename>:</emphasis> + The minimum partition size in MBytes. + Specify an integer value such as 500. + Do not append the number with "MB". + You do not need this option if you use + <filename>--source</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>--source</filename>:</emphasis> + This option is a + Wic-specific option that + names the source of the data that populates + the partition. + The most common value for this option is + "rootfs", but you can use any value that maps to + a valid source plug-in. + For information on the source plug-ins, see the + "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" + section.</para> + <para>If you use + <filename>--source rootfs</filename>, + Wic creates a partition as + large as needed and to fill it with the contents + of the root filesystem pointed to by the + <filename>-r</filename> command-line option + or the equivalent rootfs derived from the + <filename>-e</filename> command-line + option. + The filesystem type used to create the + partition is driven by the value of the + <filename>--fstype</filename> option + specified for the partition. + See the entry on + <filename>--fstype</filename> that + follows for more information. + </para> + <para>If you use + <filename>--source <replaceable>plugin-name</replaceable></filename>, + Wic creates a partition as + large as needed and fills it with the contents + of the partition that is generated by the + specified plug-in name using the data pointed + to by the <filename>-r</filename> command-line + option or the equivalent rootfs derived from the + <filename>-e</filename> command-line + option. + Exactly what those contents and filesystem type + end up being are dependent on the given plug-in + implementation. + </para> + <para>If you do not use the + <filename>--source</filename> option, the + <filename>wic</filename> command creates an + empty partition. + Consequently, you must use the + <filename>--size</filename> option to specify + the size of the empty partition. + </para></listitem> + <listitem><para> + <emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> + Forces the partition to be created on a + particular disk. + </para></listitem> + <listitem><para> + <emphasis><filename>--fstype</filename>:</emphasis> + Sets the file system type for the partition. + Valid values are: + <itemizedlist> + <listitem><para><filename>ext4</filename> + </para></listitem> + <listitem><para><filename>ext3</filename> + </para></listitem> + <listitem><para><filename>ext2</filename> + </para></listitem> + <listitem><para><filename>btrfs</filename> + </para></listitem> + <listitem><para><filename>squashfs</filename> + </para></listitem> + <listitem><para><filename>swap</filename> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis><filename>--fsoptions</filename>:</emphasis> + Specifies a free-form string of options to be + used when mounting the filesystem. + This string will be copied into the + <filename>/etc/fstab</filename> file of the + installed system and should be enclosed in + quotes. + If not specified, the default string + is "defaults". + </para></listitem> + <listitem><para> + <emphasis><filename>--label label</filename>:</emphasis> + Specifies the label to give to the filesystem to + be made on the partition. + If the given label is already in use by another + filesystem, a new label is created for the + partition. + </para></listitem> + <listitem><para> + <emphasis><filename>--active</filename>:</emphasis> + Marks the partition as active. + </para></listitem> + <listitem><para> + <emphasis><filename>--align (in KBytes)</filename>:</emphasis> + This option is a + Wic-specific option that + says to start a partition on an + <replaceable>x</replaceable> KBytes + boundary.</para></listitem> + <listitem><para> + <emphasis><filename>--no-table</filename>:</emphasis> + This option is a + Wic-specific option. + Using the option reserves space for the + partition and causes it to become populated. + However, the partition is not added to the + partition table. + </para></listitem> + <listitem><para> + <emphasis><filename>--extra-space</filename>:</emphasis> + This option is a + Wic-specific option that + adds extra space after the space filled by the + content of the partition. + The final size can go beyond the size specified + by the <filename>--size</filename> option. + The default value is 10 Mbytes. + </para></listitem> + <listitem><para> + <emphasis><filename>--overhead-factor</filename>:</emphasis> + This option is a + Wic-specific option that + multiplies the size of the partition by the + option's value. + You must supply a value greater than or equal to + "1". + The default value is "1.3". + </para></listitem> + <listitem><para> + <emphasis><filename>--part-type</filename>:</emphasis> + This option is a + Wic-specific option that + specifies the partition type globally + unique identifier (GUID) for GPT partitions. + You can find the list of partition type GUIDs + at + <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>. + </para></listitem> + <listitem><para> + <emphasis><filename>--use-uuid</filename>:</emphasis> + This option is a + Wic-specific option that + causes Wic to generate a + random GUID for the partition. + The generated identifier is used in the + bootloader configuration to specify the root + partition. + </para></listitem> + <listitem><para> + <emphasis><filename>--uuid</filename>:</emphasis> + This option is a + Wic-specific + option that specifies the partition UUID. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='command-bootloader'> + <title>Command: bootloader</title> + + <para> + This command specifies how the bootloader should be + configured and supports the following options: + <note> + Bootloader functionality and boot partitions are + implemented by the various + <filename>--source</filename> + plug-ins that implement bootloader functionality. + The bootloader command essentially provides a + means of modifying bootloader configuration. + </note> + <itemizedlist> + <listitem><para> + <emphasis><filename>--timeout</filename>:</emphasis> + Specifies the number of seconds before the + bootloader times out and boots the default + option. + </para></listitem> + <listitem><para> + <emphasis><filename>--append</filename>:</emphasis> + Specifies kernel parameters. + These parameters will be added to the syslinux + <filename>APPEND</filename> or + <filename>grub</filename> kernel command line. + </para></listitem> + <listitem><para> + <emphasis><filename>--configfile</filename>:</emphasis> + Specifies a user-defined configuration file for + the bootloader. + You can provide a full pathname for the file or + a file that exists in the + <filename>canned-wks</filename> folder. + This option overrides all other bootloader + options. + </para></listitem> + </itemizedlist> + </para> + </section> </section> </section> </section> |