From a0f4706d238d84380f2fffcea869096bcd643556 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 29 May 2013 11:45:12 +0300 Subject: ref-manual: Updated note for FILESEXTRAPATHS variable. Added a bit more clarification (different wording) on why to use the immediate expansion operator and on why to include the trailing separating colon character. (From yocto-docs rev: 1ca951af9bc3b9a60bb7503d21a7ef94bb46454a) Signed-off-by: Scott Rifenbark Conflicts: documentation/ref-manual/ref-variables.xml Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-variables.xml | 307 +++++++++++++++-------------- 1 file changed, 161 insertions(+), 146 deletions(-) (limited to 'documentation') diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index ac4686f4da..b075f54c7e 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -600,31 +600,31 @@ Core layer for images cannot be removed COMPATIBLE_HOST - A regular expression that resolves to one or more hosts - (when the recipe is native) or one or more targets (when + A regular expression that resolves to one or more hosts + (when the recipe is native) or one or more targets (when the recipe is non-native) with which a recipe is compatible. The regular expression is matched against HOST_SYS. You can use the variable to stop recipes from being built - for classes of systems with which the recipes are not + for classes of systems with which the recipes are not compatible. Stopping these builds is particularly useful with kernels. - The variable also helps to increase parsing speed - since the build system skips parsing recipes not + The variable also helps to increase parsing speed + since the build system skips parsing recipes not compatible with the current system. COMPATIBLE_MACHINE - A regular expression that resolves to one or more + A regular expression that resolves to one or more target machines with which a recipe is compatible. The regular expression is matched against MACHINEOVERRIDES. You can use the variable to stop recipes from being built for machines with which the recipes are not compatible. Stopping these builds is particularly useful with kernels. - The variable also helps to increase parsing speed + The variable also helps to increase parsing speed since the build system skips parsing recipes not compatible with the current machine. @@ -746,8 +746,8 @@ Core layer for images cannot be removed Specifies a weak bias for recipe selection priority. - The most common usage of this is variable is to set - it to "-1" within a recipe for a development version of a + The most common usage of this is variable is to set + it to "-1" within a recipe for a development version of a piece of software. Using the variable in this way causes the stable version of the recipe to build by default in the absence of @@ -755,10 +755,10 @@ Core layer for images cannot be removed being used to build the development version. - The bias provided by DEFAULT_PREFERENCE - is weak and is overridden by + The bias provided by DEFAULT_PREFERENCE + is weak and is overridden by BBFILE_PRIORITY - if the that variable is different between two layers + if the that variable is different between two layers that contain different versions of the same recipe. @@ -909,12 +909,12 @@ Core layer for images cannot be removed DISTROOVERRIDES - This variable lists overrides specific to the current - distribution. - By default, the variable list includes the value of the + This variable lists overrides specific to the current + distribution. + By default, the variable list includes the value of the DISTRO variable. - You can extend the variable to apply any variable overrides + You can extend the variable to apply any variable overrides you want as part of the distribution and are not already in OVERRIDES through some other means. @@ -1158,16 +1158,16 @@ Core layer for images cannot be removed Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files. - The directories BitBake uses when it processes recipes - are defined by the + The directories BitBake uses when it processes recipes + are defined by the FILESPATH - variable, and can be extended using + variable, and can be extended using FILESEXTRAPATHS. - Best practices dictate that you accomplish this by using the - variable from within a .bbappend file + Best practices dictate that you accomplish this by using the + variable from within a .bbappend file and that you prepend paths as follows: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -1175,13 +1175,28 @@ Core layer for images cannot be removed In the above example, the build system looks for files in a directory that has the same name as the corresponding append file. + + When extending FILESEXTRAPATHS, + be sure to use the immediate expansion + (:=) operator. + Immediate expansion makes sure that BitBake evaluates + THISDIR at the time the directive + is encountered rather than at some later time when + expansion might result in a directory that does not + contain the files you need. + Also, include the trailing separating colon + character if you are prepending. + The trailing colon character is necessary because you + are directing BitBake to extend the path by prepending + directories to the search path. + Here is another common use: FILESEXTRAPATHS_prepend := "${THISDIR}/files:" - In this example, the build system extends the + In this example, the build system extends the FILESPATH variable to include a - directory named files that is in the + directory named files that is in the same directory as the corresponding append file. @@ -1195,11 +1210,11 @@ Core layer for images cannot be removed By prepending paths in .bbappend files, you allow multiple append files that reside in - different layers but are used for the same recipe to + different layers but are used for the same recipe to correctly extend the path. Be sure to use the immediate expansion - (:=) operator and include + (:=) operator and include the trailing separating colon character. @@ -1209,17 +1224,17 @@ Core layer for images cannot be removed FILESPATH - The default set of directories the OpenEmbedded build system + The default set of directories the OpenEmbedded build system uses when searching for patches and files. During the build process, BitBake searches each directory in - FILESPATH in the specified order when - looking for files and patches specified by each + FILESPATH in the specified order when + looking for files and patches specified by each file:// URI in a recipe. - The default value for the FILESPATH - variable is defined in the base.bbclass + The default value for the FILESPATH + variable is defined in the base.bbclass class found in meta/classes in the Source Directory: @@ -1227,18 +1242,18 @@ Core layer for images cannot be removed "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" - Do not hand-edit the FILESPATH + Do not hand-edit the FILESPATH variable. Be aware that the default FILESPATH directories do not map to directories in custom layers - where append files (.bbappend) + where append files (.bbappend) are used. If you want the build system to find patches or files that reside with your append files, you need to extend - the FILESPATH variable by using - the - FILESEXTRAPATHS + the FILESPATH variable by using + the + FILESEXTRAPATHS variable. @@ -1306,10 +1321,10 @@ Core layer for images cannot be removed HOST_SYS - Specifies the system, including the architecture and the + Specifies the system, including the architecture and the operating system, for with the build is occurring in the context of the current - recipe. + recipe. The OpenEmbedded build system automatically sets this variable. You do not need to set the variable yourself. @@ -1319,12 +1334,12 @@ Core layer for images cannot be removed Here are two examples: Given a native recipe on a 32-bit - x86 machine running Linux, the value is + x86 machine running Linux, the value is "i686-linux". - Given a recipe being built for a + Given a recipe being built for a little-endian MIPS target running Linux, - the value might be "mipsel-linux". + the value might be "mipsel-linux". @@ -1419,24 +1434,24 @@ Core layer for images cannot be removed Specifies the list of locales to install into the image during the root filesystem construction process. - The OpenEmbedded build system automatically splits locale - files, which are used for localization, into separate - packages. + The OpenEmbedded build system automatically splits locale + files, which are used for localization, into separate + packages. Setting the IMAGE_LINGUAS variable - ensures that any locale packages that correspond to packages - already selected for installation into the image are also - installed. + ensures that any locale packages that correspond to packages + already selected for installation into the image are also + installed. Here is an example: IMAGE_LINGUAS = "pt-br de-de" - In this example, the build system ensures any Brazilian - Portuguese and German locale files that correspond to - packages in the image are installed (i.e. + In this example, the build system ensures any Brazilian + Portuguese and German locale files that correspond to + packages in the image are installed (i.e. *-locale-pt-br - and *-locale-de-de as well as + and *-locale-de-de as well as *-locale-pt - and *-locale-de, since some software + and *-locale-de, since some software packages only provide locale files by language and not by country-specific language). @@ -1672,12 +1687,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" INSANE_SKIP - Specifies the QA checks to skip for a specific package + Specifies the QA checks to skip for a specific package within a recipe. - For example, to skip the check for symbolic link - .so files in the main package of a + For example, to skip the check for symbolic link + .so files in the main package of a recipe, add the following to the recipe. - The package name override must be used, which in this + The package name override must be used, which in this example is ${PN}: INSANE_SKIP_${PN} += "dev-so" @@ -1685,7 +1700,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" See the "Generated Output Quality Assurance Checks - insane.bbclass" - section for a list of the valid QA checks you can + section for a list of the valid QA checks you can specify using this variable. @@ -2199,7 +2214,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" LOG_DIR - Specifies the directory to which the OpenEmbedded build + Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log. @@ -2474,22 +2489,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" MACHINEOVERRIDES - Lists overrides specific to the current machine. + Lists overrides specific to the current machine. By default, this list includes the value - of MACHINE. - You can extend the list to apply variable overrides for + of MACHINE. + You can extend the list to apply variable overrides for classes of machines. - For example, all QEMU emulated machines (e.g. qemuarm, + For example, all QEMU emulated machines (e.g. qemuarm, qemux86, and so forth) include a common file named meta/conf/machine/include/qemu.inc - that prepends MACHINEOVERRIDES with + that prepends MACHINEOVERRIDES with the following variable override: MACHINEOVERRIDES =. "qemuall:" Applying an override like qemuall affects all QEMU emulated machines elsewhere. - Here is an example from the + Here is an example from the connman-conf recipe: SRC_URI_append_qemuall = "file://wired.config \ @@ -2578,18 +2593,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" A string identifying the host distribution. Strings consist of the host distributor ID - followed by the release, as reported by the + followed by the release, as reported by the lsb_release tool - or as read from /etc/lsb-release. - For example, when running a build on Ubuntu 12.10, the value - is "Ubuntu-12.10". - If this information is unable to be determined, the value + or as read from /etc/lsb-release. + For example, when running a build on Ubuntu 12.10, the value + is "Ubuntu-12.10". + If this information is unable to be determined, the value resolves to "Unknown". - This variable is used by default to isolate native shared - state packages for different distributions (e.g. to avoid - problems with glibc version + This variable is used by default to isolate native shared + state packages for different distributions (e.g. to avoid + problems with glibc version incompatibilities). Additionally, the variable is checked against SANITY_TESTED_DISTROS @@ -2920,15 +2935,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" PROVIDES - A list of aliases that a recipe also provides. - These aliases are useful for satisfying dependencies of - other recipes during the build (as specified by + A list of aliases that a recipe also provides. + These aliases are useful for satisfying dependencies of + other recipes during the build (as specified by DEPENDS). - A recipe's own + A recipe's own PN - is implicitly already in its - PROVIDES list. + is implicitly already in its + PROVIDES list. @@ -3090,8 +3105,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" RM_WORK_EXCLUDE - With rm_work enabled, this - variable specifies a list of packages whose work directories + With rm_work enabled, this + variable specifies a list of packages whose work directories should not be removed. See the "Removing Work Files During the Build - rm_work.bbclass" section for more details. @@ -3102,9 +3117,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" RPROVIDES - A list of package name aliases that a package also provides. - These aliases are useful for satisfying runtime dependencies - of other packages both during the build and on the target + A list of package name aliases that a package also provides. + These aliases are useful for satisfying runtime dependencies + of other packages both during the build and on the target (as specified by RDEPENDS). @@ -3113,7 +3128,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" - As with all package-controlling variables, you must always + As with all package-controlling variables, you must always use the variable in conjunction with a package name override. Here is an example: @@ -3163,18 +3178,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" RREPLACES - A list of packages replaced by a package. - The package manager uses this variable to determine which - package should be installed to replace other package(s) + A list of packages replaced by a package. + The package manager uses this variable to determine which + package should be installed to replace other package(s) during an upgrade. - In order to also have the other package(s) removed at the - same time, you must add the name of the other + In order to also have the other package(s) removed at the + same time, you must add the name of the other package to the RCONFLICTS variable. As with all package-controlling variables, you must use - this variable in conjunction with a package name + this variable in conjunction with a package name override. Here is an example: @@ -3187,14 +3202,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" RSUGGESTS - A list of additional packages that you can suggest for - installation by the package manager at the time a package + A list of additional packages that you can suggest for + installation by the package manager at the time a package is installed. Not all package managers support this functionality. As with all package-controlling variables, you must always - use this variable in conjunction with a package name + use this variable in conjunction with a package name override. Here is an example: @@ -3239,19 +3254,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" SANITY_TESTED_DISTROS - A list of the host distribution identifiers that the + A list of the host distribution identifiers that the build system has been tested against. Identifiers consist of the host distributor ID - followed by the release, + followed by the release, as reported by the lsb_release tool - or as read from /etc/lsb-release. - Separate the list items with explicit newline + or as read from /etc/lsb-release. + Separate the list items with explicit newline characters (\n). - If SANITY_TESTED_DISTROS is not empty - and the current value of + If SANITY_TESTED_DISTROS is not empty + and the current value of NATIVELSBSTRING - does not appear in the list, then the build system reports - a warning that indicates the current host distribution has + does not appear in the list, then the build system reports + a warning that indicates the current host distribution has not been tested as a build host. @@ -3302,17 +3317,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" SIGGEN_EXCLUDERECIPES_ABISAFE - A list of recipes that are completely stable and will + A list of recipes that are completely stable and will never change. The ABI for the recipes in the list are presented by output from the tasks run to build the recipe. - Use of this variable is one way to remove dependencies from + Use of this variable is one way to remove dependencies from one recipe on another that affect task signatures and - thus force rebuilds when the recipe changes. + thus force rebuilds when the recipe changes. If you add an inappropriate variable to this list, - the software might break at runtime if the - interface of the recipe was changed after the other + the software might break at runtime if the + interface of the recipe was changed after the other had been built. @@ -3322,25 +3337,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS - A list of recipe dependencies that should not be used to + A list of recipe dependencies that should not be used to determine signatures of tasks from one recipe when they - depend on tasks from another recipe. + depend on tasks from another recipe. For example: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" - In this example, intone depends on + In this example, intone depends on mplayer2. - Use of this variable is one mechanism to remove dependencies - that affect task signatures and thus force rebuilds when a - recipe changes. + Use of this variable is one mechanism to remove dependencies + that affect task signatures and thus force rebuilds when a + recipe changes. If you add an inappropriate dependency for a recipe - relationship, the software might break during - runtime if the interface of the second recipe was + relationship, the software might break during + runtime if the interface of the second recipe was changed after the first recipe had been built. @@ -3369,12 +3384,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Groups together machines based upon the same family - of SOC (System On Chip). + of SOC (System On Chip). You typically set this variable in a common - .inc file that you include in the - configuration files of all the machines. + .inc file that you include in the + configuration files of all the machines. - You must include + You must include conf/machine/include/soc-family.inc for this variable to appear in MACHINEOVERRIDES. @@ -3397,56 +3412,56 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" SRC_URI The list of source files - local or remote. - This variable tells the OpenEmbedded build system which bits + This variable tells the OpenEmbedded build system which bits to pull in for the build and how to pull them in. - For example, if the recipe or append file only needs to - fetch a tarball from the Internet, the recipe or - append file uses a single SRC_URI + For example, if the recipe or append file only needs to + fetch a tarball from the Internet, the recipe or + append file uses a single SRC_URI entry. - On the other hand, if the recipe or append file needs to - fetch a tarball, apply two patches, and include a custom + On the other hand, if the recipe or append file needs to + fetch a tarball, apply two patches, and include a custom file, the recipe or append file would include four instances of the variable. The following list explains the available URI protocols: file:// - - Fetches files, which are usually files shipped with + Fetches files, which are usually files shipped with the Metadata, from the local machine. The path is relative to the FILESPATH variable. - Thus, the build system searches, in order, from the - following directories, which are assumed to be a + Thus, the build system searches, in order, from the + following directories, which are assumed to be a subdirectories of the directory in which the - recipe file (.bb) or - append file (.bbappend) + recipe file (.bb) or + append file (.bbappend) resides: ${BPN} - - The base recipe name without any special + The base recipe name without any special suffix or version numbers. ${BP} - ${BPN}-${PV}. - The base recipe name and version but without + The base recipe name and version but without any special package name suffix. - files - - Files within a directory, which is named - files and is also + files - + Files within a directory, which is named + files and is also alongside the recipe or append file. - If you want the build system to pick up files - specified through a + If you want the build system to pick up files + specified through a SRC_URI statement from your append file, you need to be - sure to extend the + sure to extend the FILESPATH - variable by also using the + variable by also using the FILESEXTRAPATHS variable from within your append file. @@ -3691,9 +3706,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" STAMPS_DIR - Specifies the base directory in which the OpenEmbedded + Specifies the base directory in which the OpenEmbedded build system places stamps. - The default directory is + The default directory is ${TMPDIR}/stamps. @@ -3715,10 +3730,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" SYSROOT_PREPROCESS_FUNCS - A list of functions to execute after files are staged into + A list of functions to execute after files are staged into the sysroot. - These functions are usually used to apply additional - processing on the staged files, or to stage additional + These functions are usually used to apply additional + processing on the staged files, or to stage additional files. @@ -3730,15 +3745,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" T - This variable points to a directory were BitBake places - temporary files, which consist mostly of task logs and - scripts, when building a particular recipe. + This variable points to a directory were BitBake places + temporary files, which consist mostly of task logs and + scripts, when building a particular recipe. The variable is typically set as follows: T = "${WORKDIR}/temp" The WORKDIR - is the directory into which BitBake unpacks and builds the + is the directory into which BitBake unpacks and builds the recipe. The default bitbake.conf file sets this variable. The T variable is not to be confused with -- cgit v1.2.3-54-g00ecf