summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-12-21 07:44:25 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-02 13:16:12 +0000
commit3ad993da1038c327c60da781315b748380228a7c (patch)
tree6a2c6861ba37cfd3daf6243bd81004ad89d53df2
parent9f51f11ca6599ca820c2c01c8b07a8ee73975318 (diff)
downloadpoky-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>
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml123
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 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
1777 <para> 1777 <para>
1778 However, if the compile step fails, you need to diagnose the 1778 However, if the compile step fails, you need to diagnose the
1779 failure. 1779 failure.
1780 Some common issues for failure are parallel build failures, 1780 Here are some common issues that cause failures:
1781 improper host path usage when building for the target, and 1781 <itemizedlist>
1782 so forth. 1782 <listitem><para><emphasis>Parallel build failures:</emphasis>
1783 These failures manifest themselves as intermittent
1784 errors, or errors reporting that a file or directory
1785 that should be created by some other part of the build
1786 process could not be found.
1787 This type of failure can occur even if, upon inspection,
1788 the file or directory does exist after the build has
1789 failed, because that part of the build process happened
1790 in the wrong order.</para>
1791 <para>To fix the problem, you need to either satisfy
1792 the missing dependency in the Makefile or whatever
1793 script produced the Makefile, or (as a workaround)
1794 set
1795 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
1796 to an empty string:
1797 <literallayout class='monospaced'>
1798 PARALLEL_MAKE = ""
1799 </literallayout></para></listitem>
1800 <listitem><para><emphasis>Improper host path usage:</emphasis>
1801 This failure applies to recipes building for the target
1802 or <filename>nativesdk</filename> only.
1803 The failure occurs when the compilation process uses
1804 headers, libraries, or other files from the host system
1805 when the process is cross-compiling for the target and
1806 should not be.</para>
1807 <para>To fix the problem, you should be able to see
1808 the host paths being used (e.g.
1809 <filename>/usr/include</filename>,
1810 <filename>/usr/lib</filename>, and so forth) by
1811 examining the <filename>log.do_configure</filename>
1812 file.</para></listitem>
1813 </itemizedlist>
1783 </para> 1814 </para>
1784 </section> 1815 </section>
1785 1816
@@ -1787,9 +1818,9 @@ do_unpack unpacks the source, and S must be set
1787 <title>Installing</title> 1818 <title>Installing</title>
1788 1819
1789 <para> 1820 <para>
1790 During <filename>do_install</filename>, files your recipe builds 1821 During <filename>do_install</filename>, the files and their
1791 are copied from locations where work is being done to locations 1822 structure that your recipe built are copied to locations on the
1792 on the target device. 1823 target device.
1793 The installation process moves the 1824 The installation process moves the
1794 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>, 1825 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
1795 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>, 1826 <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
1881 targets that can result in race conditions. 1912 targets that can result in race conditions.
1882 If you experience intermittent failures during 1913 If you experience intermittent failures during
1883 <filename>do_install</filename>, you might be able to work 1914 <filename>do_install</filename>, you might be able to work
1884 around them by setting 1915 around them by disabling parallel make install by adding the
1916 following to the recipe:
1917 <literallayout class='monospaced'>
1918 PARALLEL_MAKEINST = ""
1919 </literallayout>
1920 See
1885 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink> 1921 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
1886 to and empty string in the recipe. 1922 for additional information.
1887 </note> 1923 </note>
1888 </section> 1924 </section>
1889 1925
@@ -1891,13 +1927,20 @@ do_unpack unpacks the source, and S must be set
1891 <title>Supporting Services</title> 1927 <title>Supporting Services</title>
1892 1928
1893 <para> 1929 <para>
1930 If you want to install a service, which is a process that
1931 usually starts on boot and runs in the background, then
1932 you must include some additional definitions in your recipe.
1933 </para>
1934
1935 <para>
1894 If you are adding services and the service initialization 1936 If you are adding services and the service initialization
1895 script or the service file itself is not installed, you must 1937 script or the service file itself is not installed, you must
1896 provide for that installation in your recipe using a 1938 provide for that installation in your recipe using a
1897 <filename>do_install_append</filename> function. 1939 <filename>do_install_append</filename> function.
1898 If your recipe already has a <filename>do_install</filename> 1940 If your recipe already has a <filename>do_install</filename>
1899 function, you will need to be sure to change it so that it 1941 function, update the function near its end rather than
1900 handles the installation of your services. 1942 adding an additional <filename>do_install_append</filename>
1943 function.
1901 </para> 1944 </para>
1902 1945
1903 <para> 1946 <para>
@@ -1909,11 +1952,39 @@ do_unpack unpacks the source, and S must be set
1909 </para> 1952 </para>
1910 1953
1911 <para> 1954 <para>
1912 <emphasis>Paul</emphasis> - We need to get some detail here on specific extra 1955 Here are some examples:
1913 functions needed in some recipes (e.g. how to add support for 1956 <itemizedlist>
1914 services like sysvinit and systemd, how to add 1957 <listitem><para><emphasis>SysVinit:</emphasis>
1915 <filename>PACKAGECONFIG</filename> options, how to 1958 The SysVinit service is a group of processes that
1916 deal with alternatives, and so forth). 1959 control the very basic functions of your system.
1960 SysVinit includes the init program, the first program
1961 started by the Linux kernel when the system boots.
1962 Init then controls the startup, running and shutdown
1963 of all other programs.</para>
1964 <para>To include this service, your recipe needs to
1965 inherit the
1966 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink>
1967 class.
1968 The class helps facilitate safely installing the
1969 package on the target.</para>
1970 <para>You will need to set the
1971 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>,
1972 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>,
1973 and
1974 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink>
1975 variables within your recipe.</para></listitem>
1976 <listitem><para><emphasis>Systemd:</emphasis>
1977 The Systemd service is a system management daemon
1978 designed for the Linux startup process.
1979 Systemd is the first process to execute and is
1980 therefore the parent process of all child processes.
1981 </para>
1982 <para>To include this service, your recipe needs to
1983 inherit the
1984 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink>
1985 class.
1986 See the class for more information.</para></listitem>
1987 </itemizedlist>
1917 </para> 1988 </para>
1918 </section> 1989 </section>
1919 1990
@@ -1921,9 +1992,18 @@ do_unpack unpacks the source, and S must be set
1921 <title>Packaging</title> 1992 <title>Packaging</title>
1922 1993
1923 <para> 1994 <para>
1995 The <filename>do_package</filename> task splits the files
1996 produced by the recipe into logical components.
1997 Even software that produces a single binary might still have
1998 debug symbols, documentation, and other logical components.
1924 The <filename>do_package</filename> task ensures that files 1999 The <filename>do_package</filename> task ensures that files
1925 are packaged correctly. 2000 are split up and packaged correctly.
1926 To be sure your packages are correct, examine the 2001 </para>
2002
2003 <para>
2004 After you build your software you need to be sure your packages
2005 are correct.
2006 Examine the
1927 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename> 2007 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
1928 directory and make sure files are where you expect them to be. 2008 directory and make sure files are where you expect them to be.
1929 </para> 2009 </para>
@@ -1946,6 +2026,15 @@ do_unpack unpacks the source, and S must be set
1946 To accomplish runtime testing, add the build's output 2026 To accomplish runtime testing, add the build's output
1947 packages to your image and test them on the target. 2027 packages to your image and test them on the target.
1948 </para> 2028 </para>
2029
2030 <para>
2031 To facilitate testing, you can customize your image to include
2032 the <filename>-dbg</filename> package.
2033 For information on how to customize your image by adding
2034 specific packages, see the
2035 "<link linkend='usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</link>"
2036 section.
2037 </para>
1949 </section> 2038 </section>
1950 </section> 2039 </section>
1951 2040