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 @@ -3470,6 +3470,17 @@ used on a particular system. + + The wic 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 + "Plugins" + section for information on these plugins. + + This section provides some background information on wic, describes what you need to have in @@ -3507,12 +3518,13 @@ easier-to-use and more flexible replacements for a couple bits of existing functionality in OE Core's directdisk.bbclass and - mkefidisk.sh script. - The replaced scripts are implemented by a - general-purpose partitioning language based on Red Hat - kickstart syntax. - Underlying code for wic succeeded - from several projects over time. + mkefidisk.sh scripts. + 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. @@ -3586,6 +3598,20 @@ + + You can also get detailed help on a number of topics + from the help system. + The output of wic ‐‐help + 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 + wic help: + + $ wic help <help topic> + + + You can find more out about the images wic creates using the provided @@ -3603,8 +3629,10 @@ Operational Modes - You can run wic in two modes: Raw and - Cooked: + 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: Raw Mode: 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: - 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 Once the lines are changed, the example generates the @@ -4215,31 +4243,46 @@ You do not need this option if you use --source. --source: - This option is a wic-specific option that can - currently have one of two values, "bootimg" or - "rootfs". - If --source rootfs is - used, it tells the wic command - to create a partition as large as needed to fill - with the contents of the root filesystem - (specified by the -r - wic option) and to fill it - with the contents of /rootfs. - - If --source bootimg - is used, it tells the wic - command to create a partition as large as needed to - fill with the contents of the boot partition - (specified by the -b - wic option). - Exactly what those contents are depend on the value - of the --fstype option for - that partition. - If --fstype=efi is specified, - the boot artifacts contained in HDDDIR are used, - and if --fstype=msdos is - specified, the boot artifacts found in - STAGING_DATADIR are used. + 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 plugin. + For information on the source plugins, see the + "Plugins" + section. + If you use + ‐‐source rootfs, + wic creates a partition as + large as needed and to fill it with the contents of + the root filesystem pointed to by the + -r command-line option + or the equivalent rootfs derived from the + -e command-line + option. + The filesystem type used to create the + partition is driven by the value of the + ‐‐fstype option + specified for the partition. + See the entry on + ‐‐fstype that + follows for more information. + + If you use + ‐‐source <plugin-name>, + wic 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 -r command-line + option or the equivalent rootfs derived from the + -e command-line + option. + Exactly what those contents and + filesystem type end up being are dependent + on the given plugin implementation. --ondisk or --ondrive: Forces the partition to be created on a particular @@ -4248,10 +4291,6 @@ Sets the file system type for the partition. Valid values are: - msdos - - efi - ext4 ext3 @@ -4267,11 +4306,11 @@ ‐‐fsoptions: 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 /etc/fstab file of the installed system and should be enclosed in - quotes. + quotes. If not specified, the default string is "defaults". @@ -4297,6 +4336,21 @@ This command specifies how the boot loader should be and supports the following options: + + + Bootloader functionality and boot partitions + are implemented by the various + ‐‐source + plugins that implement bootloader + functionality. + The bootloader command essentially provides a + means of modifying bootloader configuration. + + + Future updates will implement more options. + If you use anything that is not specifically + supported, results can be unpredictable. + --timeout: Specifies the number of seconds before the @@ -4307,22 +4361,6 @@ These will be added to the syslinux APPEND or grub kernel command line. - - The boot type is determined by the fstype of - the /boot 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). - - If the boot type is "efi", the image will - use grub and has one - menuentry: "boot". - If the boot type is "pcbios", the image - will use syslinux and has one menu label: "boot". - - Future updates will implement more options. - If you use anything that is not specifically - supported, results can be unpredictable.