summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-01-09 11:03:26 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-21 21:58:00 +0000
commitf0dff1123b17392385ca333af2f50e441f6ef2c4 (patch)
treec8bf02e9666075486d3a357cc7ce132f641637a8
parentb0fd1c3ec5dd3641dd3d8f54ab00772e6ca5592e (diff)
downloadpoky-f0dff1123b17392385ca333af2f50e441f6ef2c4.tar.gz
dev-manual: Edits to "Examples" and "Post-Installation" sections.
Applied review comments to these sections, which are part of the "Writing a New Recipe" section. Moved the Post-installation section out of the examples area into its own, higher-level section as it was not really an example. Other edits were direct result of Paul Eggleton's review. (From yocto-docs rev: c147a8bedf79d0be42d7b338e10b7e42d7c0b080) 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.xml172
1 files changed, 87 insertions, 85 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index c8aec0702c..1f552d8d3b 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2142,6 +2142,87 @@
2142 </para> 2142 </para>
2143 </section> 2143 </section>
2144 2144
2145 <section id='usingpoky-extend-addpkg-postinstalls'>
2146 <title>Post-Installation Scripts</title>
2147
2148 <para>
2149 Post-installation scripts run immediately after installing
2150 a package on the target, or during image creation when a
2151 package is included in an image.
2152 To add a post-installation script to a package, add a
2153 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2154 the <filename>.bb</filename> file and use
2155 <filename>PACKAGENAME</filename> as the name of the package
2156 you want to attach to the <filename>postinst</filename>
2157 script.
2158 To apply the post-installation script to the main package
2159 for the recipe, which is usually what is required, specify
2160 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2161 in place of <filename>PACKAGENAME</filename>.
2162 </para>
2163
2164 <para>
2165 A post-installation function has the following structure:
2166 <literallayout class='monospaced'>
2167 pkg_postinst_PACKAGENAME () {
2168 #!/bin/sh -e
2169 # Commands to carry out
2170 }
2171 </literallayout>
2172 </para>
2173
2174 <para>
2175 The script defined in the post-installation function is
2176 called when the root filesystem is created.
2177 If the script succeeds, the package is marked as installed.
2178 If the script fails, the package is marked as unpacked and
2179 the script is executed when the image boots again.
2180 </para>
2181
2182 <para>
2183 Sometimes it is necessary for the execution of a
2184 post-installation script to be delayed until the first boot.
2185 For example, the script might need to be executed on the
2186 device itself.
2187 To delay script execution until boot time, use the following
2188 structure in the post-installation script:
2189 <literallayout class='monospaced'>
2190 pkg_postinst_PACKAGENAME () {
2191 #!/bin/sh -e
2192 if [ x"$D" = "x" ]; then
2193 # Actions to carry out on the device go here
2194 else
2195 exit 1
2196 fi
2197 }
2198 </literallayout>
2199 </para>
2200
2201 <para>
2202 The previous example delays execution until the image boots
2203 again because the
2204 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
2205 variable points to the directory containing the image when
2206 the root filesystem is created at build time but is unset
2207 when executed on the first boot.
2208 </para>
2209
2210 <note>
2211 Equivalent support for <filename>pre-install</filename>,
2212 <filename>pre-uninstall</filename>, and
2213 <filename>post-uninstall</filename> scripts exist
2214 by way of <filename>pkg_preinst</filename>,
2215 <filename>pkg_prerm</filename>, and
2216 <filename>pkg_postrm</filename>, respectively.
2217 These scrips work in exactly the same way as does
2218 <filename>pkg_postinst</filename> with the exception that they
2219 run at different times.
2220 Also, because of when they run, they are not applicable to
2221 being run at image creation time like
2222 <filename>pkg_postinst</filename>.
2223 </note>
2224 </section>
2225
2145 <section id='new-recipe-testing'> 2226 <section id='new-recipe-testing'>
2146 <title>Testing</title> 2227 <title>Testing</title>
2147 2228
@@ -2171,7 +2252,6 @@
2171 <listitem><para>Using an Autotooled package</para></listitem> 2252 <listitem><para>Using an Autotooled package</para></listitem>
2172 <listitem><para>Using a Makefile-based package</para></listitem> 2253 <listitem><para>Using a Makefile-based package</para></listitem>
2173 <listitem><para>Splitting an application into multiple packages</para></listitem> 2254 <listitem><para>Splitting an application into multiple packages</para></listitem>
2174 <listitem><para>Installing a post-initialization script</para></listitem>
2175 </itemizedlist> 2255 </itemizedlist>
2176 </para> 2256 </para>
2177 2257
@@ -2193,11 +2273,10 @@
2193 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> 2273 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2194 in this case - the directory BitBake uses for the build. 2274 in this case - the directory BitBake uses for the build.
2195 <literallayout class='monospaced'> 2275 <literallayout class='monospaced'>
2196 DESCRIPTION = "Simple helloworld application" 2276 SUMMARY = "Simple helloworld application"
2197 SECTION = "examples" 2277 SECTION = "examples"
2198 LICENSE = "MIT" 2278 LICENSE = "MIT"
2199 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" 2279 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2200 PR = "r0"
2201 2280
2202 SRC_URI = "file://helloworld.c" 2281 SRC_URI = "file://helloworld.c"
2203 2282
@@ -2240,11 +2319,10 @@
2240 generated (one package per language). 2319 generated (one package per language).
2241 Following is one example: (<filename>hello_2.3.bb</filename>) 2320 Following is one example: (<filename>hello_2.3.bb</filename>)
2242 <literallayout class='monospaced'> 2321 <literallayout class='monospaced'>
2243 DESCRIPTION = "GNU Helloworld application" 2322 SUMMARY = "GNU Helloworld application"
2244 SECTION = "examples" 2323 SECTION = "examples"
2245 LICENSE = "GPLv2+" 2324 LICENSE = "GPLv2+"
2246 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" 2325 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2247 PR = "r0"
2248 2326
2249 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" 2327 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2250 2328
@@ -2292,7 +2370,7 @@
2292 <para> 2370 <para>
2293 In the following example, <filename>mtd-utils</filename> is a makefile-based package: 2371 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2294 <literallayout class='monospaced'> 2372 <literallayout class='monospaced'>
2295 DESCRIPTION = "Tools for managing memory technology devices." 2373 SUMMARY = "Tools for managing memory technology devices."
2296 SECTION = "base" 2374 SECTION = "base"
2297 DEPENDS = "zlib lzo e2fsprogs util-linux" 2375 DEPENDS = "zlib lzo e2fsprogs util-linux"
2298 HOMEPAGE = "http://www.linux-mtd.infradead.org/" 2376 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
@@ -2324,26 +2402,6 @@
2324 BBCLASSEXTEND = "native" 2402 BBCLASSEXTEND = "native"
2325 </literallayout> 2403 </literallayout>
2326 </para> 2404 </para>
2327
2328 <para>
2329 If your sources are available as a tarball instead of a Git repository, you
2330 will need to provide the URL to the tarball as well as an
2331 <filename>md5</filename> or <filename>sha256</filename> sum of
2332 the download.
2333 Here is an example:
2334 <literallayout class='monospaced'>
2335 SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2"
2336 SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
2337 </literallayout>
2338 You can generate the <filename>md5</filename> or <filename>sha256</filename> sums
2339 by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands
2340 with the target file as the only argument.
2341 Here is an example:
2342 <literallayout class='monospaced'>
2343 $ md5sum mtd-utils-1.4.9.tar.bz2
2344 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
2345 </literallayout>
2346 </para>
2347 </section> 2405 </section>
2348 2406
2349 <section id='splitting-an-application-into-multiple-packages'> 2407 <section id='splitting-an-application-into-multiple-packages'>
@@ -2357,21 +2415,21 @@
2357 </para> 2415 </para>
2358 2416
2359 <para> 2417 <para>
2360 Following is an example that uses the <filename>libXpm</filename> recipe. 2418 Following is an example that uses the <filename>libxpm</filename> recipe.
2361 By default, this recipe generates a single package that contains the library along 2419 By default, this recipe generates a single package that contains the library along
2362 with a few binaries. 2420 with a few binaries.
2363 You can modify the recipe to split the binaries into separate packages: 2421 You can modify the recipe to split the binaries into separate packages:
2364 <literallayout class='monospaced'> 2422 <literallayout class='monospaced'>
2365 require xorg-lib-common.inc 2423 require xorg-lib-common.inc
2366 2424
2367 DESCRIPTION = "X11 Pixmap library" 2425 SUMMARY = "X11 Pixmap library"
2368 LICENSE = "X-BSD" 2426 LICENSE = "X-BSD"
2369 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" 2427 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2370 DEPENDS += "libxext libsm libxt" 2428 DEPENDS += "libxext libsm libxt"
2371 PR = "r3" 2429 PR = "r3"
2372 PE = "1" 2430 PE = "1"
2373 2431
2374 XORG_PN = "libXpm" 2432 XORG_PN = "libxpm"
2375 2433
2376 PACKAGES =+ "sxpm cxpm" 2434 PACKAGES =+ "sxpm cxpm"
2377 FILES_cxpm = "${bindir}/cxpm" 2435 FILES_cxpm = "${bindir}/cxpm"
@@ -2394,62 +2452,6 @@
2394 does not include the above listed files. 2452 does not include the above listed files.
2395 </para> 2453 </para>
2396 </section> 2454 </section>
2397
2398 <section id='usingpoky-extend-addpkg-postinstalls'>
2399 <title>Post-Installation Scripts</title>
2400
2401 <para>
2402 To add a post-installation script to a package, add a
2403 <filename>pkg_postinst_PACKAGENAME()</filename> function to the
2404 <filename>.bb</filename> file and use
2405 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
2406 <filename>postinst</filename> script.
2407 Normally,
2408 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2409 can be used, which automatically expands to <filename>PACKAGENAME</filename>.
2410 A post-installation function has the following structure:
2411 <literallayout class='monospaced'>
2412 pkg_postinst_PACKAGENAME () {
2413 #!/bin/sh -e
2414 # Commands to carry out
2415 }
2416 </literallayout>
2417 </para>
2418
2419 <para>
2420 The script defined in the post-installation function is called when the
2421 root filesystem is created.
2422 If the script succeeds, the package is marked as installed.
2423 If the script fails, the package is marked as unpacked and the script is
2424 executed when the image boots again.
2425 </para>
2426
2427 <para>
2428 Sometimes it is necessary for the execution of a post-installation
2429 script to be delayed until the first boot.
2430 For example, the script might need to be executed on the device itself.
2431 To delay script execution until boot time, use the following structure in the
2432 post-installation script:
2433 <literallayout class='monospaced'>
2434 pkg_postinst_PACKAGENAME () {
2435 #!/bin/sh -e
2436 if [ x"$D" = "x" ]; then
2437 # Actions to carry out on the device go here
2438 else
2439 exit 1
2440 fi
2441 }
2442 </literallayout>
2443 </para>
2444
2445 <para>
2446 The previous example delays execution until the image boots again because the
2447 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
2448 variable points
2449 to the directory containing the image when the root filesystem is created at build time but
2450 is unset when executed on the first boot.
2451 </para>
2452 </section>
2453 </section> 2455 </section>
2454 </section> 2456 </section>
2455 2457