diff options
Diffstat (limited to 'documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html')
-rw-r--r-- | documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html | 383 |
1 files changed, 0 insertions, 383 deletions
diff --git a/documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html b/documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html deleted file mode 100644 index fcf46d9d35..0000000000 --- a/documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html +++ /dev/null | |||
@@ -1,383 +0,0 @@ | |||
1 | <html> | ||
2 | <head> | ||
3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
4 | <title>2.7. Recipe Syntax</title> | ||
5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
8 | <link rel="up" href="overview-development-environment.html" title="Chapter 2. The Yocto Project Development Environment"> | ||
9 | <link rel="prev" href="licensing.html" title="2.6. Licensing"> | ||
10 | <link rel="next" href="development-concepts.html" title="2.8. Development Concepts"> | ||
11 | </head> | ||
12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.7. Recipe Syntax"> | ||
13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
14 | <a name="recipe-syntax"></a>2.7. Recipe Syntax</h2></div></div></div> | ||
15 | <p> | ||
16 | Understanding recipe file syntax is important for | ||
17 | writing recipes. | ||
18 | The following list overviews the basic items that make up a | ||
19 | BitBake recipe file. | ||
20 | For more complete BitBake syntax descriptions, see the | ||
21 | "<a class="link" href="../bitbake-user-manual/bitbake-user-manual-metadata.html" target="_self">Syntax and Operators</a>" | ||
22 | chapter of the BitBake User Manual. | ||
23 | </p> | ||
24 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
25 | <li class="listitem"> | ||
26 | <p><span class="emphasis"><em>Variable Assignments and Manipulations:</em></span> | ||
27 | Variable assignments allow a value to be assigned to a | ||
28 | variable. | ||
29 | The assignment can be static text or might include | ||
30 | the contents of other variables. | ||
31 | In addition to the assignment, appending and prepending | ||
32 | operations are also supported.</p> | ||
33 | <p>The following example shows some of the ways | ||
34 | you can use variables in recipes: | ||
35 | </p> | ||
36 | <pre class="literallayout"> | ||
37 | S = "${WORKDIR}/postfix-${PV}" | ||
38 | CFLAGS += "-DNO_ASM" | ||
39 | SRC_URI_append = " file://fixup.patch" | ||
40 | </pre> | ||
41 | <p> | ||
42 | </p> | ||
43 | </li> | ||
44 | <li class="listitem"> | ||
45 | <p><span class="emphasis"><em>Functions:</em></span> | ||
46 | Functions provide a series of actions to be performed. | ||
47 | You usually use functions to override the default | ||
48 | implementation of a task function or to complement | ||
49 | a default function (i.e. append or prepend to an | ||
50 | existing function). | ||
51 | Standard functions use <code class="filename">sh</code> shell | ||
52 | syntax, although access to OpenEmbedded variables and | ||
53 | internal methods are also available.</p> | ||
54 | <p>The following is an example function from the | ||
55 | <code class="filename">sed</code> recipe: | ||
56 | </p> | ||
57 | <pre class="literallayout"> | ||
58 | do_install () { | ||
59 | autotools_do_install | ||
60 | install -d ${D}${base_bindir} | ||
61 | mv ${D}${bindir}/sed ${D}${base_bindir}/sed | ||
62 | rmdir ${D}${bindir}/ | ||
63 | } | ||
64 | </pre> | ||
65 | <p> | ||
66 | It is also possible to implement new functions that | ||
67 | are called between existing tasks as long as the | ||
68 | new functions are not replacing or complementing the | ||
69 | default functions. | ||
70 | You can implement functions in Python | ||
71 | instead of shell. | ||
72 | Both of these options are not seen in the majority of | ||
73 | recipes.</p> | ||
74 | </li> | ||
75 | <li class="listitem"> | ||
76 | <p><span class="emphasis"><em>Keywords:</em></span> | ||
77 | BitBake recipes use only a few keywords. | ||
78 | You use keywords to include common | ||
79 | functions (<code class="filename">inherit</code>), load parts | ||
80 | of a recipe from other files | ||
81 | (<code class="filename">include</code> and | ||
82 | <code class="filename">require</code>) and export variables | ||
83 | to the environment (<code class="filename">export</code>).</p> | ||
84 | <p>The following example shows the use of some of | ||
85 | these keywords: | ||
86 | </p> | ||
87 | <pre class="literallayout"> | ||
88 | export POSTCONF = "${STAGING_BINDIR}/postconf" | ||
89 | inherit autoconf | ||
90 | require otherfile.inc | ||
91 | </pre> | ||
92 | <p> | ||
93 | </p> | ||
94 | </li> | ||
95 | <li class="listitem"> | ||
96 | <p><span class="emphasis"><em>Comments:</em></span> | ||
97 | Any lines that begin with the hash character | ||
98 | (<code class="filename">#</code>) are treated as comment lines | ||
99 | and are ignored: | ||
100 | </p> | ||
101 | <pre class="literallayout"> | ||
102 | # This is a comment | ||
103 | </pre> | ||
104 | <p> | ||
105 | </p> | ||
106 | </li> | ||
107 | </ul></div> | ||
108 | <p> | ||
109 | </p> | ||
110 | <p> | ||
111 | This next list summarizes the most important and most commonly | ||
112 | used parts of the recipe syntax. | ||
113 | For more information on these parts of the syntax, you can | ||
114 | reference the | ||
115 | <a class="link" href="../bitbake-user-manual/bitbake-user-manual-metadata.html" target="_self">Syntax and Operators</a> | ||
116 | chapter in the BitBake User Manual. | ||
117 | </p> | ||
118 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
119 | <li class="listitem"> | ||
120 | <p><span class="emphasis"><em>Line Continuation: <code class="filename">\</code></em></span> - | ||
121 | Use the backward slash (<code class="filename">\</code>) | ||
122 | character to split a statement over multiple lines. | ||
123 | Place the slash character at the end of the line that | ||
124 | is to be continued on the next line: | ||
125 | </p> | ||
126 | <pre class="literallayout"> | ||
127 | VAR = "A really long \ | ||
128 | line" | ||
129 | </pre> | ||
130 | <p> | ||
131 | </p> | ||
132 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
133 | <h3 class="title">Note</h3> | ||
134 | You cannot have any characters including spaces | ||
135 | or tabs after the slash character. | ||
136 | </div> | ||
137 | <p> | ||
138 | </p> | ||
139 | </li> | ||
140 | <li class="listitem"> | ||
141 | <p> | ||
142 | <span class="emphasis"><em>Using Variables: <code class="filename">${...}</code></em></span> - | ||
143 | Use the <code class="filename">${<em class="replaceable"><code>VARNAME</code></em>}</code> syntax to | ||
144 | access the contents of a variable: | ||
145 | </p> | ||
146 | <pre class="literallayout"> | ||
147 | SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" | ||
148 | </pre> | ||
149 | <p> | ||
150 | </p> | ||
151 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
152 | <h3 class="title">Note</h3> | ||
153 | It is important to understand that the value of a | ||
154 | variable expressed in this form does not get | ||
155 | substituted automatically. | ||
156 | The expansion of these expressions happens | ||
157 | on-demand later (e.g. usually when a function that | ||
158 | makes reference to the variable executes). | ||
159 | This behavior ensures that the values are most | ||
160 | appropriate for the context in which they are | ||
161 | finally used. | ||
162 | On the rare occasion that you do need the variable | ||
163 | expression to be expanded immediately, you can use | ||
164 | the <code class="filename">:=</code> operator instead of | ||
165 | <code class="filename">=</code> when you make the | ||
166 | assignment, but this is not generally needed. | ||
167 | </div> | ||
168 | <p> | ||
169 | </p> | ||
170 | </li> | ||
171 | <li class="listitem"> | ||
172 | <p><span class="emphasis"><em>Quote All Assignments: <code class="filename">"<em class="replaceable"><code>value</code></em>"</code></em></span> - | ||
173 | Use double quotes around the value in all variable | ||
174 | assignments. | ||
175 | </p> | ||
176 | <pre class="literallayout"> | ||
177 | VAR1 = "${OTHERVAR}" | ||
178 | VAR2 = "The version is ${PV}" | ||
179 | </pre> | ||
180 | <p> | ||
181 | </p> | ||
182 | </li> | ||
183 | <li class="listitem"> | ||
184 | <p><span class="emphasis"><em>Conditional Assignment: <code class="filename">?=</code></em></span> - | ||
185 | Conditional assignment is used to assign a value to | ||
186 | a variable, but only when the variable is currently | ||
187 | unset. | ||
188 | Use the question mark followed by the equal sign | ||
189 | (<code class="filename">?=</code>) to make a "soft" assignment | ||
190 | used for conditional assignment. | ||
191 | Typically, "soft" assignments are used in the | ||
192 | <code class="filename">local.conf</code> file for variables | ||
193 | that are allowed to come through from the external | ||
194 | environment. | ||
195 | </p> | ||
196 | <p>Here is an example where | ||
197 | <code class="filename">VAR1</code> is set to "New value" if | ||
198 | it is currently empty. | ||
199 | However, if <code class="filename">VAR1</code> has already been | ||
200 | set, it remains unchanged: | ||
201 | </p> | ||
202 | <pre class="literallayout"> | ||
203 | VAR1 ?= "New value" | ||
204 | </pre> | ||
205 | <p> | ||
206 | In this next example, <code class="filename">VAR1</code> | ||
207 | is left with the value "Original value": | ||
208 | </p> | ||
209 | <pre class="literallayout"> | ||
210 | VAR1 = "Original value" | ||
211 | VAR1 ?= "New value" | ||
212 | </pre> | ||
213 | <p> | ||
214 | </p> | ||
215 | </li> | ||
216 | <li class="listitem"> | ||
217 | <p><span class="emphasis"><em>Appending: <code class="filename">+=</code></em></span> - | ||
218 | Use the plus character followed by the equals sign | ||
219 | (<code class="filename">+=</code>) to append values to existing | ||
220 | variables. | ||
221 | </p> | ||
222 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
223 | <h3 class="title">Note</h3> | ||
224 | This operator adds a space between the existing | ||
225 | content of the variable and the new content. | ||
226 | </div> | ||
227 | <p>Here is an example: | ||
228 | </p> | ||
229 | <pre class="literallayout"> | ||
230 | SRC_URI += "file://fix-makefile.patch" | ||
231 | </pre> | ||
232 | <p> | ||
233 | </p> | ||
234 | </li> | ||
235 | <li class="listitem"> | ||
236 | <p><span class="emphasis"><em>Prepending: <code class="filename">=+</code></em></span> - | ||
237 | Use the equals sign followed by the plus character | ||
238 | (<code class="filename">=+</code>) to prepend values to existing | ||
239 | variables. | ||
240 | </p> | ||
241 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
242 | <h3 class="title">Note</h3> | ||
243 | This operator adds a space between the new content | ||
244 | and the existing content of the variable. | ||
245 | </div> | ||
246 | <p>Here is an example: | ||
247 | </p> | ||
248 | <pre class="literallayout"> | ||
249 | VAR =+ "Starts" | ||
250 | </pre> | ||
251 | <p> | ||
252 | </p> | ||
253 | </li> | ||
254 | <li class="listitem"> | ||
255 | <p><span class="emphasis"><em>Appending: <code class="filename">_append</code></em></span> - | ||
256 | Use the <code class="filename">_append</code> operator to | ||
257 | append values to existing variables. | ||
258 | This operator does not add any additional space. | ||
259 | Also, the operator is applied after all the | ||
260 | <code class="filename">+=</code>, and | ||
261 | <code class="filename">=+</code> operators have been applied and | ||
262 | after all <code class="filename">=</code> assignments have | ||
263 | occurred. | ||
264 | </p> | ||
265 | <p>The following example shows the space being | ||
266 | explicitly added to the start to ensure the appended | ||
267 | value is not merged with the existing value: | ||
268 | </p> | ||
269 | <pre class="literallayout"> | ||
270 | SRC_URI_append = " file://fix-makefile.patch" | ||
271 | </pre> | ||
272 | <p> | ||
273 | You can also use the <code class="filename">_append</code> | ||
274 | operator with overrides, which results in the actions | ||
275 | only being performed for the specified target or | ||
276 | machine: | ||
277 | </p> | ||
278 | <pre class="literallayout"> | ||
279 | SRC_URI_append_sh4 = " file://fix-makefile.patch" | ||
280 | </pre> | ||
281 | <p> | ||
282 | </p> | ||
283 | </li> | ||
284 | <li class="listitem"> | ||
285 | <p><span class="emphasis"><em>Prepending: <code class="filename">_prepend</code></em></span> - | ||
286 | Use the <code class="filename">_prepend</code> operator to | ||
287 | prepend values to existing variables. | ||
288 | This operator does not add any additional space. | ||
289 | Also, the operator is applied after all the | ||
290 | <code class="filename">+=</code>, and | ||
291 | <code class="filename">=+</code> operators have been applied and | ||
292 | after all <code class="filename">=</code> assignments have | ||
293 | occurred. | ||
294 | </p> | ||
295 | <p>The following example shows the space being | ||
296 | explicitly added to the end to ensure the prepended | ||
297 | value is not merged with the existing value: | ||
298 | </p> | ||
299 | <pre class="literallayout"> | ||
300 | CFLAGS_prepend = "-I${S}/myincludes " | ||
301 | </pre> | ||
302 | <p> | ||
303 | You can also use the <code class="filename">_prepend</code> | ||
304 | operator with overrides, which results in the actions | ||
305 | only being performed for the specified target or | ||
306 | machine: | ||
307 | </p> | ||
308 | <pre class="literallayout"> | ||
309 | CFLAGS_prepend_sh4 = "-I${S}/myincludes " | ||
310 | </pre> | ||
311 | <p> | ||
312 | </p> | ||
313 | </li> | ||
314 | <li class="listitem"> | ||
315 | <p><span class="emphasis"><em>Overrides:</em></span> - | ||
316 | You can use overrides to set a value conditionally, | ||
317 | typically based on how the recipe is being built. | ||
318 | For example, to set the | ||
319 | <a class="link" href="../ref-manual/var-KBRANCH.html" target="_self"><code class="filename">KBRANCH</code></a> | ||
320 | variable's value to "standard/base" for any target | ||
321 | <a class="link" href="../ref-manual/var-MACHINE.html" target="_self"><code class="filename">MACHINE</code></a>, | ||
322 | except for qemuarm where it should be set to | ||
323 | "standard/arm-versatile-926ejs", you would do the | ||
324 | following: | ||
325 | </p> | ||
326 | <pre class="literallayout"> | ||
327 | KBRANCH = "standard/base" | ||
328 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | ||
329 | </pre> | ||
330 | <p> | ||
331 | Overrides are also used to separate alternate values | ||
332 | of a variable in other situations. | ||
333 | For example, when setting variables such as | ||
334 | <a class="link" href="../ref-manual/var-FILES.html" target="_self"><code class="filename">FILES</code></a> | ||
335 | and | ||
336 | <a class="link" href="../ref-manual/var-RDEPENDS.html" target="_self"><code class="filename">RDEPENDS</code></a> | ||
337 | that are specific to individual packages produced by | ||
338 | a recipe, you should always use an override that | ||
339 | specifies the name of the package. | ||
340 | </p> | ||
341 | </li> | ||
342 | <li class="listitem"><p><span class="emphasis"><em>Indentation:</em></span> | ||
343 | Use spaces for indentation rather than than tabs. | ||
344 | For shell functions, both currently work. | ||
345 | However, it is a policy decision of the Yocto Project | ||
346 | to use tabs in shell functions. | ||
347 | Realize that some layers have a policy to use spaces | ||
348 | for all indentation. | ||
349 | </p></li> | ||
350 | <li class="listitem"> | ||
351 | <p><span class="emphasis"><em>Using Python for Complex Operations: <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code></em></span> - | ||
352 | For more advanced processing, it is possible to use | ||
353 | Python code during variable assignments (e.g. | ||
354 | search and replacement on a variable).</p> | ||
355 | <p>You indicate Python code using the | ||
356 | <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code> | ||
357 | syntax for the variable assignment: | ||
358 | </p> | ||
359 | <pre class="literallayout"> | ||
360 | SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz | ||
361 | </pre> | ||
362 | <p> | ||
363 | </p> | ||
364 | </li> | ||
365 | <li class="listitem"><p><span class="emphasis"><em>Shell Function Syntax:</em></span> | ||
366 | Write shell functions as if you were writing a shell | ||
367 | script when you describe a list of actions to take. | ||
368 | You should ensure that your script works with a generic | ||
369 | <code class="filename">sh</code> and that it does not require | ||
370 | any <code class="filename">bash</code> or other shell-specific | ||
371 | functionality. | ||
372 | The same considerations apply to various system | ||
373 | utilities (e.g. <code class="filename">sed</code>, | ||
374 | <code class="filename">grep</code>, <code class="filename">awk</code>, | ||
375 | and so forth) that you might wish to use. | ||
376 | If in doubt, you should check with multiple | ||
377 | implementations - including those from BusyBox. | ||
378 | </p></li> | ||
379 | </ul></div> | ||
380 | <p> | ||
381 | </p> | ||
382 | </div></body> | ||
383 | </html> | ||