diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 305dc316b4..d22c2a70a1 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -2008,13 +2008,13 @@ any arguments to get started). - Just because 'wic' can generate an image doesn't mean that it + Just because 'wic' can generate an image does not mean that it will boot on a given machine. 'wic' tries to spot the most obvious usages that are likely to cause problems but, as a relatively low-level tool, it can't in general figure out whether a generated image is appropriate for a given piece of hardware - it's really up to you to provide intelligent inputs to the image creation process. If -you suspect that your image isn't working as expected due to some bug +you suspect that your image is not working as expected due to some bug or missing feature of the tool, please file a bug report describing the details. @@ -2180,7 +2180,7 @@ the details. $ wic create <kickstart_file> -e <image_name> This form is the simplest and most user-friendly, as it - does not requre specifying all individual parameters. + does not require specifying all individual parameters. All you need to provide is your own .wks file or one provided with the release. @@ -2224,6 +2224,25 @@ the details. -k <kernel_dir> -n <native_sysroot> + + + Here are the actual partition language commands + used in the mkefidisk.wks file to generate + an image: + + # short-description: Create an EFI disk image + # long-description: Creates a partitioned EFI disk image that the user + # can directly dd to boot media. + + part /boot --source bootimg --ondisk sda --fstype=efi --label msdos --active --align 1024 + + part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 + + 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" + +
@@ -2267,10 +2286,10 @@ the details. This example shows the easiest way to create an image by running in Cooked Mode and using the - <-e> option with a - provided kickstart file. - All that is necessary is to specify the image - used to generate the artifacts. + -e option with a provided kickstart + file. + All that is necessary is to specify the image used to + generate the artifacts. Your local.conf needs to have the MACHINE variable set to the machine you are using, which is @@ -2278,14 +2297,14 @@ the details. - The output specifies exactly which image were - created and where the image was created. + The output specifies exactly which image was + created as well as where it was created. The output also names the artifacts used and the exact .wks script that was used to generate the image. You should always verify the details provided in the - output to make sure that the imagewas indeed created + output to make sure that the image was indeed created exactly as expected. @@ -2311,7 +2330,7 @@ the details. Because wic image creation is driven - by the kickstart file, it is easy to drive image creation + 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 directdisk kickstart file. @@ -2321,9 +2340,10 @@ the details. As mentioned earlier, you can use the command wic list images to show the list of provided kickstart files. - The directory in which these files reside is in the - Source Directory - in scripts/lib/image/canned-wks/. + The directory in which these files reside is + scripts/lib/image/canned-wks/ + located in the + Source Directory. Because the available files reside in this directory, you can create and add your own custom files to the directory. Subsequent use of the wic list images @@ -2359,22 +2379,13 @@ the details. part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 - (I AM HERE) - Once the lines are changed, Once we've made that change, we generate a directdisksdb image, -pointing the process at the core-image-minimal artifacts for the nuc -(Next Unit of Computing), selected as our current MACHINE in -local.conf. - - - - Once we've set the build up, we run a core-image-minimal nuc build: - - $ bitbake core-image-minimal - - Once the build is finished, we can then use nuc to create our -directdisk image for the nuc to boot. In this case, we'll use the -'-e' option to have wic discover the appropriate build artifacts and -generate the image: + Once the lines are changed, the example generates the + directdisksdb image. + The command points the process at the + core-image-minimal artifacts for the + Next Unit of Computing (nuc) + MACHINE + the local.conf. $ wic create directdisksdb -e core-image-minimal Checking basic build environment... @@ -2395,9 +2406,10 @@ generate the image: The image(s) were created using OE kickstart file: /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks - Using the path specified in the output for the image name and -location, you can now directly dd the image to a USB stick or whatever -media you built the image for, and boot the resulting media: + Continuing with the example, you can now directly + dd the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb 86018+0 records in @@ -2405,13 +2417,18 @@ media you built the image for, and boot the resulting media: 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s [trz@empanada tmp]$ sudo eject /dev/sdb - Of course, you can just use the directdisk image directly if you don't -have any special needs. +
+ +
+ Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename> - Here'we're creating a wic image based on core-image-minimal and -crownbay-noemgd, which works right out of the box. + This example creates an image based on + core-image-minimal and a + crownbay-noemgd + MACHINE + that works right out of the box. $ wic create directdisk -e core-image-minimal @@ -2433,10 +2450,19 @@ crownbay-noemgd, which works right out of the box. The image(s) were created using OE kickstart file: /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks - Finally, here's an example that doesn't take the easy way out and -manually specifies each build artifact, along with a non-canned .wks -file, and also uses the -o option to have wic create the output -somewhere other than the default /var/tmp/wic: + +
+ +
+ Using a Modified Kickstart File and Running in Raw Mode + + + This next example manually specifies each build artifact + (runs in Raw Mode) and uses a modified kickstart file. + The example also uses the -o option + to cause wic to create the output + somewhere other than the default + /var/tmp/wic directory: $ 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 --kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel --native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux @@ -2455,28 +2481,11 @@ somewhere other than the default /var/tmp/wic: The image(s) were created using OE kickstart file: /home/trz/test.wks - In this case, we didn't need to have the proper machine selected in -local.conf - we manually specified each artifact and therefore wic -doesn't need further information from the build system. - - - - Finally, here's an example of the actual partition language commands -used to generate the mkefidisk image i.e. these are the contents of the -mkefidisk.wks OE kickstart file: - - # short-description: Create an EFI disk image - # long-description: Creates a partitioned EFI disk image that the user - # can directly dd to boot media. - - part /boot --source bootimg --ondisk sda --fstype=efi --label msdos --active --align 1024 - - part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 - - 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" - + For this example, + MACHINE + did not have to be specified in the + local.conf file since the artifact is + manually specified.
@@ -2485,16 +2494,18 @@ mkefidisk.wks OE kickstart file: OpenEmbedded Kickstart (.wks) Reference - The current 'wic' implementation supports only the basic kickstart -partitioning commands: 'partition' (or 'part' for short) and -'bootloader'. + The current wic implementation supports + only the basic kickstart partitioning commands: + partition (or part + for short) and bootloader. - They are listed below and mostly follow the syntax and meaning of the -standard kickstart options for those commands. The documentation below -is based on the Fedora kickstart documentation of the same commands, -but modified to reflect wic capabilities. For reference: + Following is a listing of the commands, their syntax, and + meanings. + The commands are based on the Fedora kickstart documentation + but with modifications to reflect wic + capabilities. http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader @@ -2505,13 +2516,14 @@ but modified to reflect wic capabilities. For reference: Command: part or partition - Creates a partition on the system. - Use the following syntax: + This command creates a partition on the system and uses the + following syntax: part <mntpoint> - The <mntpoint> is where the partition will be mounted and must be of -one of the following forms: + The <mntpoint> is where the + partition will be mounted and must be of one of the + following forms: /<path>: For example, /, @@ -2525,57 +2537,75 @@ one of the following forms: Following are the supported options: - - --size - The minimum partition size in megabytes. Specify an integer value - here such as 500. Do not append the number with MB. Not needed if - --source is used. - - --source - bootimg - rootfs - - The --source 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 /rootfs - (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. - - --ondisk or --ondrive - Forces the partition to be created on a particular disk. - - --fstype - Sets the file system type for the partition. Valid values are: - msdos - efi - ext4 - ext3 - ext2 - btrfs - swap - - --label label - Specify 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 will be created for this partition. - - --active - Mark the partition as active. - - --align (in kB) - The '--align' option is a mic-specific option that says to start a - partition on an x kB boundary. - + + --size: + 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 + --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. + + --ondisk or --ondrive: + Forces the partition to be created on a particular + disk. + --fstype: + Sets the file system type for the partition. + Valid values are: + + msdos + + efi + + ext4 + + ext3 + + ext2 + + btrfs + + swap + + + --label label: + 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. + --active: + Marks the partition as active. + --align (in KBytes): + This option is specific to the Meego Image + Creator (mic) that says to start a partition on an + x KBytes boundary. + @@ -2583,33 +2613,36 @@ one of the following forms: Command: bootloader - This command specifies how the boot loader should be installed. - - - - Following are the supported options: - - --timeout - Specify the number of seconds before the bootloader times out and - boots the default option. - - --append - Specifies kernel parameters. 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's the - fstype, which currently be: '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 - using anything not - explicitly supported can result in unpredictable results. - + This command specifies how the boot loader should be + and supports the following options: + + --timeout: + Specifies the number of seconds before the + bootloader times out and boots the default option. + + --append: + Specifies kernel parameters. + 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. + +