summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml152
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 @@
3471 </para> 3471 </para>
3472 3472
3473 <para> 3473 <para>
3474 The <filename>wic</filename> command and the infrastructure
3475 it is based on is by definition incomplete.
3476 Its purpose is to allow the generation of customized images,
3477 and as such was designed to be completely extensible via a
3478 plugin interface.
3479 See the
3480 "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
3481 section for information on these plugins.
3482 </para>
3483
3484 <para>
3474 This section provides some background information on 3485 This section provides some background information on
3475 <filename>wic</filename>, describes what you need to have in 3486 <filename>wic</filename>, describes what you need to have in
3476 place to run the tool, provides instruction on how to use 3487 place to run the tool, provides instruction on how to use
@@ -3507,12 +3518,13 @@
3507 easier-to-use and more flexible replacements for a 3518 easier-to-use and more flexible replacements for a
3508 couple bits of existing functionality in OE Core's 3519 couple bits of existing functionality in OE Core's
3509 <filename>directdisk.bbclass</filename> and 3520 <filename>directdisk.bbclass</filename> and
3510 <filename>mkefidisk.sh</filename> script. 3521 <filename>mkefidisk.sh</filename> scripts.
3511 The replaced scripts are implemented by a 3522 The difference between
3512 general-purpose partitioning language based on Red Hat 3523 <filename>wic</filename> and those examples is
3513 kickstart syntax. 3524 that with <filename>wic</filename> the
3514 Underlying code for <filename>wic</filename> succeeded 3525 functionality of those scripts is implemented
3515 from several projects over time.</para></listitem> 3526 by a general-purpose partitioning language, which is
3527 based on Redhat kickstart syntax.</para></listitem>
3516 </itemizedlist> 3528 </itemizedlist>
3517 </para> 3529 </para>
3518 </section> 3530 </section>
@@ -3587,6 +3599,20 @@
3587 </para> 3599 </para>
3588 3600
3589 <para> 3601 <para>
3602 You can also get detailed help on a number of topics
3603 from the help system.
3604 The output of <filename>wic &dash;&dash;help</filename>
3605 displays a list of available help
3606 topics under a "Help topics" heading.
3607 You can have the help system display the help text for
3608 a given topic by prefacing the topic with
3609 <filename>wic help</filename>:
3610 <literallayout class='monospaced'>
3611 $ wic help &lt;help topic&gt;
3612 </literallayout>
3613 </para>
3614
3615 <para>
3590 You can find more out about the images 3616 You can find more out about the images
3591 <filename>wic</filename> creates using the provided 3617 <filename>wic</filename> creates using the provided
3592 kickstart files with the following form of the command: 3618 kickstart files with the following form of the command:
@@ -3603,8 +3629,10 @@
3603 <title>Operational Modes</title> 3629 <title>Operational Modes</title>
3604 3630
3605 <para> 3631 <para>
3606 You can run <filename>wic</filename> in two modes: Raw and 3632 You can use <filename>wic</filename> in two different
3607 Cooked: 3633 modes, depending on how much control you need for
3634 specifying the Openembedded build artifacts that are
3635 used for creating the image: Raw and Cooked:
3608 <itemizedlist> 3636 <itemizedlist>
3609 <listitem><para><emphasis>Raw Mode:</emphasis> 3637 <listitem><para><emphasis>Raw Mode:</emphasis>
3610 You explicitly specify build artifacts through 3638 You explicitly specify build artifacts through
@@ -3746,7 +3774,7 @@
3746 # long-description: Creates a partitioned EFI disk image that the user 3774 # long-description: Creates a partitioned EFI disk image that the user
3747 # can directly dd to boot media. 3775 # can directly dd to boot media.
3748 3776
3749 part /boot &dash;&dash;source bootimg-efi &dash;&dash;ondisk sda &dash;&dash;fstype=efi &dash;&dash;active 3777 part /boot &dash;&dash;source bootimg-efi &dash;&dash;ondisk sda &dash;&dash;active
3750 3778
3751 part / &dash;&dash;source rootfs &dash;&dash;ondisk sda &dash;&dash;fstype=ext3 &dash;&dash;label platform 3779 part / &dash;&dash;source rootfs &dash;&dash;ondisk sda &dash;&dash;fstype=ext3 &dash;&dash;label platform
3752 3780
@@ -3889,7 +3917,7 @@
3889 The example changes the following two lines and leaves the 3917 The example changes the following two lines and leaves the
3890 remaining lines untouched: 3918 remaining lines untouched:
3891 <literallayout class='monospaced'> 3919 <literallayout class='monospaced'>
3892 part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024 3920 part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
3893 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 3921 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
3894 </literallayout> 3922 </literallayout>
3895 Once the lines are changed, the example generates the 3923 Once the lines are changed, the example generates the
@@ -4215,31 +4243,46 @@
4215 You do not need this option if you use 4243 You do not need this option if you use
4216 <filename>--source</filename>.</para></listitem> 4244 <filename>--source</filename>.</para></listitem>
4217 <listitem><para><emphasis><filename>--source</filename>:</emphasis> 4245 <listitem><para><emphasis><filename>--source</filename>:</emphasis>
4218 This option is a wic-specific option that can 4246 This option is a
4219 currently have one of two values, "bootimg" or 4247 <filename>wic</filename>-specific option that
4220 "rootfs".</para> 4248 names the source of the data that populates
4221 <para>If <filename>--source rootfs</filename> is 4249 the partition.
4222 used, it tells the <filename>wic</filename> command 4250 The most common value for this option is
4223 to create a partition as large as needed to fill 4251 "rootfs", but you can use any value that maps to
4224 with the contents of the root filesystem 4252 a valid source plugin.
4225 (specified by the <filename>-r</filename> 4253 For information on the source plugins, see the
4226 <filename>wic</filename> option) and to fill it 4254 "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
4227 with the contents of <filename>/rootfs</filename>. 4255 section.</para>
4228 </para> 4256 <para>If you use
4229 <para>If <filename>--source bootimg</filename> 4257 <filename>&dash;&dash;source rootfs</filename>,
4230 is used, it tells the <filename>wic</filename> 4258 <filename>wic</filename> creates a partition as
4231 command to create a partition as large as needed to 4259 large as needed and to fill it with the contents of
4232 fill with the contents of the boot partition 4260 the root filesystem pointed to by the
4233 (specified by the <filename>-b</filename> 4261 <filename>-r</filename> command-line option
4234 <filename>wic</filename> option). 4262 or the equivalent rootfs derived from the
4235 Exactly what those contents are depend on the value 4263 <filename>-e</filename> command-line
4236 of the <filename>--fstype</filename> option for 4264 option.
4237 that partition. 4265 The filesystem type used to create the
4238 If <filename>--fstype=efi</filename> is specified, 4266 partition is driven by the value of the
4239 the boot artifacts contained in HDDDIR are used, 4267 <filename>&dash;&dash;fstype</filename> option
4240 and if <filename>--fstype=msdos</filename> is 4268 specified for the partition.
4241 specified, the boot artifacts found in 4269 See the entry on
4242 <filename>STAGING_DATADIR</filename> are used. 4270 <filename>&dash;&dash;fstype</filename> that
4271 follows for more information.
4272 </para>
4273 <para>If you use
4274 <filename>&dash;&dash;source &lt;plugin-name&gt;</filename>,
4275 <filename>wic</filename> creates a partition as
4276 large as needed and fills it with the contents of
4277 the partition that is generated by the
4278 specified plugin name using the data pointed
4279 to by the <filename>-r</filename> command-line
4280 option or the equivalent rootfs derived from the
4281 <filename>-e</filename> command-line
4282 option.
4283 Exactly what those contents and
4284 filesystem type end up being are dependent
4285 on the given plugin implementation.
4243 </para></listitem> 4286 </para></listitem>
4244 <listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> 4287 <listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis>
4245 Forces the partition to be created on a particular 4288 Forces the partition to be created on a particular
@@ -4248,10 +4291,6 @@
4248 Sets the file system type for the partition. 4291 Sets the file system type for the partition.
4249 Valid values are: 4292 Valid values are:
4250 <itemizedlist> 4293 <itemizedlist>
4251 <listitem><para><filename>msdos</filename>
4252 </para></listitem>
4253 <listitem><para><filename>efi</filename>
4254 </para></listitem>
4255 <listitem><para><filename>ext4</filename> 4294 <listitem><para><filename>ext4</filename>
4256 </para></listitem> 4295 </para></listitem>
4257 <listitem><para><filename>ext3</filename> 4296 <listitem><para><filename>ext3</filename>
@@ -4267,11 +4306,11 @@
4267 </itemizedlist></para></listitem> 4306 </itemizedlist></para></listitem>
4268 <listitem><para><emphasis><filename>&dash;&dash;fsoptions</filename>:</emphasis> 4307 <listitem><para><emphasis><filename>&dash;&dash;fsoptions</filename>:</emphasis>
4269 Specifies a free-form string of options to be 4308 Specifies a free-form string of options to be
4270 used when mounting the filesystem. 4309 used when mounting the filesystem.
4271 This string will be copied into the 4310 This string will be copied into the
4272 <filename>/etc/fstab</filename> file of the 4311 <filename>/etc/fstab</filename> file of the
4273 installed system and should be enclosed in 4312 installed system and should be enclosed in
4274 quotes. 4313 quotes.
4275 If not specified, the default string 4314 If not specified, the default string
4276 is "defaults". 4315 is "defaults".
4277 </para></listitem> 4316 </para></listitem>
@@ -4297,6 +4336,21 @@
4297 <para> 4336 <para>
4298 This command specifies how the boot loader should be 4337 This command specifies how the boot loader should be
4299 and supports the following options: 4338 and supports the following options:
4339 <note>
4340 <para>
4341 Bootloader functionality and boot partitions
4342 are implemented by the various
4343 <filename>&dash;&dash;source</filename>
4344 plugins that implement bootloader
4345 functionality.
4346 The bootloader command essentially provides a
4347 means of modifying bootloader configuration.
4348 </para>
4349 <para>
4350 Future updates will implement more options.
4351 If you use anything that is not specifically
4352 supported, results can be unpredictable.</para>
4353 </note>
4300 <itemizedlist> 4354 <itemizedlist>
4301 <listitem><para><emphasis><filename>--timeout</filename>:</emphasis> 4355 <listitem><para><emphasis><filename>--timeout</filename>:</emphasis>
4302 Specifies the number of seconds before the 4356 Specifies the number of seconds before the
@@ -4307,22 +4361,6 @@
4307 These will be added to the syslinux 4361 These will be added to the syslinux
4308 <filename>APPEND</filename> or 4362 <filename>APPEND</filename> or
4309 <filename>grub</filename> kernel command line. 4363 <filename>grub</filename> kernel command line.
4310 </para>
4311 <para>The boot type is determined by the fstype of
4312 the <filename>/boot</filename> mountpoint.
4313 If the fstype is "msdos" the boot type is
4314 "pcbios", otherwise it is the fstype, which
4315 is currently "efi" (more to be added later).
4316 </para>
4317 <para>If the boot type is "efi", the image will
4318 use <filename>grub</filename> and has one
4319 menuentry: "boot".</para>
4320 <para>If the boot type is "pcbios", the image
4321 will use syslinux and has one menu label: "boot".
4322 </para>
4323 <para>Future updates will implement more options.
4324 If you use anything that is not specifically
4325 supported, results can be unpredictable.
4326 </para></listitem> 4364 </para></listitem>
4327 </itemizedlist> 4365 </itemizedlist>
4328 </para> 4366 </para>