summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-07-18 10:29:29 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-07-22 15:05:14 +0100
commit60907ba907557bfd1b0f10fa39f3dd3fdbceda8c (patch)
tree00d7cf5877462ed9a2b48e869c75c8b791d96d41
parentdc743744d8e3a9caef577aeab6b7f51bc08ded17 (diff)
downloadpoky-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.xml171
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
2010the command and sub-commands; it contains hooks for future commits to
2011connect with the actual functionality, once implemented.
2012 </para>
2013
2014 <para>
2015 Help is integrated into the 'wic' command itself - you can also see
2016that for details and reminders on usage (simply invoke 'wic' without
2017any arguments to get started).
2018 </para>
2019
2020 <note>
2021 Just because 'wic' can generate an image does not mean that it
2022will boot on a given machine. 'wic' tries to spot the most obvious
2023usages that are likely to cause problems but, as a relatively
2024low-level tool, it can't in general figure out whether a generated
2025image is appropriate for a given piece of hardware - it's really up to
2026you to provide intelligent inputs to the image creation process. If
2027you suspect that your image is not working as expected due to some bug
2028or missing feature of the tool, please file a bug report describing
2029the 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 &lt;image_name&gt;.wks -r &lt;rootfs_dir&gt; -b &lt;bootimg_dir&gt; / 2125 $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...]
2141 -k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt; 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>&lt;image_name&gt;.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 &lt;rootfs_dir&gt;</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 &lt;bootimg_dir&gt;</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 &lt;kernel_dir&gt;</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 &lt;native_sysroot&gt;</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 &lt;kickstart_file&gt; -e &lt;image_name&gt; 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>&lt;kickstart&gt;</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 &lt;image_name&gt;</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 &lt;rootfs_dir&gt; -b &lt;bootimg_dir&gt; \ 2223 $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \
2234 -k &lt;kernel_dir&gt; -n &lt;native_sysroot&gt; 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 &dash;&dash;source bootimg-efi &dash;&dash;ondisk sda &dash;&dash;fstype=efi &dash;&dash;active
2248 2238
2249 part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 2239 part / &dash;&dash;source rootfs &dash;&dash;ondisk sda &dash;&dash;fstype=ext3 &dash;&dash;label platform
2250 2240
2251 part swap --ondisk sda --size 44 --label swap1 --fstype=swap 2241 part swap &dash;&dash;ondisk sda &dash;&dash;size 44 &dash;&dash;label swap1 &dash;&dash;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 &dash;&dash;timeout=10 &dash;&dash;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