diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 717a453061..053df0f838 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1146,6 +1146,12 @@
requires a recipe to define the component.
This section describes how to create, write, and test a new
recipe.
+
+ For information on variables that are useful for recipes and
+ for information about recipe naming issues, see the
+ "Required"
+ section of the Yocto Project Reference Manual.
+
@@ -1162,6 +1168,16 @@
Locate a Base Recipe
+
+ Before writing a recipe from scratch, it is often useful to
+ check whether someone else has written one already.
+ OpenEmbedded is a good place to look as it has a wider scope
+ and range of packages.
+ Because the Yocto Project aims to be compatible with
+ OpenEmbedded, most recipes you find there should work for
+ you.
+
+
Working from an existing recipe or a skeleton recipe is the
best way to get started.
@@ -1204,6 +1220,42 @@
+
+
+ When writing shell functions, you need to be aware of BitBake's
+ curly brace parsing.
+ If a recipe uses a closing curly brace within the function and
+ the character has no leading spaces, BitBake produces a parsing
+ error.
+ If you use a pair of curly brace in a shell function, the
+ closing curly brace must not be located at the start of the line
+ without leading spaces.
+ Here is an example that causes BitBake to produce a parsing
+ error:
+
+ fakeroot create_shar() {
+ cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
+ usage()
+ {
+ echo "test"
+ ###### The following "}" at the start of the line causes a parsing error ######
+ }
+ EOF
+ }
+
+ Writing the recipe this way avoids the error:
+
+ fakeroot create_shar() {
+ cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
+ usage()
+ {
+ echo "test"
+ ######The following "}" with a leading space at the start of the line avoids the error ######
+ }
+ EOF
+ }
+
+
@@ -2036,89 +2088,32 @@ do_unpack unpacks the source, and S must be set
section.
-
-
- Writing a Recipe to Add a Package to Your Image
-
-
- Recipes let you define packages you can add to your image.
- Writing a recipe means creating a .bb file that sets some
- variables.
- For information on variables that are useful for recipes and for information about recipe naming
- issues, see the
- "Required"
- section of the Yocto Project Reference Manual.
-
-
-
- Before writing a recipe from scratch, it is often useful to check
- whether someone else has written one already.
- OpenEmbedded is a good place to look as it has a wider scope and range of packages.
- Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
- you find there should work for you.
-
-
-
- For new packages, the simplest way to add a recipe is to base it on a similar
- pre-existing recipe.
- The sections that follow provide some examples that show how to add standard
- types of packages.
-
-
-
- When writing shell functions, you need to be aware of BitBake's
- curly brace parsing.
- If a recipe uses a closing curly brace within the function and
- the character has no leading spaces, BitBake produces a parsing
- error.
- If you use a pair of curly brace in a shell function, the
- closing curly brace must not be located at the start of the line
- without leading spaces.
- Here is an example that causes BitBake to produce a parsing
- error:
-
- fakeroot create_shar() {
- cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
- usage()
- {
- echo "test"
- ###### The following "}" at the start of the line causes a parsing error ######
- }
- EOF
- }
-
- Writing the recipe this way avoids the error:
-
- fakeroot create_shar() {
- cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
- usage()
- {
- echo "test"
- ######The following "}" with a leading space at the start of the line avoids the error ######
- }
- EOF
- }
-
-
-
-
- Single .c File Package (Hello World!)
+
+ Hello World Example
- Building an application from a single file that is stored locally (e.g. under
- files/) requires a recipe that has the file listed in
- the
- SRC_URI
- variable.
- Additionally, you need to manually write the do_compile and
- do_install tasks.
- The S
- variable defines the
- directory containing the source code, which is set to
-
- WORKDIR in this case - the directory BitBake uses for the build.
-
+ To help summarize how to write a recipe, this section provides
+ an example recipe that builds a single "Hello World!" package.
+
+
+
+ Single .c File Package (Hello World!)
+
+
+ Building an application from a single file that is stored locally (e.g. under
+ files/) requires a recipe that has the file listed in
+ the
+ SRC_URI
+ variable.
+ Additionally, you need to manually write the do_compile and
+ do_install tasks.
+ The S
+ variable defines the
+ directory containing the source code, which is set to
+
+ WORKDIR in this case - the directory BitBake uses for the build.
+
DESCRIPTION = "Simple helloworld application"
SECTION = "examples"
LICENSE = "MIT"
@@ -2137,32 +2132,32 @@ do_unpack unpacks the source, and S must be set
install -d ${D}${bindir}
install -m 0755 helloworld ${D}${bindir}
}
-
-
+
+
-
- By default, the helloworld, helloworld-dbg,
- and helloworld-dev packages are built.
- For information on how to customize the packaging process, see the
- "Splitting an Application
- into Multiple Packages" section.
-
-
+
+ By default, the helloworld, helloworld-dbg,
+ and helloworld-dev packages are built.
+ For information on how to customize the packaging process, see the
+ "Splitting an Application
+ into Multiple Packages" section.
+
+
-
- Autotooled Package
-
- Applications that use Autotools such as autoconf and
- automake require a recipe that has a source archive listed in
- SRC_URI and
- also inherits Autotools, which instructs BitBake to use the
- autotools.bbclass file, which contains the definitions of all the steps
- needed to build an Autotool-based application.
- The result of the build is automatically packaged.
- And, if the application uses NLS for localization, packages with local information are
- generated (one package per language).
- Following is one example: (hello_2.3.bb)
-
+
+ Autotooled Package
+
+ Applications that use Autotools such as autoconf and
+ automake require a recipe that has a source archive listed in
+ SRC_URI and
+ also inherits Autotools, which instructs BitBake to use the
+ autotools.bbclass file, which contains the definitions of all the steps
+ needed to build an Autotool-based application.
+ The result of the build is automatically packaged.
+ And, if the application uses NLS for localization, packages with local information are
+ generated (one package per language).
+ Following is one example: (hello_2.3.bb)
+
DESCRIPTION = "GNU Helloworld application"
SECTION = "examples"
LICENSE = "GPLv2+"
@@ -2172,49 +2167,49 @@ do_unpack unpacks the source, and S must be set
SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
inherit autotools gettext
-
-
+
+
-
- The variable
- LIC_FILES_CHKSUM
- is used to track source license changes as described in the
- "Tracking License Changes" section.
- You can quickly create Autotool-based recipes in a manner similar to the previous example.
-
-
+
+ The variable
+ LIC_FILES_CHKSUM
+ is used to track source license changes as described in the
+ "Tracking License Changes" section.
+ You can quickly create Autotool-based recipes in a manner similar to the previous example.
+
+
-
- Makefile-Based Package
+
+ Makefile-Based Package
-
- Applications that use GNU make also require a recipe that has
- the source archive listed in
- SRC_URI.
- You do not need to add a do_compile step since by default BitBake
- starts the make command to compile the application.
- If you need additional make options, you should store them in the
- EXTRA_OEMAKE
- variable.
- BitBake passes these options into the make GNU invocation.
- Note that a do_install task is still required.
- Otherwise, BitBake runs an empty do_install task by default.
-
+
+ Applications that use GNU make also require a recipe that has
+ the source archive listed in
+ SRC_URI.
+ You do not need to add a do_compile step since by default BitBake
+ starts the make command to compile the application.
+ If you need additional make options, you should store them in the
+ EXTRA_OEMAKE
+ variable.
+ BitBake passes these options into the make GNU invocation.
+ Note that a do_install task is still required.
+ Otherwise, BitBake runs an empty do_install task by default.
+
-
- Some applications might require extra parameters to be passed to the compiler.
- For example, the application might need an additional header path.
- You can accomplish this by adding to the
- CFLAGS variable.
- The following example shows this:
-
+
+ Some applications might require extra parameters to be passed to the compiler.
+ For example, the application might need an additional header path.
+ You can accomplish this by adding to the
+ CFLAGS variable.
+ The following example shows this:
+
CFLAGS_prepend = "-I ${S}/include "
-
-
+
+
-
- In the following example, mtd-utils is a makefile-based package:
-
+
+ In the following example, mtd-utils is a makefile-based package:
+
DESCRIPTION = "Tools for managing memory technology devices."
SECTION = "base"
DEPENDS = "zlib lzo e2fsprogs util-linux"
@@ -2245,46 +2240,46 @@ do_unpack unpacks the source, and S must be set
PARALLEL_MAKE = ""
BBCLASSEXTEND = "native"
-
-
+
+
-
- If your sources are available as a tarball instead of a Git repository, you
- will need to provide the URL to the tarball as well as an
- md5 or sha256 sum of
- the download.
- Here is an example:
-
+
+ If your sources are available as a tarball instead of a Git repository, you
+ will need to provide the URL to the tarball as well as an
+ md5 or sha256 sum of
+ the download.
+ Here is an example:
+
SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2"
SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
-
- You can generate the md5 or sha256 sums
- by using the md5sum or sha256sum commands
- with the target file as the only argument.
- Here is an example:
-
+
+ You can generate the md5 or sha256 sums
+ by using the md5sum or sha256sum commands
+ with the target file as the only argument.
+ Here is an example:
+
$ md5sum mtd-utils-1.4.9.tar.bz2
82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
-
-
-
+
+
+
-
- Splitting an Application into Multiple Packages
+
+ Splitting an Application into Multiple Packages
-
- You can use the variables
- PACKAGES and
- FILES
- to split an application into multiple packages.
-
+
+ You can use the variables
+ PACKAGES and
+ FILES
+ to split an application into multiple packages.
+
-
- Following is an example that uses the libXpm recipe.
- By default, this recipe generates a single package that contains the library along
- with a few binaries.
- You can modify the recipe to split the binaries into separate packages:
-
+
+ Following is an example that uses the libXpm recipe.
+ By default, this recipe generates a single package that contains the library along
+ with a few binaries.
+ You can modify the recipe to split the binaries into separate packages:
+
require xorg-lib-common.inc
DESCRIPTION = "X11 Pixmap library"
@@ -2299,61 +2294,61 @@ do_unpack unpacks the source, and S must be set
PACKAGES =+ "sxpm cxpm"
FILES_cxpm = "${bindir}/cxpm"
FILES_sxpm = "${bindir}/sxpm"
-
-
+
+
-
- In the previous example, we want to ship the sxpm
- and cxpm binaries in separate packages.
- Since bindir would be packaged into the main
- PN
- package by default, we prepend the PACKAGES
- variable so additional package names are added to the start of list.
- This results in the extra FILES_*
- variables then containing information that define which files and
- directories go into which packages.
- Files included by earlier packages are skipped by latter packages.
- Thus, the main PN package
- does not include the above listed files.
-
-
+
+ In the previous example, we want to ship the sxpm
+ and cxpm binaries in separate packages.
+ Since bindir would be packaged into the main
+ PN
+ package by default, we prepend the PACKAGES
+ variable so additional package names are added to the start of list.
+ This results in the extra FILES_*
+ variables then containing information that define which files and
+ directories go into which packages.
+ Files included by earlier packages are skipped by latter packages.
+ Thus, the main PN package
+ does not include the above listed files.
+
+
-
- Post-Installation Scripts
+
+ Post-Installation Scripts
-
- To add a post-installation script to a package, add a
- pkg_postinst_PACKAGENAME() function to the
- .bb file and use
- PACKAGENAME as the name of the package you want to attach to the
- postinst script.
- Normally,
- PN
- can be used, which automatically expands to PACKAGENAME.
- A post-installation function has the following structure:
-
+
+ To add a post-installation script to a package, add a
+ pkg_postinst_PACKAGENAME() function to the
+ .bb file and use
+ PACKAGENAME as the name of the package you want to attach to the
+ postinst script.
+ Normally,
+ PN
+ can be used, which automatically expands to PACKAGENAME.
+ A post-installation function has the following structure:
+
pkg_postinst_PACKAGENAME () {
#!/bin/sh -e
# Commands to carry out
}
-
-
+
+
-
- The script defined in the post-installation function is called when the
- root filesystem is created.
- If the script succeeds, the package is marked as installed.
- If the script fails, the package is marked as unpacked and the script is
- executed when the image boots again.
-
+
+ The script defined in the post-installation function is called when the
+ root filesystem is created.
+ If the script succeeds, the package is marked as installed.
+ If the script fails, the package is marked as unpacked and the script is
+ executed when the image boots again.
+
-
- Sometimes it is necessary for the execution of a post-installation
- script to be delayed until the first boot.
- For example, the script might need to be executed on the device itself.
- To delay script execution until boot time, use the following structure in the
- post-installation script:
-
+
+ Sometimes it is necessary for the execution of a post-installation
+ script to be delayed until the first boot.
+ For example, the script might need to be executed on the device itself.
+ To delay script execution until boot time, use the following structure in the
+ post-installation script:
+
pkg_postinst_PACKAGENAME () {
#!/bin/sh -e
if [ x"$D" = "x" ]; then
@@ -2362,15 +2357,35 @@ do_unpack unpacks the source, and S must be set
exit 1
fi
}
-
-
+
+
+
+
+ The previous example delays execution until the image boots again because the
+ D
+ variable points
+ to the directory containing the image when the root filesystem is created at build time but
+ is unset when executed on the first boot.
+
+
+
+
+
+
+
+
+
+
+ Writer Notes
- The previous example delays execution until the image boots again because the
- D
- variable points
- to the directory containing the image when the root filesystem is created at build time but
- is unset when executed on the first boot.
+
+
+ Need to edit the faq.xml chapter and find the single reference to
+ usingpoky-extend-addpkg and replace it
+ with new-recipe-testing-hello-world-example.
+
+