From 3cb04638b46f26da61fc894221462b738ffeca0c Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 3 Jun 2014 09:33:04 +0300 Subject: 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 (From yocto-docs rev: 48ecc543d9f614b5258ab2573f0406aa3c778647) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 186 ++++++++++++++------- 1 file changed, 127 insertions(+), 59 deletions(-) (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml') 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 @@ subdirectory that is not specified in the patch file, use the "patchdir" option in the entry. + + + As with all local files referenced in + SRC_URI + using file://, you should place + patch files in a directory next to the recipe either + named the same as the base name of the recipe + (BPN), + or "files". +
@@ -2190,9 +2200,23 @@ In these cases, you need to go back and add additional options to the configure script as well as possibly add additional build-time dependencies to - DEPENDS. - Occasionally, it is necessary to apply a patch to the - source to ensure the correct paths are used. + DEPENDS. + Occasionally, it is necessary to apply a patch + to the source to ensure the correct paths are used. + If you need to specify paths to find files staged + into the sysroot from other recipes, use the variables + that the OpenEmbedded build system provides + (e.g. + STAGING_BINDIR, + STAGING_INCDIR, + STAGING_DATADIR, and so forth). + @@ -2263,7 +2287,8 @@ recipe. The function must first use install -d to create the - directories. + directories under + ${D}. Once the directories exist, your function can use install to manually install the built software into the directories. @@ -2398,56 +2423,100 @@ Packaging - The do_package task splits the files - produced by the recipe into logical components. - Even software that produces a single binary might still have - debug symbols, documentation, and other logical components - that should be split out. - The do_package task ensures that files - are split up and packaged correctly. - - - - The insane class adds a step to the - package generation process so that output quality assurance - checks are generated by the OpenEmbedded build system. - This step performs a range of checks to be sure the build's - output is free of common problems that show up during runtime. - For information on these checks, see the - insane - class and the - "QA Error and Warning Messages" - chapter in the Yocto Project Reference Manual. - - - - After you build your software, you need to be sure your packages - are correct. - Examine the - ${WORKDIR}/packages-split - directory and make sure files are where you expect them to be. - - - - If you discover problems, you can set - PACKAGES, - FILES, - do_install(_append), and so forth as - needed. - - - - See the - "Splitting an Application into Multiple Packages" - section for an example that shows how you might split - your software into more than one package. - - - - For an example showing how to install a post-installation - script, see the - "Post-Installation Scripts" - section. + Successful packaging is a combination of automated processes + performed by the OpenEmbedded build system and some + specific steps you need to take. + The following list describes the process: + + Splitting Files: + The do_package task splits the + files produced by the recipe into logical components. + Even software that produces a single binary might + still have debug symbols, documentation, and other + logical components that should be split out. + The do_package task ensures + that files are split up and packaged correctly. + + Running QA Checks: + The insane class adds a step to + the package generation process so that output quality + assurance checks are generated by the OpenEmbedded + build system. + This step performs a range of checks to be sure the + build's output is free of common problems that show + up during runtime. + For information on these checks, see the + insane + class and the + "QA Error and Warning Messages" + chapter in the Yocto Project Reference Manual. + + Hand-Checking Your Packages: + After you build your software, you need to be sure + your packages are correct. + Examine the + ${WORKDIR}/packages-split + directory and make sure files are where you expect + them to be. + If you discover problems, you can set + PACKAGES, + FILES, + do_install(_append), and so forth as + needed. + + Splitting an Application into Multiple Packages: + If you need to split an application into several + packages, see the + "Splitting an Application into Multiple Packages" + section for an example. + + Installing a Post-Installation Script: + For an example showing how to install a + post-installation script, see the + "Post-Installation Scripts" + section. + + Marking Package Architecture: + Depending on what your recipe is building and how it + is configured, it might be important to mark the + packages produced as being specific to a particular + machine, or to mark them as not being specific to + a particular machine or architecture at all. + By default, packages produced for the target are + marked as being specific to the architecture of the + target machine because that is usually the desired + result. + However, if the recipe configures the software to be + built specific to the target machine (e.g. the + MACHINE + value is passed into the configure script or a patch + is applied only for a particular machine), then you + should mark the packages produced as being + machine-specific by adding the following to the + recipe: + + PACKAGE_ARCH = "${MACHINE_ARCH}" + + On the other hand, if the recipe produces packages + that do not contain anything specific to the target + machine or architecture at all (e.g. recipes + that simply package script files or configuration + files), you should use the + allarch + class to do this for you by adding this to your + recipe: + + inherit allarch + + Ensuring that the package architecture is correct is + not critical while you are doing the first few builds + of your recipe, but it is important in order to + to ensure that your recipe rebuilds (or does not + rebuild) appropriately in response to changes in + configuration, and to ensure that you get the + appropriate packages installed on the target machine. + +
@@ -2497,8 +2566,8 @@ package is included in an image. To add a post-installation script to a package, add a pkg_postinst_PACKAGENAME() function to - the recipe file (.bb) and use - PACKAGENAME as the name of the package + the recipe file (.bb) and replace + PACKAGENAME with the name of the package you want to attach to the postinst script. To apply the post-installation script to the main package @@ -2546,9 +2615,8 @@ The previous example delays execution until the image boots - again because the - D - variable points to the directory containing the image when + again because the environment variable D + points to the directory containing the image when the root filesystem is created at build time but is unset when executed on the first boot. -- cgit v1.2.3-54-g00ecf