From 4b4b9c9c1929b7e7ad1381791f6bb720d5d8bc54 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 18 Oct 2018 13:12:32 -0700 Subject: ref-manual: Updates to describe wildcarding support Added specific wildcarding support descriptions for all related variables and file panthnames. (From yocto-docs rev: 543e398c4ae1bce38517a88cd91c957a583a2892) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-terms.xml | 30 +++++- documentation/ref-manual/ref-variables.xml | 167 ++++++++++++++++++++--------- 2 files changed, 144 insertions(+), 53 deletions(-) (limited to 'documentation') diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml index e25a147549..c573a521a7 100644 --- a/documentation/ref-manual/ref-terms.xml +++ b/documentation/ref-manual/ref-terms.xml @@ -29,11 +29,31 @@ information in the similarly-named recipe file. For an example of an append file in use, see the "Using .bbappend Files in Your Layer" - section in the Yocto Project Development Tasks Manual. - - Append files can also use wildcard patterns in their - version numbers so they can be applied to more than one - version of the underlying recipe file. + section in the Yocto Project Development Tasks Manual. + + When you name an append file, you can use the + "%" wildcard character to allow for + matching recipe names. + For example, suppose you have an append file named as follows: + + busybox_1.21.%.bbappend + + That append file would match any + busybox_1.21.x.bb + version of the recipe. + So, the append file would match the following recipe names: + + busybox_1.21.1.bb + busybox_1.21.2.bb + busybox_1.21.3.bb + + Important + The use of the "%" character + is limited in that it only works directly in front of the + .bbappend portion of the append file's + name. + You cannot use the wildcard character in any other + location of the name. diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 1bc6e2b77d..1774ba24c0 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -679,6 +679,13 @@ BB_ALLOWED_NETWORKS = "*.gnu.org" + Important + The use of the "*" + character only works at the beginning of + a host name. + You cannot use the wildcard character in any + other location of the name. + Mirrors not in the host list are skipped and @@ -1133,12 +1140,22 @@ BBFILES - BBFILES[doc] = "List of recipe files used by BitBake to build software." + BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software." - List of recipe files used by BitBake to build software. + A space-separated list of recipe files BitBake uses to + build software. + + + + When specifying recipe files, you can pattern match using + Python's + glob + syntax. + For details on the syntax, see the documentation by + following the previous link. @@ -1267,15 +1284,19 @@ match any of the expressions. It is as if BitBake does not see them at all. Consequently, matching files are not parsed or otherwise - used by BitBake. + used by BitBake. + + The values you provide are passed to Python's regular expression compiler. + Consequently, the syntax follows Python's Regular + Expression (re) syntax. The expressions are compared against the full paths to the files. For complete syntax information, see Python's - documentation for the appropriate release at - . + documentation at + . @@ -1443,6 +1464,17 @@ set up during compilation so that they are correct for use when installed into the sysroot and called by the build processes of other recipes. + + The BINCONFIG_GLOB variable + uses + shell globbing, + which is recognition and expansion of wildcards during + pattern matching. + Shell globbing is very similar to + fnmatch + and + glob. + @@ -2366,6 +2398,14 @@ Defines wildcards to match when installing a list of complementary packages for all the packages explicitly (or implicitly) installed in an image. + + The COMPLEMENTARY_GLOB variable + uses Unix filename pattern matching + (fnmatch), + which is similar to the Unix style pathname pattern + expansion + (glob). + The resulting list of complementary packages is associated with an item that can be added to IMAGE_FEATURES. @@ -4782,23 +4822,38 @@ FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" + Notes + + + When specifying files or paths, you can pattern + match using Python's + glob + syntax. + For details on the syntax, see the + documentation by following the previous link. + + + When specifying paths as part of the + FILES variable, it is + good practice to use appropriate path + variables. + For example, use ${sysconfdir} + rather than /etc, or + ${bindir} rather than + /usr/bin. + You can find a list of these variables at the + top of the + meta/conf/bitbake.conf + file in the + Source Directory. + You will also find the default values of the + various FILES_* variables + in this file. + + + - - When specifying paths as part of the - FILES variable, it is good practice - to use appropriate path variables. - For example, use ${sysconfdir} rather - than /etc, or - ${bindir} rather than - /usr/bin. - You can find a list of these variables at the top of the - meta/conf/bitbake.conf file in the - Source Directory. - You will also find the default values of the various - FILES_* variables in this file. - - If some of the files you provide with the FILES variable are editable and you @@ -10935,47 +10990,63 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" - If there are multiple versions of recipes available, this - variable determines which recipe should be given preference. + If multiple versions of recipes exist, this + variable determines which version is given preference. You must always suffix the variable with the PN you want to select, and you should set the PV accordingly for precedence. - You can use the "%" character as a - wildcard to match any number of characters, which can be - useful when specifying versions that contain long revision - numbers that could potentially change. + + + + The PREFERRED_VERSION variable + supports limited wildcard use through the + "%" character. + You can use the character to match any number of + characters, which can be useful when specifying versions + that contain long revision numbers that potentially change. Here are two examples: PREFERRED_VERSION_python = "3.4.0" PREFERRED_VERSION_linux-yocto = "4.12%" - - The specified version is matched against - PV, - which does not necessarily match the version part of - the recipe's filename. - For example, consider two recipes - foo_1.2.bb and - foo_git.bb where - foo_git.bb contains the following - assignment: - + Important + The use of the "%" character + is limited in that it only works at the end of the + string. + You cannot use the wildcard character in any other + location of the string. + + + + + The specified version is matched against + PV, + which does not necessarily match the version part of + the recipe's filename. + For example, consider two recipes + foo_1.2.bb and + foo_git.bb where + foo_git.bb contains the following + assignment: + PV = "1.1+git${SRCPV}" - - In this case, the correct way to select - foo_git.bb is by using an - assignment such as the following: - + + In this case, the correct way to select + foo_git.bb is by using an + assignment such as the following: + PREFERRED_VERSION_foo = "1.1+git%" - - Compare that previous example against the following - incorrect example, which does not work: - + + Compare that previous example against the following + incorrect example, which does not work: + PREFERRED_VERSION_foo = "git" - - + + + + Sometimes the PREFERRED_VERSION variable can be set by configuration files in a way that is hard to change. -- cgit v1.2.3-54-g00ecf