diff options
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 719 |
1 files changed, 719 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index e2df99e491..1d2d74927c 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml | |||
@@ -1917,6 +1917,725 @@ | |||
1917 | </section> | 1917 | </section> |
1918 | </section> | 1918 | </section> |
1919 | 1919 | ||
1920 | <section id='creating-partitioned-images'> | ||
1921 | <title>Creating Partitioned Images</title> | ||
1922 | |||
1923 | <para> | ||
1924 | Creating an image for a particular hardware target using the | ||
1925 | OpenEmbedded build system does not necessarily mean you can boot | ||
1926 | that image as is on your device. | ||
1927 | Physical devices accept and boot images in various ways depending | ||
1928 | on the specifics of the device. | ||
1929 | Usually information about the hardware can tell you what image | ||
1930 | format the device requires. | ||
1931 | Should your device require multiple partitions on an SD card, flash, | ||
1932 | or an HDD, you can use the OpenEmbedded Image Creator | ||
1933 | (<filename>wic</filename>) to create the properly partitioned image. | ||
1934 | </para> | ||
1935 | |||
1936 | <para> | ||
1937 | Using the <filename>wic</filename> command, you can also describe | ||
1938 | your desired final image and have BitBake assemble the image. | ||
1939 | The 'wic' command generates partitioned images from existing | ||
1940 | OpenEmbedded build artifacts. | ||
1941 | Image generation is driven by partitioning commands contained | ||
1942 | in an Openembedded kickstart file (<filename>.wks</filename>) | ||
1943 | specified either directly on the command-line or as one of a | ||
1944 | selection of canned <filename>.wks</filename> files | ||
1945 | (see 'wic list images'). | ||
1946 | When applied to a given set of build artifacts, the result is an | ||
1947 | image or set of images that can be directly written onto media and | ||
1948 | used on a particular system. | ||
1949 | </para> | ||
1950 | |||
1951 | <para> | ||
1952 | 'wic' is based loosely on the 'mic' (Meego Image Creator) framework, | ||
1953 | but heavily modified to make direct use of OpenEmbedded build | ||
1954 | artifacts instead of package installation and configuration, things | ||
1955 | already incorporated in the OE artifacts. | ||
1956 | </para> | ||
1957 | |||
1958 | <note> | ||
1959 | The name 'wic' comes from 'oeic', which stands for 'OpenEmbedded | ||
1960 | Image Creator'. The 'oe' diphthong in 'oeic' has been promoted to the | ||
1961 | letter 'w', because 'oeic' is impossible to remember or pronounce. | ||
1962 | </note> | ||
1963 | |||
1964 | <note> | ||
1965 | This is a completely independent standalone utility that | ||
1966 | initially provides easier-to-use and more flexible replacements for a | ||
1967 | couple bits of existing functionality in oe-core: directdisk.bbclass | ||
1968 | and mkefidisk.sh. The replaced scripts are implemented by a | ||
1969 | general-purpose partitioning 'language' based on Red Hat kickstart | ||
1970 | syntax (with the underlying code borrowed from Tizen mic, which in | ||
1971 | turn was borrowed from Meego mic, in turn borrowed from Fedora livecd, | ||
1972 | etc.). | ||
1973 | </note> | ||
1974 | |||
1975 | <para> | ||
1976 | This section covers the mechanics of invoking and providing help for | ||
1977 | the command and sub-commands; it contains hooks for future commits to | ||
1978 | connect with the actual functionality, once implemented. | ||
1979 | </para> | ||
1980 | |||
1981 | <para> | ||
1982 | Help is integrated into the 'wic' command itself - you can also see | ||
1983 | that for details and reminders on usage (simply invoke 'wic' without | ||
1984 | any arguments to get started). | ||
1985 | </para> | ||
1986 | |||
1987 | <note> | ||
1988 | Just because 'wic' can generate an image doesn't mean that it | ||
1989 | will boot on a given machine. 'wic' tries to spot the most obvious | ||
1990 | usages that are likely to cause problems but, as a relatively | ||
1991 | low-level tool, it can't in general figure out whether a generated | ||
1992 | image is appropriate for a given piece of hardware - it's really up to | ||
1993 | you to provide intelligent inputs to the image creation process. If | ||
1994 | you suspect that your image isn't working as expected due to some bug | ||
1995 | or missing feature of the tool, please file a bug report describing | ||
1996 | the details. | ||
1997 | </note> | ||
1998 | |||
1999 | <section id='requirements'> | ||
2000 | <title>Requirements</title> | ||
2001 | |||
2002 | <para> | ||
2003 | wic has only been tested on and is only designed to work on the | ||
2004 | distros officially supported by Yocto. | ||
2005 | </para> | ||
2006 | |||
2007 | <para> | ||
2008 | Aside from the standard system utilities, such as 'cp', wic expects the | ||
2009 | following utilities to be installed on the host machine: | ||
2010 | <itemizedlist> | ||
2011 | <listitem><para><emphasis>parted:</emphasis> | ||
2012 | GNU Parted - a partition manipulation program | ||
2013 | </para></listitem> | ||
2014 | </itemizedlist> | ||
2015 | </para> | ||
2016 | </section> | ||
2017 | |||
2018 | <section id='raw-vs-cooked-mode'> | ||
2019 | <title>Raw Vs. Cooked Mode</title> | ||
2020 | |||
2021 | <para> | ||
2022 | 'wic' can be used in 'raw' mode, where artifacts are explicitly | ||
2023 | specified via command-line arguments (see the command documentation | ||
2024 | and examples below), or it can be used in a more easily usable | ||
2025 | 'cooked' mode which uses the current MACHINE setting and a specified | ||
2026 | image name to automatically locate the artifacts used to create the | ||
2027 | image. | ||
2028 | </para> | ||
2029 | |||
2030 | <note> | ||
2031 | The prerequisite for generating any image is to have the build | ||
2032 | artifacts already available. For example, to create a 'wic' image | ||
2033 | using the build artifacts from a core-image-minimal build, you must | ||
2034 | already have created a core-image-minimal OpenembeddedCore image. It | ||
2035 | may seem redundant to generate an OpenEmbedded image in order to | ||
2036 | create a 'wic' image, and in fact to some degree it is. At the | ||
2037 | moment, however, that's typically how build artifacts are generated, | ||
2038 | and future versions will likely be more integrated into the build | ||
2039 | system and will be able to skip that step. There is a benefit | ||
2040 | however, in that 'wic' images are created more quickly and without the | ||
2041 | need for root access. | ||
2042 | </note> | ||
2043 | </section> | ||
2044 | |||
2045 | <section id='command-summary'> | ||
2046 | <title>Command Summary</title> | ||
2047 | |||
2048 | <para> | ||
2049 | The general form of the 'wic' command in raw mode is: | ||
2050 | <literallayout class='monospaced'> | ||
2051 | $ wic create myimage.wks -r <rootfs-dir> -b <bootimg-dir> | ||
2052 | -k <kernel-dir> -n <native-sysroot> | ||
2053 | </literallayout> | ||
2054 | <note> | ||
2055 | The 'wic' does NOT require root privileges, and in fact should | ||
2056 | not be run as root. | ||
2057 | </note> | ||
2058 | </para> | ||
2059 | |||
2060 | <para> | ||
2061 | The .wks file specified in the command is an OE kickstart file (see | ||
2062 | the OE kickstart syntax section below) and can of course be specified | ||
2063 | directly on the command-line, but the user can also choose from a set | ||
2064 | of 'canned' .wks files available via the 'wic list images' command | ||
2065 | (example below). | ||
2066 | </para> | ||
2067 | |||
2068 | <para> | ||
2069 | The -r, -b, -k, and -n options refer to the corresponding OpenEmbedded | ||
2070 | build artifacts. Using OpenEmbedded terminology: | ||
2071 | <itemizedlist> | ||
2072 | <listitem><para><emphasis>-r option:</emphasis> | ||
2073 | Used to specify the path to the /rootfs dir to | ||
2074 | use as the .wks rootfs source.</para></listitem> | ||
2075 | <listitem><para><emphasis>-b option:</emphasis> | ||
2076 | Used to specify the path to the dir containing | ||
2077 | the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the | ||
2078 | .wks bootimg source.</para></listitem> | ||
2079 | <listitem><para><emphasis>-k option:</emphasis> | ||
2080 | Used to specify the path to the dir containing | ||
2081 | the kernel to use in the .wks bootimg. | ||
2082 | </para></listitem> | ||
2083 | <listitem><para><emphasis>-n option:</emphasis> | ||
2084 | Used to specify the path to the native sysroot | ||
2085 | containing the tools to use to build the image. | ||
2086 | </para></listitem> | ||
2087 | </itemizedlist> | ||
2088 | </para> | ||
2089 | |||
2090 | <para> | ||
2091 | For more technical detail on the origin and meanings of those | ||
2092 | artifacts, see the Yocto documentation corresponding to those topics | ||
2093 | elsewhere. In most cases, it's not important to know that, because | ||
2094 | 'cooked' mode provides a convenient shortcut allowing the user to | ||
2095 | forget about the raw details and simply specify artifacts via a | ||
2096 | high-level OpenEmbedded image name. | ||
2097 | </para> | ||
2098 | |||
2099 | <para> | ||
2100 | If instead of specifying a user-defined .wks file, you prefer to use | ||
2101 | one of the 'canned' wic images, you can simply specify a canned image | ||
2102 | name (without the .wks extension) in place of a .wks file. Use 'wic | ||
2103 | list images' to get a list of 'canned' images: | ||
2104 | <literallayout class='monospaced'> | ||
2105 | $ wic list images | ||
2106 | mkefidisk Create an EFI disk image | ||
2107 | directdisk Create a 'pcbios' direct disk image | ||
2108 | </literallayout> | ||
2109 | To use one of the canned images, simply specify it in the raw command. | ||
2110 | For example: | ||
2111 | <literallayout class='monospaced'> | ||
2112 | $ wic create directdisk -r <rootfs-dir> -b <bootimg-dir> | ||
2113 | -k <kernel-dir> -n <native-sysroot> | ||
2114 | </literallayout> | ||
2115 | Finally, the general form of the 'wic' command in cooked mode is: | ||
2116 | <literallayout class='monospaced'> | ||
2117 | $ wic create directdisk -e <image-name> | ||
2118 | </literallayout> | ||
2119 | This form is the simplest and most user-friendly, as it allows you to | ||
2120 | skip the need for specifying all the parameters individually. | ||
2121 | </para> | ||
2122 | |||
2123 | <para> | ||
2124 | <filename><image-name></filename> refers to the Openembedded image name that you've already | ||
2125 | build the artifacts for, for example, 'core-image-minimal'. | ||
2126 | <note> | ||
2127 | In order to use cooked mode, you must have the machine that you | ||
2128 | built the artifacts with selected in local.conf. | ||
2129 | </note> | ||
2130 | </para> | ||
2131 | </section> | ||
2132 | |||
2133 | <section id='wic-usage-examples'> | ||
2134 | <title>'wic' Usage Examples</title> | ||
2135 | |||
2136 | <para> | ||
2137 | As mentioned, the main prerequisite for generating any image is to | ||
2138 | have the build artifacts already available. The below examples assume | ||
2139 | the user has already built a 'core-image-minimal' for a specific | ||
2140 | machine (future versions won't require this redundant step, but for | ||
2141 | now that's typically how build artifacts get generated). | ||
2142 | </para> | ||
2143 | |||
2144 | <para> | ||
2145 | The other prerequisite is to source the build environment: | ||
2146 | <literallayout class='monospaced'> | ||
2147 | $ source oe-init-build-env | ||
2148 | </literallayout> | ||
2149 | To start out with, we'll generate an image from one of the canned .wks | ||
2150 | files. The following generates a list of available images: | ||
2151 | <literallayout class='monospaced'> | ||
2152 | $ wic list images | ||
2153 | mkefidisk Create an EFI disk image | ||
2154 | directdisk Create a 'pcbios' direct disk image | ||
2155 | </literallayout> | ||
2156 | You can get more information about any of the available images by typing | ||
2157 | 'wic list xxx help', where 'xxx' is one of the image names. | ||
2158 | </para> | ||
2159 | |||
2160 | <para> | ||
2161 | For example: | ||
2162 | <literallayout class='monospaced'> | ||
2163 | $ wic list mkefidisk help | ||
2164 | </literallayout> | ||
2165 | Creates a partitioned EFI disk image that the user | ||
2166 | can directly dd to boot media. | ||
2167 | </para> | ||
2168 | |||
2169 | <para> | ||
2170 | At any time, you can get help on the 'wic' command or any subcommand | ||
2171 | (currently 'list' and 'create'). For instance, to get the description | ||
2172 | of 'wic create' command and its parameters: | ||
2173 | <literallayout class='monospaced'> | ||
2174 | $ wic create | ||
2175 | |||
2176 | Usage: | ||
2177 | |||
2178 | Create a new OpenEmbedded image | ||
2179 | |||
2180 | usage: wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>] | ||
2181 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY FILE>] | ||
2182 | [-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir] | ||
2183 | [-k, --kernel-dir] [-n, --native-sysroot] [-s, --skip-build-check] | ||
2184 | |||
2185 | This command creates an OpenEmbedded image based on the 'OE kickstart | ||
2186 | commands' found in the <wks file>. | ||
2187 | |||
2188 | The -o option can be used to place the image in a directory with a | ||
2189 | different name and location. | ||
2190 | |||
2191 | See 'wic help create' for more detailed instructions. | ||
2192 | |||
2193 | [...] | ||
2194 | </literallayout> | ||
2195 | </para> | ||
2196 | |||
2197 | <para> | ||
2198 | Continuing further, as mentioned in the command, you can get even more | ||
2199 | detailed information by adding 'help' to the above: | ||
2200 | <literallayout class='monospaced'> | ||
2201 | $ wic help create | ||
2202 | |||
2203 | NAME | ||
2204 | wic create - Create a new OpenEmbedded image | ||
2205 | |||
2206 | SYNOPSIS | ||
2207 | wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>] | ||
2208 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY FILE>] | ||
2209 | [-e | --image-name] [-r, --rootfs-dir] [-b, --bootimg-dir] | ||
2210 | [-k, --kernel-dir] [-n, --native-sysroot] [-s, | ||
2211 | --skip-build-check] | ||
2212 | |||
2213 | DESCRIPTION | ||
2214 | This command creates an OpenEmbedded image based on the 'OE | ||
2215 | kickstart commands' found in the <wks file>. | ||
2216 | |||
2217 | In order to do this, wic needs to know the locations of the | ||
2218 | various build artifacts required to build the image. | ||
2219 | |||
2220 | Users can explicitly specify the build artifact locations using | ||
2221 | the -r, -b, -k, and -n options. See below for details on where | ||
2222 | the corresponding artifacts are typically found in a normal | ||
2223 | OpenEmbedded build. | ||
2224 | |||
2225 | Alternatively, users can use the -e option to have 'mic' determine | ||
2226 | those locations for a given image. If the -e option is used, the | ||
2227 | user needs to have set the appropriate MACHINE variable in | ||
2228 | local.conf, and have sourced the build environment. | ||
2229 | |||
2230 | The -e option is used to specify the name of the image to use the | ||
2231 | artifacts from e.g. core-image-sato. | ||
2232 | |||
2233 | The -r option is used to specify the path to the /rootfs dir to | ||
2234 | use as the .wks rootfs source. | ||
2235 | |||
2236 | The -b option is used to specify the path to the dir containing | ||
2237 | the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the | ||
2238 | .wks bootimg source. | ||
2239 | |||
2240 | The -k option is used to specify the path to the dir containing | ||
2241 | the kernel to use in the .wks bootimg. | ||
2242 | |||
2243 | The -n option is used to specify the path to the native sysroot | ||
2244 | containing the tools to use to build the image. | ||
2245 | |||
2246 | The -s option is used to skip the build check. The build check is | ||
2247 | a simple sanity check used to determine whether the user has | ||
2248 | sourced the build environment so that the -e option can operate | ||
2249 | correctly. If the user has specified the build artifact locations | ||
2250 | explicitly, 'wic' assumes the user knows what he or she is doing | ||
2251 | and skips the build check. | ||
2252 | |||
2253 | When 'wic -e' is used, the locations for the build artifacts | ||
2254 | values are determined by 'wic -e' from the output of the 'bitbake | ||
2255 | -e' command given an image name e.g. 'core-image-minimal' and a | ||
2256 | given machine set in local.conf. In that case, the image is | ||
2257 | created as if the following 'bitbake -e' variables were used: | ||
2258 | |||
2259 | -r: IMAGE_ROOTFS | ||
2260 | -k: STAGING_KERNEL_DIR | ||
2261 | -n: STAGING_DIR_NATIVE | ||
2262 | -b: HDDDIR and STAGING_DATA_DIR (handlers decide which to use) | ||
2263 | |||
2264 | If 'wic -e' is not used, the user needs to select the appropriate | ||
2265 | value for -b (as well as -r, -k, and -n). | ||
2266 | |||
2267 | The -o option can be used to place the image in a directory with a | ||
2268 | different name and location. | ||
2269 | |||
2270 | As an alternative to the wks file, the image-specific properties | ||
2271 | that define the values that will be used to generate a particular | ||
2272 | image can be specified on the command-line using the -i option and | ||
2273 | supplying a JSON object consisting of the set of name:value pairs | ||
2274 | needed by image creation. | ||
2275 | |||
2276 | The set of properties available for a given image type can be | ||
2277 | listed using the 'wic list' command. | ||
2278 | </literallayout> | ||
2279 | So, the easiest way to create an image is to use the -e option with a | ||
2280 | canned .wks file. To use the -e option, you need to specify the image | ||
2281 | used to generate the artifacts and you actually need to have the | ||
2282 | MACHINE used to build them specified in your local.conf (these | ||
2283 | requirements aren't necessary if you aren't using the -e options. | ||
2284 | </para> | ||
2285 | |||
2286 | <para> | ||
2287 | Below, we generate a mkefidisk image, pointing the process at the | ||
2288 | core-image-minimal artifacts for the minnow, selected as our current | ||
2289 | MACHINE in local.conf. | ||
2290 | </para> | ||
2291 | |||
2292 | <para> | ||
2293 | First, once we've set the build up, we run a core-image-minimal minnow | ||
2294 | build: | ||
2295 | <literallayout class='monospaced'> | ||
2296 | $ bitbake core-image-minimal | ||
2297 | </literallayout> | ||
2298 | Once the build is finished, we can then use wic to create an EFI image | ||
2299 | for the minnow to boot. In this case, we'll use the '-e' option to | ||
2300 | have wic discover the appropriate build artifacts and generate the | ||
2301 | image: | ||
2302 | <literallayout class='monospaced'> | ||
2303 | $ wic create mkefidisk -e core-image-minimal | ||
2304 | Checking basic build environment... | ||
2305 | Done. | ||
2306 | |||
2307 | Creating image(s)... | ||
2308 | |||
2309 | Info: The new image(s) can be found here: | ||
2310 | /var/tmp/wic/build/mkefidisk-201310230946-sda.direct | ||
2311 | |||
2312 | The following build artifacts were used to create the image(s): | ||
2313 | ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs | ||
2314 | BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg | ||
2315 | KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel | ||
2316 | NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux | ||
2317 | |||
2318 | |||
2319 | The image(s) were created using OE kickstart file: | ||
2320 | /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks | ||
2321 | </literallayout> | ||
2322 | The output specifies exactly which image was created and where it was | ||
2323 | created. It also names the artifacts that were used and the exact | ||
2324 | .wks script that was used to generate the image. You should always | ||
2325 | verify the details provided in the output to make sure that the image | ||
2326 | was indeed created exactly as expected. | ||
2327 | </para> | ||
2328 | |||
2329 | <para> | ||
2330 | Using the path specified in the output for the image name and | ||
2331 | location, you can now directly dd the image to a USB stick or whatever | ||
2332 | media you built the image for, and boot the resulting media: | ||
2333 | <literallayout class='monospaced'> | ||
2334 | $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb | ||
2335 | [sudo] password for trz: | ||
2336 | 182274+0 records in | ||
2337 | 182274+0 records out | ||
2338 | 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s | ||
2339 | [trz@empanada ~]$ sudo eject /dev/sdb | ||
2340 | </literallayout> | ||
2341 | The next example uses a modified 'directdisk' script as an example. | ||
2342 | </para> | ||
2343 | |||
2344 | <para> | ||
2345 | Because wic image creation is driven by .wks files, it's easy to | ||
2346 | change the parameters that drive image creation: simply modify the | ||
2347 | .wks file. | ||
2348 | </para> | ||
2349 | |||
2350 | <para> | ||
2351 | As illustrated previously, 'wic list images' provides a list of | ||
2352 | available images. The images displayed are simply the list of .wks | ||
2353 | files in the scripts/lib/image/canned-wks/ directory, minus the .wks | ||
2354 | extension. | ||
2355 | </para> | ||
2356 | |||
2357 | <para> | ||
2358 | To add a new image to that list, simply add a new .wks file. | ||
2359 | </para> | ||
2360 | |||
2361 | <para> | ||
2362 | For this example, we already have a .wks file that already does pretty | ||
2363 | much what we want, but for our particular hardware, we know we'll be | ||
2364 | booting from sdb instead of sda, which is what the directdisk script uses. | ||
2365 | </para> | ||
2366 | |||
2367 | <para> | ||
2368 | What we can do is simply create a copy of the directdisk.wks file in | ||
2369 | the scripts/lib/image/canned-wks/ directory and change the lines that | ||
2370 | specify the target disk to boot from. | ||
2371 | </para> | ||
2372 | |||
2373 | <para> | ||
2374 | First, we copy the directdisk.wks file to directdisksdb.wks: | ||
2375 | <literallayout class='monospaced'> | ||
2376 | $ 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 | ||
2377 | </literallayout> | ||
2378 | Then we modify the directdisksdb.wks file and change all instances of | ||
2379 | '--ondisk sda' to '--ondisk sdb'. The following two lines are the | ||
2380 | lines we end up changing (leaving the rest alone): | ||
2381 | <literallayout class='monospaced'> | ||
2382 | part /boot --source bootimg --ondisk sdb --fstype=msdos --label boot --active --align 1024 | ||
2383 | part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 | ||
2384 | </literallayout> | ||
2385 | Once we've made that change, we generate a directdisksdb image, | ||
2386 | pointing the process at the core-image-minimal artifacts for the nuc | ||
2387 | (Next Unit of Computing), selected as our current MACHINE in | ||
2388 | local.conf. | ||
2389 | </para> | ||
2390 | |||
2391 | <para> | ||
2392 | Once we've set the build up, we run a core-image-minimal nuc build: | ||
2393 | <literallayout class='monospaced'> | ||
2394 | $ bitbake core-image-minimal | ||
2395 | </literallayout> | ||
2396 | Once the build is finished, we can then use nuc to create our | ||
2397 | directdisk image for the nuc to boot. In this case, we'll use the | ||
2398 | '-e' option to have wic discover the appropriate build artifacts and | ||
2399 | generate the image: | ||
2400 | <literallayout class='monospaced'> | ||
2401 | $ wic create directdisksdb -e core-image-minimal | ||
2402 | Checking basic build environment... | ||
2403 | Done. | ||
2404 | |||
2405 | Creating image(s)... | ||
2406 | |||
2407 | Info: The new image(s) can be found here: | ||
2408 | /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct | ||
2409 | |||
2410 | The following build artifacts were used to create the image(s): | ||
2411 | ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs | ||
2412 | BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share | ||
2413 | KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel | ||
2414 | NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux | ||
2415 | |||
2416 | |||
2417 | The image(s) were created using OE kickstart file: | ||
2418 | /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks | ||
2419 | </literallayout> | ||
2420 | Using the path specified in the output for the image name and | ||
2421 | location, you can now directly dd the image to a USB stick or whatever | ||
2422 | media you built the image for, and boot the resulting media: | ||
2423 | <literallayout class='monospaced'> | ||
2424 | $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb | ||
2425 | 86018+0 records in | ||
2426 | 86018+0 records out | ||
2427 | 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s | ||
2428 | [trz@empanada tmp]$ sudo eject /dev/sdb | ||
2429 | </literallayout> | ||
2430 | Of course, you can just use the directdisk image directly if you don't | ||
2431 | have any special needs. | ||
2432 | </para> | ||
2433 | |||
2434 | <para> | ||
2435 | Here'we're creating a wic image based on core-image-minimal and | ||
2436 | crownbay-noemgd, which works right out of the box. | ||
2437 | <literallayout class='monospaced'> | ||
2438 | $ wic create directdisk -e core-image-minimal | ||
2439 | |||
2440 | Checking basic build environment... | ||
2441 | Done. | ||
2442 | |||
2443 | Creating image(s)... | ||
2444 | |||
2445 | Info: The new image(s) can be found here: | ||
2446 | /var/tmp/wic/build/directdisk-201309252350-sda.direct | ||
2447 | |||
2448 | The following build artifacts were used to create the image(s): | ||
2449 | |||
2450 | ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs | ||
2451 | BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share | ||
2452 | KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel | ||
2453 | NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel | ||
2454 | |||
2455 | The image(s) were created using OE kickstart file: | ||
2456 | /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks | ||
2457 | </literallayout> | ||
2458 | Finally, here's an example that doesn't take the easy way out and | ||
2459 | manually specifies each build artifact, along with a non-canned .wks | ||
2460 | file, and also uses the -o option to have wic create the output | ||
2461 | somewhere other than the default /var/tmp/wic: | ||
2462 | <literallayout class='monospaced'> | ||
2463 | $ 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 | ||
2464 | |||
2465 | Creating image(s)... | ||
2466 | |||
2467 | Info: The new image(s) can be found here: | ||
2468 | /home/trz/testwic/build/test-201309260032-sda.direct | ||
2469 | |||
2470 | The following build artifacts were used to create the image(s): | ||
2471 | |||
2472 | ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs | ||
2473 | BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share | ||
2474 | KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel | ||
2475 | NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel | ||
2476 | |||
2477 | The image(s) were created using OE kickstart file: | ||
2478 | /home/trz/test.wks | ||
2479 | </literallayout> | ||
2480 | In this case, we didn't need to have the proper machine selected in | ||
2481 | local.conf - we manually specified each artifact and therefore wic | ||
2482 | doesn't need further information from the build system. | ||
2483 | </para> | ||
2484 | |||
2485 | <para> | ||
2486 | Finally, here's an example of the actual partition language commands | ||
2487 | used to generate the mkefidisk image i.e. these are the contents of the | ||
2488 | mkefidisk.wks OE kickstart file: | ||
2489 | <literallayout class='monospaced'> | ||
2490 | # short-description: Create an EFI disk image | ||
2491 | # long-description: Creates a partitioned EFI disk image that the user | ||
2492 | # can directly dd to boot media. | ||
2493 | |||
2494 | part /boot --source bootimg --ondisk sda --fstype=efi --label msdos --active --align 1024 | ||
2495 | |||
2496 | part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 | ||
2497 | |||
2498 | part swap --ondisk sda --size 44 --label swap1 --fstype=swap | ||
2499 | |||
2500 | bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda- intel.enable_msi=0" | ||
2501 | </literallayout> | ||
2502 | </para> | ||
2503 | </section> | ||
2504 | </section> | ||
2505 | |||
2506 | <section id='openembedded-kickstart-wks-reference'> | ||
2507 | <title>OpenEmbedded Kickstart (.wks) Reference</title> | ||
2508 | |||
2509 | <para> | ||
2510 | The current 'wic' implementation supports only the basic kickstart | ||
2511 | partitioning commands: 'partition' (or 'part' for short) and | ||
2512 | 'bootloader'. | ||
2513 | </para> | ||
2514 | |||
2515 | <para> | ||
2516 | They are listed below and mostly follow the syntax and meaning of the | ||
2517 | standard kickstart options for those commands. The documentation below | ||
2518 | is based on the Fedora kickstart documentation of the same commands, | ||
2519 | but modified to reflect wic capabilities. For reference: | ||
2520 | <literallayout class='monospaced'> | ||
2521 | http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition | ||
2522 | http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader | ||
2523 | </literallayout> | ||
2524 | </para> | ||
2525 | |||
2526 | <section id='command-part-or-partition'> | ||
2527 | <title>Command: part or partition</title> | ||
2528 | |||
2529 | <para> | ||
2530 | Creates a partition on the system. | ||
2531 | Use the following syntax: | ||
2532 | <literallayout class='monospaced'> | ||
2533 | part <mntpoint> | ||
2534 | </literallayout> | ||
2535 | The <mntpoint> is where the partition will be mounted and must be of | ||
2536 | one of the following forms: | ||
2537 | <itemizedlist> | ||
2538 | <listitem><para><filename>/<path></filename>: | ||
2539 | For example, <filename>/</filename>, | ||
2540 | <filename>/usr</filename>, and | ||
2541 | <filename>/home</filename></para></listitem> | ||
2542 | <listitem><para><filename>swap</filename>: | ||
2543 | The partition will be used as swap space. | ||
2544 | </para></listitem> | ||
2545 | </itemizedlist> | ||
2546 | </para> | ||
2547 | |||
2548 | <para> | ||
2549 | Following are the supported options: | ||
2550 | <literallayout class='monospaced'> | ||
2551 | --size | ||
2552 | The minimum partition size in megabytes. Specify an integer value | ||
2553 | here such as 500. Do not append the number with MB. Not needed if | ||
2554 | --source is used. | ||
2555 | |||
2556 | --source | ||
2557 | bootimg | ||
2558 | rootfs | ||
2559 | |||
2560 | The --source option is a wic-specific option that can currently | ||
2561 | have one of two values, 'bootimg' or 'rootfs'. | ||
2562 | |||
2563 | If '--source rootfs' is used, it tells the wic command to create a | ||
2564 | partition as large as needed to fill with the contents of /rootfs | ||
2565 | (specified by the -r 'wic' option) and to fill it with the | ||
2566 | contents of /rootfs. | ||
2567 | |||
2568 | If '--source bootimg' is used, it tells the wic command to create | ||
2569 | a partition as large as needed to fill with the contents of the | ||
2570 | boot partition (specified by the -b 'wic' option). Exactly what | ||
2571 | those contents are depend on the value of the --fstype option for | ||
2572 | that partition. If '--fstype=efi' is specified, the boot | ||
2573 | artifacts contained in HDDDIR are used, and if '--fstype=msdos' is | ||
2574 | specified, the boot artifacts found in STAGING_DATADIR are used. | ||
2575 | |||
2576 | --ondisk or --ondrive | ||
2577 | Forces the partition to be created on a particular disk. | ||
2578 | |||
2579 | --fstype | ||
2580 | Sets the file system type for the partition. Valid values are: | ||
2581 | msdos | ||
2582 | efi | ||
2583 | ext4 | ||
2584 | ext3 | ||
2585 | ext2 | ||
2586 | btrfs | ||
2587 | swap | ||
2588 | |||
2589 | --label label | ||
2590 | Specify the label to give to the filesystem to be made on the | ||
2591 | partition. If the given label is already in use by another | ||
2592 | filesystem, a new label will be created for this partition. | ||
2593 | |||
2594 | --active | ||
2595 | Mark the partition as active. | ||
2596 | |||
2597 | --align (in kB) | ||
2598 | The '--align' option is a mic-specific option that says to start a | ||
2599 | partition on an x kB boundary. | ||
2600 | </literallayout> | ||
2601 | </para> | ||
2602 | </section> | ||
2603 | |||
2604 | <section id='command-bootloader'> | ||
2605 | <title>Command: bootloader</title> | ||
2606 | |||
2607 | <para> | ||
2608 | This command specifies how the boot loader should be installed. | ||
2609 | </para> | ||
2610 | |||
2611 | <para> | ||
2612 | Following are the supported options: | ||
2613 | <literallayout class='monospaced'> | ||
2614 | --timeout | ||
2615 | Specify the number of seconds before the bootloader times out and | ||
2616 | boots the default option. | ||
2617 | |||
2618 | --append | ||
2619 | Specifies kernel parameters. These will be added to the syslinux | ||
2620 | APPEND or grub kernel command line. | ||
2621 | |||
2622 | The boot type is determined by the fstype of the /boot mountpoint. If | ||
2623 | the fstype is 'msdos' the boot type is 'pcbios', otherwise it's the | ||
2624 | fstype, which currently be: 'efi' (more to be added later). | ||
2625 | |||
2626 | If the boot type is 'efi', the image will use grub and has one | ||
2627 | menuentry: 'boot'. | ||
2628 | |||
2629 | If the boot type is 'pcbios', the image will use syslinux and has one | ||
2630 | menu label: 'boot'. | ||
2631 | |||
2632 | Future updates will implement more options - using anything not | ||
2633 | explicitly supported can result in unpredictable results. | ||
2634 | </literallayout> | ||
2635 | </para> | ||
2636 | </section> | ||
2637 | </section> | ||
2638 | |||
1920 | <section id='configuring-the-kernel'> | 2639 | <section id='configuring-the-kernel'> |
1921 | <title>Configuring the Kernel</title> | 2640 | <title>Configuring the Kernel</title> |
1922 | 2641 | ||