diff options
author | Jamie Lenehan <lenehan@twibble.org> | 2007-01-13 05:50:11 +0000 |
---|---|---|
committer | Jamie Lenehan <lenehan@twibble.org> | 2007-01-13 05:50:11 +0000 |
commit | bba22bb70eaa7c91aab7480678df4048f44b701e (patch) | |
tree | 9b1957f05a7da18e75ccd2844e9462c201f31194 /usermanual | |
parent | 9d2ec6bcbaa0f4a83db106a461ba9362da110fbf (diff) | |
download | openembedded-bba22bb70eaa7c91aab7480678df4048f44b701e.tar.gz |
usermanual: More updated for the recipes chapter:
- Remove the structure section, it doesn't really fit in this chapter.
- Fill in the introduction part of the directories section.
- Fill out the packaging section.
Diffstat (limited to 'usermanual')
-rw-r--r-- | usermanual/chapters/recipes.xml | 563 |
1 files changed, 482 insertions, 81 deletions
diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml index bef96db3fe..8259f89b97 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -558,13 +558,6 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> <para></para> </section> - <section id="bb_structure" xreflabel="structure"> - <title>Structure</title> - - <para>talk about about what directories and files are involved - using - bitbake stuff would cover this in detail, just short summary here</para> - </section> - <section id="bb_sources" xreflabel="sources"> <title>Sources: Downloading, patching and additional files</title> @@ -685,19 +678,84 @@ mv fixed.recipe.bb myrecipe.bb</screen></para> <section id="bb_directories" xreflabel="directories"> <title>Directories: What goes where</title> - <para>target directories</para> + <para>A large part of the work or a recipe is involved with specifying + where files and found and where they have to go. It's important for + example that programs do not try and use files from <emphasis + role="bold">/usr/include</emphasis> or <emphasis + role="bold">/usr/lib</emphasis> since they are for the host system, not + the target. Similarly you don't want programs installed into <emphasis + role="bold">/usr/bin</emphasis> since that may overwrite your host system + programs with versions that don't work on the host!</para> + + <para>The following are some of the directories commonly referred to in + recipes and will be described in more detail in the rest of this + section:</para> + + <variablelist> + <varlistentry> + <term>Working directory: WORKDIR</term> - <para>unpacked source directory</para> + <listitem> + <para>This working directory for a recipe is where archive files + will be extracted, plain files will be placed, subdirectories for + logs, installed files etc will be created.</para> + </listitem> + </varlistentry> - <para>work directory</para> + <varlistentry> + <term>Unpacked source code directory: S</term> - <para>files/filespath</para> + <listitem> + <para>This is where patches are applied and where the program is + expected to be compiled in.</para> + </listitem> + </varlistentry> - <para>staging directories</para> + <varlistentry> + <term>Destination directory: D</term> - <para>install directories</para> + <listitem> + <para>The destination directory. This is where your package should + be installed into. The packaging system will then take the files + from directories under here and package them up for installation on + the target.</para> + </listitem> + </varlistentry> - <para></para> + <varlistentry> + <term>Installation directories: bindir, docdir, ...</term> + + <listitem> + <para>There are a set of variables available to describe all of the + paths on the target that you may want to use. Recipes should use + these variables rather than hard coding any specific paths.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Staging directories: STAGING_LIBDIR, STAGING_INCDIR, ...</term> + + <listitem> + <para>Staging directories are a special area for headers, libraries + and other files that are generated by one recipe that may be needed + by another recipe. A library package for example needs to make the + library and headers available to other recipes so that they can link + against them.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>File path directories: FILE, FILE_DIRNAME, FILESDIR, + FILESPATH</term> + + <listitem> + <para>These directories are used to control where files are found. + Understanding these can help you separate patches for different + versions or releases of your recipes and/or use the same patch over + multiple versions etc.</para> + </listitem> + </varlistentry> + </variablelist> <section> <title>WORKDIR: The working directory</title> @@ -1640,103 +1698,446 @@ inherit autotools</screen></para> <section id="bb_packages" xreflabel="packages"> <title>Packaging: Defining packages and their contents</title> - <para>[</para> + <para>A bitbake recipe is a set of instructions from creating one, or + more, packages for installation on the target device. Typically these are + .ipkg or .deb packages (although bitbake itself isn't associated with any + particular packaging format).</para> - <para>Talk about multiple packages and putting things in those - packages</para> + <para>By default several packages are produced automatically without any + special action required on the part of the recipe author. The following + 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 +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 + can see from above that the packaging did the following:</para> - <para>philosophy of packaging - dbg, doc, dev, main package, libs, - additional</para> + <itemizedlist> + <listitem> + <para>Created a main package, <emphasis + role="bold">helloworld_0.1-r0_sh4.ipk</emphasis>. This package + contains the helloworld binary <emphasis + role="bold">/usr/bin/helloworld</emphasis>.</para> + </listitem> - <para>PACKAGES</para> + <listitem> + <para>Created a documentation package, <emphasis + role="bold">helloworld-doc_0.1-r0_sh4.ipk</emphasis>. This package + contains the readme file <emphasis + role="bold">/usr/share/doc/helloworld/README.txt</emphasis>.</para> + </listitem> - <para>FILES</para> + <listitem> + <para>Considered creating a debug package, <emphasis + role="bold">helloworld-dbg-0.1-r0_sh4.ipk</emphasis>, a development + package <emphasis role="bold">helloworld-dev-0.1-r0_sh4.ipk</emphasis> + and a locale package <emphasis + role="bold">helloworld-locale-0.1-r0_sh4.ipk</emphasis>. It didn't + create the package due to the fact that it couldn't find any files + that would actually go in the package.</para> + </listitem> + </itemizedlist> - <para>wildcards and how they effect dir/file selection</para> + <para>There are several things happening here which are important to + understand:</para> - <para>debian naming?</para> + <orderedlist> + <listitem> + <para>There is a default set of packages that are considered for + creation. This set of packages is controlled via the <emphasis + role="bold">PACKAGES</emphasis> variable.</para> + </listitem> - <para>-dbg packages and how to handle them</para> + <listitem> + <para>For each package there is a default set of files and/or + directories that are considered to belong to those packages. The + documentation packages for example include anything found <emphasis + role="bold">/usr/share/doc</emphasis>. The set of files and + directories is controlled via the <emphasis + role="bold">FILES_<package-name></emphasis> variables.</para> + </listitem> - <para>package ordering and how it effects wildcards</para> + <listitem> + <para>By default packages that contain no files are not created and no + error is generated. The decision to create empty packages or not is + controlled via the <emphasis role="bold">ALLOW_EMPTY</emphasis> + variable.</para> + </listitem> + </orderedlist> - <para>modifying vs replacing PACKAGES</para> + <section> + <title>Philosophy</title> - <para>"find tmp/<package-name>/install"</para> + <para>Separate packaging, where possible, is of high importance in + OpenEmbedded. Many of the target devices have limited storage space and + RAM and giving distributions and users the option of not installing a + part of the package they don't need allows them to reduce the amount of + storage space required.</para> - <para>]</para> + <para>As an example almost no distributions will include documentation + or development libraries since they are not required for the day to day + operation of the device. In particular if your package provides multiple + binaries, and it would be common to only use one or the other, then you + should consider separating them into separate packages.</para> - <para></para> + <para>By default several groups of files are automatically separate out, + including:</para> - <para>The default assignment of PACKAGES and FILES is:</para> + <variablelist> + <varlistentry> + <term>dev</term> - <variablelist> - <varlistentry> - <term>PACKAGES</term> + <listitem> + <para>Any files required for development. This includes header + files, static libraries, the shared library symlinks required only + for linking etc. These would only ever need to be installed by + someone attempt to compile applications on the target device. + While this does happen it is very uncommon and so these files are + automatically moved into a separate package</para> + </listitem> + </varlistentry> - <listitem> - <para>Lists the names of each of the packages which are to be - generated.<screen>PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen></para> - </listitem> - </varlistentry> + <varlistentry> + <term>doc</term> - <varlistentry> - <term>FILES_${PN}</term> + <listitem> + <para>Any documentation related files, including man pages. These + are files which are of informational purposes only. For many + embedded devices there is no way for the user to see any of the + documentation anyway, and documentation can consume a lot of + space. By separating these out they don't take any space by + default but distributions and/or users may choose to install them + if they need some documentation on a specific package.</para> + </listitem> + </varlistentry> - <listitem> - <para>The base package, this includes everything needed to actually - run the application on the target system.<screen>FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*.so.* \ -${sysconfdir} ${sharedstatedir} ${localstatedir} /bin/* /sbin/* \ -/lib/*.so* ${datadir}/${PN} ${libdir}/${PN}/* ${datadir}/pixmaps \ -${datadir}/applications ${datadir}/idl ${datadir}/omf \ -${datadir}/sounds ${libdir}/bonobo/servers"</screen></para> - </listitem> - </varlistentry> + <varlistentry> + <term>locale</term> - <varlistentry> - <term>FILES_${PN}-dbg</term> + <listitem> + <para>Locale information provides translation information for + packages. Many users do not require these translations, and many + devices will only want to provide them for user visible + components, such as UI related items, and not for system binaries. + By separating these out it is left up to the distribution or users + to decide if they are required or not.</para> + </listitem> + </varlistentry> + </variablelist> + </section> - <listitem> - <para>Non-stripped versions executable's. OE automatically runs - strip on binary commands but leaves the originals in a .debug - directory.<screen>FILES_${PN}-dbg = "${bindir}/.debug ${sbindir}/.debug \ -${libexecdir}/.debug ${libdir}/.debug /bin/.debug /sbin/.debug \ -/lib/.debug ${libdir}/${PN}/.debug"</screen></para> - </listitem> - </varlistentry> + <section> + <title>Default packages and files</title> + + <para>The defaults package settings are defined in <emphasis + role="bold">conf/bitbake.conf</emphasis> and are suitable for a lot of + recipes without any changes. The following list shows the default values + for the packaging related variables:</para> + + <para><variablelist> + <varlistentry> + <term>PACKAGES</term> + + <listitem> + <para>This variable lists the names of each of the packages that + are to be generated.<screen>PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen>Note + that the order of packages is important: the packages are + processed in the listed order. So if two packages specify the + same file then the first package listed in packages will get the + file. This is important when packages use wildcards to specify + their contents.</para> + + <para>For example if the main package, <emphasis + role="bold">${PN}</emphasis>, contains <emphasis + role="bold">/usr/bin/*</emphasis> (i.e. all files in <emphasis + role="bold">/usr/bin</emphasis>), but you want <emphasis + role="bold">/usr/bin/tprogram</emphasis> in a separate package, + <emphasis role="bold">${PN}-tpackage</emphasis>, you would need + to either ensure that <emphasis + role="bold">${PN}-tpackage</emphasis> is listed prior to + <emphasis role="bold">${PN}</emphasis> in <emphasis + role="bold">PACKAGES</emphasis> or that <emphasis + role="bold">FILES_${PN}</emphasis> was modified to not contain + the wildcard that matches <emphasis + role="bold">/usr/bin/tprogram</emphasis>.</para> + + <para>Note that the -dbg package contains the debugging + information that has been extracted from binaries and libraries + prior to them being stripped. This package should always be the + first package in the package list to ensure that the debugging + information is correctly extracted and moved to the package + prior to any other packaging decisions being made.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FILES_${PN}</term> + + <listitem> + <para>The base package, this includes everything needed to + actually run the application on the target system.<screen>FILES_${PN} = "\ + ${bindir}/* \ + ${sbindir}/* \ + ${libexecdir}/* \ + ${libdir}/lib*.so.* \ + ${sysconfdir} \ + ${sharedstatedir} \ + ${localstatedir} \ + /bin/* \ + /sbin/* \ + /lib/*.so* \ + ${datadir}/${PN} \ + ${libdir}/${PN}/* \ + ${datadir}/pixmaps \ + ${datadir}/applications \ + ${datadir}/idl \ + ${datadir}/omf \ + ${datadir}/sounds \ + ${libdir}/bonobo/servers"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FILES_${PN}-dbg</term> + + <listitem> + <para>The debugging information extracted from non-stripped + versions of libraries and executable's. OpenEmbedded + automatically extracts the debugging information into files in + .debug directories and then strips the original files.<screen>FILES_${PN}-dbg = "\ + ${bindir}/.debug \ + ${sbindir}/.debug \ + ${libexecdir}/.debug \ + ${libdir}/.debug \ + /bin/.debug \ + /sbin/.debug \ + /lib/.debug \ + ${libdir}/${PN}/.debug"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FILES_${PN}-doc</term> + + <listitem> + <para>Documentation related files. All documentation is + separated into it's own package so that it does not need to be + installed unless explicitly required.<screen>FILES_${PN}-doc = "\ + ${docdir} \ + ${mandir} \ + ${infodir} \ + ${datadir}/gtk-doc \ + ${datadir}/gnome/help"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FILES_${PN}-dev</term> + + <listitem> + <para>Development related files. Any headers, libraries and + support files needed for development work on the target.<screen>FILES_${PN}-dev = "\ + ${includedir} \ + ${libdir}/lib*.so \ + ${libdir}/*.la \ + ${libdir}/*.a \ + ${libdir}/*.o \ + ${libdir}/pkgconfig \ + /lib/*.a \ + /lib/*.o \ + ${datadir}/aclocal"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FILES_${PN}-locale</term> + + <listitem> + <para>Locale related files.<screen>FILES_${PN}-locale = "${datadir}/locale"</screen></para> + </listitem> + </varlistentry> + </variablelist></para> + </section> - <varlistentry> - <term>FILES_${PN}-doc</term> + <section> + <title>Wildcards</title> + <para>Wildcards used in the <emphasis role="bold">FILES</emphasis> + variables are processed via the python function <emphasis + role="bold">fnmatch</emphasis>. The following items are of note about + this function:</para> + + <itemizedlist> <listitem> - <para>Documentation related files. All documentation is separated - into it's own package so that it does not need to be installed - unless explicitly required.<screen>FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ -${datadir}/gnome/help"</screen></para> + <para><emphasis role="bold">/<dir>/*</emphasis>: This will + match all files and directories in the <emphasis + role="bold">dir</emphasis>., it will not match other + directories.</para> </listitem> - </varlistentry> - - <varlistentry> - <term>FILES_${PN}-dev</term> <listitem> - <para>Development related files. Any headers, libraries and support - files needed for development work on the target.<screen>FILES_${PN}-dev = "${includedir} ${libdir}/lib*.so ${libdir}/*.la -${libdir}/*.a ${libdir}/*.o ${libdir}/pkgconfig /lib/*.a /lib/*.o -${datadir}/aclocal"</screen></para> + <para><emphasis role="bold">/<dir>/a*</emphasis>: This will + only match files, and not directories.</para> </listitem> - </varlistentry> - - <varlistentry> - <term>FILES_${PN}-locale</term> <listitem> - <para>Locale related files.<screen>FILES_${PN}-locale = "${datadir}/locale"</screen></para> + <para><emphasis role="bold">/dir</emphasis>: will include the + directory <emphasis role="bold">dir</emphasis> in the package, which + in turn will include all files in the directory and all + subdirectories.</para> </listitem> - </varlistentry> - </variablelist> + </itemizedlist> - <para></para> + <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 are now package, list the file and included in the list of + packages:</para> + + <screen>FILES-${PN}-test = "${bindir}/test" +PACKAGES += "FILES-${PN}-test"</screen> + + <para>When the package is regenerated no <emphasis + role="bold">${PN}-test</emphasis> package will be created. The reason + for this is that the <emphasis role="bold">PACKAGES</emphasis> line now + looks like this:<screen>{PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale ${PN}-test</screen>Note + how <emphasis role="bold">${PN}</emphasis> is listed prior to <emphasis + role="bold">${PN}-test</emphasis>, and if we look at the definition of + <emphasis role="bold">FILES-${PN}</emphasis> it contains the <emphasis + role="bold">${bindir}/*</emphasis> wildcard. Since <emphasis + role="bold">${PN}</emphasis> is first it'll match that wildcard are be + moved into the <emphasis role="bold">${PN}</emphasis> package prior to + processing of the <emphasis role="bold">${PN}-test</emphasis> + package.</para> + + <para>To make these work we have two options:</para> + + <orderedlist> + <listitem> + <para>Modify the definition of <emphasis + role="bold">${PN}</emphasis> so that the wildcard does not match the + test program.</para> + + <para>We could do this for example:<screen>FILES-${PN} = "${bindir}/p*"</screen>So + now this will only match things in the bindir that start with p, and + therefore not match our test program. Note that <emphasis + role="bold">FILES-${PN}</emphasis> contains a lot more entries and + we'd need to add any of the other that refer to files that are to be + included in the package. In this case we have no other files, so + it's safe to do this simple declaration.</para> + </listitem> + + <listitem> + <para>Modify the order of packages so that the <emphasis + role="bold">${PN}-test</emphasis> package is listed first.</para> + + <para>The most obvious way to do this would be to prepend our new + package name to the packages list instead of appending it:<screen>PACKAGES =+ "FILES-${PN}-test"</screen>In + some cases this would work fine, however there is a problem with + this for packages that include binaries. The package will now be + listed before the -dbg package and often this will result in the + .debug directories being included in the package. In this case we + are explicitly listing only a single file (and not using wildcards) + and therefore it would be ok.</para> + + <para>In general it's more common to have to redefine the entire + package list to include your new package plus any of the default + packages that you require:<screen>PACKAGES = "${PN}-dbg ${PN}-test ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen></para> + </listitem> + </orderedlist> + </section> + + <section> + <title>Checking the packages</title> + + <para>During recipe development it's useful to be able to check on + exactly what files went into each package, which files were not packaged + and which packages contain no files.</para> + + <para>One of easiest method is to run find on the install directory. In + the install directory there is one subdirectory created per package, and + the files are moved into the install directory as they are matched to a + specific package. The following shows the packages and files for the + helloworld example:<screen>~/oe%> find tmp/work/helloworld-0.1-r0/install +tmp/work/helloworld-0.1-r0/install +tmp/work/helloworld-0.1-r0/install/helloworld-locale +tmp/work/helloworld-0.1-r0/install/helloworld-dbg +tmp/work/helloworld-0.1-r0/install/helloworld-dev +tmp/work/helloworld-0.1-r0/install/helloworld-doc +tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr +tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share +tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc +tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld +tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld/README.txt +tmp/work/helloworld-0.1-r0/install/helloworld +tmp/work/helloworld-0.1-r0/install/helloworld/usr +tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin +tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin/helloworld +~/oe%></screen>The above shows that the -local, -dbg and -dev packages are + all empty, and the -doc and base package contain a single file each. + Uses "<emphasis role="bold">-type f</emphasis>" option to find to show + just files will make this clearer as well.</para> + + <para>In addition to the install directory the image directory (which + corresponds to the destination directory, <emphasis + role="bold">D</emphasis>) will contain any files that were not + packaged:<screen>~/oe%> find tmp/work/helloworld-0.1-r0/image +tmp/work/helloworld-0.1-r0/image +tmp/work/helloworld-0.1-r0/image/usr +tmp/work/helloworld-0.1-r0/image/usr/bin +tmp/work/helloworld-0.1-r0/image/usr/share +tmp/work/helloworld-0.1-r0/image/usr/share/doc +tmp/work/helloworld-0.1-r0/image/usr/share/doc/helloworld +~/oe%></screen>In this case all files were packaged and so there are no + left over files. Using find with "<emphasis role="bold">-type + f</emphasis>" makes this much clearer:<screen>~/oe%> find tmp/work/helloworld-0.1-r0/image -type f +~/oe%></screen></para> + + <para>Messages reading missing files are also display by bitbake during + the package task:<screen>NOTE: package helloworld-0.1-r0: task do_package: started +NOTE: the following files were installed but not shipped in any package: +NOTE: /usualdir/README.txt +NOTE: package helloworld-0.1-r0: task do_package: completed</screen>Except in + very unusual circumstances there should be no unpackaged files left + behind by a recipe.</para> + </section> + + <section> + <title>Debian naming</title> + + <para></para> + </section> + + <section> + <title>Empty packages</title> + + <para>By default empty packages are ignored. Occasionally you may wish + to actually created empty packages, typically done when you want a + virtual package which will install other packages via dependencies + without actually installing anything itself. The <emphasis + role="bold">ALLOW_EMPTY</emphasis> variable is used to control the + creation of empty packages:</para> + + <variablelist> + <varlistentry> + <term>ALLOW_EMPTY</term> + + <listitem> + <para>Controls if empty packages will be created or not. By + default this is <emphasis role="bold">"0"</emphasis> and empty + packages are not created. Setting this to <emphasis + role="bold">"1"</emphasis> will permit the creation of empty + packages (packages containing no files).</para> + </listitem> + </varlistentry> + </variablelist> + + <para></para> + </section> </section> <section id="bb_tasks" xreflabel="tasks"> |