From 71460e5fc274467d5d59f4f45ccb298590f699e8 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Sat, 21 Dec 2013 08:49:03 -0600 Subject: dev-manual: Integrated Hello World section into new writing recipe section This change merged in the Hello World section as a summarizing example section to the new "Writing a New Recipe" section. (From yocto-docs rev: 79c858e1590e5ab4c56b19dc51b03e0e570b6209) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 465 +++++++++++---------- 1 file changed, 240 insertions(+), 225 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 717a453..053df0f 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. +
@@ -1163,6 +1169,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. Here are some points on both methods: @@ -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. - +
+ Hello World Example - - 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 - } - - + + 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!) +
+ 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. - + + 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. + +
-- cgit v1.1