diff options
Diffstat (limited to 'usermanual')
-rw-r--r-- | usermanual/chapters/recipes.xml | 202 | ||||
-rw-r--r-- | usermanual/reference/class_autotools.xml | 48 | ||||
-rw-r--r-- | usermanual/reference/class_siteinfo.xml | 180 | ||||
-rw-r--r-- | usermanual/reference/dirs_staging.xml | 4 | ||||
-rw-r--r-- | usermanual/usermanual.xml | 3 |
5 files changed, 377 insertions, 60 deletions
diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index 83c3f39279..7ed33868f5 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -335,6 +335,17 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> <para>It is good practice to always define PR in your recipes, even for the <emphasis>"r0"</emphasis> release, so that when editing the recipe it is clear that the PR number needs to be updated.</para> + + <para>You should always increment PR when modifying a recipe. + Sometimes this can be avoided if the change will have no effect on the + actual packages generated by the recipe, such as updating the SRC_URI + to point to a new host. If in any doubt then you should increase the + PR regardless of what has been changed.</para> + + <para>The PR value should never be decremented. If you accidentally + submit a large PR value for example then it should be left at the + value and just increased for new releases, not reset back to a lower + version.</para> </note></para> <para>When a recipe is being processed some variables are automatically @@ -1212,8 +1223,8 @@ NOTE: package helloworld-0.1-r0: task do_package: started NOTE: package helloworld-0.1-r0: task do_package: completed NOTE: package helloworld-0.1-r0: task do_package_write: started NOTE: Not creating empty archive for helloworld-dbg-0.1-r0 -Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld_0.1-r0_sh4.ipk -Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld-doc_0.1-r0_sh4.ipk +Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk +Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk NOTE: Not creating empty archive for helloworld-dev-0.1-r0 NOTE: Not creating empty archive for helloworld-locale-0.1-r0 NOTE: package helloworld-0.1-r0: task do_package_write: completed @@ -1228,9 +1239,9 @@ Build statistics: <para>The package was successfully built, the output consists of two .ipkg files, which are ready to be installed on the target. One contains - the binary and the other contains the readme file:<screen>~/oe%> ls -l tmp/deploy/ipk/helloworld* --rw-r--r-- 1 lenehan lenehan 3040 Jan 12 14:46 tmp/deploy/ipk/helloworld_0.1-r0_sh4.ipk --rw-r--r-- 1 lenehan lenehan 768 Jan 12 14:46 tmp/deploy/ipk/helloworld-doc_0.1-r0_sh4.ipk + the binary and the other contains the readme file:<screen>~/oe%> ls -l tmp/deploy/ipk/*/helloworld* +-rw-r--r-- 1 lenehan lenehan 3040 Jan 12 14:46 tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk +-rw-r--r-- 1 lenehan lenehan 768 Jan 12 14:46 tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk ~/oe%></screen></para> <para>It's worthwhile looking at the working directory to see where @@ -1714,8 +1725,8 @@ inherit autotools</screen></para> example of the packaging output from the helloworld example above shows this packaging in action:<screen>[NOTE: package helloworld-0.1-r0: task do_package_write: started NOTE: Not creating empty archive for helloworld-dbg-0.1-r0 -Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld_0.1-r0_sh4.ipk -Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld-doc_0.1-r0_sh4.ipk +Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk +Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk NOTE: Not creating empty archive for helloworld-dev-0.1-r0 NOTE: Not creating empty archive for helloworld-locale-0.1-r0 NOTE: package helloworld-0.1-r0: task do_package_write: completed</screen>We @@ -1999,9 +2010,10 @@ NOTE: package helloworld-0.1-r0: task do_package_write: completed</screen>We <para>Note that the order of packages effects the files that will be matched via wildcards. Consider the case where we have three binaries in - the /usr/bin directory and we want the test program in a separate - package:<screen>/usr/bin/programa /usr/bin/programb /usr/bin/test</screen>So - we define a new package and instruct bitbake to /usr/bin/test in it.</para> + the <command>/usr/bin</command> directory and we want the test program + in a separate package:<screen>/usr/bin/programa /usr/bin/programb /usr/bin/test</screen>So + we define a new package and instruct bitbake to include /usr/bin/test in + it.</para> <screen>FILES-${PN}-test = "${bindir}/test" PACKAGES += "FILES-${PN}-test"</screen> @@ -2019,7 +2031,8 @@ PACKAGES += "FILES-${PN}-test"</screen> processing of the <emphasis role="bold">${PN}-test</emphasis> package.</para> - <para>To achieve what we are trying to accomplish we have two options:</para> + <para>To achieve what we are trying to accomplish we have two + options:</para> <orderedlist> <listitem> @@ -2112,15 +2125,109 @@ NOTE: package helloworld-0.1-r0: task do_package: completed</screen>Except in </section> <section> + <title>Excluding files</title> + + <para>There's no actual support for explicitly excluding files from + packaging. You could just leave them out of any package, but then you'll + get warnings (or errors if requesting full package checking) during + packaging which is not desirable. It also doesn't let other people know + that you've deliberately avoided packaging the file or files.</para> + + <para>In order to exclude a file totally you should avoid installing it + in the first place during the install task.</para> + + <para>In some cases it may be easier to let the package install the file + and then explicitly remove the file and the end of the install task. The + following example from the samba recipe shows the removal of several + files that get installed via the default install task generated by the + <xref linkend="autotools_class" />. By using + <emphasis>do_install_append</emphasis> these commands and run after the + autotools generated install task:</para> + + <screen>do_install_append() { + ... + rm -f ${D}${bindir}/*.old + rm -f ${D}${sbindir}/*.old + ... +}</screen> + </section> + + <section> <title>Debian naming</title> - <para>This section is to be completed</para> + <para>A special <emphasis>debian library name</emphasis> policy can be + applied for packages that contain a single shared library. When enabled + packages will be renamed to match the debian policy for such + packages.</para> + + <para>Debian naming is enabled by including the debian class via either + <command>local.conf</command> or your distributions configuration + file:<screen>INHERIT += "debian"</screen></para> + + <para>The policy works by looking at the shared library name and version + and will automatically rename the package to + <emphasis><libname><lib-major-version></emphasis>. For + example if the package name (PN) is <command>foo</command> and the + package ships a file named <command>libfoo.so.1.2.3</command> then the + package will be renamed to <command>libfoo1</command> to follow the + debian policy.</para> + + <para>If we look at the <emphasis>lzo_1.08.bb</emphasis> recipe, + currently at release 14, it generates a package containing a single + shared library :<screen>~oe/build/titan-glibc-25%> find tmp/work/lzo-1.08-r14/install/ +tmp/work/lzo-1.08-r14/install/lzo +tmp/work/lzo-1.08-r14/install/lzo/usr +tmp/work/lzo-1.08-r14/install/lzo/usr/lib +tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1 +tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0</screen>Without + debian naming this package would have been called + <command>lzo_1.08-r14_sh4.ipk</command> (and the corresponding dev and + dbg packages would have been called + <command>lzo-dbg_1.08-r14_sh4.ipk</command> and + <command>lzo-dev_1.08-r14_sh4.ipk</command>). However with debian naming + enabled the package is renamed based on the name of the shared library, + which is <command>liblzo.so.1.0.0</command> in this case. So the name + <command>lzo</command> is replaced with + <command>liblzo1</command>:<screen>~oe/build/titan-glibc-25%> find tmp/deploy/ipk/ -name '*lzo*' +tmp/deploy/ipk/sh4/liblzo1_1.08-r14_sh4.ipk +tmp/deploy/ipk/sh4/liblzo-dev_1.08-r14_sh4.ipk +tmp/deploy/ipk/sh4/liblzo-dbg_1.08-r14_sh4.ipk</screen></para> + + <para>Some variables are available which effect the operation of the + debian renaming class:</para> - <itemizedlist> - <listitem> - <para>inherit += "debian"</para> - </listitem> - </itemizedlist> + <variablelist> + <varlistentry> + <term>LEAD_SONAME</term> + + <listitem> + <para>If the package actually contains multiple shared libraries + then one will be selected automatically and a warning will be + generated. This variable is a regular expression which is used to + select which shared library from those available is to be used for + debian renaming.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DEBIAN_NOAUTONAME_<pkgname></term> + + <listitem> + <para>If this variable is set to 1 for a package then debian + renaming will not be applied for the package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AUTO_LIBNAME_PKGS</term> + + <listitem> + <para>If set this variable specifies the prefix of packages which + will be subject to debian renaming. This can be used to prevent + all of the packages being renamed via the renaming policy.</para> + </listitem> + </varlistentry> + </variablelist> </section> <section> @@ -3103,21 +3210,50 @@ do_configure() { <section id="recipes_defaultpreference" xreflabel="default preference"> <title>Preferences: How to disable packages</title> - <para>This section is to be completed.</para> - - <itemizedlist> - <listitem> - <para>what DEFAULT_PREFERENCE does</para> - </listitem> - - <listitem> - <para>why you would want to use it</para> - </listitem> - - <listitem> - <para>using it with overrides</para> - </listitem> - </itemizedlist> + <para>When bitbake is asked to build a package and multiple version of + that package are available it will normally select the version with the + highest version number (where the version is defined via the + <command>PV</command> variable).</para> + + <para>For example if we were to ask bitbake to build procps and the + following packages are available:<screen>~/oe%> ls packages/procps +procps-3.1.15/ procps-3.2.1/ procps-3.2.5/ procps-3.2.7/ procps.inc +procps_3.1.15.bb procps_3.2.1.bb procps_3.2.5.bb procps_3.2.7.bb +~/oe%></screen>then we would expect that version <command>3.2.7</command> + (the highest version number) would be built.</para> + + <para>Sometimes this is not what you actually want to happen though. + Perhaps you have added a new version does not yet work or maybe the new + version has no support for your target yet. Help is at hand since bitbake + is not only looking at the version to decided which version to build but + is also looking at the preference for the versions, as defined via a + <command>DEFAULT_PREFERENCE</command> variable contained without the + recipes.</para> + + <para>By default <command>DEFAULT_PREFERENCE</command> is set to zero. + Bitbake will find the highest preference that is available and then for + all the packages at the preference level it will select the package with + the highest version. In general this means that adding a positive + <command>DEFAULT_PREFERENCE</command> will cause the package to be + preferred over other versions and a negative + <command>DEFAULT_PREFERENCE</command> will cause all other packages to be + preferred.</para> + + <para>Imagine that you are adding procps version 4.0.0, but that it does + not yet work. You could delete it to make procps build so you can build a + working image, but what you really want it just for version 4.0.0 to be + ignored until it works. By adding:<screen>DEFAULT_PREFERENCE = "-1"</screen>to + the recipe it'll cause it to be ignored by bitbake (since all the existing + versions have a preference of 0). Note that you can still call bitbake + directly on the recipe:<screen>bitbake -b packages/procps/procps_4.0.0.bb</screen>This + enables you to test, and fix the package manually without having bitbake + automatically select normally.</para> + + <para>By using this in conjunction with overrides you can also disable (or + select) specific version for a specific architecture. The following + example from glibc shows that this version has been disabled for the sh3 + architecture because it doesn't support sh3. This will force bitbake to + try and select one of the other versions instead:<screen>packages/glibc/glibc_2.3.2+cvs20040726.bb:DEFAULT_PREFERENCE_sh3 = "-99"</screen></para> </section> <section id="recipes_initscripts" xreflabel="initscripts"> @@ -3418,4 +3554,4 @@ which find <para></para> </section> -</chapter> +</chapter>
\ No newline at end of file diff --git a/usermanual/reference/class_autotools.xml b/usermanual/reference/class_autotools.xml index e4ed62ece0..a9e1a5721a 100644 --- a/usermanual/reference/class_autotools.xml +++ b/usermanual/reference/class_autotools.xml @@ -25,7 +25,7 @@ SRC_URI = "${SOURCEFORGE_MIRROR}/netcat/netcat-${PV}.tar.bz2" inherit autotools</screen>The header is defined, the location of the source code and then the inherit. For the simplest cases this is all that is - required. If you need to pass additionol parameters to the configure script, + required. If you need to pass additional parameters to the configure script, such as for enabling and/or disabling options, then they can be specified via the <command>EXTRA_OECONF</command> variable. This example from the lftp recipe shows several extra options being passed to the configure @@ -75,10 +75,16 @@ do_install_append () { <para>The autotools configuration method has support for caching the results of tests. In the cross-compilation case it is sometimes necessary - to prime the cache with pre-calculated results (since tests designed to + to prime the cache with per-calculated results (since tests designed to run on the target cannot be run when cross-compiling). These are defined - via the site file for the architecture you are using which is found in - <command>org.openembedded.dev/site/<arch>-<target-os></command>.</para> + via the site file(s) for the architecture you are using and may be + specific to the package you are building.</para> + + <para>Autoconf uses site files as definied in the + <command>CONFIG_SITE</command> variable, which is a space seperate list of + files to load in the specified order. Details on how this variable is set + is provided in the <xref linkend="siteinfo_class" /> (the class + responsbile for setting the variable) section.</para> <para>There are some things that you should keep in mind about the caching of configure tests:</para> @@ -125,27 +131,19 @@ do_install_append () { calling configure and it will then not be replaced by the value from the site file.</para> - <para>Sometimes it's useful to manually check values from the site file. - This can prove useful in situations where autotools is not used but you - still need some of the same information that an autotools configure script - would require. The following from the net-snmp recipe shows an example of - using the existing site file entries for endianess to pass the required - endianess option to the configure script:<screen>do_configure() { - # endianness fun.. inspired by openssl.inc - . ${CONFIG_SITE} - if [ "x$ac_cv_c_bigendian" = "xyes" -o "x$ac_cv_c_littleendian" = "xno" ]; then - ENDIANESS=" --with-endianness=big" - elif [ "x$ac_cv_c_littleendian" = "xyes" -o "x$ac_cv_c_bigendian" = "xno" ]; then - ENDIANESS=" --with-endianness=little" - else - oefatal do_configure cannot determine endianess - fi - oe_runconf $ENDIANESS -}</screen>It is also possible to disable the use of the cached values from the - site file by clearing the definition of <command>CONFIG_SITE</command> - prior to running the configure script. Doing this will disable the use of - the site file entirely. This however should be used as a last resort. The - following example from the db recipe shows an example of this:<screen># Cancel the site stuff - it's set for db3 and destroys the + <note> + <para>Site files are applied in order, so the application specific site + files will be applied prior to the top level site file entries. The use + of conditional assignment means that the first definition found will + apply, while when not using conditionals the last definition found will + apply.</para> + </note> + + <para>It is possible to disable the use of the cached values from the site + file by clearing the definition of <command>CONFIG_SITE</command> prior to + running the configure script. Doing this will disable the use of the site + file entirely. This however should be used as a last resort. The following + example from the db recipe shows an example of this:<screen># Cancel the site stuff - it's set for db3 and destroys the # configure. CONFIG_SITE = "" do_configure() { diff --git a/usermanual/reference/class_siteinfo.xml b/usermanual/reference/class_siteinfo.xml new file mode 100644 index 0000000000..4d66e85e7c --- /dev/null +++ b/usermanual/reference/class_siteinfo.xml @@ -0,0 +1,180 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="siteinfo_class" xreflabel="siteinfo class"> + <title>siteinfo class</title> + + <para>The siteinfo class provides information for a target with a particular + emphasis on determining the names of the site files to be passed to + autoconf, as described in the <xref linkend="autotools_class" />. Full site + information for your target can be determined by looking at the table in the + class implementation found in the + <command>classes/siteinfo.bbclass</command> file. A typical entry contains + the name of the target and a list of site information for the + target:<screen> "sh4-linux": "endian-little bit-32 common-glibc sh-common",</screen>In + the above example for sh4-linux target (that's a build for an sh4 processor + using glibc) we see that the endianess and bit-size of target are defined + and an additional set of site files that should be used are listed. These + include a common site file for glibc and a common site file for sh + processors (so sh3 and sh4 can share defines). A <command>"common"</command> + entry is automatically added to the end of each of the definitions during + processing.</para> + + <para>The class makes available three variables based on the information + provided for a target:</para> + + <variablelist> + <varlistentry> + <term>SITEINFO_ENDIANESS</term> + + <listitem> + <para>Defines the endianess of the target as either + <command>"le"</command> (little endian) or <command>"be"</command> + (big endian). The target must list either + <command>endian-little</command> or <command>endian-big</command> in + it's site information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>SITEINFO_BITS</term> + + <listitem> + <para>Defines the bitsize of the target as either + <command>"32"</command> or <command>"64"</command>. The target must + list either <command>bit-32</command> or <command>bit-64</command> in + it's site information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>CONFIG_SITE</term> + + <listitem> + <para>Defines the site files to be used by autoconf. This is a space + separated list of one or more site files for the target.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>A typical use for the <command>SITEINFO_ENDIANESS</command> and + <command>SITEINFO_BITS</command> variables is to provide configuration + within a recipe based on their values. The following example from the + <emphasis>openssl</emphasis> recipe showw the correct define for the + endiness of the target being passed to openssl via the compiler flags. The + define to add to the flags is set based on the value of the + <command>SITEINFO_ENDIANESS</command> variable. Note that use of the + <emphasis>base_conditional</emphasis> method (see the <xref + linkend="recipes_advanced_python" /> section) to select a value conditional + on the endianess setting:</para> + + <para><screen> # Additional flag based on target endiness (see siteinfo.bbclass) + CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}"</screen></para> + + <section> + <title>CONFIG_SITE: The autoconf site files</title> + + <para>The autotools configuration method has support for caching the + results of tests. In the cross-compilation case it is sometimes necessary + to prime the cache with per-calculated results (since tests designed to + run on the target cannot be run when cross-compiling). These are defined + via the site file(s) for the architecture you are using and may be + specific to the package you are building.</para> + + <para>Which site files are used is determined via the + <command>CONFIG_SITE</command> definition which is calculated via the + siteinfo class. Typically the following site files will be checked for, + and used in the order found:</para> + + <variablelist> + <varlistentry> + <term>endian-(big|little)</term> + + <listitem> + <para>Either <command>endian-big</command> or + <command>endian-little</command> depending on the endianess of the + target. This site file would contain defines that only change based + on if the target is little endian or big endian.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>bit-(32|64)</term> + + <listitem> + <para>Either <command>bit-32</command> or <command>bit-64</command> + depending on the bitsize of the target. This site file would contain + defines that only change based on if the target is a 32-bit or + 64-bit cpu.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>common-(libc|uclibc)</term> + + <listitem> + <para>Either <command>common-libc</command> or + <command>common-uclibc</command> based on the C library being used + for the target. This site file would contain defines the are + specific to the C library being used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><arch>-common</term> + + <listitem> + <para>A common site file for the target architecture. For i386, + i485, i586 and i686 this would be <command>x86-common</command>, for + sh3 and sh4 this would be <command>sh-common</command> and for + various arm targets this would be + <command>arm-common</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>common</term> + + <listitem> + <para>This is a site file which is common for all targets and + contains definitions which remain the same no matter what target is + being built.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Each of the supported site files for a target is will be checked for + in several different directories. Each time a file is found it as added to + the list of files in the <command>CONFIG_SITE</command> variable. The + following directories are checked:</para> + + <variablelist> + <varlistentry> + <term>org.openembedded.dev/packages/<packagename>/site-<version>/</term> + + <listitem> + <para>This directory is for site files which are specific to a + particular version (where version is the PV of the package) of a + package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>org.openembedded.dev/packages/<packagename>/site/</term> + + <listitem> + <para>This directory is for site files which are specific to a + particular package, but apply to all versions of the package.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>org.openembedded.dev/site/</term> + + <listitem> + <para>This directory is for site files that are common to all + packages. Originally this was the only site file directory that was + supported.</para> + </listitem> + </varlistentry> + </variablelist> + </section> +</section>
\ No newline at end of file diff --git a/usermanual/reference/dirs_staging.xml b/usermanual/reference/dirs_staging.xml index c9ab09fbec..25f3685aad 100644 --- a/usermanual/reference/dirs_staging.xml +++ b/usermanual/reference/dirs_staging.xml @@ -79,7 +79,7 @@ <row> <entry>STAGING_BINDIR</entry> - <entry>${STAGING_DIR}/${BUILD_SYS}/bin</entry> + <entry>${STAGING_DIR}/${HOST_SYS}/bin</entry> </row> <row> @@ -139,7 +139,7 @@ <row> <entry>PKG_CONFIG_PATH</entry> - <entry>${STAGING_DATADIR}/pkgconfig</entry> + <entry>${STAGING_LIBDIR}/pkgconfig</entry> </row> <row> diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml index 8f9cdd53fd..e978dd50cc 100644 --- a/usermanual/usermanual.xml +++ b/usermanual/usermanual.xml @@ -17,6 +17,7 @@ <!ENTITY class-pkgconfig SYSTEM "reference/class_pkgconfig.xml"> <!ENTITY class-rootfs_ipkg SYSTEM "reference/class_rootfs_ipkg.xml"> <!ENTITY var-section SYSTEM "reference/var_section.xml"> +<!ENTITY class-siteinfo SYSTEM "reference/class_siteinfo.xml"> <!ENTITY var-src-uri SYSTEM "reference/var_src_uri.xml"> <!ENTITY class-update-alternatives SYSTEM "reference/class_update-alternatives.xml"> <!ENTITY class-update-rcd SYSTEM "reference/class_update-rc.d.xml"> @@ -865,6 +866,8 @@ NOTE: Couldn't find shared library provider for libm.so.6 &var-section; + &class-siteinfo; + &var-src-uri; &class-update-alternatives; |