summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-02-03 11:51:04 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-02-11 12:17:06 +0000
commit2fc9281c49a562083d3736b2f8b159f0e76e3c0b (patch)
tree91122a0922595564e5d89bda0211bc04b5db55b8
parenta2e5746f29078c805b1e1e28471f323be4d59294 (diff)
downloadpoky-2fc9281c49a562083d3736b2f8b159f0e76e3c0b.tar.gz
bitbake: user-manual-metadata.xml: Edits through syntax section
I made some general improvements in the "Overview" and "Basic Syntax" sections. Additionally, I added a blank section for "Variable Flags" that will eventually hold general information on this concept. Finally, come review edits to the "Defining Pure Python Functions" section per Paul Eggleton. (Bitbake rev: 665d655f436f1a353f5fe467c5d97588f7b121c5) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml280
1 files changed, 183 insertions, 97 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index abfc89d75c..fb4bf4044c 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -8,39 +8,53 @@
8 <title>Overview</title> 8 <title>Overview</title>
9 9
10 <para> 10 <para>
11 The BitBake task executor together with various types of configuration files form the OpenEmbedded 11 The BitBake task executor together with various types of configuration
12 Core. 12 files form the OpenEmbedded Core.
13 This section provides an overview of the BitBake task executor and the configuration files by 13 This section provides an overview of the task executor and the
14 describing what they are used for and how they interact. 14 configuration files by describing their use and interaction.
15 </para> 15 </para>
16 16
17 <para> 17 <para>
18 BitBake handles the parsing and execution of the data files. The data itself is of various types: 18 BitBake handles the parsing and execution of the data files.
19 The data itself is of various types:
19 <itemizedlist> 20 <itemizedlist>
20 <listitem><para><emphasis>Recipes:</emphasis> 21 <listitem><para><emphasis>Recipes:</emphasis>
21 Provides details about particular pieces of software.</para></listitem> 22 Details about particular pieces of software.
23 </para></listitem>
22 <listitem><para><emphasis>Class Data:</emphasis> 24 <listitem><para><emphasis>Class Data:</emphasis>
23 An abstraction of common build information (e.g. how to build a Linux kernel).</para></listitem> 25 An abstraction of common build information
26 (e.g. how to build a Linux kernel).
27 </para></listitem>
24 <listitem><para><emphasis>Configuration Data:</emphasis> 28 <listitem><para><emphasis>Configuration Data:</emphasis>
25 Defines machine-specific settings, policy decisions, etc. Configuration data acts 29 Machine-specific settings, policy decisions,
26 as the glue to bind everything together.</para></listitem> 30 and so forth.
31 Configuration data acts as the glue to bind everything
32 together.</para></listitem>
27 </itemizedlist> 33 </itemizedlist>
28 What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported 34 The remainder of this chapter provides examples of BitBake metadata.
29 in any of the aforementioned areas will be documented as such. 35 Any syntax not supported in any of the previously listed areas
36 is documented as such.
30 </para> 37 </para>
31 </section> 38 </section>
32 39
33 <section id='basic-syntax'> 40 <section id='basic-syntax'>
34 <title>Basic Syntax</title> 41 <title>Basic Syntax</title>
35 42
43 <para>
44 This section provides some basic syntax examples.
45 </para>
46
36 <section id='basic-variable-setting'> 47 <section id='basic-variable-setting'>
37 <title>Basic Variable Setting</title> 48 <title>Basic Variable Setting</title>
38 49
39 <para> 50 <para>
51 The following example sets <filename>VARIABLE</filename> to
52 "value".
53 This assignment occurs immediately as the statement is parsed.
54 It is a "hard" assignment.
40 <literallayout class='monospaced'> 55 <literallayout class='monospaced'>
41 VARIABLE = "value" 56 VARIABLE = "value"
42 </literallayout> 57 </literallayout>
43 In this example, <filename>VARIABLE</filename> is <filename>value</filename>.
44 </para> 58 </para>
45 </section> 59 </section>
46 60
@@ -49,18 +63,14 @@
49 63
50 <para> 64 <para>
51 BitBake supports variables referencing one another's 65 BitBake supports variables referencing one another's
52 contents using a syntax which is similar to shell 66 contents using a syntax that is similar to shell scripting.
53 scripting 67 Following is an example that results in <filename>A</filename>
54 </para> 68 containing "aval" and <filename>B</filename> containing
55 69 "preavalpost".
56 <para>
57 <literallayout class='monospaced'> 70 <literallayout class='monospaced'>
58 A = "aval" 71 A = "aval"
59 B = "pre${A}post" 72 B = "pre${A}post"
60 </literallayout> 73 </literallayout>
61 This results in <filename>A</filename> containing
62 <filename>aval</filename> and <filename>B</filename> containing
63 <filename>preavalpost</filename>.
64 </para> 74 </para>
65 </section> 75 </section>
66 76
@@ -68,16 +78,24 @@
68 <title>Setting a default value (?=)</title> 78 <title>Setting a default value (?=)</title>
69 79
70 <para> 80 <para>
81 You can use the "?=" operator to achieve a "softer" assignment
82 for a variable.
83 This type of assignment allows you to define a variable if it
84 is undefined when the statement is parsed, but to leave the
85 value alone if the variable has a value.
86 Here is an example:
71 <literallayout class='monospaced'> 87 <literallayout class='monospaced'>
72 A ?= "aval" 88 A ?= "aval"
73 </literallayout> 89 </literallayout>
74 If <filename>A</filename> is set before the above is called, 90 If <filename>A</filename> is set at the time this statement is parsed,
75 it will retain its previous value. 91 the variable retains its value.
76 If <filename>A</filename> is unset prior to the above call, 92 However, if <filename>A</filename> is not set,
77 <filename>A</filename> will be set to <filename>aval</filename>. 93 the variable is set to "aval".
78 <note> 94 <note>
79 This assignment is immediate, so if there are multiple "?=" assignments 95 This assignment is immediate.
80 to a single variable, the first of those will be used. 96 Consequently, if multiple "?=" assignments
97 to a single variable exist, the first of those ends up getting
98 used.
81 </note> 99 </note>
82 </para> 100 </para>
83 </section> 101 </section>
@@ -86,19 +104,30 @@
86 <title>Setting a weak default value (??=)</title> 104 <title>Setting a weak default value (??=)</title>
87 105
88 <para> 106 <para>
107 It is possible to use a "weaker" assignment that in the
108 previous section by using the "??=" operator.
109 This assignment behaves identical to "?=" except that the
110 assignment is made at the end of the parsing process rather
111 than immediately.
112 Consequently, when multiple "??=" assignments exist, the last
113 one is used.
114 Also, any "=" or "?=" assignment will override the value set with
115 "??=".
116 Here is an example:
89 <literallayout class='monospaced'> 117 <literallayout class='monospaced'>
90 A ??= "somevalue" 118 A ??= "somevalue"
91 A ??= "someothervalue" 119 A ??= "someothervalue"
92 </literallayout> 120 </literallayout>
93 If <filename>A</filename> is set before the above, 121 If <filename>A</filename> is set before the above statements are parsed,
94 it will retain that value. 122 the variable retains its value.
95 If <filename>A</filename> is unset prior to the above, 123 If <filename>A</filename> is not set,
96 <filename>A</filename> will be set to <filename>someothervalue</filename>. 124 the variable is set to "someothervalue".
97 This is a lazy or weak assignment in that the assignment does not occur until the end 125 </para>
98 of the parsing process, so that the last, rather than the first, 126
99 "??=" assignment to a given variable will be used. 127 <para>
100 Any other setting of <filename>A</filename> using "=" or "?=" 128 Again, this assignment is a "lazy" or "weak" assignment
101 will, however, override the value set with "??=". 129 because it does not occur until the end
130 of the parsing process.
102 </para> 131 </para>
103 </section> 132 </section>
104 133
@@ -106,7 +135,8 @@
106 <title>Immediate variable expansion (:=)</title> 135 <title>Immediate variable expansion (:=)</title>
107 136
108 <para> 137 <para>
109 The ":=" operator results in a variable's contents being expanded immediately, 138 The ":=" operator results in a variable's
139 contents being expanded immediately,
110 rather than when the variable is actually used: 140 rather than when the variable is actually used:
111 <literallayout class='monospaced'> 141 <literallayout class='monospaced'>
112 T = "123" 142 T = "123"
@@ -116,26 +146,34 @@
116 C = "cval" 146 C = "cval"
117 C := "${C}append" 147 C := "${C}append"
118 </literallayout> 148 </literallayout>
119 In this example, <filename>A</filename> would contain 149 In this example, <filename>A</filename> contains
120 <filename>test 123</filename>, <filename>B</filename> would contain 150 "test 123" because <filename>${B}</filename> and
121 <filename>456 bval</filename>, and <filename>C</filename> 151 <filename>${A}</filename> at the time of parsing are undefined,
122 would be <filename>cvalappend</filename>. 152 which leaves "test 123".
153 And, the variable <filename>C</filename>
154 contains "cvalappend" since <filename>${C}</filename> immediately
155 expands to "cval".
123 </para> 156 </para>
124 </section> 157 </section>
125 158
126 <section id='appending-and-prepending'> 159 <section id='appending-and-prepending'>
127 <title>Appending (+=) and prepending (=+)</title> 160 <title>Appending (+=) and prepending (=+) With Spaces</title>
128 161
129 <para> 162 <para>
163 Appending and prepending values is common and can be accomplished
164 using the "+=" and "=+" operators.
165 These operators insert a space between the current
166 value and prepended or appended value.
167 Here are some examples:
130 <literallayout class='monospaced'> 168 <literallayout class='monospaced'>
131 B = "bval" 169 B = "bval"
132 B += "additionaldata" 170 B += "additionaldata"
133 C = "cval" 171 C = "cval"
134 C =+ "test" 172 C =+ "test"
135 </literallayout> 173 </literallayout>
136 In this example, <filename>B</filename> is now 174 The variable <filename>B</filename> contains
137 <filename>bval additionaldata</filename> and <filename>C</filename> 175 "bval additionaldata" and <filename>C</filename>
138 is <filename>test cval</filename>. 176 contains "test cval".
139 </para> 177 </para>
140 </section> 178 </section>
141 179
@@ -143,17 +181,18 @@
143 <title>Appending (.=) and Prepending (=.) Without Spaces</title> 181 <title>Appending (.=) and Prepending (=.) Without Spaces</title>
144 182
145 <para> 183 <para>
184 If you want to append or prepend values without an
185 inserted space, use the ".=" and "=." operators.
186 Here are some examples:
146 <literallayout class='monospaced'> 187 <literallayout class='monospaced'>
147 B = "bval" 188 B = "bval"
148 B .= "additionaldata" 189 B .= "additionaldata"
149 C = "cval" 190 C = "cval"
150 C =. "test" 191 C =. "test"
151 </literallayout> 192 </literallayout>
152 In this example, <filename>B</filename> is now 193 The variable <filename>B</filename> contains
153 <filename>bvaladditionaldata</filename> and 194 "bvaladditionaldata" and
154 <filename>C</filename> is <filename>testcval</filename>. 195 <filename>C</filename> contains "testcval".
155 In contrast to the above appending and prepending operators,
156 no additional space will be introduced.
157 </para> 196 </para>
158 </section> 197 </section>
159 198
@@ -161,49 +200,88 @@
161 <title>Appending and Prepending (Override Style Syntax)</title> 200 <title>Appending and Prepending (Override Style Syntax)</title>
162 201
163 <para> 202 <para>
203 You can also append and prepend a variable's value
204 using an override style syntax.
205 When you use this syntax, no spaces are inserted.
206 Here are some examples:
164 <literallayout class='monospaced'> 207 <literallayout class='monospaced'>
165 B = "bval" 208 B = "bval"
166 B_append = " additional data" 209 B_append = " additional data"
167 C = "cval" 210 C = "cval"
168 C_prepend = "additional data " 211 C_prepend = "additional data "
212 D = "dval"
213 D_append = "additional data"
169 </literallayout> 214 </literallayout>
170 This example results in <filename>B</filename> 215 The variable <filename>B</filename> becomes
171 becoming <filename>bval additional data</filename> and 216 "bval additional data" and <filename>C</filename> becomes
172 <filename>C</filename> becoming 217 "additional data cval".
173 <filename>additional data cval</filename>. 218 The variable <filename>D</filename> becomes
219 "dvaladditional data".
174 <note> 220 <note>
175 The spaces in <filename>_append</filename>. 221 You must control all spacing when you use the
176 Unlike the "+=" operator, additional space is not automatically added. 222 override syntax.
177 You must take steps to add space yourself.
178 </note> 223 </note>
179 </para> 224 </para>
180 </section> 225 </section>
181 226
182 <section id='removing-override-style-syntax'> 227 <section id='removing-override-style-syntax'>
183 <title>Removing (Override Style Syntax)</title> 228 <title>Removal (Override Style Syntax)</title>
184 229
185 <para> 230 <para>
231 You can remove values from lists using the removal
232 override style syntax.
233 Specifying a value for removal causes all occurrences of that
234 value to be removed from the variable.
235 </para>
236
237 <para>
238 When you use this syntax, BitBake expects one or more strings.
239 Surrounding spaces are removed as well.
240 Here is an example:
186 <literallayout class='monospaced'> 241 <literallayout class='monospaced'>
187 FOO = "123 456 789 123456 123 456 123 456" 242 FOO = "123 456 789 123456 123 456 123 456"
188 FOO_remove = "123" 243 FOO_remove = "123"
189 FOO_remove = "456" 244 FOO_remove = "456"
245 FOO2 = "abc def ghi abcdef abc def abc def"
246 FOO2_remove = "abc def"
190 </literallayout> 247 </literallayout>
191 In this example, <filename>FOO</filename> is now <filename>789 123456</filename>. 248 The variable <filename>FOO</filename> becomes
249 "789 123456" and <filename>FOO2</filename> becomes
250 "ghi abcdef".
192 </para> 251 </para>
193 </section> 252 </section>
194 253
195 <section id='variable-flags'> 254 <section id='variable-flag-syntax'>
196 <title>Variable Flags</title> 255 <title>Variable Flag Syntax</title>
197 256
198 <para> 257 <para>
199 Variables can have associated flags which provide a way of tagging extra information onto a variable. 258 Variable flags are BitBake's implementation of variable properties
200 Several flags are used internally by BitBake but they can be used externally too if needed. 259 or attributes.
201 The standard operations mentioned above also work on flags. 260 It is a way of tagging extra information onto a variable.
261 You can find more out about variable flags in general in the
262 "<link linkend='variable-flags'>Variable Flags</link>"
263 section.
264 </para>
265
266 <para>
267 You can define, append, and prepend values to variable flags.
268 All the standard syntax operations previously mentioned work
269 for variable flags except for override style syntax
270 (i.e. <filename>_prepend</filename>, <filename>_append</filename>,
271 and <filename>_remove</filename>).
272 </para>
273
274 <para>
275 Here are some examples showing how to set variable flags:
202 <literallayout class='monospaced'> 276 <literallayout class='monospaced'>
203 VARIABLE[SOMEFLAG] = "value" 277 FOO[a] = "abc"
278 FOO[b] = "123"
279 FOO[a] += "456"
204 </literallayout> 280 </literallayout>
205 In this example, <filename>VARIABLE</filename> has a flag, 281 The variable <filename>FOO</filename> has two flags:
206 <filename>SOMEFLAG</filename> that is set to <filename>value</filename>. 282 <filename>a</filename> and <filename>b</filename>.
283 The flags are immediately set to "abc" and "123", respectively.
284 The <filename>a</filename> flag becomes "abc456".
207 </para> 285 </para>
208 </section> 286 </section>
209 287
@@ -211,11 +289,14 @@
211 <title>Inline Python Variable Expansion</title> 289 <title>Inline Python Variable Expansion</title>
212 290
213 <para> 291 <para>
292 You can use inline Python variable expansion to
293 set variables.
294 Here is an example:
214 <literallayout class='monospaced'> 295 <literallayout class='monospaced'>
215 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" 296 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
216 </literallayout> 297 </literallayout>
217 This would result in the <filename>DATE</filename> 298 This example results in the <filename>DATE</filename>
218 variable containing today's date. 299 variable becoming the current date.
219 </para> 300 </para>
220 </section> 301 </section>
221 </section> 302 </section>
@@ -391,33 +472,6 @@
391 </section> 472 </section>
392 </section> 473 </section>
393 474
394 <section id='defining-python-functions-into-the-global-python-namespace'>
395 <title>Defining Python Functions into the Global Python Namespace</title>
396
397 <note>
398 <para>
399 This is only supported in <filename>.bb</filename>
400 and <filename>.bbclass</filename> files.
401 </para>
402
403 <para>
404 Python functions are in the global namespace so should use
405 unique names.
406 <literallayout class='monospaced'>
407 def get_depends(d):
408 if d.getVar('SOMECONDITION', True):
409 return "dependencywithcond"
410 else:
411 return "dependency"
412 SOMECONDITION = "1"
413 DEPENDS = "${@get_depends(d)}"
414 </literallayout>
415 This would result in <filename>DEPENDS</filename>
416 containing <filename>dependencywithcond</filename>.
417 </para>
418 </note>
419 </section>
420
421 <section id='functions'> 475 <section id='functions'>
422 <title>Functions</title> 476 <title>Functions</title>
423 477
@@ -474,6 +528,30 @@
474 </para> 528 </para>
475 </section> 529 </section>
476 530
531 <section id='defining-pure-python-functions'>
532 <title>Defining Pure Python functions</title>
533
534 <note>
535 This is only supported in <filename>.bb</filename>
536 and <filename>.bbclass</filename> files.
537 </note>
538
539 <para>
540 Python functions should use unique names.
541 <literallayout class='monospaced'>
542 def get_depends(d):
543 if d.getVar('SOMECONDITION', True):
544 return "dependencywithcond"
545 else:
546 return "dependency"
547 SOMECONDITION = "1"
548 DEPENDS = "${@get_depends(d)}"
549 </literallayout>
550 This would result in <filename>DEPENDS</filename>
551 containing <filename>dependencywithcond</filename>.
552 </para>
553 </section>
554
477 <section id='tasks'> 555 <section id='tasks'>
478 <title>Tasks</title> 556 <title>Tasks</title>
479 557
@@ -583,6 +661,14 @@
583 </para> 661 </para>
584 </section> 662 </section>
585 663
664 <section id='variable-flags'>
665 <title>Variable Flags</title>
666
667 <para>
668 This section describes variable flags.
669 </para>
670 </section>
671
586 <section id='task-flags'> 672 <section id='task-flags'>
587 <title>Task Flags</title> 673 <title>Task Flags</title>
588 674
@@ -702,7 +788,7 @@
702 </para> 788 </para>
703 </section> 789 </section>
704 790
705 <section id='configiguration-files'> 791 <section id='parsing-configuration-files'>
706 <title>Configuration files</title> 792 <title>Configuration files</title>
707 793
708 <para> 794 <para>
@@ -992,7 +1078,7 @@
992 </para> 1078 </para>
993 1079
994 <para> 1080 <para>
995 It may be desireable to recurse not just through the 1081 It may be desirable to recurse not just through the
996 dependencies of those tasks but through the 1082 dependencies of those tasks but through the
997 build and runtime dependencies of dependent tasks too. 1083 build and runtime dependencies of dependent tasks too.
998 If that is the case, the taskname itself should 1084 If that is the case, the taskname itself should