diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-07-18 10:29:29 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-07-22 15:05:14 +0100 |
commit | 60907ba907557bfd1b0f10fa39f3dd3fdbceda8c (patch) | |
tree | 00d7cf5877462ed9a2b48e869c75c8b791d96d41 | |
parent | dc743744d8e3a9caef577aeab6b7f51bc08ded17 (diff) | |
download | poky-60907ba907557bfd1b0f10fa39f3dd3fdbceda8c.tar.gz |
dev-manual: Updates to the "Creating Partitioned Images" section.
These updates are to the wic section. I have updated the syntax
and some requirements for running and using wic. The original
information was never reviewed before appearing in only the 1.5.2
verison of the dev-manual.
(From yocto-docs rev: 66c755f2753c52bdb304281d2109c2c253941d35)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 171 |
1 files changed, 83 insertions, 88 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 941550dc24..c8de6bff93 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml | |||
@@ -1940,7 +1940,7 @@ | |||
1940 | format the device requires. | 1940 | format the device requires. |
1941 | Should your device require multiple partitions on an SD card, flash, | 1941 | Should your device require multiple partitions on an SD card, flash, |
1942 | or an HDD, you can use the OpenEmbedded Image Creator | 1942 | or an HDD, you can use the OpenEmbedded Image Creator |
1943 | () to create the properly partitioned image. | 1943 | to create the properly partitioned image. |
1944 | </para> | 1944 | </para> |
1945 | 1945 | ||
1946 | <para> | 1946 | <para> |
@@ -1949,8 +1949,10 @@ | |||
1949 | Image generation is driven by partitioning commands contained | 1949 | Image generation is driven by partitioning commands contained |
1950 | in an Openembedded kickstart file (<filename>.wks</filename>) | 1950 | in an Openembedded kickstart file (<filename>.wks</filename>) |
1951 | specified either directly on the command-line or as one of a | 1951 | specified either directly on the command-line or as one of a |
1952 | selection of canned <filename>.wks</filename> files | 1952 | selection of canned <filename>.wks</filename> files as shown |
1953 | (see 'wic list images'). | 1953 | with the <filename>wic list images</filename> command in the |
1954 | "<link linkend='using-a-provided-kickstart_file'>Using a Provided Kickstart File</link>" | ||
1955 | section. | ||
1954 | When applied to a given set of build artifacts, the result is an | 1956 | When applied to a given set of build artifacts, the result is an |
1955 | image or set of images that can be directly written onto media and | 1957 | image or set of images that can be directly written onto media and |
1956 | used on a particular system. | 1958 | used on a particular system. |
@@ -2003,34 +2005,6 @@ | |||
2003 | </para> | 2005 | </para> |
2004 | </section> | 2006 | </section> |
2005 | 2007 | ||
2006 | <!-- | ||
2007 | |||
2008 | <para> | ||
2009 | This section covers the mechanics of invoking and providing help for | ||
2010 | the command and sub-commands; it contains hooks for future commits to | ||
2011 | connect with the actual functionality, once implemented. | ||
2012 | </para> | ||
2013 | |||
2014 | <para> | ||
2015 | Help is integrated into the 'wic' command itself - you can also see | ||
2016 | that for details and reminders on usage (simply invoke 'wic' without | ||
2017 | any arguments to get started). | ||
2018 | </para> | ||
2019 | |||
2020 | <note> | ||
2021 | Just because 'wic' can generate an image does not mean that it | ||
2022 | will boot on a given machine. 'wic' tries to spot the most obvious | ||
2023 | usages that are likely to cause problems but, as a relatively | ||
2024 | low-level tool, it can't in general figure out whether a generated | ||
2025 | image is appropriate for a given piece of hardware - it's really up to | ||
2026 | you to provide intelligent inputs to the image creation process. If | ||
2027 | you suspect that your image is not working as expected due to some bug | ||
2028 | or missing feature of the tool, please file a bug report describing | ||
2029 | the details. | ||
2030 | </note> | ||
2031 | |||
2032 | --> | ||
2033 | |||
2034 | <section id='wic-requirements'> | 2008 | <section id='wic-requirements'> |
2035 | <title>Requirements</title> | 2009 | <title>Requirements</title> |
2036 | 2010 | ||
@@ -2131,14 +2105,65 @@ the details. | |||
2131 | </itemizedlist> | 2105 | </itemizedlist> |
2132 | </para> | 2106 | </para> |
2133 | 2107 | ||
2108 | <para> | ||
2109 | Regardless of the mode you use, you need to have the build | ||
2110 | artifacts ready and available. | ||
2111 | Additionally, the environment must be set up using the | ||
2112 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
2113 | or | ||
2114 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> | ||
2115 | script found in the | ||
2116 | <link linkend='build-directory'>Build Directory</link>. | ||
2117 | </para> | ||
2118 | |||
2134 | <section id='raw-mode'> | 2119 | <section id='raw-mode'> |
2135 | <title>Raw Mode</title> | 2120 | <title>Raw Mode</title> |
2136 | 2121 | ||
2137 | <para> | 2122 | <para> |
2138 | The general form of the 'wic' command in raw mode is: | 2123 | The general form of the 'wic' command in raw mode is: |
2139 | <literallayout class='monospaced'> | 2124 | <literallayout class='monospaced'> |
2140 | $ wic create <image_name>.wks -r <rootfs_dir> -b <bootimg_dir> / | 2125 | $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...] |
2141 | -k <kernel_dir> -n <native_sysroot> | 2126 | |
2127 | Where: | ||
2128 | |||
2129 | <replaceable>image_name</replaceable>.wks | ||
2130 | An an OpenEmbedded kickstart file. You can provide | ||
2131 | your own custom file or use a file from a set of | ||
2132 | provided files as described by further options. | ||
2133 | |||
2134 | -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable> | ||
2135 | The name of a directory in which to create image. | ||
2136 | |||
2137 | -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable> | ||
2138 | The name of a file containing the values for image | ||
2139 | properties as a JSON file. | ||
2140 | |||
2141 | -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable> | ||
2142 | The name of the image from which to use the artifacts | ||
2143 | (e.g. <filename>core-image-sato</filename>). | ||
2144 | |||
2145 | -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> | ||
2146 | The path to the <filename>/rootfs</filename> directory to use as the | ||
2147 | <filename>.wks</filename> rootfs source. | ||
2148 | |||
2149 | -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> | ||
2150 | The path to the directory containing the boot artifacts | ||
2151 | (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg | ||
2152 | source. | ||
2153 | |||
2154 | -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable> | ||
2155 | The path to the directory containing the kernel to use | ||
2156 | in the <filename>.wks</filename> boot image. | ||
2157 | |||
2158 | -n <replaceable>NATIVE_SYSROOT</replaceable>, --native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> | ||
2159 | The path to the native sysroot containing the tools to use | ||
2160 | to build the image. | ||
2161 | |||
2162 | -p, --skip-build-check | ||
2163 | Skips the build check. | ||
2164 | |||
2165 | -D, --debug | ||
2166 | Output debug information. | ||
2142 | </literallayout> | 2167 | </literallayout> |
2143 | <note> | 2168 | <note> |
2144 | You do not need root privileges to run | 2169 | You do not need root privileges to run |
@@ -2147,37 +2172,6 @@ the details. | |||
2147 | utility. | 2172 | utility. |
2148 | </note> | 2173 | </note> |
2149 | </para> | 2174 | </para> |
2150 | |||
2151 | <para> | ||
2152 | Following is a description of the <filename>wic</filename> | ||
2153 | parameters and options: | ||
2154 | <itemizedlist> | ||
2155 | <listitem><para><emphasis><filename><image_name>.wks</filename>:</emphasis> | ||
2156 | An OpenEmbedded kickstart file. | ||
2157 | You can provide your own custom file or use a | ||
2158 | file from a set of provided files as described | ||
2159 | following this list.</para></listitem> | ||
2160 | <listitem><para><emphasis><filename>-r <rootfs_dir></filename>:</emphasis> | ||
2161 | Specifies the path to the root filesystem directory | ||
2162 | to be used and the <filename>.wks</filename> | ||
2163 | root filesystem source.</para></listitem> | ||
2164 | <listitem><para><emphasis><filename>-b <bootimg_dir></filename>:</emphasis> | ||
2165 | Specifies the path to the directory that contains | ||
2166 | the boot artifacts (e.g. the | ||
2167 | <filename>EFI</filename> or | ||
2168 | <filename>syslinux</filename> directories) to use | ||
2169 | as the <filename>.wks</filename> boot image source. | ||
2170 | </para></listitem> | ||
2171 | <listitem><para><emphasis><filename>-k <kernel_dir></filename>:</emphasis> | ||
2172 | Specifies the path to the dir containing the kernel | ||
2173 | to use in the <filename>.wks</filename> boot | ||
2174 | image.</para></listitem> | ||
2175 | <listitem><para><emphasis><filename>-n <native_sysroot></filename>:</emphasis> | ||
2176 | Specifies the path to the native sysroot | ||
2177 | that contains the tools used to build the image. | ||
2178 | </para></listitem> | ||
2179 | </itemizedlist> | ||
2180 | </para> | ||
2181 | </section> | 2175 | </section> |
2182 | 2176 | ||
2183 | <section id='cooked-mode'> | 2177 | <section id='cooked-mode'> |
@@ -2187,7 +2181,17 @@ the details. | |||
2187 | The general form of the <filename>wic</filename> command | 2181 | The general form of the <filename>wic</filename> command |
2188 | using Cooked Mode is: | 2182 | using Cooked Mode is: |
2189 | <literallayout class='monospaced'> | 2183 | <literallayout class='monospaced'> |
2190 | $ wic create <kickstart_file> -e <image_name> | 2184 | $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable> |
2185 | |||
2186 | Where: | ||
2187 | |||
2188 | <replaceable>kickstart_file</replaceable> | ||
2189 | An OpenEmbedded kickstart file. You can provide your own | ||
2190 | custom file or supplied file. | ||
2191 | |||
2192 | <replaceable>image_name</replaceable> | ||
2193 | Specifies the image built using the OpenEmbedded build | ||
2194 | system. | ||
2191 | </literallayout> | 2195 | </literallayout> |
2192 | This form is the simplest and most user-friendly, as it | 2196 | This form is the simplest and most user-friendly, as it |
2193 | does not require specifying all individual parameters. | 2197 | does not require specifying all individual parameters. |
@@ -2195,20 +2199,6 @@ the details. | |||
2195 | <filename>.wks</filename> file or one provided with the | 2199 | <filename>.wks</filename> file or one provided with the |
2196 | release. | 2200 | release. |
2197 | </para> | 2201 | </para> |
2198 | |||
2199 | <para> | ||
2200 | Following is a description of the <filename>wic</filename> | ||
2201 | parameters and options: | ||
2202 | <itemizedlist> | ||
2203 | <listitem><para><emphasis><filename><kickstart></filename>:</emphasis> | ||
2204 | An OpenEmbedded kickstart file. | ||
2205 | You can provide your own custom file or supplied | ||
2206 | file.</para></listitem> | ||
2207 | <listitem><para><emphasis><filename>-e <image_name></filename>:</emphasis> | ||
2208 | Specifies the image built using the OpenEmbedded | ||
2209 | build system.</para></listitem> | ||
2210 | </itemizedlist> | ||
2211 | </para> | ||
2212 | </section> | 2202 | </section> |
2213 | </section> | 2203 | </section> |
2214 | 2204 | ||
@@ -2222,16 +2212,16 @@ the details. | |||
2222 | Use the following command to list the available files: | 2212 | Use the following command to list the available files: |
2223 | <literallayout class='monospaced'> | 2213 | <literallayout class='monospaced'> |
2224 | $ wic list images | 2214 | $ wic list images |
2225 | mkefidisk Create an EFI disk image | ||
2226 | directdisk Create a 'pcbios' direct disk image | 2215 | directdisk Create a 'pcbios' direct disk image |
2216 | mkefidisk Create an EFI disk image | ||
2227 | </literallayout> | 2217 | </literallayout> |
2228 | When you use a provided file, you do not have to use the | 2218 | When you use a provided file, you do not have to use the |
2229 | <filename>.wks</filename> extension. | 2219 | <filename>.wks</filename> extension. |
2230 | Here is an example in Raw Mode that uses the | 2220 | Here is an example in Raw Mode that uses the |
2231 | <filename>directdisk</filename> file: | 2221 | <filename>directdisk</filename> file: |
2232 | <literallayout class='monospaced'> | 2222 | <literallayout class='monospaced'> |
2233 | $ wic create directdisk -r <rootfs_dir> -b <bootimg_dir> \ | 2223 | $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \ |
2234 | -k <kernel_dir> -n <native_sysroot> | 2224 | -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable> |
2235 | </literallayout> | 2225 | </literallayout> |
2236 | </para> | 2226 | </para> |
2237 | 2227 | ||
@@ -2244,13 +2234,13 @@ the details. | |||
2244 | # long-description: Creates a partitioned EFI disk image that the user | 2234 | # long-description: Creates a partitioned EFI disk image that the user |
2245 | # can directly dd to boot media. | 2235 | # can directly dd to boot media. |
2246 | 2236 | ||
2247 | part /boot --source bootimg --ondisk sda --fstype=efi --label msdos --active --align 1024 | 2237 | part /boot ‐‐source bootimg-efi ‐‐ondisk sda ‐‐fstype=efi ‐‐active |
2248 | 2238 | ||
2249 | part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 | 2239 | part / ‐‐source rootfs ‐‐ondisk sda ‐‐fstype=ext3 ‐‐label platform |
2250 | 2240 | ||
2251 | part swap --ondisk sda --size 44 --label swap1 --fstype=swap | 2241 | part swap ‐‐ondisk sda ‐‐size 44 ‐‐label swap1 ‐‐fstype=swap |
2252 | 2242 | ||
2253 | bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda- intel.enable_msi=0" | 2243 | bootloader ‐‐timeout=10 ‐‐append="rootwait console=ttyPCH0,115200" |
2254 | </literallayout> | 2244 | </literallayout> |
2255 | </para> | 2245 | </para> |
2256 | </section> | 2246 | </section> |
@@ -2377,7 +2367,8 @@ the details. | |||
2377 | directory and then changing the lines that specify the | 2367 | directory and then changing the lines that specify the |
2378 | target disk from which to boot. | 2368 | target disk from which to boot. |
2379 | <literallayout class='monospaced'> | 2369 | <literallayout class='monospaced'> |
2380 | $ 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 | 2370 | $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \ |
2371 | /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks | ||
2381 | </literallayout> | 2372 | </literallayout> |
2382 | Next, the example modifies the | 2373 | Next, the example modifies the |
2383 | <filename>directdisksdb.wks</filename> file and changes all | 2374 | <filename>directdisksdb.wks</filename> file and changes all |
@@ -2474,7 +2465,11 @@ the details. | |||
2474 | somewhere other than the default | 2465 | somewhere other than the default |
2475 | <filename>/var/tmp/wic</filename> directory: | 2466 | <filename>/var/tmp/wic</filename> directory: |
2476 | <literallayout class='monospaced'> | 2467 | <literallayout class='monospaced'> |
2477 | $ 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 | 2468 | $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \ |
2469 | /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ | ||
2470 | --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ | ||
2471 | --kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \ | ||
2472 | --native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux | ||
2478 | 2473 | ||
2479 | Creating image(s)... | 2474 | Creating image(s)... |
2480 | 2475 | ||