summaryrefslogtreecommitdiffstats
path: root/documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html
diff options
context:
space:
mode:
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.html383
1 files changed, 383 insertions, 0 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
new file mode 100644
index 0000000000..fcf46d9d35
--- /dev/null
+++ b/documentation/getting-started/eclipse/html/getting-started/recipe-syntax.html
@@ -0,0 +1,383 @@
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>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-11 18:38:26 +0000