From 6e60caf8a95128e373d22b5c66dabe827e5b1bd4 Mon Sep 17 00:00:00 2001 From: Jamie Lenehan Date: Fri, 12 Jan 2007 01:41:12 +0000 Subject: usermanual: Add a list of all the installation variables and there typical values to the reference section. --- usermanual/chapters/.mtn2git_empty | 0 usermanual/chapters/recipes.xml | 1459 +++++++++++++++++++++++++++++++++ usermanual/chapters/usage.xml | 138 ++++ usermanual/reference/dirs_install.xml | 193 +++++ usermanual/usermanual.xml | 2 + 5 files changed, 1792 insertions(+) create mode 100644 usermanual/chapters/.mtn2git_empty create mode 100644 usermanual/chapters/recipes.xml create mode 100644 usermanual/chapters/usage.xml create mode 100644 usermanual/reference/dirs_install.xml (limited to 'usermanual') diff --git a/usermanual/chapters/.mtn2git_empty b/usermanual/chapters/.mtn2git_empty new file mode 100644 index 0000000000..e69de29bb2 diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml new file mode 100644 index 0000000000..5eba6fd3e8 --- /dev/null +++ b/usermanual/chapters/recipes.xml @@ -0,0 +1,1459 @@ + + + Recipes + +
+ Introduction + + A bitbake recipe is a set of instructions that describe what needs + to be done to retrierve the source code for some application, apply any + necessary patches, provide any additional files (such as init scripts), + compile it, install it and generated binary packages. The end result is a + binary package that you can install on your target device, and maybe some + intermediate files, such as libraries and headers, which can be used when + building other application. + + In many ways the process is similar to creating .deb or .rpm + packages for your standard desktop distributions with one major difference + - in OpenEmbedded everything is being cross-compiled. This often makes the + task far more difficult (depending on how well suited the application is + to cross compiling), then it is for other packaging systems and sometime + impossible. + + This chapter assumes that you are familiar with working with + bitbake, including the work flow, required directory structures, bitbake + configuration and the use of monotone. If you are not familiar with these + then first take a look at the chapter on bitbake usage. +
+ +
+ Syntax of recipes + + The basic items that make up a bitbake recipe file are: + + + + functions + + + Functions provide a series of actions to be performed. + Functions are usually used to override the default implementation of + a task function, or to compliment (append or prepend to an existing + function) a default function. Standard functions use sh shell + syntax, although access to OpenEmbedded variables and internal + methods is also available. + + The following is an example function from the sed + recipe: + + do_install () { + autotools_do_install + install -d ${D}${base_bindir} + mv ${D}${bindir}/sed ${D}${base_bindir}/sed.${PN} +}It is also possible to implement new functions, that are not + replacing or complimenting the default functions, which are called + between existing tasks. It is also possible to implement functions + in python instead of sh. Both of these options are not seen in the + majority of recipes. + + + + + variable assignments and manipulations + + + Variable assignments allow a value to be assigned to a + variable. The assignment may be static text or might include the + contents of other variables. In addition to assignment, appending + and prepending operations are also supported. + + The follow example shows the some of the ways variables can be + used in recipes:S = "${WORKDIR}/postfix-${PV}" +PR = "r4" +CFLAGS += "-DNO_ASM" +SRC_URI_append = "file://fixup.patch;patch=1" + + + + + keywords + + + Only a few keywords are used in btbake recipes. They are used + for things such as including common functions + (inherit), loading parts of a recipe from other + files (include and + require) and exporting variables to the + environment (export). + + The following example shows the use of some of these + keywords:export POSTCONF = "${STAGING_BINDIR}/postconf" +inherit autoconf +require otherfile.inc + + + + + comments + + + Any lines that begin with a # are treated as comment lines and + are ignored.# This is a comment + + + + + The following is a summary of the most important (and most commonly + used) parst of the recipe syntax: + + + + Line continuation: \ + + + To split a line over multiple lines you should place a \ at + the end of the line that is to be continued on the next line. + + VAR = "A really long \ + line" + + Note that there must not be anything (no spaces or tabs) after + the \. + + + + + Comments: # + + + Any lines beginning with a # are comments and will be + ignored.# This is a comment + + + + + Using variables: ${...} + + + To access the contents of a variable you need to access it via + ${<varname>}:SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" + + + + + Quote all assignments + + + All variable assignments should be quoted with double quotes. + (It may work without them at pesent, but it will not work in the + future).VAR1 = "${OTHERVAR}" +VAR2 = "The version is ${PV}" + + + + + Appending: += + + + You can append values to existing variables using the + += operator. Note that this operator will add a + space between the existing content of the variable and the new + content.SRC_URI += "file://fix-makefile.patch;patch=1" + + + + + Prepending: =+ + + + You can preprend values to existing variables using the + =+ operator. Note that this operater will add a + space between the new content and the existing content of the + cariable.VAR =+ "Starts" + + + + + Appending: _append + + + You can append values to existing variables using the + _append method. Note that this operator does + not add any additional space, and it is applied after all the + +=, and =+ operators have + been applied. + + The following example show the space being explicity added to + the start to ensure the appended value is not merged with the + existing value:SRC_URI_append = " file://fix-makefile.patch;patch=1"The + _append method can also be used with overrides, + which result in the actions only being performed for the specified + target or machine: [TODO: Link to section on overrides]SRC_URI_append_sh4 = " file://fix-makefile.patch;patch=1"Note + that the appended information is a variable itself, and therefore + it's possible to used += or + =+ to assign variables to the + _append information:SRC_URI_append = " file://fix-makefile.patch;patch=1" +SRC_URI_append += "file://fix-install.patch;patch=1" + + + + + Prepending: _prepend + + + You can prepend values to existing variables using the + _prepend method. Note that this operator does not add any additional + space, and it is applied after all the +=, and + =+ operators have been applied. + + The following example show the space being explicity added to + the end to ensure the prepended value is not merged with the + existing value:CFLAGS_prepend = "-I${S}/myincludes "The + _prepend method can also be used with + overrides, which result in the actions only being performed for the + specified target or machine: [TODO: Link to section on + overrides]CFLAGS_prepend_sh4 = " file://fix-makefile.patch;patch=1"Note + that the appended information is a variable itself, and therefore + it's possible to used += or + =+ to assign variables to the + _prepend information:CFLAGS_prepend = "-I${S}/myincludes " +CFLAGS_prepend += "-I${S}/myincludes2 "Note also the lack of a space + when using += to append to a preprend value - remember that the += + operator is adding space itself. + + + + + Spaces vs tabs + + + Spaces should be used for indentation, not hard tabs. Both + currently work, however it is a policy decision of OE that spaces + always be used. + + + + + Style: oe-stylize.py + + + To help with using the correct style in your recipes there is + a python script in the contrib directory called + oe-stylize.py which can be used to reformat + your recipes to the correct style. The output will contain a list of + warning (to let you know what you did wrong) which should be edited + out before using the new file.contrib/oe-stylize.py myrecipe.bb > fixed-recipe.bb +vi fixed-recipe.bb +mv fixed.recipe.bb myrecipe.bb + + + + + Using python for complex operations: ${@...} + + + For more advanced processing it is possible to use python code + during variable assignments, for doing search and replace on a + variable for example. + + Python code is indicated by a proceeding @ sign in the + variable assignment.CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}"More + information about using python is available in the section. + + + + + Shell syntax + + + When describing a list of actions to take shell syntax is used + (as if you were writing a shell script). You should ensure that you + script would work with a generic sh and not require any bash (or + other shell) specific functionality. The same applies to various + system utilities (sed, grep, awk etc) that you may wish to use. If + in doubt you should check with multiple implementations - including + those from busybox. + + + + + For a detailed description of the syntax for the bitbake recipe + files you should refer to the bitbake use manual. +
+ +
+ Recipe naming: Names, versions and releases + + Recipes in OpenEmbedded use a standard naming convention that + includes the package name and version number in the filename. In addition + to the name and version there is also a release number, which is indicates + changes to the way the package is built and/or packaged. The release + number is contained within the recipe itself. + + The expected fomat of recipe name is:<package-name>_<version>.bb + + where <package-name> is the name of the + package (application, library, module, or whatever it is that is being + packaged) and version is the version number. + + So a typical recipe name would be:strace_4.5.14.bbwhich + would be for version 4.5.14 of the + strace application. + + The release version is defined via the package release variable, PR, + contained in the recipe. The expected format is:r<n>where + <n> is an integer number starting from 0 + initially and then incremented each time the recipe, or something that + effects the recipe, is modified. So a typical defintion of the release + would be:PR = "r1"to specify release number + 1 (the second release, the first would have been + 0). If there is no definition of PR in the recipe + then the default value of "r0" is used. + + + It is good practice to always define PR in your recipes, even + for the "r0" release, so that when editing the + recipe it is clear that the PR number needs to be updated. + + + When a recipe is being processed some variables are automatically + set based on the recipe file name and can be used for other purposes from + within the recipe itself. These include: + + + + PN + + + The package name. Determined from the recipe filename - + everything up until the first underscore is considered to be the + package name. For the strace_4.5.14.bb recipe the + PN variable would be set to "strace". + + + + + PV + + + The package version. Determined from the recipe filename - + everything between the first underscore and the final .bb is + considered to be the pacakge version. For the + strace_4.5.14.bb recipe the PV variable would be + set to "4.5.14". + + + + + PR + + + The package release. This is explicitly set in the recipe, or + if not set it defaults to "r0" if not + set. + + + + + P + + + The package name and versions seperated by a hyphen.P = "${PN}-${PV}" + + For the strace_4.5.14.bb recipe the P + variable would be set to + "strace-4.5.14". + + + + + PF + + + The package name, version and release seperated by + hypens.PF = "${PN}-${PV}-${PR}" + + For the strace_4.5.14.bb recipe, with PR + set to "r1" in the recipe, the PF variable + would be set to "strace-4.5.14-r1". + + + + + While some of these variables are not commonly used in recipes (they + are used internally though) both PN and PV are used a lot. + + In the following example we are instructing the packaging system to + include an additional directory in the package. We use PN to refer to the + name of the package rather than spelling out the package name:FILES_${PN} += "${sysconfdir}/myconf" + + In the next example we are specifying the URL for the package + source, by using PV in place of the actual version number it is possible + to duplicate, or rename, the recipe for a new version without having to + edit the URL:SRC_URI = "ftp://ftp.vim.org/pub/vim/unix/vim-${PV}.tar.bz2" + + +
+ +
+ Variables + + One of the most confusing part of bitbake recipes for new users is + the large amount of variables that appear to be avaialble to change and/or + control the behaviour of some aspect of the recipe. Some variables, such + as those derived from the file name are reasonably obvious, others are not + at all obvious. + + There are several places where these variables are derived from + and/or used: + + + + A large number of variables are definied in the bitbake + configuration file conf/bitbake.conf - it's often a good idea to look + through that file when trying to determine what a particular variable + means. + + + + Machine and distribution configuration files in conf/machine and + conf/distro will sometimes define some variables specific to the + machine and/or distribution. You should look at the appropriate files + for your targets to see if anything is being definied that effects the + recipes you are building. + + + + Bitbake itself will define some variables. The FILE variables + that defines the name of the bitbake recipe being processed is set by + bitbake itself for example. Refer to the bitbake manual for more + information on the variables that bitbake sets. + + + + The classes, that are used via the inherit keyword, define + and/or use the majority of the remaining variables. A class is a like + a library that contain parts of a bitbake recipe that are used by + multiple recipes. To make them useable in more situations they often + include a large number of variables to control how the class + operates. + + + + [ + + talk about predefinied variables + + look in conf/bitbake.conf + + target filesystem paths + + build variables + + data/time variables + + ] + + + + [TODO: Table probably goes to ref section, just mention some of the + more common of these here] + + + + build vs host vs target + + build - run on the build system, produce things that run on the + build system + + host - run on the build system, produce things for the + + +
+ +
+ Header + + talk about some of the header entries + + + + + + DESCRIPTION + + + Describes what the software does. Hopefully this gives enough + information to a use to know if it's the right application for + them. + + The default description is: "Version ${PV}-${PR} of + package ${PN}". + + + + + HOMEPAGE + + + The URL of the home page of the application where new releases + and more information can be found. + + The default homepage is "unknown". + + + + + SECTION + + + The section is used to categorise the application into a + specific group. Often used by GUI based installers to help users + when searching for software. + + See for a list of the + available sections. + + The default section is "base". + + + + + PRIORITY + + + The default priority is + "optional". + + + + + LICENSE + + + The license for the application. If it is not one of the + standard linceses then the license itself must be included + (where?) + + The default licenses is "unknown". + + + + + +
+ +
+ 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 + + [ + + talk about sources + + SRC_URI example + + tar.gz explain + + patch explain + + file explain + + svn/cvs/git etc explain? + + point to SR_URI in reference section for more details + + ] + + Before a recipe can start compiling and packaging up your software + it needs to know where to get the source from. This is controlled via the + in the recipe which is able to + describe: + + - http and https URI's + + - cvs, svn and git URI's + + - files + + - patches + + + + +
+ +
+ Directories: What goes where + + target directories + + unpacked source directory + + work directory + + files/filespath + + staging directories + + install directories + + + +
+ WORKDIR: The working directory + + [UNEDITED] + + The workdir is the directory into which the source code is + extracted, to which files (non patch files) are copied and where the + logs and installation files are created. A typical reason for needing to + reference the work directory is for non patch files. If we take a look + at the recipe for quagga we can see an example of this: + + SRC_URI = "http://www.quagga.net/download/quagga-${PV}.tar.gz \ + file://fix-for-lib-inpath.patch;patch=1 \ + file://quagga.init \ + file://quagga.default \ + file://watchquagga.init \ + file://watchquagga.default"This has two init files and two + configuration files which are not patches, but actually files that it + wants to include in the generated packages. Bitbake will copy these + files into the work directory. So to access them we refer to + WORKDIR: + + do_install () { + # Install init script and default settings + install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga + install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga + install -m 0644 ${WORKDIR}/watchquagga.default ${D}${sysconfdir}/default/watchquagga + install -m 0755 ${WORKDIR}/quagga.init ${D}${sysconfdir}/init.d/quagga + install -m 0755 ${WORKDIR}/watchquagga.init ${D}${sysconfdir}/init.d/watchquagga + ... + + +
+ +
+ S: The unpacked source code directory + + [UNEDITED] + + Bitbake expects to find the source for a package in the + <packagename>-<version> directory, so for a package called + widgets_1.2.bb we are extracting widgets-1.2.tar.gz and bitbake expects + to source to end up in a directory called widgets-1.2 within the work + directory. If the source does not end up in this directory then bitbake + needs to be told this by explicitly setting S. + + For example, lets assume widgets-1.2.tar.gz extracts into a + directory called widgets - without the version number, instead of + widgets-1.2 which is what the default value of S assumes. Therefore we + need to modify S to specify the directory the source was actually + extracted into: + + SRC_URI = "http://www.example.com/software/widgets-${PN}.tar.gz" +S = "${WORKDIR}/widgets" + + +
+ +
+ D: The destination directory + + [UNEDITED] + + aaa +
+ +
+ Staging directories + + [UNEDITED] + + The staging directories are used during a stage task where the + libraries and headers are copied to the staging area to be used during + the building of other applications. + + [Table to reference section, just mention lib and include dirs + here] + + + + + + + + + + Directory + + Definition + + + + + + STAGING_DIR + + ${TMPDIR}/staging + + + + STAGING_BINDIR + + ${STAGING_DIR}/${BUILD_SYS}/bin + + + + STAGING_LIBDIR + + ${STAGING_DIR}/${HOST_SYS}/lib + + + + STAGING_INCDIR + + ${STAGING_DIR}/${HOST_SYS}/include + + + + STAGING_DATADIR + + ${STAGING_DIR}/${HOST_SYS}/share + + + + STAGING_LOADER_DIR + + ${STAGING_DIR}/${HOST_SYS}/loader + + + + STAGING_FIRMWARE_DIR + + ${STAGING_DIR}/${HOST_SYS}/firmware + + + + STAGING_PYDIR + + ${STAGING_DIR}/lib/python2.4 + + + + STAGING_KERNEL_DIR + + ${STAGING_DIR}/${HOST_SYS}/kernel + + + + PKG_CONFIG_PATH + + ${STAGING_DATADIR}/pkgconfig + + + + + + +
+ +
+ ... + + + + +
+ +
+ FILESPATH/FILESDIR: Finding local files + + [UNEDITED] + + + + + + FILE + + + The path to the .bb file which is currently being + processed. + + + + + FILE_DIRNAME + + + The path to the directory which contains the FILE which is + currently being processed.FILE_DIRNAME = "${@os.path.dirname(bb.data.getVar('FILE', d))}" + + + + + FILESPATH + + + The default set of directories which are available to use + for the file:// URI's. Each directory is searched, in the + specified order, in an attempt to find the file specified by each + file:// URI: FILESPATH = "${FILE_DIRNAME}/${PF}:${FILE_DIRNAME}/${P}:\ +${FILE_DIRNAME}/${PN}:${FILE_DIRNAME}/files:${FILE_DIRNAME}" + + + + + FILESDIR + + + The default directory to search for file:// URI's. Only used + if the file is not found in FILESPATH. This can be used to easily + add one additional directory to the search path without having to + modify the default FILESPATH setting. By default this is just the + first directory from FILESPATH. FILESDIR = "${@bb.which(bb.data.getVar('FILESPATH', d, 1), '.')}" + + + + + The most common reason for changing the FILESPATH/FILESDIR value + is when building one recipe that includes another. The native recipes + are typically where this occurs. As an example the m4-native recipe + includes the m4 recipe. This is fine, except that the m4 recipes expects + its files and patches to be located in the m4 directory while the native + file name results in them being searched for in m4-native. So the + m4-native recipe sets the FILESDIR variable to the value that of m4 to + add the actual m4 directory (where m4 itself has its files stored) to + the list of directories search for: include m4_${PV}.bb inherit native + FILESDIR = "${@os.path.dirname(bb.data.getVar('FILE',d,1))}/m4" + + +
+
+ +
+ Basic examples + + XX + +
+ Hello world + + Now it's time for out first recipe. This is going to be one of the + simpliest possible recipes - all code is included and there's only one + file to complile and one readme file. + + + + Create the files and add them: + + Create the recipe:cat > packages/helloworld/helloworld_0.1.bb +DESCRIPTION = "Hello world program" + +SRC_URI = "file://helloworld.c \ + file://README.txt" + +do_compile() { + ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/helloworld.c -o helloworld +} + +do_install() { + install -m 0755 -d ${D}${bindir} ${D}${docdir}/helloworld + install -m 0644 ${S}/helloworld ${D}${bindir} + install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/helloworld +} +^D + + SRC_URI refers to two files, no patches - found in "files" + dir. + + do_compile just compiles our one file and create helloworld + bin + + do_install create dirs, copies files. Not use of S, D, WORKDIR, + bindir, docdir vars. +
+ +
+ An autotools package + + Show simple autoconf example + + %> cat packages/tuxnes/tuxnes_0.75.bb +DESCRIPTION = "Tuxnes Nintendo (8bit) Emulator" +HOMEPAGE = "http://prdownloads.sourceforge.net/tuxnes/tuxnes-0.75.tar.gz" +LICENSE = "GPLv2" +SECTION = "x/games" +PRIORITY = "optional" +PR ="r1" + +SRC_URI = "http://heanet.dl.sourceforge.net/sourceforge/tuxnes/tuxnes-0.75.tar.gz" + +inherit autotools + + Example show EXTRA_OECONF or leave for advanced autoconf + section? + + Note about classes below + + Note about autoconf in ref section +
+
+ +
+ Dependencies: What's needed to build and/or run the + package? + + [ + + DEPENDS + + RDEPENDS + + auto sh libs depends + + auto building of RDEPENDS + + ] + + Dependencies should be failiar to anyone who has used a .rpm and + .deb based desktop distribution. A dependency is something that a package + requires to either build or run. +
+ +
+ Messages: Letting the user know things + + [UNEDITED] + + + + + + oenote + + + Display some informational messages to the user. + + + + + oewarn + + + Display a warning to the user. + + + + + oedebug + + + Display an error message to the user and abort the + action. + + + + + oefatal + + + Display a debugging message to the user but only if they have + requested debugging output. + + + + + Of the four functions only oefatal will abort the currently + executing task. +
+ +
+ Methods: Inbuilt methods to make your life easier + + oe_runmake + + oe_runconf + + oe_libinstall +
+ +
+ Packaging: Defining packages and their contents + + [ + + Talk about multiple packages and putting things in those + packages + + philosophy of packaging - dbg, doc, dev, main pakage, libs, + additional + + PACKAGES + + FILES + + wildcards and how they effect dir/file selection + + debian naming? + + -dbg packages and how to handle them + + package ordering and how it effects wildcards + + modifying vs replacing PACKAGES + + "find tmp/<package-name>/install" + + ] + + + + The default assignment of PACKAGES and FILES is: + + + + PACKAGES + + + Lists the names of each of the packages which are to be + generated.PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale" + + + + + 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 + + + Non-stripped versions executables. 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" + + + + + FILES_${PN}-doc + + + Documentation related files. All documentation is seperated + 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" + + + + + +
+ +
+ Tasks: Playing with tasks + + [ + + tasks are explained elesewhere, here we talk about + replacing/modifying/adding + + configure + + compile + + stage + + install + + ..._append/_prepend + + add task ... + + empty tasks (":") + + ] +
+ +
+ Classes: The seperation of common functionality + + [ + + what are classes + + some examples - autotools, update-rc.d, distutils, cpan + + ] +
+ +
+ Staging: Making includes and libraries available for + building + + [ + + Why staging + + where staging to + + what does/does not go in staging + + ] +
+ +
+ Autoconf: All about autotools + + [ + + More about building autoconf packages + + EXTRA_OECONF + + Problems with /usr/include + + Configuring to search on staging + + -L${STAGING_LIBDIR} vs ${TARGET_LDFLAGS} + + site files + + refer to ref manual for site files info + + ] +
+ +
+ Installation scripts: Running scripts during package install and/or + removal + + [ + + Talk about pre and post inst/remove scripts + + Talk about "sh" syntax (ie, vs "bash" syntax) + + Talk about offline install stuff + + Make note about how classes can effect this + + ] +
+ +
+ Configuration files + + Configuration files that are installed as part of a package require + special handling. Without special handling as soon as the user upgrades to + a new version of the package then changes they have made to the + configuration files will be lost. + + In order to prevent this from happening you need to tell the + packaging system which files are configuration files. Such files will + result in the user being asked how the user wants to handle any + configuration file changes (if any), as shown in this example:Downloading http://nynaeve.twibble.org/ipkg-titan-glibc//./p3scan_2.9.05d-r1_sh4.ipk + Configuration file '/etc/p3scan/p3scan.conf' + ==> File on system created by you or by a script. + ==> File also in package provided by package maintainer. + What would you like to do about it ? Your options are: + Y or I : install the package maintainer's version + N or O : keep your currently-installed version + D : show the differences between the versions (if diff is installed) + The default action is to keep your current version. + *** p3scan.conf (Y/I/N/O/D) [default=N] ?To declare a file as a + configuration file you need to define the + CONFFILES_<pkgname> variable as a whitespace + separated list of configuration files. The following example from clamav + shows two files being marked as configuration files:CONFFILES_${PN}-daemon = "${sysconfdir}/clamd.conf \ + ${sysconfdir}/default/clamav-daemon"Note + the user of ${PN}-daemon as the package name. The + ${PN} variable will expand to clamav + and therefore these conf files are declared as being in the clamav-daemon + package. +
+ +
+ Package relationships + + [ + + RRECOMENDS + + RCONFLICTS + + PROVIDES + + ] +
+ +
+ Fakeroot: Dealing with the need for "root" + + Sometimes packages requires root permissions in order to perform + some action, such as changing user or group owners or creating device + nodes. Since OpenEmbedded will not keep the user and group information + it's usually preferably to remove that from the makefiles. For device + nodes it's usually preferably to create them from the initial device node + lists or via udev configuration. + + However if you can't get by without root permissions then you can + use to simulate a root environment, without + the need to really give root access. + + Using is done by prefixing the + task:fakeroot do_install() {Since this requires fakeroot + you also need to add a dependency on + fakeroot-native:DEPENDS = "fakeroot-native"See + the fuse recipe for an example. Further information on , including a description of it works, is provided in + the reference section: . +
+ +
+ Native: Packages for the build host + + Talk about native packages +
+ +
+ Development: Strategies for developing recipes + + Talk about how to go about developing things +
+ +
+ Advanced versioning: How to deal with rc and pre versions + + Talk about 1.0.0+2.0.0rc type stuff +
+ +
+ Exports: Modifying the environment + + Talk about the use of export in recipes +
+ +
+ Includes: Reusing recipe contents for multiple versions (and other + purposes) + + Talk about the use of include and require and .inc files and how to + separate these out. +
+ +
+ Python: Advanced functionality with python + + Talk about using python code in recipes + + Samples of useful python code. +
+ +
+ Preferences: How to disable packages + + Talk about using DEFAULT_PREFERENCE + + Why you should use it. + + Using overrides & preferences together. +
+ +
+ Initscripts: How to handle daemons + + update-rc.d class + + sh vs bash + + start/stop/restart params + + sample / standard script format + + note about volatiles being described below + + reference section for more info +
+ +
+ Alternatives: How to handle the same command in multiple + packages + + Why you should care + + Using them + + reference section for more info +
+ +
+ Volatiles: How to handle the /var directory + + [ + + Talk about tmpfs for var + + Talk about how volatiles work + + Talk about logging via syslog so non-disk logs will may be + used + + Talk about default volatiles + + reference section for more info + + ] + + The /var directory is for storing volatile information, that is + information which is constantly changing and which in general may be + easily recreated. In embedded applications it is often desirable that such + files are not stored on disk or flash for various reasons include possible + reduced lifetime of the flash, limited storage space or to ensure + filesystem corruption cannot occur due to a sudden power loss. + + For these reasons many of the OpenEmbedded distributions use a tmpfs + memory based filesystem for /var instead of a disk or flash based + filesystem. The consequence of this is that all contents of the /var + directory is lost when the device is powered off or restarted. Therefore + special handling of /var is required in all packages to ensure that they + don't restrict the options available to individual distributions. This + special handling is provided via the populate-volatiles.sh script. + + If your package requires directory, symlinks or files in /var then + you should be using the populate-volatiles facilities. + + + +
+ Declaring volatiles + + + + - don't include /var stuff in pacakges + + - any expect dirs in def volatiles to exist + + - add volatiles file for any other distributions +
+ +
+ Logging and log files + + As a consequence of the non-volatile and/or small capacity of the + /var file system some distributions choose methods of logging other than + writing to a file. The most typical is the use of an in-memory circular + log buffer which can be read using the logread command. + + To ensure that each distribution is able to implement logging in a + method that is suitable for its goals all packages should be configured + by default to log via syslog, and not log directly to a file, if + possible. If the distribution and/or end-user requires logging to a file + then they can configured syslog and/or your application to implement + this. +
+ +
+ Summary + + In summary the following are required when dealing with + /var: + + + + Configure all logging to use syslog whenever possible. This + leaves the decision on where to log upto the individual + distributions. + + + + Don't include any /var directories, file or + symlinks in packages. They would be lost on a reboot and so should + not be included in packages. + + + + The only directories that you can assume exist are those + listed in the default volatiles file: + packages/initscripts/initscripts-1.0/volatiles. + + + + For any other directories, files or links that are required in + /var you should install your own volatiles list + as part of the package. + + +
+
+ +
+ STUFF STILL TO BE CONSIDERED/ADDED + + about optimisation + + about download directories + + about parrallel builds + + about determing endianess (aka net-snmp, openssl, hping etc + style) + + about adding users/groups + + about PACKAGES_DYNAMIC + + about LEAD_SONAME + + about "python () {" - looks like it is always run when a recipe is + parsed? see pam/libpam + + about SRCDATE with svn/cvs? + + about INHIBIT_DEFAULT_DEPS? + + about COMPATIBLE_MACHINE and COMPATIBLE_HOST + + +
+ \ No newline at end of file diff --git a/usermanual/chapters/usage.xml b/usermanual/chapters/usage.xml new file mode 100644 index 0000000000..2e1f887d38 --- /dev/null +++ b/usermanual/chapters/usage.xml @@ -0,0 +1,138 @@ + + + Usage + +
+ Introduction + + Using bitbake +
+ +
+ Work space + + 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. + + 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. + + strace-4.5.14 This is the directory created by the extracted source + code. (Refered to by the S variable in the recipes). + + temp Scripts to perform the various stages (configure, compile, etc) + and the logs containing the output of those scripts. +
+ +
+ Temp dir + + The temp directory contains the scripts to perform various actions + and the log files generated by those actions: +
+ +
+ Install dir + + 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: + + +
+ +
+ Deploy dir + + 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. +
+ +
+ Working with a single package + + 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 +
+ +
+ Interactive bitbake + + 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] +
+ +
+ Devshell + + +
+ +
+ Workflow + + 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. +
+ \ No newline at end of file diff --git a/usermanual/reference/dirs_install.xml b/usermanual/reference/dirs_install.xml new file mode 100644 index 0000000000..3d85f2ca8d --- /dev/null +++ b/usermanual/reference/dirs_install.xml @@ -0,0 +1,193 @@ + +
+ Directories: Installation variables + + The following table provides a list of the variables that are used to + control the directories into which files are installed. + + These variables can be used directly by the recipe to refer to paths + that will be used after the package is installed. For example, when specify + the location of configuration files you need to specify the location on the + target as show in the following example from quagga:# Indicate that the default files are configuration files +CONFFILES_${PN} = "${sysconfdir}/default/quagga" +CONFFILES_${PN}-watchquagga = "${sysconfdir}/default/watchquagga" + + When using these variables to actually install the components of a + package from within a bitbake recipe they should used relative to the + destination directory, D. The following + example from the quagga recipe shows some addition files being manually + installed from within the recipe itself:do_install () { + # Install init script and default settings + install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga + install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga + + + + + + Variable name + + Definition + + Typical value + + + + + + prefix + + /usr + + /usr + + + + base_prefix + + (empty) + + (empty) + + + + exec_prefix + + ${base_prefix} + + (empty) + + + + base_bindir + + ${base_prefix}/bin + + /bin + + + + base_sbindir + + ${base_prefix}/sbin + + /sbin + + + + base_libdir + + ${base_prefix}/lib + + /lib + + + + datadir + + ${prefix}/share + + /usr/share + + + + sysconfdir + + /etc + + /etc + + + + localstatedir + + /var + + /var + + + + infodir + + ${datadir}/info + + /usr/share/info + + + + mandir + + ${datadir}/man + + /usr/share/man + + + + docdir + + ${datadir}/doc + + /usr/share/doc + + + + servicedir + + /srv + + /srv + + + + bindir + + ${exec_prefix}/bin + + /usr/bin + + + + sbindir + + ${exec_prefix}/sbin + + /usr/sbin + + + + libexecdir + + ${exec_prefix}/libexec + + /usr/libexec + + + + libdir + + ${exec_prefix}/lib + + /usr/lib + + + + includedir + + ${exec_prefix}/include + + /usr/include + + + + + + + + + + + + + + +
\ No newline at end of file diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml index e95667dc46..22cdd7be8b 100644 --- a/usermanual/usermanual.xml +++ b/usermanual/usermanual.xml @@ -7,6 +7,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + @@ -594,6 +595,7 @@ NOTE: Couldn't find shared library provider for libm.so.6 Reference &class-autotools; &class-binconfig; + &dirs-install; &class-distutils; &fakeroot; &class-image_ipkg; -- cgit 1.2.3-korg