summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-10-18 13:12:32 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-10-20 14:28:00 +0100
commit4b4b9c9c1929b7e7ad1381791f6bb720d5d8bc54 (patch)
tree6e8e76330e0269de6321bb4b33d37742248d2ca5 /documentation/ref-manual
parentafec74f512508639648b76cc35fbfaf5f47455fe (diff)
downloadpoky-4b4b9c9c1929b7e7ad1381791f6bb720d5d8bc54.tar.gz
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 <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/ref-terms.xml30
-rw-r--r--documentation/ref-manual/ref-variables.xml167
2 files changed, 144 insertions, 53 deletions
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 @@
29 information in the similarly-named recipe file. 29 information in the similarly-named recipe file.
30 For an example of an append file in use, see the 30 For an example of an append file in use, see the
31 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" 31 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
32 section in the Yocto Project Development Tasks Manual. 32 section in the Yocto Project Development Tasks Manual.</para>
33 <note> 33
34 Append files can also use wildcard patterns in their 34 <para>When you name an append file, you can use the
35 version numbers so they can be applied to more than one 35 "<filename>%</filename>" wildcard character to allow for
36 version of the underlying recipe file. 36 matching recipe names.
37 For example, suppose you have an append file named as follows:
38 <literallayout class='monospaced'>
39 busybox_1.21.%.bbappend
40 </literallayout>
41 That append file would match any
42 <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename>
43 version of the recipe.
44 So, the append file would match the following recipe names:
45 <literallayout class='monospaced'>
46 busybox_1.21.1.bb
47 busybox_1.21.2.bb
48 busybox_1.21.3.bb
49 </literallayout>
50 <note><title>Important</title>
51 The use of the "<filename>%</filename>" character
52 is limited in that it only works directly in front of the
53 <filename>.bbappend</filename> portion of the append file's
54 name.
55 You cannot use the wildcard character in any other
56 location of the name.
37 </note> 57 </note>
38 </para></listitem> 58 </para></listitem>
39 <listitem><para id='bitbake-term'> 59 <listitem><para id='bitbake-term'>
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 @@
679 <literallayout class='monospaced'> 679 <literallayout class='monospaced'>
680 BB_ALLOWED_NETWORKS = "*.gnu.org" 680 BB_ALLOWED_NETWORKS = "*.gnu.org"
681 </literallayout> 681 </literallayout>
682 <note><title>Important</title>
683 The use of the "<filename>*</filename>"
684 character only works at the beginning of
685 a host name.
686 You cannot use the wildcard character in any
687 other location of the name.
688 </note>
682 </para></listitem> 689 </para></listitem>
683 <listitem><para> 690 <listitem><para>
684 Mirrors not in the host list are skipped and 691 Mirrors not in the host list are skipped and
@@ -1133,12 +1140,22 @@
1133 1140
1134 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm> 1141 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
1135 <info> 1142 <info>
1136 BBFILES[doc] = "List of recipe files used by BitBake to build software." 1143 BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software."
1137 </info> 1144 </info>
1138 <glossdef> 1145 <glossdef>
1139 <para role="glossdeffirst"> 1146 <para role="glossdeffirst">
1140<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 1147<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1141 List of recipe files used by BitBake to build software. 1148 A space-separated list of recipe files BitBake uses to
1149 build software.
1150 </para>
1151
1152 <para>
1153 When specifying recipe files, you can pattern match using
1154 Python's
1155 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
1156 syntax.
1157 For details on the syntax, see the documentation by
1158 following the previous link.
1142 </para> 1159 </para>
1143 </glossdef> 1160 </glossdef>
1144 </glossentry> 1161 </glossentry>
@@ -1267,15 +1284,19 @@
1267 match any of the expressions. 1284 match any of the expressions.
1268 It is as if BitBake does not see them at all. 1285 It is as if BitBake does not see them at all.
1269 Consequently, matching files are not parsed or otherwise 1286 Consequently, matching files are not parsed or otherwise
1270 used by BitBake.</para> 1287 used by BitBake.
1288 </para>
1289
1271 <para> 1290 <para>
1272 The values you provide are passed to Python's regular 1291 The values you provide are passed to Python's regular
1273 expression compiler. 1292 expression compiler.
1293 Consequently, the syntax follows Python's Regular
1294 Expression (re) syntax.
1274 The expressions are compared against the full paths to 1295 The expressions are compared against the full paths to
1275 the files. 1296 the files.
1276 For complete syntax information, see Python's 1297 For complete syntax information, see Python's
1277 documentation for the appropriate release at 1298 documentation at
1278 <ulink url='http://docs.python.org/release/'></ulink>. 1299 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
1279 </para> 1300 </para>
1280 1301
1281 <para> 1302 <para>
@@ -1443,6 +1464,17 @@
1443 set up during compilation so that they are correct for 1464 set up during compilation so that they are correct for
1444 use when installed into the sysroot and called by the 1465 use when installed into the sysroot and called by the
1445 build processes of other recipes. 1466 build processes of other recipes.
1467 <note>
1468 The <filename>BINCONFIG_GLOB</filename> variable
1469 uses
1470 <ulink url='http://tldp.org/LDP/abs/html/globbingref.html'>shell globbing</ulink>,
1471 which is recognition and expansion of wildcards during
1472 pattern matching.
1473 Shell globbing is very similar to
1474 <ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
1475 and
1476 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>.
1477 </note>
1446 </para> 1478 </para>
1447 1479
1448 <para> 1480 <para>
@@ -2366,6 +2398,14 @@
2366 Defines wildcards to match when installing a list of 2398 Defines wildcards to match when installing a list of
2367 complementary packages for all the packages explicitly 2399 complementary packages for all the packages explicitly
2368 (or implicitly) installed in an image. 2400 (or implicitly) installed in an image.
2401 <note>
2402 The <filename>COMPLEMENTARY_GLOB</filename> variable
2403 uses Unix filename pattern matching
2404 (<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>),
2405 which is similar to the Unix style pathname pattern
2406 expansion
2407 (<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>).
2408 </note>
2369 The resulting list of complementary packages is associated 2409 The resulting list of complementary packages is associated
2370 with an item that can be added to 2410 with an item that can be added to
2371 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>. 2411 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
@@ -4782,23 +4822,38 @@
4782 <literallayout class='monospaced'> 4822 <literallayout class='monospaced'>
4783 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" 4823 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
4784 </literallayout> 4824 </literallayout>
4825 <note><title>Notes</title>
4826 <itemizedlist>
4827 <listitem><para>
4828 When specifying files or paths, you can pattern
4829 match using Python's
4830 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
4831 syntax.
4832 For details on the syntax, see the
4833 documentation by following the previous link.
4834 </para></listitem>
4835 <listitem><para>
4836 When specifying paths as part of the
4837 <filename>FILES</filename> variable, it is
4838 good practice to use appropriate path
4839 variables.
4840 For example, use <filename>${sysconfdir}</filename>
4841 rather than <filename>/etc</filename>, or
4842 <filename>${bindir}</filename> rather than
4843 <filename>/usr/bin</filename>.
4844 You can find a list of these variables at the
4845 top of the
4846 <filename>meta/conf/bitbake.conf</filename>
4847 file in the
4848 <link linkend='source-directory'>Source Directory</link>.
4849 You will also find the default values of the
4850 various <filename>FILES_*</filename> variables
4851 in this file.
4852 </para></listitem>
4853 </itemizedlist>
4854 </note>
4785 </para> 4855 </para>
4786 4856
4787 <note>
4788 When specifying paths as part of the
4789 <filename>FILES</filename> variable, it is good practice
4790 to use appropriate path variables.
4791 For example, use <filename>${sysconfdir}</filename> rather
4792 than <filename>/etc</filename>, or
4793 <filename>${bindir}</filename> rather than
4794 <filename>/usr/bin</filename>.
4795 You can find a list of these variables at the top of the
4796 <filename>meta/conf/bitbake.conf</filename> file in the
4797 <link linkend='source-directory'>Source Directory</link>.
4798 You will also find the default values of the various
4799 <filename>FILES_*</filename> variables in this file.
4800 </note>
4801
4802 <para> 4857 <para>
4803 If some of the files you provide with the 4858 If some of the files you provide with the
4804 <filename>FILES</filename> variable are editable and you 4859 <filename>FILES</filename> variable are editable and you
@@ -10935,47 +10990,63 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
10935 <glossdef> 10990 <glossdef>
10936 <para role="glossdeffirst"> 10991 <para role="glossdeffirst">
10937<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 10992<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10938 If there are multiple versions of recipes available, this 10993 If multiple versions of recipes exist, this
10939 variable determines which recipe should be given preference. 10994 variable determines which version is given preference.
10940 You must always suffix the variable with the 10995 You must always suffix the variable with the
10941 <link linkend='var-PN'><filename>PN</filename></link> 10996 <link linkend='var-PN'><filename>PN</filename></link>
10942 you want to select, and you should set the 10997 you want to select, and you should set the
10943 <link linkend='var-PV'><filename>PV</filename></link> 10998 <link linkend='var-PV'><filename>PV</filename></link>
10944 accordingly for precedence. 10999 accordingly for precedence.
10945 You can use the "<filename>%</filename>" character as a 11000 </para>
10946 wildcard to match any number of characters, which can be 11001
10947 useful when specifying versions that contain long revision 11002 <para>
10948 numbers that could potentially change. 11003 The <filename>PREFERRED_VERSION</filename> variable
11004 supports limited wildcard use through the
11005 "<filename>%</filename>" character.
11006 You can use the character to match any number of
11007 characters, which can be useful when specifying versions
11008 that contain long revision numbers that potentially change.
10949 Here are two examples: 11009 Here are two examples:
10950 <literallayout class='monospaced'> 11010 <literallayout class='monospaced'>
10951 PREFERRED_VERSION_python = "3.4.0" 11011 PREFERRED_VERSION_python = "3.4.0"
10952 PREFERRED_VERSION_linux-yocto = "4.12%" 11012 PREFERRED_VERSION_linux-yocto = "4.12%"
10953 </literallayout> 11013 </literallayout>
10954 <note> 11014 <note><title>Important</title>
10955 The specified version is matched against 11015 The use of the "<filename>%</filename>" character
10956 <link linkend='var-PV'><filename>PV</filename></link>, 11016 is limited in that it only works at the end of the
10957 which does not necessarily match the version part of 11017 string.
10958 the recipe's filename. 11018 You cannot use the wildcard character in any other
10959 For example, consider two recipes 11019 location of the string.
10960 <filename>foo_1.2.bb</filename> and 11020 </note>
10961 <filename>foo_git.bb</filename> where 11021 </para>
10962 <filename>foo_git.bb</filename> contains the following 11022
10963 assignment: 11023 <para>
10964 <literallayout class='monospaced'> 11024 The specified version is matched against
11025 <link linkend='var-PV'><filename>PV</filename></link>,
11026 which does not necessarily match the version part of
11027 the recipe's filename.
11028 For example, consider two recipes
11029 <filename>foo_1.2.bb</filename> and
11030 <filename>foo_git.bb</filename> where
11031 <filename>foo_git.bb</filename> contains the following
11032 assignment:
11033 <literallayout class='monospaced'>
10965 PV = "1.1+git${SRCPV}" 11034 PV = "1.1+git${SRCPV}"
10966 </literallayout> 11035 </literallayout>
10967 In this case, the correct way to select 11036 In this case, the correct way to select
10968 <filename>foo_git.bb</filename> is by using an 11037 <filename>foo_git.bb</filename> is by using an
10969 assignment such as the following: 11038 assignment such as the following:
10970 <literallayout class='monospaced'> 11039 <literallayout class='monospaced'>
10971 PREFERRED_VERSION_foo = "1.1+git%" 11040 PREFERRED_VERSION_foo = "1.1+git%"
10972 </literallayout> 11041 </literallayout>
10973 Compare that previous example against the following 11042 Compare that previous example against the following
10974 incorrect example, which does not work: 11043 incorrect example, which does not work:
10975 <literallayout class='monospaced'> 11044 <literallayout class='monospaced'>
10976 PREFERRED_VERSION_foo = "git" 11045 PREFERRED_VERSION_foo = "git"
10977 </literallayout> 11046 </literallayout>
10978 </note> 11047 </para>
11048
11049 <para>
10979 Sometimes the <filename>PREFERRED_VERSION</filename> 11050 Sometimes the <filename>PREFERRED_VERSION</filename>
10980 variable can be set by configuration files in a way that 11051 variable can be set by configuration files in a way that
10981 is hard to change. 11052 is hard to change.