From 9f51f11ca6599ca820c2c01c8b07a8ee73975318 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 20 Dec 2013 09:41:32 -0600 Subject: dev-manual: Completed the "Fetching" and "Configuration" sections. This involved a first draft and implementation of Paul's review comments. Also worked on the "Configuration" section. (From yocto-docs rev: 0e168dbaf5f4949c4c5f79fe7da406ca91390e22) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 380 +++++++++++++++------ 1 file changed, 280 insertions(+), 100 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index f6184ce..6d1d083 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1183,8 +1183,6 @@ Use and modify the following skeleton recipe: - inherit <stuff> - SUMMARY = "" HOMEPAGE = "" LICENSE = "" @@ -1195,7 +1193,9 @@ SRC_URI[md5sum] = "" SRC_URI[sha256sum] = "" - S = ${WORKDIR}/${PN}-${PV} + S = "${WORKDIR}/${PN}-${PV}" + + inherit <stuff> Modifying this recipe is the recommended method for creating a new recipe. @@ -1206,6 +1206,135 @@ +
+ Naming the Recipe + + + Once you have your base recipe, you need to name it and be + sure that it resides where the OpenEmbedded build system + can find it. + + + + When you name your recipe, you need to follow this naming + convention: + + <basename>_<version>.bb + + Use lower-cased characters and do not include the reserved + suffixes -native, + -cross, -initial, + or -dev. + Here are some examples: + + cups_1.7.0.bb + gawk_4.0.2.bb + xdg-utils_1.1.0-rc1.bb + + + + + The OpenEmbedded build system locates your recipe through + the layer.conf file and the + BBFILES + variable. + This variable sets up a path from which the build system can + locate recipes. + Here is the typical use: + + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + Consequently, you need to be sure you locate your new recipe + inside your layer such that it can be found. + + + + You can find more information on how layers are structured + in the + "Understanding and Creating Layers" + section. + +
+ +
+ Running a Build on the Recipe + + + Creating a new recipe is an iterative process that requires + using BitBake to process the recipe multiple times in order to + progressively discover and add information to the recipe. + + + + To process the recipe, use the following BitBake command form + from within the + Build Directory: + + $ bitbake <base-recipe-name> + + Before you run BitBake, be sure that you source a build + environment setup script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres. + + + + The OpenEmbedded build system creates a temporary work + directory + (${WORKDIR}) + where it keeps extracted source files, log files, images, and + so forth. + + + + This temporary work directory is constructed depending on + several factors. + For packages that are not dependent on a particular machine, + WORKDIR is defined as follows: + + ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR} + + As an example, assume a Source Directory top-level folder name + poky, a default Build Directory at + poky/build, a qemux86 + package architecture, and a linux target + operating system. + Furthermore, suppose your recipe is named + foo_1.3.0-r0.bb. + In this case, the work directory the build system uses to + build the package would be as follows: + + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + + Inside this directory you can find sub-directories such as + image, package-split, + and temp. + After the build, you can examine these to determine how well + the build went. + + + + You can find more information about the build process in the + "A Closer Look at the Yocto Project Development Environment" + chapter of the Yocto Project Reference Manual. + + + + You can also reference the following variables in the + Yocto Project Reference Manual's glossary for more information: + + The temporary directory - TMPDIR + The package architecture - PACKAGE_ARCH + The target operating system - TARGET_OS + The recipe name - PN + The recipe version - PV + The recipe revision - PR + + +
+
Fetching Code @@ -1268,7 +1397,7 @@ you provide the SRC_URI variable in your recipe: - + Avoid hard-coding URLs: Rather than hard-coding the version in an URL, it is good practice to use ${PV}, @@ -1279,7 +1408,7 @@ as renaming the recipe to match the new version. Notice that the two examples in the previous paragraph both use ${PV}. - + Using the file:// URI protocol: When you specify local files using the file:// URI protocol, the build system fetches files from the local machine. @@ -1297,26 +1426,15 @@ For more information, see the SRC_URI variable. - - Files mentioned in SRC_URI whose - names end in a typical archive extension - (e.g. .tar, - .tar.gz, - .tar.bz2, - .zip, and so forth), - are automatically extracted during - the do_unpack task. - - + Specifying patch files: Files mentioned in SRC_URI whose names end in .patch or .diff are treated as patches and are automatically applied during the - do_patch task. - - Patches should be applicable with the "-p1" option to - patch (i.e. one directory level in the path will be - stripped off.) + do_patch task. + The build system should be able to apply patches + with the "-p1" option (i.e. one directory level in the + path will be stripped off). If your patch needs to have more directory levels stripped off, specify the number of levels using the "striplevel" option in the SRC_URI @@ -1325,7 +1443,17 @@ specific subdirectory that is not specified in the patch file, use the "patchdir" option in the entry. - + Extracting archived source files: + Files mentioned in SRC_URI whose + names end in a typical archive extension + (e.g. .tar, + .tar.gz, + .tar.bz2, + .zip, and so forth), + are automatically extracted during + the do_unpack task. + + Specifying source from an SCM: For Git repositories, you must specify SRCREV and you should specify @@ -1347,14 +1475,36 @@ - Also part of the SRC_URI variable are the + If your SRC_URI statement includes + URLs pointing to individual files fetched from a remote server + other than a version control system, BitBake attempts to + verify the files against checksums defined in your recipe to + ensure they have not been tampered with or otherwise modified + since the recipe was written. + Two checksums are used: SRC_URI[md5sum] = "" and - SRC_URI[sha256sum] = "" statements. - These two checksums ensure that the remote file (and hence - the source code you are building) has not changed since the - recipe was written. - You must provide these two checksums whenever you fetch - source from anywhere other than an SCM or a local file. + SRC_URI[sha256sum] = "". + + + + If your SRC_URI variable points to + more than a single URL (excluding SCM URLs), you need to + provide the md5 and + sha256 checksums for each URL. + For these cases, you provide a name for each URL as part of + the SRC_URI and then reference that name + in the subsequent checksum statements. + Here is an example: + + SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \ + ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch + + SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8" + SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d" + + SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92" + SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430" + @@ -1371,13 +1521,14 @@
Unpacking Code +do_unpack unpacks the source, and S must be set +> to point to where it will be unpacked + - During the build, source code that is fetched needs to be - unpacked. - The OpenEmbedded build system uses the - do_unpack task to organize the source - files into the temporary work directory pointed to by - ${S}. + During the build, the do_unpack task + unpacks the source and + ${S} + points to where it will be unpacked. @@ -1388,6 +1539,13 @@ source from an SCM like Git or Subversion, your recipe needs to define S. + + + If processing your recipe using BitBake successfully unpacks + the source files, you need to be sure that the structure + created in ${S} matches the structure + from the source. +
@@ -1401,10 +1559,11 @@ variables: LICENSE: + This variable specifies the license for the software. If you do not know the license under which the software you are building is distributed, you can go to the source code and look for that information. - Places that hold this information are the + Typical files containing this information include COPYING, LICENSE, and README files. @@ -1412,17 +1571,20 @@ a source file. The key is to find something that states the public license needed for the software. - For example, the - COPYING - file for the htop software states - clearly that the software is licensed under the - "GNU GENERAL PUBLIC LICENSE Version 2, June 1991". - Consequently, if you were writing a recipe to build - htop, you would include the - following: + For example, given a piece of software licensed under + the GNU General Public License version 2, you would + set LICENSE as follows: LICENSE = "GPLv2" - + + The licenses you specify with + LICENSE be any name as long as + you do not use spaces. + For standard licenses, use the names of the files in + meta/files/common-licenses/ + or the SPDXLICENSEMAP flag names + defined in meta/conf/licenses.conf. + LIC_FILES_CHKSUM: The OpenEmbedded build system uses this variable to make sure the license text has not changed. @@ -1435,7 +1597,7 @@ will compare the checksums of the files to be sure the text has not changed. Any differences result in an error with the message - containing the proper checksum. + containing the current checksum. For more explanation and examples of how to set the LIC_FILES_CHKSUM variable, see the "Tracking License Changes" @@ -1511,76 +1673,94 @@ Configuring the Recipe - Configurations for your recipe might include passing in - configuration options in the case of an Autotools or CMake - enabled software or tweaking with the - DEPENDS - situation. - Regardless, you need to consider this part of the recipe. + Most software provides some means of setting build-time + configuration options before compilation. + Typically, setting these options is accomplished by running a + configure script with some options, or by modifying a build + configuration file. - If the software you are building uses Autotools or CMake to - get built, you do not have to create a - do_configure task in your recipe. - You might still want to make some adjustments however. - For example, you can set - EXTRA_OECONF - to pass any needed configure options that are specific to the - recipe. + When considering configuration, you should realize that + required build-time or runtime dependencies might or might not + be noted in the software's documentation. - If the source files have a configure.ac - or CMakeLists.txt file, then your software - is built using Autotools or CMake, respectively. - For either of these cases, you just need to worry about - tweaking the configuration. - However, if you don't have these files then your software is - being built by some other system and you need to provide a - do_configure task in your recipe. + The following list provides configuration items of note based + on how your software is built: + + Autotools: + If your source files have a + configure.ac file, then your + software is built using Autotools. + If this is the case, you just need to worry about + tweaking the configuration. + When using Autotools, your recipe needs to inherit + the + autotools + class and your recipe does not have to contain a + do_configure task. + However, you might still want to make some adjustments. + For example, you can set + EXTRA_OECONF + to pass any needed configure options that are specific + to the recipe. + CMake: + If your source files have a + CMakeLists.txt file, then your + software is built using CMake. + If this is the case, you just need to worry about + tweaking the configuration. + When you use CMake, your recipe needs to inherit + the + cmake + class and your recipe does not have to contain a + do_configure task. + You can make some adjustments by setting + EXTRA_OECMAKE + to pass any needed configure options that are specific + to the recipe. + Other: + If your source files do not have a + configure.ac or + CMakeLists.txt file, then your + software is built using some method other than Autotools + or CMake. + If this is the case, you need to provide a + do_configure task in your recipe. + + Even if your software is not being built by + Autotools or CMake, you still might not need to deal + with any configuration issues. + You need to determine if configuration is even a required step. + You might need to modify a Makefile or some configuration file + used for the build to specify necessary build options. + Or, perhaps you might need to run a hand-written configuration + script as opposed to something that + autoconf would run. + For the case involving a hand-written + configuration script, you would run + ./configure --help and look for + the options you need to set. + - Even if you are using Autotools or CMake and configuration - succeeds during the build, it is always good practice to look - at the log.do_configure file to ensure - that nothing needs to be added to + Once configuration succeeds, it is always good practice to + look at the log.do_configure file to + ensure that nothing needs to be added to DEPENDS. For example, if the configure script reports that it found - something not mentioned in DEPENDS, or that - it did not find something that it needed for some desired - optional functionality, then you would need to add + something not mentioned in DEPENDS, or + that it did not find something that it needed for some + desired optional functionality, then you would need to add those to DEPENDS. Looking at the log might also reveal items being checked for and/or enabled that you do not want, or items not being found that are in DEPENDS, in which case you would need to look at passing extra options to the - configure script as needed using - EXTRA_OECONF. - - - - You should also realize that required build-time or runtime - dependencies might or might not be noted in the software's - documentation. - - - - Even if your software is not being built by Autotools or CMake, - you still might not need to deal with any configuration issues. - You to determine if configuration is even a required step. - You might need to modify a Makefile or some configuration file - used for the build to specify necessary build options. - Or, perhaps you might need to run a hand-written configuration - script as opposed to something that - autoconf would run. - - - - For the case involving a hand-written configuration script, you - would run ./configure --help and look for - the options you need to set. + configure script as needed.
-- cgit v1.1