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. +