diff options
| -rw-r--r-- | usermanual/chapters/recipes.xml | 205 | ||||
| -rw-r--r-- | usermanual/chapters/usage.xml | 903 | ||||
| -rw-r--r-- | usermanual/reference/class_autotools.xml | 48 | ||||
| -rw-r--r-- | usermanual/reference/class_image.xml (renamed from usermanual/reference/class_image_ipkg.xml) | 29 | ||||
| -rw-r--r-- | usermanual/reference/class_rootfs_ipkg.xml | 6 | ||||
| -rw-r--r-- | usermanual/reference/class_siteinfo.xml | 180 | ||||
| -rw-r--r-- | usermanual/reference/dirs_staging.xml | 4 | ||||
| -rw-r--r-- | usermanual/reference/fakeroot.xml | 4 | ||||
| -rw-r--r-- | usermanual/reference/image_types.xml | 128 | ||||
| -rw-r--r-- | usermanual/usermanual.xml | 10 |
10 files changed, 1313 insertions, 204 deletions
diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index 83c3f39279..a7904f2b58 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,53 @@ 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 versions of + that package are available then bitbake will normally select the version + that has the highest version number (where the version number 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 it to select version + <command>3.2.7</command> (the highest version number) to build.</para> + + <para>Sometimes this is not actually what you want to happen though. + Perhaps you have added a new version of the package that 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 numbers to decided + which version to build but it is also looking at the preference for each + of those version. The preference is defined via the + <command>DEFAULT_PREFERENCE</command> variable contained within the + recipe.</para> + + <para>The default preference (when no + <command>DEFAULT_PREFERENCE</command> is specified) is 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 or rename your new recipe so you can build + a working image, but what you really to do is just ignore the new 4.0.0 + version until it works. By adding:<screen>DEFAULT_PREFERENCE = "-1"</screen>to + the recipe this is what will happen. Bitbake will now ignore this version + (since all of 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 feature in conjunction with overrides you can also + disable (or select) specific versions based on the override. 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 available versions of glibc + 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 +3557,4 @@ which find <para></para> </section> -</chapter> +</chapter>
\ No newline at end of file diff --git a/usermanual/chapters/usage.xml b/usermanual/chapters/usage.xml index 2e1f887d38..f2031b3346 100644 --- a/usermanual/chapters/usage.xml +++ b/usermanual/chapters/usage.xml @@ -1,138 +1,841 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter> - <title>Usage</title> +<chapter id="chapter_using_bitbake_and_oe"> + <title>Using bitbake and OE</title> <section id="usage_introduction" xreflabel="introduction"> <title>Introduction</title> - <para>Using bitbake</para> + <para>If your reading this manual you probably already have some idea of + what OpenEmbedded is all about, which is taking a lot of software and + creating something that you can run on another device. Its all about + downloading some source code, compiling it, creating packages (like .deb + or .rpm) and/or creating boot images that can written to flash on the + device. The complexities of cross-compiling and the variety of devices to + be supported lead to a lot more complexity in on OpenEmbedded based + distribution than you'd find in a typical desktop distribution (which + doesn't get cross-compiled).</para> + + <para>A major part of OpenEmbedded deals with compiling source code for + various projects. For each project OpenEmbedded has to:</para> + + <orderedlist> + <listitem> + <para>Download the source code, and any supporting files (such as + initscripts);</para> + </listitem> + + <listitem> + <para>Extract the source code and apply any patches that might be + wanted;</para> + </listitem> + + <listitem> + <para>Configure the software if needed (such as is done by running the + configure script);</para> + </listitem> + + <listitem> + <para>Compile everything;</para> + </listitem> + + <listitem> + <para>Package up all the files into some package format, like .deb or + .rpm or .ipk, ready for installation.</para> + </listitem> + </orderedlist> + + <para>As mentioned this is made for more complex than normal due + to:</para> + + <orderedlist> + <listitem> + <para>Cross-compiling: cross-compiling is difficult, and lots of + software has no support for cross-compiling. All packages included in + OE are cross-compiled;</para> + </listitem> + + <listitem> + <para>Due to cross-compiling the executable's that are created cannot + normally be run, so any software that tries to run things as part of + it's build process need to have changes made to handle this some other + way</para> + </listitem> + </orderedlist> + + <para>Of course there's a lot more to OE then just compiling packages + though. Just some of the things that OE can handle:</para> + + <itemizedlist> + <listitem> + <para>Support for glibc and uclibc;</para> + </listitem> + + <listitem> + <para>Support for building for multiple targets;</para> + </listitem> + + <listitem> + <para>Dependencies - automatically building anything that is required + for the package your really want;</para> + </listitem> + + <listitem> + <para>Creation of flash and disk images for booting directly on the + target device;</para> + </listitem> + + <listitem> + <para>Support for various packaging formats;</para> + </listitem> + + <listitem> + <para>Automatically creating all of the cross-compiling tools you'll + need;</para> + </listitem> + + <listitem> + <para>Support for "native" packages that are built for the host + computer and not for the target;</para> + </listitem> + </itemizedlist> + + <para>This chapter assumes you have master the Getting Start guides to + OpenEmbedded (see the OpenEmbedded web site for details), and therefore + have an appropriately configured setup and have managed to build the + cross-compilers for your target. This section talks you through some of + the background on what is happening with the aim of helping you understand + how to debug and develop within OpenEmbedded.</para> </section> <section id="usage_workspace" xreflabel="workspace"> <title>Work space</title> - <para>The work directory (the working area) is where all of the source is - extracted, patched and built: ~/devel/oe/build/titan-glibc-25%> ls - tmp/work/strace-4.5.14-r1 image/ install/ strace-4.5.14/ temp/ The - subdirectories in the working area are: image When the install is being - run for the package it's files are installed into this directory. They are - moved out when being placed into individual packages and so only the - directores it created should remain. Any other that remain have not been - packaged. </para> - - <para>install The install directory contains a subdirectory per package to - be created with the appropriate files located under each package (moved - from the image directory) and some files related to processing of the - packages. </para> - - <para>strace-4.5.14 This is the directory created by the extracted source - code. (Refered to by the S variable in the recipes). </para> - - <para>temp Scripts to perform the various stages (configure, compile, etc) - and the logs containing the output of those scripts. </para> - </section> + <para>Let's start out by taking a look at a typically working area OE. + Note that this isn't exactly what you'll see - there are a lot of options that + can effect exactly how things are done, but it gives us a pretty good idea + of whats going on. What we are looking at here is the tmp directory (as + specified by TMPDIR in your local.conf):<screen>%> find tmp -maxdepth 2 -type d +tmp +tmp/stamps +tmp/cross +tmp/cross/bin +tmp/cross/libexec +tmp/cross/lib +tmp/cross/share +tmp/cross/sh4-linux +tmp/cache +tmp/cache/titan +tmp/work +tmp/work/busybox-1.2.1-r13 +tmp/work/libice-1_1.0.3-r0 +tmp/work/arpwatch-2.1a15-r2 +... +tmp/rootfs +tmp/rootfs/bin +tmp/rootfs/usr +tmp/rootfs/media +tmp/rootfs/dev +tmp/rootfs/var +tmp/rootfs/lib +tmp/rootfs/sbin +tmp/rootfs/mnt +tmp/rootfs/boot +tmp/rootfs/sys +tmp/rootfs/proc +tmp/rootfs/etc +tmp/rootfs/home +tmp/rootfs/tmp +tmp/staging +tmp/staging/man +tmp/staging/x86_64-linux +tmp/staging/pkgdata +tmp/staging/pkgmaps +tmp/staging/var +tmp/staging/sh4-linux +tmp/staging/local +tmp/staging/etc +tmp/deploy +tmp/deploy/addons +tmp/deploy/ipk +tmp/deploy/sources +tmp/deploy/images</screen></para> - <section id="usage_tempdir" xreflabel="tempdir"> - <title>Temp dir</title> + <para>The various top level directories under tmp include:</para> - <para>The temp directory contains the scripts to perform various actions - and the log files generated by those actions:</para> - </section> + <variablelist> + <varlistentry> + <term>stamps</term> + + <listitem> + <para>Nothing of interest to users in here. These time stamps are + used by bitbake to keep track of what tasks it has completed and + what tasks it still has outstanding. This is how it knows that + certain actions have been completed and it doesn't need to do them + again.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cross</term> + + <listitem> + <para>Contains the cross-compiler toolchain. That is the gcc and + binutils that run on the host system but produce output for the + target system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cache</term> - <section id="usage_installdir" xreflabel="installdir"> - <title>Install dir</title> + <listitem> + <para>Nothing of interest to users in here. This contains the + bitbake parse cache and is used to avoid the need to parse all of + the recipes each time bitbake is run. This makes bitbake a lot + faster on the 2nd and subsequent runs.</para> + </listitem> + </varlistentry> - <para>The install directory contains one subdirectory per package to be - generated, each containing the files to be included in that package, and - some package control files:</para> + <varlistentry> + <term>work</term> + + <listitem> + <para>The work directory. This is the directory in which all + packages are built - this is where the source code is extract, + patches applied, software configure, compiled, installed and + package. This is where you'll spend most of you time looking when + working in OE.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>rootfs</term> + + <listitem> + <para>The generated root filesystem image for your target device. + This is the contents of the root filesystem (NOTE: fakeroot means it + doesn't have the correct device special nodes and permissions to use + directly).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>staging</term> + + <listitem> + <para>Contains the staging area, which is used to stored natively + compiled tools and and libraries and headers for the target that are + required for building other software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>deploy</term> + + <listitem> + <para>Contains the final output from OE. This includes the + installation packages (typically .ipkg packages) and flash and/or + disk images. This is where you go to get the final product.</para> + </listitem> + </varlistentry> + </variablelist> <para></para> + + <section id="usage_workdir" xreflabel="work directory"> + <title>work directory</title> + + <para>The working directory is where all files are extracted and + everything is configured, compiled and packaged. In other words this is + where all the action happens. Each bitbake recipe will produce a + corresponding directory in the working area, with the name containing + the recipe name, version and the release number (as defined by the PR + variable in the recipe).</para> + + <para>In the following example we show some of the directories that are + created and in this case they are created directly in the work + directory:<screen>~%> find tmp/work -maxdepth 1 -type d | head -4 +tmp/work +tmp/work/busybox-1.2.1-r13 +tmp/work/libice-1_1.0.3-r0 +tmp/work/arpwatch-2.1a15-r2</screen>Depending on your distribution settings + you may have an additional subdirectory present:<screen>~%> find tmp/work -maxdepth 2 -type d | head -4 +tmp/work +tmp/work/sh4-linux +tmp/work/sh4-linux/busybox-1.2.1-r13 +tmp/work/sh4-linux/libice-1_1.0.3-r0 +tmp/work/sh4-linux/arpwatch-2.1a15-r2</screen></para> + + <para>where are additional directory corresponding to the target + architecture and OS has been inserted. This is added by the use of the + <emphasis>multimachine</emphasis> feature which is used to allow builds + for multiple targets within the one work directory (which in turn + enables the sharing of native functionality and a reduction in the time + taken to build for multiple machines). We'll assume multimachine is not + being used for the rest of this chapter, just remember to add the extra + directory if your distribution is using it.</para> + + <para>Using lzo 1.08 as an example we'll examine the working directory + and see what it contain for a typical recipe:<screen>%> find tmp/work/lzo-1.08-r14 -maxdepth 1 +tmp/work/lzo-1.08-r14 +tmp/work/lzo-1.08-r14/temp +tmp/work/lzo-1.08-r14/lzo-1.08 +tmp/work/lzo-1.08-r14/install +tmp/work/lzo-1.08-r14/image</screen></para> + + <para>The directory, <emphasis + role="bold">tmp/work/lzo-1.08-r14</emphasis>, is know as the working + directory for the recipe is held in the <emphasis + role="bold">WORKDIR</emphasis> variable in bitbake. You'll sometimes see + recipes refer directly to <emphasis role="bold">WORKDIR</emphasis> and + if so this is the directory they are referring to. The <emphasis + role="bold">1.08</emphasis> is the version of lzo and the <emphasis + role="bold">r14</emphasis> is the release number, as defined by the + <emphasis role="bold">PR</emphasis> variable in the recipe.</para> + + <para>Under <emphasis role="bold">WORKDIR</emphasis> there are four + directories:</para> + + <variablelist> + <varlistentry> + <term>temp</term> + + <listitem> + <para>The temp directories contains logs and in some cases scripts + that actually implement specific tasks.</para> + + <para>You can look at the logs in this directory to get more + information into what happened (or didn't happen). This is usually + the first thing to look at when things are going wrong and these + usually need to be included when reporting bugs.</para> + + <para>The scripts can be used to see what a particular task, such + as configure or compile, is trying to do.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>lzo-1.08</term> + + <listitem> + <para>This is the unpacked source code directory, which was + created when the lzo source code was extracted in this directory. + The name and format of this directory is therefore dependent on + the actual source code packaging. Within recipes this directory is + referred to as <emphasis role="bold">S</emphasis> and is usually + expected to be named like this, that is + <emphasis><name>-<version></emphasis>. If the source + code extracts to somewhere else you would need to manually specify + the value of <emphasis role="bold">S</emphasis> in your + recipe.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>install</term> + + <listitem> + <para>The installation directory (or destination directory) is + where the software needs to be installed into in order to be + packaged. This directory is referred to as <emphasis + role="bold">D</emphasis> in recipes. So instead of installing into + <emphasis role="bold">/usr/bin</emphasis> and <emphasis + role="bold">/usr/lib</emphasis> for example you would need to + install into <emphasis role="bold">${D}/usr/bin</emphasis> and + <emphasis role="bold">${D}/usr/lib</emphasis> in order for the + packaging system to work.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>image</term> + + <listitem> + <para>The image directory is used to split the installed files + into separate packages. One subdirectory is created per package to + be generated and the files and moved from the install directory + (<emphasis role="bold">D</emphasis>) over to this directory as + each packaging instruction is processed. Typically there will be + separate documentation (<emphasis>-doc</emphasis>), debugging + (<emphasis>-dbg</emphasis>) and development + (<emphasis>-dev</emphasis>) packages automatically created.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The various variables that can be used in a recipe are described + in detail in the recipes chapter of this manual.</para> + + <para>What can you do with this information? How about checking out what + happened during the configuration of lzo:<screen>~%> less tmp/work/lzo-1.08-r14/temp/log.do_configure.* +... +checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fschedule-insns bug... unknown +checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fstrength-reduce bug... unknown +checking whether ccache sh4-linux-gcc -ml -m4 accepts -fstrict-aliasing... yes +checking the alignment of the assembler... 0 +checking whether to build assembler versions... no +configure: creating ./config.status +config.status: creating Makefile +config.status: creating examples/Makefile +config.status: creating include/Makefile +config.status: creating ltest/Makefile +config.status: creating minilzo/Makefile +config.status: creating src/Makefile +config.status: creating tests/Makefile +config.status: creating config.h +config.status: executing depfiles commands</screen></para> + + <para>Or perhaps you want to see which files were included in each of + the generated packages:<screen>~%> find tmp/work/lzo-1.08-r14/install +tmp/work/lzo-1.08-r14/install +tmp/work/lzo-1.08-r14/install/lzo-doc +tmp/work/lzo-1.08-r14/install/lzo-dbg +tmp/work/lzo-1.08-r14/install/lzo-dbg/usr +tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib +tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug +tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug/liblzo.so.1.0.0 +tmp/work/lzo-1.08-r14/install/lzo-dev +tmp/work/lzo-1.08-r14/install/lzo-dev/usr +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo2a.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1y.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1b.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1f.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoconf.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1x.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo16bit.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1a.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1z.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoutil.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1c.h +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.a +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.so +tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.la +tmp/work/lzo-1.08-r14/install/lzo.shlibdeps +tmp/work/lzo-1.08-r14/install/lzo-locale +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></para> + </section> </section> - <section id="usage_deploydir" xreflabel="deploydir"> - <title>Deploy dir</title> + <section id="usage_tasks" xreflabel="tasks"> + <title>Tasks</title> + + <para>When you build a software package you generally perform a number of + steps or tasks. These would include things like "download the source + code", "unpack the source code", "run the configure script", "build the + software", "install the software" etc. OpenEmbedded builds software in a + similar way - by performing a set of tasks. Understanding these tasks is + critical to understanding how things get done in OpenEmbedded.</para> + + <para></para> + + <para>The following is a list of the most commonly seen tasks:</para> + + <variablelist> + <varlistentry> + <term>fetch</term> + + <listitem> + <para>The fetch task is responsible for fetching any source code + that is required. This means things such as downloading files and + checking out from svn or git repositories for example.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>unpack</term> + + <listitem> + <para>The unpack task is responsible for extracting files from + archives, such as .tar.gz, into the working area and copying any + additional files into the working area.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>patch</term> + + <listitem> + <para>The patch task is responsible for applying any patches to the + unpacked source code</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>configure</term> + + <listitem> + <para>The configure task takes care of the configuration of the + package. Running a configure script ("./configure <options>") + is probably the form of configuration that is most recognised but + it's not the only configuration system that exists.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>compile</term> - <para>The deploy directory is where the final packaged files (typically - .ipk files) and and flash images or nfs images etc end up. For our strace - example we end up with just two .ipk files, one for the application and - one for the documentation.</para> + <listitem> + <para>The compile task actually compiles the software. This could be + as simple as running "make".</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>populate_staging (stage)</term> + + <listitem> + <para>The populate_staging task (stage is an alternate, easier to + type name, that can be used to refer to this task) is responsible + for making available libraries and headers (if any) that may be + required by other packages to build. For example if you compile zlib + then it's headers and the library need to be made available for + other applications to include and link against.</para> + + <para>NOTE that this is different to the install (and packaging) + related tasks in that this is making available things for use during + build on the development host while the installed files are being + made available for use on the target device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term></term> + + <listitem> + <para></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>install</term> + + <listitem> + <para>The install task is responsible for actually installing the + software. Now this needs to install the software into the + destination directory (${D}) but once package the destination + directory will be removed from all the files. In other words if you + install something into ${D}/bin then it will end up in the /bin + directory in the package and therefore on the target.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>package</term> + + <listitem> + <para>The package task takes the installed files and splits them + into separate directories under the ${WORKDIR}/install directory, + one per package. It moves the files for the destination directory, + ${D}, that they were installed in into the appropriate packages + subdirectory. Usually there will be a main package a separate + documentation (-doc), development (-dev) and debugging packages + (-dbg) for example.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>package_write</term> + + <listitem> + <para>The package_write task is responsible for taking each packages + subdirectory and creating any actual installation package, such as + .ipk, .deb or .rpm.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term></term> + + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + + <para></para> + + <para>Note that these are not the only possible set of tasks. There are + various methods available to insert additional tasks in between existing + tasks if needed. As an example the insane.bbclass, which performs various + QA checks, does these checks by inserting a new task, qa_configure, + between the configure and compile tasks to check on the result of + configuration and another new tasks, qa_staging, between populate_staging + and build to validate the files that have been staged.</para> + + <para></para> + + <para>You can see a list of all the tasks available for a specific recipe + by explicitly calling bitbake on the recipe and asking it for a list of + tasks:</para> + + <para><screen>~%> bitbake -b packages/perl/perl_5.8.8.bb -c listtasks +NOTE: package perl-5.8.8: started +NOTE: package perl-5.8.8-r11: task do_listtasks: started +do_fetchall +do_listtasks +do_rebuild +do_compile +do_build +do_populate_staging +do_mrproper +do_fetch +do_configure +do_clean +do_package +do_unpack +do_install +do_package_write +do_distribute_sources +do_showdata +do_qa_configure +do_qa_staging +do_patch +NOTE: package perl-5.8.8-r11: task do_listtasks: completed +NOTE: package perl-5.8.8: completed +~%> </screen></para> + + <para>Note that <emphasis>do_</emphasis> prefixed to the tasks - the + <emphasis>do_<task></emphasis> is the name of the method that + implements the required functionality for + <emphasis><task></emphasis>, so the above is actually listing the + methods that implement the available tasks. It's sometimes a but confusing + but just remember that the do_ is the method name (with a definition + usually found in the of the .bbclass files in the classes + directory.)</para> </section> - <section id="usage_singlepkg" xreflabel="singlepkg"> + <section id="usage_workwithsinglepackage" + xreflabel="working with a single package"> <title>Working with a single package</title> <para>When working on fixing and/or creating a single recipe you can ask - bitbake to deal with a single .bb file only. The -b <bb-file> option - asks bitbake to only process the named file. So to clean and rebuild a - single package you can do: %> bitbake -b <bb-file> -c clean %> - bitbake -D -b <bb-file> The various options that are useful here - are: -b <bb-file> Specify which recipe to process -c <action> - Specify which action to perform (see below) -D Enable debugging output. - This gives you a lot more output during the operation. -f Force on - operation. This is useful in getting bitbake to perform some operation it - normally wouldn't do. For example, if you try and compile twice ina row - then bitbake will not do anything on the second attempt since it has - already gone through the compile stage. By adding -f forces it the action - to take place. The most common actions (used with -c) are: fetch Will - download any files that need to be fetched. unpack Extracts the source - code into the working directory, but does not apply any patches. patch - Applies patches into the source in the working directory. configure Runs - the configuration task for the recipe. compile Actually compile - everything. stage Copy required files into the staging area. install - Install files that are going to be package. package Package files. - Normally this means creating the .ipkg files. clean Clean the package - - this deletes the entire working directory for the package, so on the next - build the source will be extracted, patches applied etc. Note that each - action will run any preceeding actions that have not yet been performed. - So starting with compile will also peform the fetch, unpack, patch and - configure actions. A typically development session would involve editing - files in the working directory and running: %> bitbake -f - packages/testapp/testapp_4.3.bb -c compile (Try and compile) look at logs, - edit some files in working area %> bitbake -f - packages/testapp/testapp_4.3.bb -c compile -f (Force re-compile) and then - once appropriate patches have been made and the recipe updated: %> - bitbake -f packages/testapp/testapp_4.3.bb -c clean (Remove working files) - %> bitbake -f packages/testapp/testapp_4.3.bb (Try everything from - scratch) A full list of available tasks for a specific package can be - obtained with the listtasks task: %> bitbake -f - packages/testapp/testapp_4.3.bb -c listtasks </para> + bitbake to deal directly with a single .bb file only. The <emphasis>-b + <bb-file></emphasis> option asks bitbake to only process the named + file. Note that this ignores any dependencies that are in the recipe, so + these must have already been handled.</para> + + <para>A typically example of this is to clean and then rebuild a package + with some debugging information:</para> + + <para><screen>%> bitbake -b <bb-file> -c clean +%> bitbake -b <bb-file> -D</screen></para> + + <para>The various options to bitbake that are useful here are:</para> + + <variablelist> + <varlistentry> + <term>-b <bb-file></term> + + <listitem> + <para>Specify which recipe to process;</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-c <action></term> + + <listitem> + <para>Specify which action to perform, typically the name of one of + the tasks supported by the recipe;</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-D</term> + + <listitem> + <para>Display debugging information, use two <emphasis + role="bold">-D</emphasis>'s for additional debugging.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-f</term> + + <listitem> + <para>Force an operation. This is useful in getting bitbake to + perform some operation it normally wouldn't do. For example, if you + try and compile twice in a row then bitbake will not do anything on + the second attempt since it has already performed the compile task. + By adding <emphasis role="bold">-f</emphasis> it will force it to + perform the action regardless of if it thinks it's been done + previously.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The most common actions (used with -c) are:</para> + + <variablelist> + <varlistentry> + <term>fetch</term> + + <listitem> + <para>Try to download all of the required source files, but don't do + anything else with them.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>unpack</term> + + <listitem> + <para>Unpack the source file but don't apply the patches yet. + Sometimes you may want to look at the extracted, but not patched + source code and that's what just unpacking will give you (some + time's handy to get diffs generated against the original + source).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>patch</term> + + <listitem> + <para>Apply any patches.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>configure</term> + + <listitem> + <para>Performs and configuration that is required for the + software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>compile</term> + + <listitem> + <para>Perform the actual compilation steps of the software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>stage</term> + + <listitem> + <para>If any files, such as header and libraries, will be required + by other packages then they need to be installed into the staging + area and that's what this task takes care of.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>install</term> + + <listitem> + <para>Install the software in preparation for packaging.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>package</term> + + <listitem> + <para>Package the software. Remember that this moves the files from + the installation directory, D, into the packing install area. So to + re-package you also need to re-install first.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>clean</term> + + <listitem> + <para>Delete the entire directory for this version of the software. + Usually done to allow a test build with no chance of old files or + changes being left behind.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Note that each of the actions that corresponds to task's will run + any preceding tasks that have not yet been performed. So starting with + compile will also perform the fetch, unpack, patch and configure + actions.</para> + + <para>A typically development session might involve editing files in the + working directory and recompiling until it all works:<screen>[... test ...] +%> bitbake -b packages/testapp/testapp_4.3.bb -c compile -D + +[... save a copy of main.c and make some changes ...] +%> vi tmp/work/testapp-4.3-r0/main.c +%> bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f + +[... create a patch and add it to the recipe ...] +%> vi packages/testapp/testapp_4.3.bb + +[... test from clean ...] +%> bitbake -b packages/testapp/testapp_4.3.bb -c clean +%> bitbake -b packages/testapp/testapp_4.3.bb + +[... NOTE: How to create the patch is not covered at this point ...]</screen></para> + + <para>Here's another example showing how you might go about fixing up the + packaging in your recipe:<screen>%> bitbake -b packages/testapp/testapp_4.3.bb -c install -f +%> bitbake -b packages/testapp/testapp_4.3.bb -c stage -f +%> find tmp/work/testapp_4.3/install +... +%> vi packages/testapp/testapp_4.3.bb</screen>At this stage you play with + the <emphasis role="bold">PACKAGE_</emphasis> and <emphasis + role="bold">FILES_</emphasis> variables and then repeat the above + sequence.</para> + + <para>Note how we install and then stage. This is one of those things + where understanding the tasks helps a lot! Remember that stage moves the + files from where they were installed (${D}) into the various + subdirectories (under <emphasis role="bold">${WORKDIR}/instal</emphasis>l) + for each package. So if you try and run a stage task without a prior + install there won't be any files there to stage! Note also that the stage + tasks clears all the subdirectories in <emphasis + role="bold">${WORKDIR}/install</emphasis> so you won't get any left over + files. But beware, the install task doesn't clear <emphasis + role="bold">${D}</emphasis> directory, so any left over files from a + previous packing attempt will be left behind (which is ok if all you care + about it staging).</para> </section> - <section id="usage_bbinteractive" xreflabel="bbinteractive"> + <section id="usage_interactive_bitbake" xreflabel="interactive bitbake"> <title>Interactive bitbake</title> - <para>To interactively test things use: %> bitbake -i this will open - the bitbake shell. From here there are a lot of commands available (try - help). First thing you will want to do is parse all of the recipes. - BB>> parse You can now build a specific recipe: BB>> build - net-snmp If it fails you may want to clean the build before trying again: - BB>> clean net-snmp If you update the recipe by editing the .bb file - (to fix some issues) then you will want to clean the package, reparse the - modified recipe, and the build again: BB>> clean net-snmp BB>> - reparse net-snmp BB>> build net-snmp Note that you can use wildcards - in the bitbake shell as well: BB>> build t* The interacive mode was - most useful with bitbake versions prior to 1.4 where the entire set of - recipes had to be reparsed each time bitbake was run. Since bitbake 1.4 - the parseing is cached between runs and so it is no where near as painful - to run individual bitbake commands and therefore the interactive mode is - no longer as important as it once was. [edit] </para> + <para>To interactively test things use:<screen>%> bitbake -i</screen>this + will open the bitbake shell. From here there are a lot of commands + available (try help).</para> + + <para>First thing you will want to do is parse all of the recipes (recent + bitbake version do this automatically when needed, so you don't need to + manually do this anymore):<screen>BB>> parse</screen>You can now + build a specific recipe:<screen>BB>> build net-snmp</screen>If it + fails you may want to clean the build before trying again:<screen>BB>> clean net-snmp</screen>If + you update the recipe by editing the .bb file (to fix some issues) then + you will want to clean the package, reparse the modified recipe, and the + build again:<screen>BB>> clean net-snmp +BB>> reparse net-snmp +BB>> build net-snmp</screen>Note that you can use wildcards in the + bitbake shell as well:<screen>BB>> build t*</screen></para> + + <para></para> </section> <section id="usage_devshell" xreflabel="devshell"> <title>Devshell</title> - <para></para> + <para>[To be done]</para> </section> - <section id="usage_workflow" xreflabel="workflow"> - <title>Workflow</title> + <section id="usage_patches" xreflabel="patching"> + <title>Patching and patch management</title> - <para>fetch Will download any files that need to be fetched. unpack - Extracts the source code into the working directory, but does not apply - any patches. patch Applies patches into the source in the working - directory. configure Runs the configuration task for the recipe. compile - Actually compile everything. stage Copy required files into the staging - area. install Install files that are going to be package. package Package - files. Normally this means creating the .ipkg files. </para> + <para>[To be done]</para> </section> </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_image_ipkg.xml b/usermanual/reference/class_image.xml index 0b440eba45..7d203f888c 100644 --- a/usermanual/reference/class_image_ipkg.xml +++ b/usermanual/reference/class_image.xml @@ -1,25 +1,26 @@ <?xml version="1.0" encoding="UTF-8"?> -<section id="image_ipkg_class" xreflabel="image_ipkg class"> - <title>image_ipkg class</title> +<section id="image_class" xreflabel="image class"> + <title>image class</title> - <para>The image_ipkg class is used to generate filesystem images containing - a root filesystem, as generated by the <xref linkend="rootfs_ipkg_class" />, - for use on the target device. This could be a <emphasis>jffs2</emphasis> - image which is to be written directly into the flash on the target device - for example. In addition this class also configures the ipkg feeds (where to - get updates from) and is able to generate multiple different image - types.</para> + <para>The image class is used to generate filesystem images containing a + root filesystem, as generated by the rootfs class for the package type, such + as <xref linkend="rootfs_ipkg_class" />, for use on the target device. This + could be a <emphasis>jffs2</emphasis> image which is to be written directly + into the flash on the target device for example. In addition this class also + configures the ipkg feeds (where to get updates from) and is able to + generate multiple different image types.</para> <para>Summary of the actions performed by the <emphasis>image_ipkg</emphasis> class:</para> <orderedlist> <listitem> - <para>Inherits the <xref linkend="rootfs_ipkg_class" /> in order to - bring in the functionality required to generate a root filesystem image. - The root filesystem image is generate from a set of ipkg packages, and - then the required images are generated using the contents of the root - filesystem;</para> + <para>Inherits the rootfs class for the appropriate package type, + typically <xref linkend="rootfs_ipkg_class" />, in order to bring in the + functionality required to generate a root filesystem image. The root + filesystem image is generate from a set of of packages (typically .ipkg + packages), and then the required images are generated using the contents + of the root filesystem;</para> </listitem> <listitem> diff --git a/usermanual/reference/class_rootfs_ipkg.xml b/usermanual/reference/class_rootfs_ipkg.xml index 930272ebf9..b60adf8e70 100644 --- a/usermanual/reference/class_rootfs_ipkg.xml +++ b/usermanual/reference/class_rootfs_ipkg.xml @@ -8,8 +8,8 @@ the root filesystem of the target device.</para> <para>This class is normally not used directly, but instead used from the - <xref linkend="image_ipkg_class" /> which creates images from a set of - <command>.ipkg</command> files.</para> + <xref linkend="image_class" /> which creates images from a set of package + (typically <command>.ipkg</command>) files.</para> <para>Summary of actions performed by the <emphasis>rootfs_ipkg</emphasis> class:</para> @@ -210,6 +210,6 @@ <para>The class also provides a function <command>real_do_rootfs</command> which is executed without <xref linkend="fakeroot" /> and therefore can be - used from other classes, such as <xref linkend="image_ipkg_class" />, that + used from other classes, such as <xref linkend="image_class" />, that are already running under the control of <xref linkend="fakeroot" />.</para> </section>
\ No newline at end of file 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/reference/fakeroot.xml b/usermanual/reference/fakeroot.xml index 68892fce87..5eb6a48eb0 100644 --- a/usermanual/reference/fakeroot.xml +++ b/usermanual/reference/fakeroot.xml @@ -5,7 +5,7 @@ <para>The fakeroot program is designed to allow non-root users to perform actions that would normally require root privileges as part of the package generation process. It is used by the <xref linkend="rootfs_ipkg_class" /> - for root filesystem creation and by the <xref linkend="image_ipkg_class" /> + for root filesystem creation and by the <xref linkend="image_class" /> for the creation of filesystem images. Some recipes also use fakeroot to assist with parts of the package installation (usually) or building where root privligeses are expected by the package.</para> @@ -32,7 +32,7 @@ the command will fail, telling is that we do not have permission to create device nodes:<screen>~%> mknod hdc b 22 0 mknod: `hdc': Operation not permitted</screen>Yet the <xref - linkend="image_ipkg_class" /> is able to create device nodes and include + linkend="image_class" /> is able to create device nodes and include them in the final images, all without the need to have root privileges.</para> diff --git a/usermanual/reference/image_types.xml b/usermanual/reference/image_types.xml index 2efb9b8072..8d01559fc0 100644 --- a/usermanual/reference/image_types.xml +++ b/usermanual/reference/image_types.xml @@ -7,7 +7,7 @@ several variables which can be used to control the type of output images and the settings for those images, such as endianess or compression ratios. This section details the available images and the variables that effect them. See - the <xref linkend="image_ipkg_class" /> section for details on how image + the <xref linkend="image_class" /> section for details on how image generation is configured.</para> <para>The final root file system will consist of all of the files located in @@ -93,17 +93,21 @@ <para>Creates jffs2 <emphasis>"Journaling flash file system 2"</emphasis> images. This is a read/write, compressed filesystem for mtd (flash) devices. It is not supported for block - devices.<screen>IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ + devices.<screen>IMAGE_CMD_jffs2 = "mkfs.jffs2 \ + -x lzo \ + --root=${IMAGE_ROOTFS} \ --faketime \ --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ ${EXTRA_IMAGECMD}"</screen></para> - <para>The <command>EXTRA_IMAGECMD</command> variable for jffs2 is - passed to <command>mkfs.jffs2</command> and by default is used to - enabled pad, to define the endianess and to specify the block - size:</para> + <para>The <command>EXTRA_IMAGECMD</command> variable for jffs2 + passed to <command>mkfs.jffs2</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_jffs2 = ""</screen></para> - <para><screen>EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000"</screen></para> + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for jffs2 was set to + enable padding, to define the endianess and to specify the block + size:<screen><emphasis>EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000"</emphasis></screen></para> </listitem> </varlistentry> @@ -121,8 +125,8 @@ ${EXTRA_IMAGECMD}"</screen></para> <para>The <command>EXTRA_IMAGECMD</command> variable for cramfs is - passed to <command>mkcramfs</command> and is not used by - default.</para> + passed to <command>mkcramfs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_cramfs = ""</screen></para> </listitem> </varlistentry> @@ -137,8 +141,8 @@ ${EXTRA_IMAGECMD}"</screen></para> <para>The <command>EXTRA_IMAGECMD</command> variable for ext2 is - passed to <command>genext2fs</command> and is not used by - default.</para> + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext2 = ""</screen></para> <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to specify the size of the ext2 image and is set to 64k by @@ -147,13 +151,35 @@ </varlistentry> <varlistentry> + <term>ext3</term> + + <listitem> + <para>Creates an <emphasis>"Extended Filesystem 3"</emphasis> image + file. This is the standard Linux journaling file system.<screen>IMAGE_CMD_ext3 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \ + -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3 \ + ${EXTRA_IMAGECMD}; \ +tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext3 is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext3 = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext3 image and is set to 64k by + default:<screen>IMAGE_ROOTFS_SIZE_ext3 = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> <term>ext2.gz</term> <listitem> <para>Creates a version of the ext2 filesystem image compressed with <command>gzip</command>.</para> - <para><screen>IMAGE_CMD_ext2.gz = "mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \ + <para><screen>IMAGE_CMD_ext2.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz && \ +mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \ genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \ ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2 \ ${EXTRA_IMAGECMD}; \ @@ -163,8 +189,8 @@ mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2.gz \ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> <para>The <command>EXTRA_IMAGECMD</command> variable for ext2.gz is - passed to <command>genext2fs</command> and is not used by - default.</para> + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext2.gz = ""</screen></para> <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to specify the size of the ext2 image and is set to 64k by @@ -175,6 +201,36 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> </varlistentry> <varlistentry> + <term>ext3.gz</term> + + <listitem> + <para>Creates a version of the ext3 filesystem image compressed with + <command>gzip</command>.</para> + + <para><screen>IMAGE_CMD_ext3.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz && \ +mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \ +genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3 \ + ${EXTRA_IMAGECMD}; \ +tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \ +gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \ +mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3.gz \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3.gz; \ +rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext3.gz is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext3.gz = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext2 image and is set to 64k by + default:</para> + + <para><screen>IMAGE_ROOTFS_SIZE_ext3.gz = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> <term>squashfs</term> <listitem> @@ -193,10 +249,12 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> ${EXTRA_IMAGECMD} -noappend"</screen></para> <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is - passed to <command>mksquashfs</command> and by default is used - specify the endianess and block size of the filesystem:</para> + passed to <command>mksquashfs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_squashfs = ""</screen></para> - <para><screen>EXTRA_IMAGECMD_squashfs = "-le -b 16384"</screen></para> + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for squashfs specified + the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs = "-le -b 16384"</emphasis></screen></para> </listitem> </varlistentry> @@ -220,10 +278,12 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> ${EXTRA_IMAGECMD} -noappend"</screen></para> <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is - passed to <command>mksquashfs-lzma</command> and by default is used - specify the endianess and block size of the filesystem:</para> + passed to <command>mksquashfs-lzma</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_squashfs-lzma = ""</screen></para> - <para><screen>EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384"</screen></para> + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for squashfs specified + the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384"</emphasis></screen></para> </listitem> </varlistentry> @@ -231,8 +291,7 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> <term>tar</term> <listitem> - <para>Creates a <command>bzip2</command> compressed .tar - archive.</para> + <para>Creates a .tar archive.</para> <para><screen>IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} && \ tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ."</screen></para> @@ -271,6 +330,31 @@ rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> supported for tar.bz2 images.</para> </listitem> </varlistentry> + + <varlistentry> + <term>cpio</term> + + <listitem> + <para>Creates a .cpio archive:<screen>IMAGE_CMD_cpio = "cd ${IMAGE_ROOTFS} && \ + (find . | cpio -o -H newc >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio)"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for cpio images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cpio.gz</term> + + <listitem> + <para>Creates a <command>gzip</command> compressed .cpio + archive.<screen>IMAGE_CMD_cpio.gz = cd ${IMAGE_ROOTFS} && \ + (find . | cpio -o -H newc | gzip -c -9 >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio.gz)"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for cpio.gz images.</para> + </listitem> + </varlistentry> </variablelist> <para>The above built in list of image types is defined in the bitbake diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml index 690ac5a01b..fa17ac2e12 100644 --- a/usermanual/usermanual.xml +++ b/usermanual/usermanual.xml @@ -5,6 +5,7 @@ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY chapter-usage SYSTEM "chapters/usage.xml"> <!ENTITY chapter-recipes SYSTEM "chapters/recipes.xml"> <!ENTITY class-autotools SYSTEM "reference/class_autotools.xml"> <!ENTITY class-binconfig SYSTEM "reference/class_binconfig.xml"> @@ -12,11 +13,12 @@ <!ENTITY dirs-staging SYSTEM "reference/dirs_staging.xml"> <!ENTITY class-distutils SYSTEM "reference/class_distutils.xml"> <!ENTITY fakeroot SYSTEM "reference/fakeroot.xml"> -<!ENTITY class-image_ipkg SYSTEM "reference/class_image_ipkg.xml"> +<!ENTITY class-image SYSTEM "reference/class_image.xml"> <!ENTITY image-types SYSTEM "reference/image_types.xml"> <!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"> @@ -834,7 +836,7 @@ NOTE: Couldn't find shared library provider for libm.so.6 <!-- Bitbake usage chapter --> - <!-- &chapter-usage; - this is not ready yet --> + <!-- &chapter-usage; - this is not ready yet --> <!-- Bitbake recipies chapter --> @@ -857,7 +859,7 @@ NOTE: Couldn't find shared library provider for libm.so.6 &fakeroot; - &class-image_ipkg; + &class-image; &image-types; @@ -867,6 +869,8 @@ NOTE: Couldn't find shared library provider for libm.so.6 &var-section; + &class-siteinfo; + &var-src-uri; &class-update-alternatives; |