summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-06-03 09:33:04 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-06-18 10:30:44 +0100
commit3cb04638b46f26da61fc894221462b738ffeca0c (patch)
tree4185f30ba9dd03886ae1fbf54a36236d1c2ccb5e
parent59b50ea598538cb9ad9933ba28f9514052258d00 (diff)
downloadpoky-3cb04638b46f26da61fc894221462b738ffeca0c.tar.gz
dev-manual: Edits to "Writing a New Recipe"
Received and implemented some feedback from Paul Eggleton on this section. These were unsolicited observations. Reported-by: Paul Eggleton <paul.eggleton@intel.com> (From yocto-docs rev: 48ecc543d9f614b5258ab2573f0406aa3c778647) 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.xml186
1 files changed, 127 insertions, 59 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 2968b4d3c0..44fb9ff63a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1896,6 +1896,16 @@
1896 subdirectory that is not specified in the patch file, use the 1896 subdirectory that is not specified in the patch file, use the
1897 "patchdir" option in the entry. 1897 "patchdir" option in the entry.
1898 </para> 1898 </para>
1899
1900 <para>
1901 As with all local files referenced in
1902 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1903 using <filename>file://</filename>, you should place
1904 patch files in a directory next to the recipe either
1905 named the same as the base name of the recipe
1906 (<ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>),
1907 or "files".
1908 </para>
1899 </section> 1909 </section>
1900 1910
1901 <section id='new-recipe-licensing'> 1911 <section id='new-recipe-licensing'>
@@ -2190,9 +2200,23 @@
2190 In these cases, you need to go back and add additional 2200 In these cases, you need to go back and add additional
2191 options to the configure script as well as possibly 2201 options to the configure script as well as possibly
2192 add additional build-time dependencies to 2202 add additional build-time dependencies to
2193 <filename>DEPENDS</filename>. 2203 <filename>DEPENDS</filename>.</para>
2194 Occasionally, it is necessary to apply a patch to the 2204 <para>Occasionally, it is necessary to apply a patch
2195 source to ensure the correct paths are used. 2205 to the source to ensure the correct paths are used.
2206 If you need to specify paths to find files staged
2207 into the sysroot from other recipes, use the variables
2208 that the OpenEmbedded build system provides
2209 (e.g.
2210 <filename>STAGING_BINDIR</filename>,
2211 <filename>STAGING_INCDIR</filename>,
2212 <filename>STAGING_DATADIR</filename>, and so forth).
2213<!--
2214 (e.g.
2215 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_BINDIR'><filename>STAGING_BINDIR</filename></ulink>,
2216 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_INCDIR'><filename>STAGING_INCDIR</filename></ulink>,
2217 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DATADIR'><filename>STAGING_DATADIR</filename></ulink>,
2218 and so forth).
2219-->
2196 </para></listitem> 2220 </para></listitem>
2197 </itemizedlist> 2221 </itemizedlist>
2198 </para> 2222 </para>
@@ -2263,7 +2287,8 @@
2263 recipe. 2287 recipe.
2264 The function must first use 2288 The function must first use
2265 <filename>install -d</filename> to create the 2289 <filename>install -d</filename> to create the
2266 directories. 2290 directories under
2291 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
2267 Once the directories exist, your function can use 2292 Once the directories exist, your function can use
2268 <filename>install</filename> to manually install the 2293 <filename>install</filename> to manually install the
2269 built software into the directories.</para> 2294 built software into the directories.</para>
@@ -2398,56 +2423,100 @@
2398 <title>Packaging</title> 2423 <title>Packaging</title>
2399 2424
2400 <para> 2425 <para>
2401 The <filename>do_package</filename> task splits the files 2426 Successful packaging is a combination of automated processes
2402 produced by the recipe into logical components. 2427 performed by the OpenEmbedded build system and some
2403 Even software that produces a single binary might still have 2428 specific steps you need to take.
2404 debug symbols, documentation, and other logical components 2429 The following list describes the process:
2405 that should be split out. 2430 <itemizedlist>
2406 The <filename>do_package</filename> task ensures that files 2431 <listitem><para><emphasis>Splitting Files</emphasis>:
2407 are split up and packaged correctly. 2432 The <filename>do_package</filename> task splits the
2408 </para> 2433 files produced by the recipe into logical components.
2409 2434 Even software that produces a single binary might
2410 <para> 2435 still have debug symbols, documentation, and other
2411 The <filename>insane</filename> class adds a step to the 2436 logical components that should be split out.
2412 package generation process so that output quality assurance 2437 The <filename>do_package</filename> task ensures
2413 checks are generated by the OpenEmbedded build system. 2438 that files are split up and packaged correctly.
2414 This step performs a range of checks to be sure the build's 2439 </para></listitem>
2415 output is free of common problems that show up during runtime. 2440 <listitem><para><emphasis>Running QA Checks</emphasis>:
2416 For information on these checks, see the 2441 The <filename>insane</filename> class adds a step to
2417 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink> 2442 the package generation process so that output quality
2418 class and the 2443 assurance checks are generated by the OpenEmbedded
2419 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>" 2444 build system.
2420 chapter in the Yocto Project Reference Manual. 2445 This step performs a range of checks to be sure the
2421 </para> 2446 build's output is free of common problems that show
2422 2447 up during runtime.
2423 <para> 2448 For information on these checks, see the
2424 After you build your software, you need to be sure your packages 2449 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
2425 are correct. 2450 class and the
2426 Examine the 2451 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
2427 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename> 2452 chapter in the Yocto Project Reference Manual.
2428 directory and make sure files are where you expect them to be. 2453 </para></listitem>
2429 </para> 2454 <listitem><para><emphasis>Hand-Checking Your Packages</emphasis>:
2430 2455 After you build your software, you need to be sure
2431 <para> 2456 your packages are correct.
2432 If you discover problems, you can set 2457 Examine the
2433 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, 2458 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
2434 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>, 2459 directory and make sure files are where you expect
2435 <filename>do_install(_append)</filename>, and so forth as 2460 them to be.
2436 needed. 2461 If you discover problems, you can set
2437 </para> 2462 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2438 2463 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2439 <para> 2464 <filename>do_install(_append)</filename>, and so forth as
2440 See the 2465 needed.
2441 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>" 2466 </para></listitem>
2442 section for an example that shows how you might split 2467 <listitem><para><emphasis>Splitting an Application into Multiple Packages</emphasis>:
2443 your software into more than one package. 2468 If you need to split an application into several
2444 </para> 2469 packages, see the
2445 2470 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2446 <para> 2471 section for an example.
2447 For an example showing how to install a post-installation 2472 </para></listitem>
2448 script, see the 2473 <listitem><para><emphasis>Installing a Post-Installation Script</emphasis>:
2449 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>" 2474 For an example showing how to install a
2450 section. 2475 post-installation script, see the
2476 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
2477 section.
2478 </para></listitem>
2479 <listitem><para><emphasis>Marking Package Architecture</emphasis>:
2480 Depending on what your recipe is building and how it
2481 is configured, it might be important to mark the
2482 packages produced as being specific to a particular
2483 machine, or to mark them as not being specific to
2484 a particular machine or architecture at all.
2485 By default, packages produced for the target are
2486 marked as being specific to the architecture of the
2487 target machine because that is usually the desired
2488 result.
2489 However, if the recipe configures the software to be
2490 built specific to the target machine (e.g. the
2491 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2492 value is passed into the configure script or a patch
2493 is applied only for a particular machine), then you
2494 should mark the packages produced as being
2495 machine-specific by adding the following to the
2496 recipe:
2497 <literallayout class='monospaced'>
2498 PACKAGE_ARCH = "${MACHINE_ARCH}"
2499 </literallayout>
2500 On the other hand, if the recipe produces packages
2501 that do not contain anything specific to the target
2502 machine or architecture at all (e.g. recipes
2503 that simply package script files or configuration
2504 files), you should use the
2505 <ulink url='&YOCTO_DOCS_REF_URL;#allarch'><filename>allarch</filename></ulink>
2506 class to do this for you by adding this to your
2507 recipe:
2508 <literallayout class='monospaced'>
2509 inherit allarch
2510 </literallayout>
2511 Ensuring that the package architecture is correct is
2512 not critical while you are doing the first few builds
2513 of your recipe, but it is important in order to
2514 to ensure that your recipe rebuilds (or does not
2515 rebuild) appropriately in response to changes in
2516 configuration, and to ensure that you get the
2517 appropriate packages installed on the target machine.
2518 </para></listitem>
2519 </itemizedlist>
2451 </para> 2520 </para>
2452 </section> 2521 </section>
2453 2522
@@ -2497,8 +2566,8 @@
2497 package is included in an image. 2566 package is included in an image.
2498 To add a post-installation script to a package, add a 2567 To add a post-installation script to a package, add a
2499 <filename>pkg_postinst_PACKAGENAME()</filename> function to 2568 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2500 the recipe file (<filename>.bb</filename>) and use 2569 the recipe file (<filename>.bb</filename>) and replace
2501 <filename>PACKAGENAME</filename> as the name of the package 2570 <filename>PACKAGENAME</filename> with the name of the package
2502 you want to attach to the <filename>postinst</filename> 2571 you want to attach to the <filename>postinst</filename>
2503 script. 2572 script.
2504 To apply the post-installation script to the main package 2573 To apply the post-installation script to the main package
@@ -2546,9 +2615,8 @@
2546 2615
2547 <para> 2616 <para>
2548 The previous example delays execution until the image boots 2617 The previous example delays execution until the image boots
2549 again because the 2618 again because the environment variable <filename>D</filename>
2550 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename> 2619 points to the directory containing the image when
2551 variable points to the directory containing the image when
2552 the root filesystem is created at build time but is unset 2620 the root filesystem is created at build time but is unset
2553 when executed on the first boot. 2621 when executed on the first boot.
2554 </para> 2622 </para>