diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 6d1d08365b..717a453061 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1777,9 +1777,40 @@ do_unpack unpacks the source, and S must be set
However, if the compile step fails, you need to diagnose the
failure.
- Some common issues for failure are parallel build failures,
- improper host path usage when building for the target, and
- so forth.
+ Here are some common issues that cause failures:
+
+ Parallel build failures:
+ These failures manifest themselves as intermittent
+ errors, or errors reporting that a file or directory
+ that should be created by some other part of the build
+ process could not be found.
+ This type of failure can occur even if, upon inspection,
+ the file or directory does exist after the build has
+ failed, because that part of the build process happened
+ in the wrong order.
+ To fix the problem, you need to either satisfy
+ the missing dependency in the Makefile or whatever
+ script produced the Makefile, or (as a workaround)
+ set
+ PARALLEL_MAKE
+ to an empty string:
+
+ PARALLEL_MAKE = ""
+
+ Improper host path usage:
+ This failure applies to recipes building for the target
+ or nativesdk only.
+ The failure occurs when the compilation process uses
+ headers, libraries, or other files from the host system
+ when the process is cross-compiling for the target and
+ should not be.
+ To fix the problem, you should be able to see
+ the host paths being used (e.g.
+ /usr/include,
+ /usr/lib, and so forth) by
+ examining the log.do_configure
+ file.
+
@@ -1787,9 +1818,9 @@ do_unpack unpacks the source, and S must be set
Installing
- During do_install, files your recipe builds
- are copied from locations where work is being done to locations
- on the target device.
+ During do_install, the files and their
+ structure that your recipe built are copied to locations on the
+ target device.
The installation process moves the
${S},
${B},
@@ -1881,23 +1912,35 @@ do_unpack unpacks the source, and S must be set
targets that can result in race conditions.
If you experience intermittent failures during
do_install, you might be able to work
- around them by setting
+ around them by disabling parallel make install by adding the
+ following to the recipe:
+
+ PARALLEL_MAKEINST = ""
+
+ See
PARALLEL_MAKEINST
- to and empty string in the recipe.
+ for additional information.
Supporting Services
+
+ If you want to install a service, which is a process that
+ usually starts on boot and runs in the background, then
+ you must include some additional definitions in your recipe.
+
+
If you are adding services and the service initialization
script or the service file itself is not installed, you must
provide for that installation in your recipe using a
do_install_append function.
If your recipe already has a do_install
- function, you will need to be sure to change it so that it
- handles the installation of your services.
+ function, update the function near its end rather than
+ adding an additional do_install_append
+ function.
@@ -1909,11 +1952,39 @@ do_unpack unpacks the source, and S must be set
- Paul - We need to get some detail here on specific extra
- functions needed in some recipes (e.g. how to add support for
- services like sysvinit and systemd, how to add
- PACKAGECONFIG options, how to
- deal with alternatives, and so forth).
+ Here are some examples:
+
+ SysVinit:
+ The SysVinit service is a group of processes that
+ control the very basic functions of your system.
+ SysVinit includes the init program, the first program
+ started by the Linux kernel when the system boots.
+ Init then controls the startup, running and shutdown
+ of all other programs.
+ To include this service, your recipe needs to
+ inherit the
+ update-rc.d
+ class.
+ The class helps facilitate safely installing the
+ package on the target.
+ You will need to set the
+ INITSCRIPT_PACKAGES,
+ INITSCRIPT_NAME,
+ and
+ INITSCRIPT_PARAMS
+ variables within your recipe.
+ Systemd:
+ The Systemd service is a system management daemon
+ designed for the Linux startup process.
+ Systemd is the first process to execute and is
+ therefore the parent process of all child processes.
+
+ To include this service, your recipe needs to
+ inherit the
+ systemd
+ class.
+ See the class for more information.
+
@@ -1921,9 +1992,18 @@ do_unpack unpacks the source, and S must be set
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.
The do_package task ensures that files
- are packaged correctly.
- To be sure your packages are correct, examine the
+ are split up and packaged correctly.
+
+
+
+ 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.
@@ -1946,6 +2026,15 @@ do_unpack unpacks the source, and S must be set
To accomplish runtime testing, add the build's output
packages to your image and test them on the target.
+
+
+ To facilitate testing, you can customize your image to include
+ the -dbg package.
+ For information on how to customize your image by adding
+ specific packages, see the
+ "Customizing Images Using Custom Package Groups"
+ section.
+