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.