summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-12-21 08:49:03 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-02 13:16:12 +0000
commit71460e5fc274467d5d59f4f45ccb298590f699e8 (patch)
treeed105cefba3c8791b506cdf062d6662e4cc2a02f /documentation
parent3ad993da1038c327c60da781315b748380228a7c (diff)
downloadpoky-71460e5fc274467d5d59f4f45ccb298590f699e8.tar.gz
dev-manual: Integrated Hello World section into new writing recipe section
This change merged in the Hello World section as a summarizing example section to the new "Writing a New Recipe" section. (From yocto-docs rev: 79c858e1590e5ab4c56b19dc51b03e0e570b6209) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml465
1 files changed, 240 insertions, 225 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 717a453061..053df0f838 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1146,6 +1146,12 @@
1146 requires a recipe to define the component. 1146 requires a recipe to define the component.
1147 This section describes how to create, write, and test a new 1147 This section describes how to create, write, and test a new
1148 recipe. 1148 recipe.
1149 <note>
1150 For information on variables that are useful for recipes and
1151 for information about recipe naming issues, see the
1152 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
1153 section of the Yocto Project Reference Manual.
1154 </note>
1149 </para> 1155 </para>
1150 1156
1151 <section id='new-recipe-overview'> 1157 <section id='new-recipe-overview'>
@@ -1163,6 +1169,16 @@
1163 <title>Locate a Base Recipe</title> 1169 <title>Locate a Base Recipe</title>
1164 1170
1165 <para> 1171 <para>
1172 Before writing a recipe from scratch, it is often useful to
1173 check whether someone else has written one already.
1174 OpenEmbedded is a good place to look as it has a wider scope
1175 and range of packages.
1176 Because the Yocto Project aims to be compatible with
1177 OpenEmbedded, most recipes you find there should work for
1178 you.
1179 </para>
1180
1181 <para>
1166 Working from an existing recipe or a skeleton recipe is the 1182 Working from an existing recipe or a skeleton recipe is the
1167 best way to get started. 1183 best way to get started.
1168 Here are some points on both methods: 1184 Here are some points on both methods:
@@ -1204,6 +1220,42 @@
1204 </para></listitem> 1220 </para></listitem>
1205 </itemizedlist> 1221 </itemizedlist>
1206 </para> 1222 </para>
1223
1224 <note>
1225 <para>When writing shell functions, you need to be aware of BitBake's
1226 curly brace parsing.
1227 If a recipe uses a closing curly brace within the function and
1228 the character has no leading spaces, BitBake produces a parsing
1229 error.
1230 If you use a pair of curly brace in a shell function, the
1231 closing curly brace must not be located at the start of the line
1232 without leading spaces.</para>
1233 <para>Here is an example that causes BitBake to produce a parsing
1234 error:
1235 <literallayout class='monospaced'>
1236 fakeroot create_shar() {
1237 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
1238 usage()
1239 {
1240 echo "test"
1241 ###### The following "}" at the start of the line causes a parsing error ######
1242 }
1243 EOF
1244 }
1245 </literallayout>
1246 Writing the recipe this way avoids the error:
1247 <literallayout class='monospaced'>
1248 fakeroot create_shar() {
1249 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
1250 usage()
1251 {
1252 echo "test"
1253 ######The following "}" with a leading space at the start of the line avoids the error ######
1254 }
1255 EOF
1256 }
1257 </literallayout></para>
1258 </note>
1207 </section> 1259 </section>
1208 1260
1209 <section id='new-recipe-naming-the-recipe'> 1261 <section id='new-recipe-naming-the-recipe'>
@@ -2036,89 +2088,32 @@ do_unpack unpacks the source, and S must be set
2036 section. 2088 section.
2037 </para> 2089 </para>
2038 </section> 2090 </section>
2039 </section>
2040 2091
2041 <section id='usingpoky-extend-addpkg'> 2092 <section id='new-recipe-testing-hello-world-example'>
2042 <title>Writing a Recipe to Add a Package to Your Image</title> 2093 <title>Hello World Example</title>
2043
2044 <para>
2045 Recipes let you define packages you can add to your image.
2046 Writing a recipe means creating a <filename>.bb</filename> file that sets some
2047 variables.
2048 For information on variables that are useful for recipes and for information about recipe naming
2049 issues, see the
2050 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
2051 section of the Yocto Project Reference Manual.
2052 </para>
2053
2054 <para>
2055 Before writing a recipe from scratch, it is often useful to check
2056 whether someone else has written one already.
2057 OpenEmbedded is a good place to look as it has a wider scope and range of packages.
2058 Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
2059 you find there should work for you.
2060 </para>
2061 2094
2062 <para> 2095 <para>
2063 For new packages, the simplest way to add a recipe is to base it on a similar 2096 To help summarize how to write a recipe, this section provides
2064 pre-existing recipe. 2097 an example recipe that builds a single "Hello World!" package.
2065 The sections that follow provide some examples that show how to add standard 2098 </para>
2066 types of packages.
2067 </para>
2068
2069 <note>
2070 <para>When writing shell functions, you need to be aware of BitBake's
2071 curly brace parsing.
2072 If a recipe uses a closing curly brace within the function and
2073 the character has no leading spaces, BitBake produces a parsing
2074 error.
2075 If you use a pair of curly brace in a shell function, the
2076 closing curly brace must not be located at the start of the line
2077 without leading spaces.</para>
2078 <para>Here is an example that causes BitBake to produce a parsing
2079 error:
2080 <literallayout class='monospaced'>
2081 fakeroot create_shar() {
2082 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
2083 usage()
2084 {
2085 echo "test"
2086 ###### The following "}" at the start of the line causes a parsing error ######
2087 }
2088 EOF
2089 }
2090 </literallayout>
2091 Writing the recipe this way avoids the error:
2092 <literallayout class='monospaced'>
2093 fakeroot create_shar() {
2094 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
2095 usage()
2096 {
2097 echo "test"
2098 ######The following "}" with a leading space at the start of the line avoids the error ######
2099 }
2100 EOF
2101 }
2102 </literallayout></para>
2103 </note>
2104 2099
2105 <section id='usingpoky-extend-addpkg-singlec'> 2100 <section id='usingpoky-extend-addpkg-singlec'>
2106 <title>Single .c File Package (Hello World!)</title> 2101 <title>Single .c File Package (Hello World!)</title>
2107 2102
2108 <para> 2103 <para>
2109 Building an application from a single file that is stored locally (e.g. under 2104 Building an application from a single file that is stored locally (e.g. under
2110 <filename>files/</filename>) requires a recipe that has the file listed in 2105 <filename>files/</filename>) requires a recipe that has the file listed in
2111 the 2106 the
2112 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> 2107 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2113 variable. 2108 variable.
2114 Additionally, you need to manually write the <filename>do_compile</filename> and 2109 Additionally, you need to manually write the <filename>do_compile</filename> and
2115 <filename>do_install</filename> tasks. 2110 <filename>do_install</filename> tasks.
2116 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> 2111 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2117 variable defines the 2112 variable defines the
2118 directory containing the source code, which is set to 2113 directory containing the source code, which is set to
2119 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'> 2114 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'>
2120 WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build. 2115 WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build.
2121 <literallayout class='monospaced'> 2116 <literallayout class='monospaced'>
2122 DESCRIPTION = "Simple helloworld application" 2117 DESCRIPTION = "Simple helloworld application"
2123 SECTION = "examples" 2118 SECTION = "examples"
2124 LICENSE = "MIT" 2119 LICENSE = "MIT"
@@ -2137,32 +2132,32 @@ do_unpack unpacks the source, and S must be set
2137 install -d ${D}${bindir} 2132 install -d ${D}${bindir}
2138 install -m 0755 helloworld ${D}${bindir} 2133 install -m 0755 helloworld ${D}${bindir}
2139 } 2134 }
2140 </literallayout> 2135 </literallayout>
2141 </para> 2136 </para>
2142 2137
2143 <para> 2138 <para>
2144 By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>, 2139 By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>,
2145 and <filename>helloworld-dev</filename> packages are built. 2140 and <filename>helloworld-dev</filename> packages are built.
2146 For information on how to customize the packaging process, see the 2141 For information on how to customize the packaging process, see the
2147 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application 2142 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application
2148 into Multiple Packages</link>" section. 2143 into Multiple Packages</link>" section.
2149 </para> 2144 </para>
2150 </section> 2145 </section>
2151 2146
2152 <section id='usingpoky-extend-addpkg-autotools'> 2147 <section id='usingpoky-extend-addpkg-autotools'>
2153 <title>Autotooled Package</title> 2148 <title>Autotooled Package</title>
2154 <para> 2149 <para>
2155 Applications that use Autotools such as <filename>autoconf</filename> and 2150 Applications that use Autotools such as <filename>autoconf</filename> and
2156 <filename>automake</filename> require a recipe that has a source archive listed in 2151 <filename>automake</filename> require a recipe that has a source archive listed in
2157 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and 2152 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2158 also inherits Autotools, which instructs BitBake to use the 2153 also inherits Autotools, which instructs BitBake to use the
2159 <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps 2154 <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps
2160 needed to build an Autotool-based application. 2155 needed to build an Autotool-based application.
2161 The result of the build is automatically packaged. 2156 The result of the build is automatically packaged.
2162 And, if the application uses NLS for localization, packages with local information are 2157 And, if the application uses NLS for localization, packages with local information are
2163 generated (one package per language). 2158 generated (one package per language).
2164 Following is one example: (<filename>hello_2.3.bb</filename>) 2159 Following is one example: (<filename>hello_2.3.bb</filename>)
2165 <literallayout class='monospaced'> 2160 <literallayout class='monospaced'>
2166 DESCRIPTION = "GNU Helloworld application" 2161 DESCRIPTION = "GNU Helloworld application"
2167 SECTION = "examples" 2162 SECTION = "examples"
2168 LICENSE = "GPLv2+" 2163 LICENSE = "GPLv2+"
@@ -2172,49 +2167,49 @@ do_unpack unpacks the source, and S must be set
2172 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" 2167 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2173 2168
2174 inherit autotools gettext 2169 inherit autotools gettext
2175 </literallayout> 2170 </literallayout>
2176 </para> 2171 </para>
2177 2172
2178 <para> 2173 <para>
2179 The variable 2174 The variable
2180 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename> 2175 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2181 is used to track source license changes as described in the 2176 is used to track source license changes as described in the
2182 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section. 2177 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2183 You can quickly create Autotool-based recipes in a manner similar to the previous example. 2178 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2184 </para> 2179 </para>
2185 </section> 2180 </section>
2186 2181
2187 <section id='usingpoky-extend-addpkg-makefile'> 2182 <section id='usingpoky-extend-addpkg-makefile'>
2188 <title>Makefile-Based Package</title> 2183 <title>Makefile-Based Package</title>
2189 2184
2190 <para> 2185 <para>
2191 Applications that use GNU <filename>make</filename> also require a recipe that has 2186 Applications that use GNU <filename>make</filename> also require a recipe that has
2192 the source archive listed in 2187 the source archive listed in
2193 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>. 2188 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2194 You do not need to add a <filename>do_compile</filename> step since by default BitBake 2189 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2195 starts the <filename>make</filename> command to compile the application. 2190 starts the <filename>make</filename> command to compile the application.
2196 If you need additional <filename>make</filename> options, you should store them in the 2191 If you need additional <filename>make</filename> options, you should store them in the
2197 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename> 2192 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2198 variable. 2193 variable.
2199 BitBake passes these options into the <filename>make</filename> GNU invocation. 2194 BitBake passes these options into the <filename>make</filename> GNU invocation.
2200 Note that a <filename>do_install</filename> task is still required. 2195 Note that a <filename>do_install</filename> task is still required.
2201 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default. 2196 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2202 </para> 2197 </para>
2203 2198
2204 <para> 2199 <para>
2205 Some applications might require extra parameters to be passed to the compiler. 2200 Some applications might require extra parameters to be passed to the compiler.
2206 For example, the application might need an additional header path. 2201 For example, the application might need an additional header path.
2207 You can accomplish this by adding to the 2202 You can accomplish this by adding to the
2208 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable. 2203 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2209 The following example shows this: 2204 The following example shows this:
2210 <literallayout class='monospaced'> 2205 <literallayout class='monospaced'>
2211 CFLAGS_prepend = "-I ${S}/include " 2206 CFLAGS_prepend = "-I ${S}/include "
2212 </literallayout> 2207 </literallayout>
2213 </para> 2208 </para>
2214 2209
2215 <para> 2210 <para>
2216 In the following example, <filename>mtd-utils</filename> is a makefile-based package: 2211 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2217 <literallayout class='monospaced'> 2212 <literallayout class='monospaced'>
2218 DESCRIPTION = "Tools for managing memory technology devices." 2213 DESCRIPTION = "Tools for managing memory technology devices."
2219 SECTION = "base" 2214 SECTION = "base"
2220 DEPENDS = "zlib lzo e2fsprogs util-linux" 2215 DEPENDS = "zlib lzo e2fsprogs util-linux"
@@ -2245,46 +2240,46 @@ do_unpack unpacks the source, and S must be set
2245 PARALLEL_MAKE = "" 2240 PARALLEL_MAKE = ""
2246 2241
2247 BBCLASSEXTEND = "native" 2242 BBCLASSEXTEND = "native"
2248 </literallayout> 2243 </literallayout>
2249 </para> 2244 </para>
2250 2245
2251 <para> 2246 <para>
2252 If your sources are available as a tarball instead of a Git repository, you 2247 If your sources are available as a tarball instead of a Git repository, you
2253 will need to provide the URL to the tarball as well as an 2248 will need to provide the URL to the tarball as well as an
2254 <filename>md5</filename> or <filename>sha256</filename> sum of 2249 <filename>md5</filename> or <filename>sha256</filename> sum of
2255 the download. 2250 the download.
2256 Here is an example: 2251 Here is an example:
2257 <literallayout class='monospaced'> 2252 <literallayout class='monospaced'>
2258 SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2" 2253 SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2"
2259 SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b" 2254 SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
2260 </literallayout> 2255 </literallayout>
2261 You can generate the <filename>md5</filename> or <filename>sha256</filename> sums 2256 You can generate the <filename>md5</filename> or <filename>sha256</filename> sums
2262 by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands 2257 by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands
2263 with the target file as the only argument. 2258 with the target file as the only argument.
2264 Here is an example: 2259 Here is an example:
2265 <literallayout class='monospaced'> 2260 <literallayout class='monospaced'>
2266 $ md5sum mtd-utils-1.4.9.tar.bz2 2261 $ md5sum mtd-utils-1.4.9.tar.bz2
2267 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2 2262 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
2268 </literallayout> 2263 </literallayout>
2269 </para> 2264 </para>
2270 </section> 2265 </section>
2271 2266
2272 <section id='splitting-an-application-into-multiple-packages'> 2267 <section id='splitting-an-application-into-multiple-packages'>
2273 <title>Splitting an Application into Multiple Packages</title> 2268 <title>Splitting an Application into Multiple Packages</title>
2274 2269
2275 <para> 2270 <para>
2276 You can use the variables 2271 You can use the variables
2277 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and 2272 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2278 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename> 2273 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2279 to split an application into multiple packages. 2274 to split an application into multiple packages.
2280 </para> 2275 </para>
2281 2276
2282 <para> 2277 <para>
2283 Following is an example that uses the <filename>libXpm</filename> recipe. 2278 Following is an example that uses the <filename>libXpm</filename> recipe.
2284 By default, this recipe generates a single package that contains the library along 2279 By default, this recipe generates a single package that contains the library along
2285 with a few binaries. 2280 with a few binaries.
2286 You can modify the recipe to split the binaries into separate packages: 2281 You can modify the recipe to split the binaries into separate packages:
2287 <literallayout class='monospaced'> 2282 <literallayout class='monospaced'>
2288 require xorg-lib-common.inc 2283 require xorg-lib-common.inc
2289 2284
2290 DESCRIPTION = "X11 Pixmap library" 2285 DESCRIPTION = "X11 Pixmap library"
@@ -2299,61 +2294,61 @@ do_unpack unpacks the source, and S must be set
2299 PACKAGES =+ "sxpm cxpm" 2294 PACKAGES =+ "sxpm cxpm"
2300 FILES_cxpm = "${bindir}/cxpm" 2295 FILES_cxpm = "${bindir}/cxpm"
2301 FILES_sxpm = "${bindir}/sxpm" 2296 FILES_sxpm = "${bindir}/sxpm"
2302 </literallayout> 2297 </literallayout>
2303 </para> 2298 </para>
2304 2299
2305 <para> 2300 <para>
2306 In the previous example, we want to ship the <filename>sxpm</filename> 2301 In the previous example, we want to ship the <filename>sxpm</filename>
2307 and <filename>cxpm</filename> binaries in separate packages. 2302 and <filename>cxpm</filename> binaries in separate packages.
2308 Since <filename>bindir</filename> would be packaged into the main 2303 Since <filename>bindir</filename> would be packaged into the main
2309 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> 2304 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2310 package by default, we prepend the <filename>PACKAGES</filename> 2305 package by default, we prepend the <filename>PACKAGES</filename>
2311 variable so additional package names are added to the start of list. 2306 variable so additional package names are added to the start of list.
2312 This results in the extra <filename>FILES_*</filename> 2307 This results in the extra <filename>FILES_*</filename>
2313 variables then containing information that define which files and 2308 variables then containing information that define which files and
2314 directories go into which packages. 2309 directories go into which packages.
2315 Files included by earlier packages are skipped by latter packages. 2310 Files included by earlier packages are skipped by latter packages.
2316 Thus, the main <filename>PN</filename> package 2311 Thus, the main <filename>PN</filename> package
2317 does not include the above listed files. 2312 does not include the above listed files.
2318 </para> 2313 </para>
2319 </section> 2314 </section>
2320 2315
2321 <section id='usingpoky-extend-addpkg-postinstalls'> 2316 <section id='usingpoky-extend-addpkg-postinstalls'>
2322 <title>Post-Installation Scripts</title> 2317 <title>Post-Installation Scripts</title>
2323 2318
2324 <para> 2319 <para>
2325 To add a post-installation script to a package, add a 2320 To add a post-installation script to a package, add a
2326 <filename>pkg_postinst_PACKAGENAME()</filename> function to the 2321 <filename>pkg_postinst_PACKAGENAME()</filename> function to the
2327 <filename>.bb</filename> file and use 2322 <filename>.bb</filename> file and use
2328 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the 2323 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
2329 <filename>postinst</filename> script. 2324 <filename>postinst</filename> script.
2330 Normally, 2325 Normally,
2331 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> 2326 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2332 can be used, which automatically expands to <filename>PACKAGENAME</filename>. 2327 can be used, which automatically expands to <filename>PACKAGENAME</filename>.
2333 A post-installation function has the following structure: 2328 A post-installation function has the following structure:
2334 <literallayout class='monospaced'> 2329 <literallayout class='monospaced'>
2335 pkg_postinst_PACKAGENAME () { 2330 pkg_postinst_PACKAGENAME () {
2336 #!/bin/sh -e 2331 #!/bin/sh -e
2337 # Commands to carry out 2332 # Commands to carry out
2338 } 2333 }
2339 </literallayout> 2334 </literallayout>
2340 </para> 2335 </para>
2341 2336
2342 <para> 2337 <para>
2343 The script defined in the post-installation function is called when the 2338 The script defined in the post-installation function is called when the
2344 root filesystem is created. 2339 root filesystem is created.
2345 If the script succeeds, the package is marked as installed. 2340 If the script succeeds, the package is marked as installed.
2346 If the script fails, the package is marked as unpacked and the script is 2341 If the script fails, the package is marked as unpacked and the script is
2347 executed when the image boots again. 2342 executed when the image boots again.
2348 </para> 2343 </para>
2349 2344
2350 <para> 2345 <para>
2351 Sometimes it is necessary for the execution of a post-installation 2346 Sometimes it is necessary for the execution of a post-installation
2352 script to be delayed until the first boot. 2347 script to be delayed until the first boot.
2353 For example, the script might need to be executed on the device itself. 2348 For example, the script might need to be executed on the device itself.
2354 To delay script execution until boot time, use the following structure in the 2349 To delay script execution until boot time, use the following structure in the
2355 post-installation script: 2350 post-installation script:
2356 <literallayout class='monospaced'> 2351 <literallayout class='monospaced'>
2357 pkg_postinst_PACKAGENAME () { 2352 pkg_postinst_PACKAGENAME () {
2358 #!/bin/sh -e 2353 #!/bin/sh -e
2359 if [ x"$D" = "x" ]; then 2354 if [ x"$D" = "x" ]; then
@@ -2362,15 +2357,35 @@ do_unpack unpacks the source, and S must be set
2362 exit 1 2357 exit 1
2363 fi 2358 fi
2364 } 2359 }
2365 </literallayout> 2360 </literallayout>
2366 </para> 2361 </para>
2362
2363 <para>
2364 The previous example delays execution until the image boots again because the
2365 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
2366 variable points
2367 to the directory containing the image when the root filesystem is created at build time but
2368 is unset when executed on the first boot.
2369 </para>
2370 </section>
2371
2372
2373
2374
2375
2376 </section>
2377
2378 <section id='writer-notes'>
2379 <title>Writer Notes</title>
2367 2380
2368 <para> 2381 <para>
2369 The previous example delays execution until the image boots again because the 2382 <itemizedlist>
2370 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename> 2383 <listitem><para>
2371 variable points 2384 Need to edit the faq.xml chapter and find the single reference to
2372 to the directory containing the image when the root filesystem is created at build time but 2385 <filename>usingpoky-extend-addpkg</filename> and replace it
2373 is unset when executed on the first boot. 2386 with <filename>new-recipe-testing-hello-world-example</filename>.
2387 </para></listitem>
2388 </itemizedlist>
2374 </para> 2389 </para>
2375 </section> 2390 </section>
2376 </section> 2391 </section>