diff options
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 152 |
1 files changed, 95 insertions, 57 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index bb84dcc1c9..b995371c10 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -3471,6 +3471,17 @@ </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 via a + plugin interface. + See the + "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" + section for information on these plugins. + </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 @@ -3507,12 +3518,13 @@ easier-to-use and more flexible replacements for a couple bits of existing functionality in OE Core's <filename>directdisk.bbclass</filename> and - <filename>mkefidisk.sh</filename> script. - The replaced scripts are implemented by a - general-purpose partitioning language based on Red Hat - kickstart syntax. - Underlying code for <filename>wic</filename> succeeded - from several projects over time.</para></listitem> + <filename>mkefidisk.sh</filename> scripts. + 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> @@ -3587,6 +3599,20 @@ </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 <help topic> + </literallayout> + </para> + + <para> You can find more out about the images <filename>wic</filename> creates using the provided kickstart files with the following form of the command: @@ -3603,8 +3629,10 @@ <title>Operational Modes</title> <para> - You can run <filename>wic</filename> in two modes: Raw and - Cooked: + 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 @@ -3746,7 +3774,7 @@ # long-description: Creates a partitioned EFI disk image that the user # can directly dd to boot media. - part /boot ‐‐source bootimg-efi ‐‐ondisk sda ‐‐fstype=efi ‐‐active + part /boot ‐‐source bootimg-efi ‐‐ondisk sda ‐‐active part / ‐‐source rootfs ‐‐ondisk sda ‐‐fstype=ext3 ‐‐label platform @@ -3889,7 +3917,7 @@ The example changes the following two lines and leaves the remaining lines untouched: <literallayout class='monospaced'> - part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024 + 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 @@ -4215,31 +4243,46 @@ 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 can - currently have one of two values, "bootimg" or - "rootfs".</para> - <para>If <filename>--source rootfs</filename> is - used, it tells the <filename>wic</filename> command - to create a partition as large as needed to fill - with the contents of the root filesystem - (specified by the <filename>-r</filename> - <filename>wic</filename> option) and to fill it - with the contents of <filename>/rootfs</filename>. - </para> - <para>If <filename>--source bootimg</filename> - is used, it tells the <filename>wic</filename> - command to create a partition as large as needed to - fill with the contents of the boot partition - (specified by the <filename>-b</filename> - <filename>wic</filename> option). - Exactly what those contents are depend on the value - of the <filename>--fstype</filename> option for - that partition. - If <filename>--fstype=efi</filename> is specified, - the boot artifacts contained in HDDDIR are used, - and if <filename>--fstype=msdos</filename> is - specified, the boot artifacts found in - <filename>STAGING_DATADIR</filename> are used. + 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 <plugin-name></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></listitem> <listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> Forces the partition to be created on a particular @@ -4248,10 +4291,6 @@ Sets the file system type for the partition. Valid values are: <itemizedlist> - <listitem><para><filename>msdos</filename> - </para></listitem> - <listitem><para><filename>efi</filename> - </para></listitem> <listitem><para><filename>ext4</filename> </para></listitem> <listitem><para><filename>ext3</filename> @@ -4267,11 +4306,11 @@ </itemizedlist></para></listitem> <listitem><para><emphasis><filename>‐‐fsoptions</filename>:</emphasis> Specifies a free-form string of options to be - used when mounting the filesystem. + 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. + quotes. If not specified, the default string is "defaults". </para></listitem> @@ -4297,6 +4336,21 @@ <para> This command specifies how the boot loader should be and supports the following options: + <note> + <para> + 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. + </para> + <para> + Future updates will implement more options. + If you use anything that is not specifically + supported, results can be unpredictable.</para> + </note> <itemizedlist> <listitem><para><emphasis><filename>--timeout</filename>:</emphasis> Specifies the number of seconds before the @@ -4307,22 +4361,6 @@ These will be added to the syslinux <filename>APPEND</filename> or <filename>grub</filename> kernel command line. - </para> - <para>The boot type is determined by the fstype of - the <filename>/boot</filename> mountpoint. - If the fstype is "msdos" the boot type is - "pcbios", otherwise it is the fstype, which - is currently "efi" (more to be added later). - </para> - <para>If the boot type is "efi", the image will - use <filename>grub</filename> and has one - menuentry: "boot".</para> - <para>If the boot type is "pcbios", the image - will use syslinux and has one menu label: "boot". - </para> - <para>Future updates will implement more options. - If you use anything that is not specifically - supported, results can be unpredictable. </para></listitem> </itemizedlist> </para> |