From bba22bb70eaa7c91aab7480678df4048f44b701e Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Sat, 13 Jan 2007 05:50:11 +0000 Subject: 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. --- usermanual/chapters/recipes.xml | 563 ++++++++++++++++++++++++++++++++++------ 1 file changed, 482 insertions(+), 81 deletions(-) (limited to 'usermanual') 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 -
- Structure - - talk about about what directories and files are involved - using - bitbake stuff would cover this in detail, just short summary here -
-
Sources: Downloading, patching and additional files @@ -685,19 +678,84 @@ mv fixed.recipe.bb myrecipe.bb
Directories: What goes where - target directories + 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 /usr/include or /usr/lib since they are for the host system, not + the target. Similarly you don't want programs installed into /usr/bin since that may overwrite your host system + programs with versions that don't work on the host! + + 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: + + + + Working directory: WORKDIR - unpacked source directory + + 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. + + - work directory + + Unpacked source code directory: S - files/filespath + + This is where patches are applied and where the program is + expected to be compiled in. + + - staging directories + + Destination directory: D - install directories + + 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. + + - + + Installation directories: bindir, docdir, ... + + + 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. + + + + + Staging directories: STAGING_LIBDIR, STAGING_INCDIR, ... + + + 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. + + + + + File path directories: FILE, FILE_DIRNAME, FILESDIR, + FILESPATH + + + 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. + + +
WORKDIR: The working directory @@ -1640,103 +1698,446 @@ inherit autotools
Packaging: Defining packages and their contents - [ + 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). - Talk about multiple packages and putting things in those - packages + 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:[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: completedWe + can see from above that the packaging did the following: - philosophy of packaging - dbg, doc, dev, main package, libs, - additional + + + Created a main package, helloworld_0.1-r0_sh4.ipk. This package + contains the helloworld binary /usr/bin/helloworld. + - PACKAGES + + Created a documentation package, helloworld-doc_0.1-r0_sh4.ipk. This package + contains the readme file /usr/share/doc/helloworld/README.txt. + - FILES + + Considered creating a debug package, helloworld-dbg-0.1-r0_sh4.ipk, a development + package helloworld-dev-0.1-r0_sh4.ipk + and a locale package helloworld-locale-0.1-r0_sh4.ipk. It didn't + create the package due to the fact that it couldn't find any files + that would actually go in the package. + + - wildcards and how they effect dir/file selection + There are several things happening here which are important to + understand: - debian naming? + + + There is a default set of packages that are considered for + creation. This set of packages is controlled via the PACKAGES variable. + - -dbg packages and how to handle them + + 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 /usr/share/doc. The set of files and + directories is controlled via the FILES_<package-name> variables. + - package ordering and how it effects wildcards + + 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 ALLOW_EMPTY + variable. + + - modifying vs replacing PACKAGES +
+ Philosophy - "find tmp/<package-name>/install" + 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. - ] + 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. - + By default several groups of files are automatically separate out, + including: - The default assignment of PACKAGES and FILES is: + + + dev - - - PACKAGES + + 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 + + - - Lists the names of each of the packages which are to be - generated.PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale" - - + + doc - - FILES_${PN} + + 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. + + - - The base package, this includes everything needed to actually - run the application on the target system.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" - - + + locale - - FILES_${PN}-dbg + + 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. + + + +
- - Non-stripped versions executable's. OE automatically runs - strip on binary commands but leaves the originals in a .debug - directory.FILES_${PN}-dbg = "${bindir}/.debug ${sbindir}/.debug \ -${libexecdir}/.debug ${libdir}/.debug /bin/.debug /sbin/.debug \ -/lib/.debug ${libdir}/${PN}/.debug" - - +
+ Default packages and files + + The defaults package settings are defined in conf/bitbake.conf and are suitable for a lot of + recipes without any changes. The following list shows the default values + for the packaging related variables: + + + + PACKAGES + + + This variable lists the names of each of the packages that + are to be generated.PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"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. + + For example if the main package, ${PN}, contains /usr/bin/* (i.e. all files in /usr/bin), but you want /usr/bin/tprogram in a separate package, + ${PN}-tpackage, you would need + to either ensure that ${PN}-tpackage is listed prior to + ${PN} in PACKAGES or that FILES_${PN} was modified to not contain + the wildcard that matches /usr/bin/tprogram. + + 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. + + + + + FILES_${PN} + + + The base package, this includes everything needed to + actually run the application on the target system.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" + + + + + FILES_${PN}-dbg + + + 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.FILES_${PN}-dbg = "\ + ${bindir}/.debug \ + ${sbindir}/.debug \ + ${libexecdir}/.debug \ + ${libdir}/.debug \ + /bin/.debug \ + /sbin/.debug \ + /lib/.debug \ + ${libdir}/${PN}/.debug" + + + + + FILES_${PN}-doc + + + Documentation related files. All documentation is + separated into it's own package so that it does not need to be + installed unless explicitly required.FILES_${PN}-doc = "\ + ${docdir} \ + ${mandir} \ + ${infodir} \ + ${datadir}/gtk-doc \ + ${datadir}/gnome/help" + + + + + FILES_${PN}-dev + + + Development related files. Any headers, libraries and + support files needed for development work on the target.FILES_${PN}-dev = "\ + ${includedir} \ + ${libdir}/lib*.so \ + ${libdir}/*.la \ + ${libdir}/*.a \ + ${libdir}/*.o \ + ${libdir}/pkgconfig \ + /lib/*.a \ + /lib/*.o \ + ${datadir}/aclocal" + + + + + FILES_${PN}-locale + + + Locale related files.FILES_${PN}-locale = "${datadir}/locale" + + + +
- - FILES_${PN}-doc +
+ Wildcards + Wildcards used in the FILES + variables are processed via the python function fnmatch. The following items are of note about + this function: + + - Documentation related files. All documentation is separated - into it's own package so that it does not need to be installed - unless explicitly required.FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ -${datadir}/gnome/help" + /<dir>/*: This will + match all files and directories in the dir., it will not match other + directories. - - - - FILES_${PN}-dev - Development related files. Any headers, libraries and support - files needed for development work on the target.FILES_${PN}-dev = "${includedir} ${libdir}/lib*.so ${libdir}/*.la -${libdir}/*.a ${libdir}/*.o ${libdir}/pkgconfig /lib/*.a /lib/*.o -${datadir}/aclocal" + /<dir>/a*: This will + only match files, and not directories. - - - - FILES_${PN}-locale - Locale related files.FILES_${PN}-locale = "${datadir}/locale" + /dir: will include the + directory dir in the package, which + in turn will include all files in the directory and all + subdirectories. - - + - + 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:/usr/bin/programa /usr/bin/programb /usr/bin/testSo + we define are now package, list the file and included in the list of + packages: + + FILES-${PN}-test = "${bindir}/test" +PACKAGES += "FILES-${PN}-test" + + When the package is regenerated no ${PN}-test package will be created. The reason + for this is that the PACKAGES line now + looks like this:{PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale ${PN}-testNote + how ${PN} is listed prior to ${PN}-test, and if we look at the definition of + FILES-${PN} it contains the ${bindir}/* wildcard. Since ${PN} is first it'll match that wildcard are be + moved into the ${PN} package prior to + processing of the ${PN}-test + package. + + To make these work we have two options: + + + + Modify the definition of ${PN} so that the wildcard does not match the + test program. + + We could do this for example:FILES-${PN} = "${bindir}/p*"So + now this will only match things in the bindir that start with p, and + therefore not match our test program. Note that FILES-${PN} 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. + + + + Modify the order of packages so that the ${PN}-test package is listed first. + + The most obvious way to do this would be to prepend our new + package name to the packages list instead of appending it:PACKAGES =+ "FILES-${PN}-test"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. + + 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:PACKAGES = "${PN}-dbg ${PN}-test ${PN} ${PN}-doc ${PN}-dev ${PN}-locale" + + +
+ +
+ Checking the packages + + 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. + + 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:~/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%>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 "-type f" option to find to show + just files will make this clearer as well. + + In addition to the install directory the image directory (which + corresponds to the destination directory, D) will contain any files that were not + packaged:~/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%>In this case all files were packaged and so there are no + left over files. Using find with "-type + f" makes this much clearer:~/oe%> find tmp/work/helloworld-0.1-r0/image -type f +~/oe%> + + Messages reading missing files are also display by bitbake during + the package task: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: completedExcept in + very unusual circumstances there should be no unpackaged files left + behind by a recipe. +
+ +
+ Debian naming + + +
+ +
+ Empty packages + + 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 ALLOW_EMPTY variable is used to control the + creation of empty packages: + + + + ALLOW_EMPTY + + + Controls if empty packages will be created or not. By + default this is "0" and empty + packages are not created. Setting this to "1" will permit the creation of empty + packages (packages containing no files). + + + + + +
-- cgit 1.2.3-korg