From aa3a201629c7e40341f53d4be57b6e4223a845c8 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 9 Mar 2012 13:40:39 -0600 Subject: documentation/dev-manual: Converted to use poky.ent I converted the hard links to use the variables as established in the file poky.ent. Also, Cleaned up some bad text in the term "Yocto Project Files." Looks like a cut-and-paste problem. (From yocto-docs rev: e2e20bf4895d80dae73595e93132f37fb31121d1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 177 +++++++++++---------- 1 file changed, 92 insertions(+), 85 deletions(-) (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 4702ae94e3..74375c89bf 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1,5 +1,6 @@ +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[ %poky; ] > @@ -60,8 +61,8 @@ and then explore that folder, you will discover many BSP layers within the meta-intel layer. For more information on BSP layers, see the - "BSP Layers" - section in the Yocto Project Development Manual. + "BSP Layers" + section in the Yocto Project Board Support Package (BSP) Developer's Guide. @@ -76,7 +77,7 @@ you should be sure someone has not already created a layer containing the metadata you need. You can see the - LayerIndex + LayerIndex for a list of layers from the OpenEmbedded community that can be used in the Yocto Project. Create a Directory: Create the directory @@ -108,24 +109,24 @@ BBFILE_PRIORITY_yocto = "5" In the previous example, the recipes for the layers are added to - BBFILES. + BBFILES. The - BBFILE_COLLECTIONS + BBFILE_COLLECTIONS variable is then appended with the layer name. The - BBFILE_PATTERN + BBFILE_PATTERN variable is set to a regular expression and is used to match files from BBFILES into a particular layer. In this case, immediate expansion of - LAYERDIR + LAYERDIR sets BBFILES_PATTERN to the layer's path. The - BBFILE_PRIORITY + BBFILE_PRIORITY variable then assigns a priority to the layer. 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 + 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 @@ -199,7 +200,7 @@ Before the Yocto Project build system can use your new layer, you need to enable it. To enable your layer, simply add your layer's path to the - BBLAYERS + BBLAYERS variable in your conf/bblayers.conf file, which is found in the Yocto Project Build Directory. The following example shows how to enable a layer named meta-mylayer: @@ -290,12 +291,12 @@ PRINC = "1" This example adds or overrides files in - SRC_URI + SRC_URI within a bbappend by extending the path BitBake uses to search for files. The most reliable way to do this is by prepending the FILESEXTRAPATHS variable. For example, if you have your files in a directory that is named the same as your package - (PN), + (PN), you can add this directory by adding the following to your bbappend file: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -328,7 +329,7 @@ To specify the layer's priority manually, use the - BBFILE_PRIORITY + BBFILE_PRIORITY variable. For example: @@ -338,7 +339,7 @@ It is possible for a recipe with a lower version number - PV + PV in a layer that has a higher priority to take precedence. Also, the layer priority does not currently affect the precedence order of .conf or .bbclass files. @@ -409,7 +410,8 @@ 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. + "Required" + section of the Yocto Project Reference Manual. @@ -434,12 +436,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. + SRC_URI + variable. Additionally, you need to manually write the do_compile and do_install tasks. - The S variable defines the + 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" @@ -477,7 +481,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. @@ -500,9 +504,9 @@ The variable - LIC_FILES_CHKSUM + LIC_FILES_CHKSUM is used to track source license changes as described in the - "Track License Change" section. + "Track License Change" section. You can quickly create Autotool-based recipes in a manner similar to the previous example. @@ -512,11 +516,13 @@ 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. @@ -526,7 +532,7 @@ 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. + CFLAGS variable. The following example shows this: CFLAGS_prepend = "-I ${S}/include " @@ -568,9 +574,9 @@ You can use the variables - PACKAGES and - FILES to split an application into - multiple packages. + PACKAGES and + FILES + to split an application into multiple packages. @@ -600,17 +606,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 + PN package by default, we prepend the - PACKAGES + PACKAGES variable so additional package names are added to the start of list. This results in the extra - FILES_* + 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 + PN package does not include the above listed files. @@ -677,7 +683,7 @@ PACKAGENAME as the name of the package you want to attach to the postinst script. Normally - PN + PN can be used, which automatically expands to PACKAGENAME. A post-installation function has the following structure: @@ -716,7 +722,7 @@ The previous example delays execution until the image boots again because the - D + 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. @@ -749,7 +755,8 @@ 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). @@ -775,13 +782,13 @@ A good example of a tasks package is meta/recipes-sato/tasks/task-poky.bb. The - PACKAGES + PACKAGES variable lists the task packages to build along with the complementary -dbg and -dev packages. For each package added, you can use - RDEPENDS + RDEPENDS and - RRECOMMENDS + RRECOMMENDS entries to provide a list of packages the parent task package should contain. Following is an example: @@ -819,7 +826,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. @@ -831,7 +838,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 @@ -840,12 +847,12 @@ IMAGE_FEATURES variable and then maps that into a set of tasks or packages. Based on this information the - IMAGE_INSTALL + 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. @@ -882,7 +889,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" @@ -917,7 +924,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. @@ -930,7 +937,7 @@ 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 + BBMASK variable. Here is an example: @@ -1006,7 +1013,7 @@ so that there are some definite steps on how to do this. I need more detail her For a complete example that shows how to add a new machine to the Yocto Project, see the - "BSP Development Example" + "BSP Development Example" in Appendix A. @@ -1022,11 +1029,11 @@ so that there are some definite steps on how to do this. I need more detail her 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") @@ -1034,11 +1041,11 @@ so that there are some definite steps on how to do this. I need more detail her You might also need these variables: - + SERIAL_CONSOLE (e.g. "115200 ttyS0") - + KERNEL_IMAGETYPE (e.g. "zImage") - + IMAGE_FSTYPES (e.g. "tar.gz jffs2") @@ -1065,9 +1072,9 @@ so that there are some definite steps on how to do this. I need more detail her If you are creating a new recipe, normal recipe-writing rules apply for setting up a - SRC_URI. + 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, @@ -1085,7 +1092,7 @@ so that there are some definite steps on how to do this. I need more detail her 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)' @@ -1159,7 +1166,7 @@ so that there are some definite steps on how to do this. I need more detail her During a build, the unpacked temporary source code used by recipes to build packages is available in the Yocto Project Build Directory as defined by the - S variable. + S variable. Below is the default value for the S variable as defined in the meta/conf/bitbake.conf configuration file in the Yocto Project Files: @@ -1180,7 +1187,7 @@ so that there are some definite steps on how to do this. I need more detail her The path to the work directory for the recipe - (WORKDIR) depends + (WORKDIR) depends on the package name and the architecture of the target device. For example, here is the work directory for packages whose targets are not device-dependent: @@ -1212,15 +1219,15 @@ so that there are some definite steps on how to do this. I need more detail her To better understand how the Yocto Project build system resolves directories during the build process, see the glossary entries for the - WORKDIR, - TMPDIR, - TOPDIR, - PACKAGE_ARCH, - TARGET_OS, - PN, - PV, + WORKDIR, + TMPDIR, + TOPDIR, + PACKAGE_ARCH, + TARGET_OS, + PN, + PV, and - PR + PR variables in the Yocto Project Reference Manual. @@ -1255,7 +1262,7 @@ so that there are some definite steps on how to do this. I need more detail her Change Your Working Directory: You need to be in the directory that has the temporary source code. That directory is defined by the - S + S variable. Create a New Patch: Before modifying source code, you need to create a new patch. @@ -1287,7 +1294,7 @@ so that there are some definite steps on how to do this. I need more detail her -c cleanall with BitBake for the package. Modifications will also disappear if you use the rm_work feature as described in the - "Building an Image" + "Building an Image" section of the Yocto Project Quick Start. Generate the Patch: @@ -1307,7 +1314,7 @@ so that there are some definite steps on how to do this. I need more detail her Placing the patch here guarantees that the Yocto Project build system will find the patch. Next, add the patch into the - SRC_URI + SRC_URI of the recipe. Here is an example: @@ -1315,7 +1322,7 @@ so that there are some definite steps on how to do this. I need more detail her Increment the Package Revision Number: Finally, don't forget to 'bump' the - PR + PR value in the same recipe since the resulting packages have changed. @@ -1351,7 +1358,7 @@ so that there are some definite steps on how to do this. I need more detail her Change Your Working Directory: You need to be in the directory that has the temporary source code. That directory is defined by the - S + S variable. Initialize a Git Repository: Use the git init command to initialize a new local repository @@ -1390,7 +1397,7 @@ so that there are some definite steps on how to do this. I need more detail her -c cleanall with BitBake for the package. Modifications will also disappear if you use the rm_work feature as described in the - "Building an Image" + "Building an Image" section of the Yocto Project Quick Start. See the List of Files You Changed: @@ -1435,7 +1442,7 @@ so that there are some definite steps on how to do this. I need more detail her Placing the patch here guarantees that the Yocto Project build system will find the patch. Next, add the patch into the - SRC_URI + SRC_URI of the recipe. Here is an example: @@ -1443,7 +1450,7 @@ so that there are some definite steps on how to do this. I need more detail her Increment the Package Revision Number: Finally, don't forget to 'bump' the - PR + PR value in the same recipe since the resulting packages have changed. @@ -1481,7 +1488,7 @@ so that there are some definite steps on how to do this. I need more detail her This section overviews the Multilib process only. For more details on how to implement Multilib, see the - Multilib wiki + Multilib wiki page. @@ -1630,7 +1637,7 @@ so that there are some definite steps on how to do this. I need more detail her For concepts on kernel configuration, see the - "Kernel Configuration" + "Kernel Configuration" section in the Yocto Project Kernel Architecture and Use Manual. @@ -1804,7 +1811,7 @@ so that there are some definite steps on how to do this. I need more detail her If a committed change results in changing the package output, then the value of the - PR + 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 @@ -1817,7 +1824,7 @@ so that there are some definite steps on how to do this. I need more detail her If you are sharing a common .inc file with multiple recipes, you can also use the - INC_PR + INC_PR variable to ensure that the recipes sharing the .inc file are rebuilt when the .inc file itself is changed. @@ -1830,7 +1837,7 @@ so that there are some definite steps on how to do this. I need more detail her When upgrading the version of a package, assuming the - PV + PV changes, the PR variable should be reset to "r0" (or "$(INC_PR).0" if you are using INC_PR). @@ -1839,7 +1846,7 @@ so that there are some definite steps on how to do this. I need more detail her Usually, version increases occur only to packages. However, if for some reason PV changes but does not increase, you can increase the - PE + PE variable (Package Epoch). The PE variable defaults to "0". @@ -1876,7 +1883,7 @@ so that there are some definite steps on how to do this. I need more detail her 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 + DISTRO_PN_ALIAS variable. @@ -1928,16 +1935,16 @@ so that there are some definite steps on how to do this. I need more detail her In this case, you want a kernel source directory on the development machine where the development occurs. You want the recipe's - SRC_URI + SRC_URI variable to point to the external directory and use it as is, not copy it. To build from software that comes from an external source, all you need to do is change your recipe so that it inherits the - externalsrc.bbclass + externalsrc.bbclass class and then sets the - S + S variable to point to your external source code. Here are the statements to put in your recipe: @@ -1949,11 +1956,11 @@ so that there are some definite steps on how to do this. I need more detail her It is important to know that the externalsrc.bbclass assumes that the source directory S and the build directory - B + B are different even though by default these directories are the same. This assumption is important because it supports building different variants of the recipe by using the - BBCLASSEXTEND + BBCLASSEXTEND variable. You could allow the build directory to be the same as the source directory but you would not be able to build more than one variant of the recipe. -- cgit v1.2.3-54-g00ecf