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:
-
- 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:
-
- PREFERRED_VERSION_foo = "1.1+git%"
-
- Compare that previous example against the following
- incorrect example, which does not work:
-
- PREFERRED_VERSION_foo = "git"
-
+ 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:
+
+ PREFERRED_VERSION_foo = "1.1+git%"
+
+ 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.