From 646bda0f1d24dbabb8e8ec8e0520d8f9cb817939 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 6 Feb 2012 11:39:17 -0600 Subject: [PATCH] documentation/dev-manual/dev-manual-common-tasks.xml: links fixed. Moving the "Common Tasks" section from the YP Reference Manual into the YP Development Manual upset a bunch of links. I have corrected these links. (From yocto-docs rev: 69ee73c59958aaab6f6370231c65300d1d8c92f8) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 166 ++++++++++-------- 1 file changed, 94 insertions(+), 72 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 4fef075360..14657861fc 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -23,7 +23,7 @@ variables. For information on variables that are useful for recipes and for information about recipe naming issues, see the - Required section for recipe variables. + Required" section of the Yocto Project Reference Manual. @@ -47,12 +47,14 @@ 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. + 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. + 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" @@ -89,7 +91,7 @@ Applications that use Autotools such as autoconf and automake require a recipe that has a source archive listed in - SRC_URI and + 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. @@ -111,10 +113,10 @@ - The variable LIC_FILES_CHKSUM - is used to track source license changes as described in the - Track License Change - section. + The variable + LIC_FILES_CHKSUM + is used to track source license changes as described in the + "Track License Change" section. You can quickly create Autotool-based recipes in a manner similar to the previous example. @@ -124,11 +126,11 @@ Applications that use GNU make also require a recipe that has - the source archive listed in SRC_URI. + 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. + 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. @@ -137,8 +139,8 @@ 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. + You can accomplish this by adding to the + CFLAGS variable. The following example shows this: CFLAGS_prepend = "-I ${S}/include " @@ -179,8 +181,9 @@ Splitting an Application into Multiple Packages - You can use the variables PACKAGES and - FILES to split an application into + You can use the variables + PACKAGES and + FILES to split an application into multiple packages. @@ -211,14 +214,17 @@ 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 + 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_* + 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 + Thus, the main + PN package does not include the above listed files. @@ -284,8 +290,9 @@ 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. + Normally + PN + can be used, which automatically expands to PACKAGENAME. A post-installation function has the following structure: pkg_postinst_PACKAGENAME () { @@ -323,7 +330,8 @@ The previous example delays execution until the image boots again because the - D variable points + 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. @@ -355,7 +363,7 @@ By creating a custom image, a developer has total control over the contents of the image. It is important to use the correct names of packages in the - IMAGE_INSTALL variable. + IMAGE_INSTALL variable. You must use the OpenEmbedded notation and not the Debian notation for the names (e.g. eglibc-dev instead of libc6-dev). @@ -380,12 +388,14 @@ that is used to build the image or images. A good example of a tasks package is meta/recipes-sato/tasks/task-poky.bb. - The PACKAGES + The + PACKAGES variable lists the task packages to build along with the complementary -dbg and -dev packages. For each package added, you can use - RDEPENDS - and RRECOMMENDS + RDEPENDS + and + RRECOMMENDS entries to provide a list of packages the parent task package should contain. Following is an example: @@ -423,7 +433,7 @@ To build an image using these task packages, you need to add task-custom-apps and/or task-custom-tools to - IMAGE_INSTALL. + IMAGE_INSTALL. For other forms of image dependencies see the other areas of this section. @@ -435,7 +445,7 @@ Ultimately users might want to add extra image features to the set used by Yocto Project with the - IMAGE_FEATURES + IMAGE_FEATURES variable. To create these features, the best reference is meta/classes/core-image.bbclass, which shows how the @@ -444,12 +454,12 @@ IMAGE_FEATURES variable and then maps that into a set of tasks or packages. Based on this information the - IMAGE_INSTALL variable - is generated automatically. + IMAGE_INSTALL + variable is generated automatically. Users can add extra features by extending the class or creating a custom class for use with specialized image .bb files. You can also add more features by configuring the - EXTRA_IMAGE_FEATURES + EXTRA_IMAGE_FEATURES variable in the local.conf file found in the Yocto Project files located in the build directory. @@ -486,7 +496,7 @@ The simplest way to add extra packages to all images is by using the - IMAGE_INSTALL + IMAGE_INSTALL variable with the _append operator: IMAGE_INSTALL_append = " strace" @@ -521,7 +531,7 @@ You can add packages using a similar approach through the - POKY_EXTRA_INSTALL + POKY_EXTRA_INSTALL variable. If you use this variable, only core-image-* images are affected. @@ -534,7 +544,8 @@ It is possible to filter or mask out recipe and recipe append files such that BitBake ignores them. You can do this by providing an expression with the - BBMASK variable. + BBMASK + variable. Here is an example: BBMASK = ".*/meta-mymachine/recipes-maybe/" @@ -581,24 +592,24 @@ The most important variables to set in this file are as follows: - - TARGET_ARCH (e.g. "arm") - - PREFERRED_PROVIDER_virtual/kernel (see below) - - MACHINE_FEATURES (e.g. "kernel26 apm screen wifi") + + TARGET_ARCH (e.g. "arm") + + PREFERRED_PROVIDER_virtual/kernel (see below) + + MACHINE_FEATURES (e.g. "kernel26 apm screen wifi") You might also need these variables: - - SERIAL_CONSOLE (e.g. "115200 ttyS0") - - KERNEL_IMAGETYPE (e.g. "zImage") - - IMAGE_FSTYPES (e.g. "tar.gz jffs2") + + SERIAL_CONSOLE (e.g. "115200 ttyS0") + + KERNEL_IMAGETYPE (e.g. "zImage") + + IMAGE_FSTYPES (e.g. "tar.gz jffs2") @@ -623,9 +634,10 @@ If you are creating a new recipe, normal recipe-writing rules apply for setting - up a SRC_URI. + up a + SRC_URI. Thus, you need to specify any necessary patches and set - S to point at the source code. + S to point at the source code. You need to create a configure task that configures the unpacked kernel with a defconfig. You can do this by using a make defconfig command or, @@ -643,7 +655,7 @@ used for other machines in a given kernel. A possible way to do this is by listing the file in the SRC_URI and adding the machine to the expression in - COMPATIBLE_MACHINE: + COMPATIBLE_MACHINE: COMPATIBLE_MACHINE = '(qemux86|qemumips)' @@ -698,20 +710,20 @@ During a build, source is available in the - WORKDIR directory. + WORKDIR directory. The actual location depends on the type of package and the architecture of the target device. For a standard recipe not related to - MACHINE, the location is + MACHINE, the location is tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/. For target device-dependent packages, you should use the MACHINE variable instead of - PACKAGE_ARCH + PACKAGE_ARCH in the directory name. Be sure the package recipe sets the - S variable to something + S variable to something other than the standard WORKDIR/PN-PV/ value. @@ -729,7 +741,7 @@ option forces re-execution of the specified task. You can call other tasks this way as well. But note that all the modifications in - WORKDIR + WORKDIR are gone once you execute -c clean for a package. @@ -770,9 +782,9 @@ You can find the resulting patch file in the patches/ subdirectory of the source - (S) directory. + (S) directory. For future builds, you should copy the patch into the Yocto Project metadata and add it into the - SRC_URI of a recipe. + SRC_URI of a recipe. Here is an example: SRC_URI += "file://NAME-OF-PATCH.patch" @@ -781,8 +793,8 @@ Finally, don't forget to 'bump' the - PR value in the same recipe since - the resulting packages have changed. + PR + value in the same recipe since the resulting packages have changed. @@ -961,7 +973,8 @@ If the package exists under a different name in a different distribution, you get a distro_check mismatch. You can resolve this problem by defining a per-distro recipe name alias using the - DISTRO_PN_ALIAS variable. + DISTRO_PN_ALIAS + variable. @@ -1029,7 +1042,8 @@ To enable a layer, you simply add the layer's path to the - BBLAYERS variable in your + BBLAYERS + variable in your bblayers.conf file, which is found in the Yocto Project file's build directory. The following example shows how to enable the meta-rt: @@ -1074,21 +1088,26 @@ In the previous example, the recipes for the layers are added to - BBFILES. - The BBFILE_COLLECTIONS + BBFILES. + The + BBFILE_COLLECTIONS variable is then appended with the layer name. - The BBFILE_PATTERN variable - immediately expands with a regular expression used to match files from + The + BBFILE_PATTERN + variable immediately expands with a regular expression used to match files from BBFILES into a particular layer, in this case by using the base pathname. - The BBFILE_PRIORITY variable + The + BBFILE_PRIORITY + variable then assigns different priorities to the files in different layers. Applying priorities is useful in situations where the same package might appear in multiple layers and allows you to choose what layer should take precedence. - Note the use of the LAYERDIR + Note the use of the + LAYERDIR variable with the immediate expansion operator. The LAYERDIR variable expands to the directory of the current layer and requires the immediate expansion operator so that BitBake does not wait to expand the variable @@ -1168,7 +1187,8 @@ If a committed change results in changing the package output, then the value of the - PR variable needs to be increased + PR + variable needs to be increased (or "bumped") as part of that commit. This means that for new recipes you must be sure to add the PR variable and set its initial value equal to "r0". @@ -1180,7 +1200,8 @@ If you are sharing a common .inc file with multiple recipes, you can also use the - INC_PR variable to ensure that + INC_PR + variable to ensure that the recipes sharing the .inc file are rebuilt when the .inc file itself is changed. The .inc file must set INC_PR @@ -1192,8 +1213,8 @@ When upgrading the version of a package, assuming the - PV changes, - the PR variable should be reset to "r0" + PV + changes, the PR variable should be reset to "r0" (or "$(INC_PR).0" if you are using INC_PR). @@ -1201,7 +1222,8 @@ Usually, version increases occur only to packages. However, if for some reason PV changes but does not increase, you can increase the - PE variable (Package Epoch). + PE + variable (Package Epoch). The PE variable defaults to "0".