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.