summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-05-07 15:18:01 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-05-13 07:50:57 +0100
commitf7a161253f2be622b847fe8f642c5f72532d3210 (patch)
tree386e0bc862f59a33561fd2488c04fed0afc28c88 /documentation/dev-manual/dev-manual-common-tasks.xml
parent9943e33d22089718d1474b13c24c2635ac5d7c61 (diff)
downloadpoky-f7a161253f2be622b847fe8f642c5f72532d3210.tar.gz
dev-manual: Added new "Understanding Recipe Syntax" section.
(From yocto-docs rev: d637ba317b22de50e25750e6031defcb707b36e5) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml274
1 files changed, 274 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index bead56c978..9c316909e8 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1283,6 +1283,280 @@
1283 </itemizedlist> 1283 </itemizedlist>
1284 </section> 1284 </section>
1285 1285
1286 <section id='understanding-recipe-syntax'>
1287 <title>Understanding Recipe Syntax</title>
1288
1289 <para>
1290 The basic items that make up a BitBake recipe file are
1291 as follows:
1292 <itemizedlist>
1293 <listitem><para><emphasis>Functions:</emphasis>
1294 Functions provide a series of actions to be performed.
1295 Functions are usually used to override the default
1296 implementation of a task function, or to compliment
1297 (append or prepend to an existing function) a default
1298 function.
1299 Standard functions use <filename>sh</filename> shell
1300 syntax, although access to OpenEmbedded variables and
1301 internal methods are also available.</para>
1302 <para>The following is an example function from the
1303 <filename>sed</filename> recipe:
1304 <literallayout class='monospaced'>
1305 do_install () {
1306 autotools_do_install
1307 install -d ${D}${base_bindir}
1308 mv ${D}${bindir}/sed ${D}${base_bindir}/sed.${PN}
1309 }
1310 </literallayout>
1311 It is also possible to implement new functions, that
1312 are not replacing or complimenting the default
1313 functions, which are called between existing tasks.
1314 It is also possible to implement functions in Python
1315 instead of <filename>sh</filename>.
1316 Both of these options are not seen in the majority of
1317 recipes.</para></listitem>
1318 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
1319 Variable assignments allow a value to be assigned to a
1320 variable.
1321 The assignment can be static text or might include
1322 the contents of other variables.
1323 In addition to assignment, appending and prepending
1324 operations are also supported.</para>
1325 <para>The following example shows some of the ways
1326 you can use variables in recipes:
1327 <literallayout class='monospaced'>
1328 S = "${WORKDIR}/postfix-${PV}"
1329 PR = "r4"
1330 CFLAGS += "-DNO_ASM"
1331 SRC_URI_append = "file://fixup.patch"
1332 </literallayout>
1333 </para></listitem>
1334 <listitem><para><emphasis>Keywords:</emphasis>
1335 Only a few keywords are used in BitBake recipes.
1336 Keywords are used for things such as including common
1337 functions (<filename>inherit</filename>), loading parts
1338 of a recipe from other files
1339 (<filename>include</filename> and
1340 <filename>require</filename>) and exporting variables
1341 to the environment (<filename>export</filename>).</para>
1342 <para>The following example shows the use of some of
1343 these keywords:
1344 <literallayout class='monospaced'>
1345 export POSTCONF = "${STAGING_BINDIR}/postconf"
1346 inherit autoconf
1347 require otherfile.inc
1348 </literallayout>
1349 </para></listitem>
1350 <listitem><para><emphasis>Comments:</emphasis>
1351 Any lines that begin with the hash character
1352 (<filename>#</filename>) are treated as comment lines
1353 and are ignored:
1354 <literallayout class='monospaced'>
1355 # This is a comment
1356 </literallayout>
1357 </para></listitem>
1358 </itemizedlist>
1359 </para>
1360
1361 <para>
1362 This next list summarizes the most important and most commonly
1363 used parts of the recipe syntax.
1364 For more information on these parts of the syntax, you can
1365 reference the
1366 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
1367 chapter in the BitBake User Manual.
1368 <itemizedlist>
1369 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
1370 Use the backward slash (<filename>\</filename>
1371 character to split a statement over multiple lines.
1372 Place the slash character at the end of the line that
1373 is to be continued on the next line:
1374 <literallayout class='monospaced'>
1375 VAR = "A really long \
1376 line"
1377 </literallayout>
1378 <note>
1379 You cannot have any characters including spaces
1380 or tabs after the slash character.
1381 </note>
1382 </para></listitem>
1383 <listitem><para><emphasis>Using Variables: <filename>{...}</filename></emphasis> -
1384 Use the <filename>${&lt;varname&gt;}</filename> syntax to
1385 access the contents of a variable:
1386 <literallayout class='monospaced'>
1387 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1388 </literallayout>
1389 </para></listitem>
1390 <listitem><para><emphasis>Quote All Assignments: <filename>"&lt;value&gt;"</filename></emphasis> -
1391 Use double quotes to make all variable assignments.
1392 <literallayout class='monospaced'>
1393 VAR1 = "${OTHERVAR}"
1394 VAR2 = "The version is ${PV}"
1395 </literallayout>
1396 </para></listitem>
1397 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
1398 Conditional assignment is used to assign a value to
1399 a variable, but only when the variable is currently
1400 unset.
1401 Use the question mark followed by the equal sign
1402 (<filename>?=</filename>) to make a "soft" assignment
1403 used for conditional assignment.</para>
1404 <para>Typically, you use conditional assignment to
1405 provide
1406 a default value for use when no specific definition is
1407 provided by the machine or distro configuration in
1408 your <filename>local.conf</filename> configuration.
1409 </para>
1410 <para>Here is an example:
1411 <literallayout class='monospaced'>
1412 VAR1 ?= "New value"
1413 </literallayout>
1414 In the previous example, <filename>VAR1</filename> is
1415 set to "New value" if it is currently empty.
1416 However, if <filename>VAR1</filename> has already been
1417 set, it remains unchanged.</para>
1418 <para>In this next example, <filename>VAR1</filename>
1419 is left with the value "Original value":
1420 <literallayout class='monospaced'>
1421 VAR1 = "Original value"
1422 VAR1 ?= "New value"
1423 </literallayout>
1424 </para></listitem>
1425 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
1426 Use the plus character followed by the equals sign
1427 (<filename>+=</filename>) to append values to existing
1428 variables.
1429 <note>
1430 This operator adds a space between the existing
1431 content of the variable and the new content.
1432 </note></para>
1433 <para>Here is an example:
1434 <literallayout class='monospaced'>
1435 SRC_URI += "file://fix-makefile.patch"
1436 </literallayout>
1437 </para></listitem>
1438 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1439 Use the equals sign followed by the plus character
1440 (<filename>=+</filename>) to prepend values to existing
1441 variables.
1442 <note>
1443 This operator adds a space between the new content
1444 and the existing content of the variable.
1445 </note></para>
1446 <para>Here is an example:
1447 <literallayout class='monospaced'>
1448 VAR =+ "Starts"
1449 </literallayout>
1450 </para></listitem>
1451 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1452 Use the <filename>_append</filename> operator to
1453 append values to existing variables.
1454 This operator does not add any additional space.
1455 Also, the operator is applied after all the
1456 <filename>+=</filename>, and
1457 <filename>=+</filename> operators have been applied.
1458 </para>
1459 <para>The following example shows the space being
1460 explicitly added to the start to ensure the appended
1461 value is not merged with the existing value:
1462 <literallayout class='monospaced'>
1463 SRC_URI_append = " file://fix-makefile.patch"
1464 </literallayout>
1465 You can also use the <filename>_append</filename>
1466 operator with overrides, which results in the actions
1467 only being performed for the specified target or
1468 machine:
1469 <literallayout class='monospaced'>
1470 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1471 </literallayout>
1472 <note>
1473 The appended information is a variable itself.
1474 Therefore, it is possible to use the
1475 <filename>+=</filename> or
1476 <filename>=+</filename> operators to assign
1477 variables to the <filename>_append</filename>
1478 information:
1479 <literallayout class='monospaced'>
1480 SRC_URI_append = " file://fix-makefile.patch"
1481 SRC_URI_append += "file://fix-install.patch"
1482 </literallayout>
1483 </note>
1484 </para></listitem>
1485 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1486 Use the <filename>_prepend</filename> operator to
1487 prepend values to existing variables.
1488 This operator does not add any additional space.
1489 Also, it is applied after all the
1490 <filename>+=</filename> and
1491 <filename>=+</filename> operators have been applied.
1492 </para>
1493 <para>The following example shows the space being
1494 explicitly added to the end to ensure the prepended
1495 value is not merged with the existing value:
1496 <literallayout class='monospaced'>
1497 CFLAGS_prepend = "-I${S}/myincludes "
1498 </literallayout>
1499 You can also use the <filename>_prepend</filename>
1500 operator with overrides, which results in the actions
1501 only being performed for the specified target or
1502 machine:
1503 <literallayout class='monospaced'>
1504 CFLAGS_prepend_sh4 = " file://fix-makefile.patch"
1505 </literallayout>
1506 <note>
1507 The appended information is a variable itself.
1508 Therefore, it is possible to use the
1509 <filename>+=</filename> or
1510 <filename>=+</filename> operators to assign
1511 variables to the <filename>_prepend</filename>
1512 information:
1513 <literallayout class='monospaced'>
1514 CFLAGS_prepend = "-I${S}/myincludes "
1515 CFLAGS_prepend += "-I${S}/myincludes2 "
1516 </literallayout>
1517 Notice in this example no spacing is used at the
1518 front of the value string.
1519 Recall that the <filename>+=</filename> operator
1520 adds space itself.
1521 </note>
1522 </para></listitem>
1523 <listitem><para><emphasis>Spaces as Compared to Tabs:</emphasis>
1524 Use spaces for indentation rather than than tabs.
1525 Both currently work, however it is a policy decision
1526 of the Yocto Project to use tabs in shell functions
1527 and spaces in Python.
1528 However, realize that some layers use a policy of all
1529 spaces.
1530 </para></listitem>
1531 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@...}</filename></emphasis> -
1532 For more advanced processing, it is possible to use
1533 Python code during variable assignments (e.g.
1534 search and replacement on a variable).</para>
1535 <para>You indicate Python code using a preceding
1536 <filename>@</filename> character in the variable
1537 assignment:
1538 <literallayout class='monospaced'>
1539 CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}"
1540 </literallayout>
1541 </para></listitem>
1542 <listitem><para><emphasis>Shell Syntax:</emphasis>
1543 Use shell syntax as if you were writing a shell script
1544 when you describe a list of actions to take.
1545 You should ensure that your script works with a generic
1546 <filename>sh</filename> and that it does not require
1547 any <filename>bash</filename> or other shell-specific
1548 functionality.
1549 The same considerations apply to various system
1550 utilities (e.g. <filename>sed</filename>,
1551 <filename>grep</filename>, <filename>awk</filename>,
1552 and so forth) that you might wish to use.
1553 If in doubt, you should check with multiple
1554 implementations - including those from busybox.
1555 </para></listitem>
1556 </itemizedlist>
1557 </para>
1558 </section>
1559
1286 <section id='new-recipe-running-a-build-on-the-recipe'> 1560 <section id='new-recipe-running-a-build-on-the-recipe'>
1287 <title>Running a Build on the Recipe</title> 1561 <title>Running a Build on the Recipe</title>
1288 1562