diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 2356b9fc36..f6184cec32 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1183,9 +1183,19 @@ Use and modify the following skeleton recipe: - I need a simple - skeleton recipe - here + inherit <stuff> + + SUMMARY = "" + HOMEPAGE = "" + LICENSE = "" + + LIC_FILES_CHKSUM = "" + + SRC_URI = "" + SRC_URI[md5sum] = "" + SRC_URI[sha256sum] = "" + + S = ${WORKDIR}/${PN}-${PV} Modifying this recipe is the recommended method for creating a new recipe. @@ -1335,16 +1345,48 @@ + + + Also part of the SRC_URI variable are the + 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. + + + + To find these checksums, you can comment the statements out + and then attempt to build the software. + The build will produce an error for each missing checksum + and as part of the error message provide the correct checksum + string. + Once you have the correct checksums, simply copy them into your + recipe for a subsequent build. +
Unpacking Code - unpacking: ensure S matches the directory that contains the source. Often the -default will work for a source archive, but it depends on how the upstream -project structures their archive. If SRC_URI specifies to fetch the source from -an SCM such as git or svn you'll definitely need to set S. + 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}. + + + + If you are fetching your source files from an upstream source + archived tarball then you normally do not need to set + S. + However, if SRC_URI specifies to fetch + source from an SCM like Git or Subversion, your recipe needs + to define S.
@@ -1352,33 +1394,193 @@ an SCM such as git or svn you'll definitely need to set S. Licensing - licensing: set correct values for LICENSE and LIC_FILES_CHKSUM, i.e. look for -a license statement somewhere (COPYING, LICENSE, part of a README, top of a -source file etc.) and then set the two variables accordingly. You need to go -through this several steps, i.e. look in the directory containing the -extracted source, then set LIC_FILES_CHKSUM to point to the file without the -md5 value specified, and then run bitbake on the recipe again and it will error -out with the actual md5 value which you can then put into the recipe. I notice -we don't necessarily have a list anywhere of the common values for LICENSE -either, so maybe we need to add this to the variable reference entry for this -variable. We should also cover what to do if there is no file specifying the -license shipped with the source. + Your recipe needs to have both the + LICENSE + and + LIC_FILES_CHKSUM + variables: + + LICENSE: + 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 + COPYING, + LICENSE, and + README files. + You could also find the information near the top of + 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: + + LICENSE = "GPLv2" + + LIC_FILES_CHKSUM: + The OpenEmbedded build system uses this variable to + make sure the license text has not changed. + If it has, the build produces an error and it affords + you the chance to figure it out and correct the problem. + + You need to specify all applicable licensing + files for the software. + At the end of the configuration step, the build process + 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. + For more explanation and examples of how to set the + LIC_FILES_CHKSUM variable, see the + "Tracking License Changes" + section in the Yocto Project Reference Manual. + To determine the correct checksum string, you + can list the appropriate files in the + LIC_FILES_CHKSUM variable with + incorrect md5 strings, attempt to build the software, + and then note the resulting error messages that will + report the correct md5 strings. + Here is an example that assumes the software has a + COPYING file: + + LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" + + When you try to build the software, the build system + will produce an error and give you the correct string + that you can substitute into the recipe file for a + subsequent build. + + + + +
Configuring the Recipe - configure: this depends on whether you're using autotools or not; if you are -then you should set EXTRA_OECONF to pass any needed configure options specific -to this recipe. If you are not using autotools, you need to define your own -do_configure function, assuming there is anything to configure. At this point -you may also need to tweak DEPENDS if the configure scripts complain about any -required dependencies being missing, assuming it's not just looking in the -wrong place for the dependency in which case it's usually a matter of -supplying the appropriate configure options to point to the correct location -within the sysroot. + 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. + + + + 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. + + + + 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. + + + + 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 + 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 + 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.
@@ -1386,10 +1588,18 @@ within the sysroot. Compiling the Recipe - compile: if the recipe passes through do_compile successfully, nothing needs -to be done. If not, diagnose the failure. We might be able to highlight common -issues here such as parallel build failures, host path usage when building for -the target, etc. + During a build, the do_compile task + happens after source is fetched, unpacked, and configured. + If the recipe passes through do_compile + successfully, nothing needs to be done. + + + + However, if the compile step fails, you need to diagnose the + failure. + Some common issues for failure are parallel build failures, + improper host path usage when building for the target, and + so forth. @@ -1397,9 +1607,9 @@ the target, etc. Installing - During installation, files your recipe builds are copied from - locations where work is being done to locations on the target - device. + During do_install, files your recipe builds + are copied from locations where work is being done to locations + on the target device. The installation process moves the ${S}, ${B}, @@ -1409,28 +1619,26 @@ the target, etc. ${D} to create the structure as it should appear on the target system. - - During the installation process, some of the files might also - be modified to suit the target layout as well. - How your software is built affects what you must do to be sure your software is installed correctly. The following list describes what you must do for installation - depending on how your recipe builds your software: + depending on the type of build system used by the software + being built: - Autotools and cmake: + Autotools and CMake: If the software your recipe is building uses Autotools - or cmake, the OpenEmbedded build + or CMake, the OpenEmbedded build system understands how to install the software. Consequently, you do not have to have a do_install task as part of your recipe. You just need to make sure the install portion of the build completes with no issues. - make install: + Other (using + make install): You need to define a do_install function in your recipe. @@ -1443,7 +1651,7 @@ the target, etc. PREFIX=${D}, INSTALLROOT=${D}, and so forth). - install: + Manual: You need to define a do_install function in your recipe. @@ -1462,7 +1670,7 @@ the target, etc. For the scenarios that do not use Autotools or - cmake, you need to track the installation + CMake, you need to track the installation and diagnose and fix any issues until everything installs correctly. You need to look in the default location of @@ -1470,19 +1678,38 @@ the target, etc. ${WORKDIR}/image, to be sure your files have been installed correctly. + + + During the installation process, you might need to modify + some of the installed files to suit the target layout. + For example, you might need to replace hard-coded paths in an + initscript with values of variables provided by the build + system, such as replacing /usr/bin/ with + ${bindir}. + If you do perform such modifications during + do_install, be sure to modify the + destination file after copying rather than before copying. + Modifying after copying ensures that the build system can + re-execute do_install if needed. + + + + oe_runmake install, which can be run + directly or can be run indirectly by the autotools and CMake + classes, runs make install in parallel. + Sometimes, a Makefile can have missing dependencies between + targets that can result in race conditions. + If you experience intermittent failures during + do_install, you might be able to work + around them by setting + PARALLEL_MAKEINST + to and empty string in the recipe. +
Supporting Services - - We'll probably also need some subsections on specific extra functions needed in -some recipes e.g. how to add support for services (sysvinit and systemd), -adding PACKAGECONFIG options, dealing with alternatives, etc. There's a -question in my mind on how some of these will overlap with the class reference -section though. - - If you are adding services and the service initialization script or the service file itself is not installed, you must @@ -1491,6 +1718,9 @@ section though. If your recipe already has a do_install function, you will need to be sure to change it so that it handles the installation of your services. + + + When you create the installation for your services, you need to accomplish what is normally done by "make install". In other words, make sure your installation puts the output @@ -1498,17 +1728,32 @@ section though. target system. + + Paul - We need to get some detail here on specific extra + functions needed in some recipes (e.g. how to add support for + services like sysvinit and systemd, how to add + PACKAGECONFIG options, how to + deal with alternatives, and so forth). +
Packaging - packaging: ensure that the files are packaged correctly. Resolve any package QA -issues (we need to have more detailed docs on this, probably as its own -section). This can also involve looking at packages-split under the work -directory and checking if files are where they need to be; if not, set -PACKAGES, FILES, do_install(_append) etc. as needed. + The do_package task ensures that files + are packaged correctly. + To be sure your packages are correct, examine the + ${WORKDIR}/packages-split + directory and make sure files are where you expect them to be. + + + + If you discover problems, you can set + PACKAGES, + FILES, + do_install(_append), and so forth as + needed.
@@ -1516,8 +1761,10 @@ PACKAGES, FILES, do_install(_append) etc. as needed. Testing - runtime testing: add the output package(s) to your image and ensure that they -work at runtime. + The final step for completing your recipe is to be sure that + the software you built runs correctly. + To accomplish runtime testing, add the build's output + packages to your image and test them on the target.