diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2013-12-21 07:44:25 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-02 13:16:12 +0000 |
commit | 3ad993da1038c327c60da781315b748380228a7c (patch) | |
tree | 6a2c6861ba37cfd3daf6243bd81004ad89d53df2 /documentation | |
parent | 9f51f11ca6599ca820c2c01c8b07a8ee73975318 (diff) | |
download | ast2050-yocto-poky-3ad993da1038c327c60da781315b748380228a7c.zip ast2050-yocto-poky-3ad993da1038c327c60da781315b748380228a7c.tar.gz |
dev-manual: Completed first pass of review feedback.
(From yocto-docs rev: 5c2679b334e2130bd82bee7491d39b6cff56b0a9)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 123 |
1 files changed, 106 insertions, 17 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 6d1d083..717a453 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 <para> 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: + <itemizedlist> + <listitem><para><emphasis>Parallel build failures:</emphasis> + 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.</para> + <para>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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> + to an empty string: + <literallayout class='monospaced'> + PARALLEL_MAKE = "" + </literallayout></para></listitem> + <listitem><para><emphasis>Improper host path usage:</emphasis> + This failure applies to recipes building for the target + or <filename>nativesdk</filename> 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.</para> + <para>To fix the problem, you should be able to see + the host paths being used (e.g. + <filename>/usr/include</filename>, + <filename>/usr/lib</filename>, and so forth) by + examining the <filename>log.do_configure</filename> + file.</para></listitem> + </itemizedlist> </para> </section> @@ -1787,9 +1818,9 @@ do_unpack unpacks the source, and S must be set <title>Installing</title> <para> - During <filename>do_install</filename>, files your recipe builds - are copied from locations where work is being done to locations - on the target device. + During <filename>do_install</filename>, the files and their + structure that your recipe built are copied to locations on the + target device. The installation process moves the <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>, <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>, @@ -1881,9 +1912,14 @@ do_unpack unpacks the source, and S must be set targets that can result in race conditions. If you experience intermittent failures during <filename>do_install</filename>, you might be able to work - around them by setting + around them by disabling parallel make install by adding the + following to the recipe: + <literallayout class='monospaced'> + PARALLEL_MAKEINST = "" + </literallayout> + See <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink> - to and empty string in the recipe. + for additional information. </note> </section> @@ -1891,13 +1927,20 @@ do_unpack unpacks the source, and S must be set <title>Supporting Services</title> <para> + 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. + </para> + + <para> 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 <filename>do_install_append</filename> function. If your recipe already has a <filename>do_install</filename> - 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 <filename>do_install_append</filename> + function. </para> <para> @@ -1909,11 +1952,39 @@ do_unpack unpacks the source, and S must be set </para> <para> - <emphasis>Paul</emphasis> - 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 - <filename>PACKAGECONFIG</filename> options, how to - deal with alternatives, and so forth). + Here are some examples: + <itemizedlist> + <listitem><para><emphasis>SysVinit:</emphasis> + 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.</para> + <para>To include this service, your recipe needs to + inherit the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink> + class. + The class helps facilitate safely installing the + package on the target.</para> + <para>You will need to set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink> + variables within your recipe.</para></listitem> + <listitem><para><emphasis>Systemd:</emphasis> + 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. + </para> + <para>To include this service, your recipe needs to + inherit the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink> + class. + See the class for more information.</para></listitem> + </itemizedlist> </para> </section> @@ -1921,9 +1992,18 @@ do_unpack unpacks the source, and S must be set <title>Packaging</title> <para> + The <filename>do_package</filename> 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 <filename>do_package</filename> task ensures that files - are packaged correctly. - To be sure your packages are correct, examine the + are split up and packaged correctly. + </para> + + <para> + After you build your software you need to be sure your packages + are correct. + Examine the <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename> directory and make sure files are where you expect them to be. </para> @@ -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. </para> + + <para> + To facilitate testing, you can customize your image to include + the <filename>-dbg</filename> package. + For information on how to customize your image by adding + specific packages, see the + "<link linkend='usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</link>" + section. + </para> </section> </section> |