diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-05-07 23:50:59 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-05-13 07:50:58 +0100 |
commit | ab864d71fb85628e0f1980b84a23bad7a7e2baea (patch) | |
tree | cb892dba6a6bf8fc33c7eee66d6f9e30dd20b8ec /documentation/dev-manual | |
parent | 1744a1e5b9132cd9c93556fa10af5642e4738095 (diff) | |
download | poky-ab864d71fb85628e0f1980b84a23bad7a7e2baea.tar.gz |
dev-manual: Edits to the "Understanding Recipe Syntax" section.
(From yocto-docs rev: 97e5025ccff55efd077fdaf9b2d65eae5b59bc2b)
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')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 120 |
1 files changed, 49 insertions, 71 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 55257f7c58..01add16a60 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml | |||
@@ -1290,6 +1290,21 @@ | |||
1290 | The basic items that make up a BitBake recipe file are | 1290 | The basic items that make up a BitBake recipe file are |
1291 | as follows: | 1291 | as follows: |
1292 | <itemizedlist> | 1292 | <itemizedlist> |
1293 | <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis> | ||
1294 | Variable assignments allow a value to be assigned to a | ||
1295 | variable. | ||
1296 | The assignment can be static text or might include | ||
1297 | the contents of other variables. | ||
1298 | In addition to the assignment, appending and prepending | ||
1299 | operations are also supported.</para> | ||
1300 | <para>The following example shows some of the ways | ||
1301 | you can use variables in recipes: | ||
1302 | <literallayout class='monospaced'> | ||
1303 | S = "${WORKDIR}/postfix-${PV}" | ||
1304 | CFLAGS += "-DNO_ASM" | ||
1305 | SRC_URI_append = " file://fixup.patch" | ||
1306 | </literallayout> | ||
1307 | </para></listitem> | ||
1293 | <listitem><para><emphasis>Functions:</emphasis> | 1308 | <listitem><para><emphasis>Functions:</emphasis> |
1294 | Functions provide a series of actions to be performed. | 1309 | Functions provide a series of actions to be performed. |
1295 | You usually use functions to override the default | 1310 | You usually use functions to override the default |
@@ -1313,25 +1328,9 @@ | |||
1313 | new functions are not replacing or complimenting the | 1328 | new functions are not replacing or complimenting the |
1314 | default functions. | 1329 | default functions. |
1315 | You can implement functions in Python | 1330 | You can implement functions in Python |
1316 | instead of <filename>sh</filename>. | 1331 | instead of shell. |
1317 | Both of these options are not seen in the majority of | 1332 | Both of these options are not seen in the majority of |
1318 | recipes.</para></listitem> | 1333 | recipes.</para></listitem> |
1319 | <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis> | ||
1320 | Variable assignments allow a value to be assigned to a | ||
1321 | variable. | ||
1322 | The assignment can be static text or might include | ||
1323 | the contents of other variables. | ||
1324 | In addition to the assignment, appending and prepending | ||
1325 | operations are also supported.</para> | ||
1326 | <para>The following example shows some of the ways | ||
1327 | you can use variables in recipes: | ||
1328 | <literallayout class='monospaced'> | ||
1329 | S = "${WORKDIR}/postfix-${PV}" | ||
1330 | PR = "r4" | ||
1331 | CFLAGS += "-DNO_ASM" | ||
1332 | SRC_URI_append = "file://fixup.patch" | ||
1333 | </literallayout> | ||
1334 | </para></listitem> | ||
1335 | <listitem><para><emphasis>Keywords:</emphasis> | 1334 | <listitem><para><emphasis>Keywords:</emphasis> |
1336 | BitBake recipes use only a few keywords. | 1335 | BitBake recipes use only a few keywords. |
1337 | You use keywords to include common | 1336 | You use keywords to include common |
@@ -1389,7 +1388,8 @@ | |||
1389 | </literallayout> | 1388 | </literallayout> |
1390 | </para></listitem> | 1389 | </para></listitem> |
1391 | <listitem><para><emphasis>Quote All Assignments: <filename>"<value>"</filename></emphasis> - | 1390 | <listitem><para><emphasis>Quote All Assignments: <filename>"<value>"</filename></emphasis> - |
1392 | Use double quotes to make all variable assignments. | 1391 | Use double quotes around the value in all variable |
1392 | assignments. | ||
1393 | <literallayout class='monospaced'> | 1393 | <literallayout class='monospaced'> |
1394 | VAR1 = "${OTHERVAR}" | 1394 | VAR1 = "${OTHERVAR}" |
1395 | VAR2 = "The version is ${PV}" | 1395 | VAR2 = "The version is ${PV}" |
@@ -1401,13 +1401,14 @@ | |||
1401 | unset. | 1401 | unset. |
1402 | Use the question mark followed by the equal sign | 1402 | Use the question mark followed by the equal sign |
1403 | (<filename>?=</filename>) to make a "soft" assignment | 1403 | (<filename>?=</filename>) to make a "soft" assignment |
1404 | used for conditional assignment.</para> | 1404 | used for conditional assignment. |
1405 | <para>Typically, you use conditional assignment to | 1405 | Typically, "soft" assignments are used in the |
1406 | provide | 1406 | <filename>local.conf</filename> file for variables |
1407 | a default value for use when no specific definition is | 1407 | that are allowed to come through from the external |
1408 | provided by the machine or distro configuration in | 1408 | environment. |
1409 | your <filename>local.conf</filename> configuration. | 1409 | Doing so allows you to actually set variables from |
1410 | </para> | 1410 | the external environment that would otherwise be |
1411 | overwritten.</para> | ||
1411 | <para>Here is an example: | 1412 | <para>Here is an example: |
1412 | <literallayout class='monospaced'> | 1413 | <literallayout class='monospaced'> |
1413 | VAR1 ?= "New value" | 1414 | VAR1 ?= "New value" |
@@ -1455,7 +1456,9 @@ | |||
1455 | This operator does not add any additional space. | 1456 | This operator does not add any additional space. |
1456 | Also, the operator is applied after all the | 1457 | Also, the operator is applied after all the |
1457 | <filename>+=</filename>, and | 1458 | <filename>+=</filename>, and |
1458 | <filename>=+</filename> operators have been applied. | 1459 | <filename>=+</filename> operators have been applied and |
1460 | after all <filename>=</filename> assignments have | ||
1461 | occurred. | ||
1459 | </para> | 1462 | </para> |
1460 | <para>The following example shows the space being | 1463 | <para>The following example shows the space being |
1461 | explicitly added to the start to ensure the appended | 1464 | explicitly added to the start to ensure the appended |
@@ -1470,26 +1473,17 @@ | |||
1470 | <literallayout class='monospaced'> | 1473 | <literallayout class='monospaced'> |
1471 | SRC_URI_append_sh4 = " file://fix-makefile.patch" | 1474 | SRC_URI_append_sh4 = " file://fix-makefile.patch" |
1472 | </literallayout> | 1475 | </literallayout> |
1473 | <note> | ||
1474 | The appended information is a variable itself. | ||
1475 | Therefore, it is possible to use the | ||
1476 | <filename>+=</filename> or | ||
1477 | <filename>=+</filename> operators to assign | ||
1478 | variables to the <filename>_append</filename> | ||
1479 | information: | ||
1480 | <literallayout class='monospaced'> | ||
1481 | SRC_URI_append = " file://fix-makefile.patch" | ||
1482 | SRC_URI_append += "file://fix-install.patch" | ||
1483 | </literallayout> | ||
1484 | </note> | ||
1485 | </para></listitem> | 1476 | </para></listitem> |
1486 | <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> - | 1477 | <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> - |
1487 | Use the <filename>_prepend</filename> operator to | 1478 | Use the <filename>_prepend</filename> operator to |
1488 | prepend values to existing variables. | 1479 | prepend values to existing variables. |
1489 | This operator does not add any additional space. | 1480 | This operator does not add any additional space. |
1490 | Also, it is applied after all the | 1481 | This operator does not add any additional space. |
1491 | <filename>+=</filename> and | 1482 | Also, the operator is applied after all the |
1492 | <filename>=+</filename> operators have been applied. | 1483 | <filename>+=</filename>, and |
1484 | <filename>=+</filename> operators have been applied and | ||
1485 | after all <filename>=</filename> assignments have | ||
1486 | occurred. | ||
1493 | </para> | 1487 | </para> |
1494 | <para>The following example shows the space being | 1488 | <para>The following example shows the space being |
1495 | explicitly added to the end to ensure the prepended | 1489 | explicitly added to the end to ensure the prepended |
@@ -1504,45 +1498,29 @@ | |||
1504 | <literallayout class='monospaced'> | 1498 | <literallayout class='monospaced'> |
1505 | CFLAGS_prepend_sh4 = " file://fix-makefile.patch" | 1499 | CFLAGS_prepend_sh4 = " file://fix-makefile.patch" |
1506 | </literallayout> | 1500 | </literallayout> |
1507 | <note> | ||
1508 | The appended information is a variable itself. | ||
1509 | Therefore, it is possible to use the | ||
1510 | <filename>+=</filename> or | ||
1511 | <filename>=+</filename> operators to assign | ||
1512 | variables to the <filename>_prepend</filename> | ||
1513 | information: | ||
1514 | <literallayout class='monospaced'> | ||
1515 | CFLAGS_prepend = "-I${S}/myincludes " | ||
1516 | CFLAGS_prepend += "-I${S}/myincludes2 " | ||
1517 | </literallayout> | ||
1518 | Notice in this example no spacing is used at the | ||
1519 | front of the value string. | ||
1520 | Recall that the <filename>+=</filename> operator | ||
1521 | adds space itself. | ||
1522 | </note> | ||
1523 | </para></listitem> | 1501 | </para></listitem> |
1524 | <listitem><para><emphasis>Spaces as Compared to Tabs:</emphasis> | 1502 | <listitem><para><emphasis>Indentation:</emphasis> |
1525 | Use spaces for indentation rather than than tabs. | 1503 | Use spaces for indentation rather than than tabs. |
1526 | Both currently work, however it is a policy decision | 1504 | For shell functions, both currently work. |
1527 | of the Yocto Project to use tabs in shell functions | 1505 | However, it is a policy decision of the Yocto Project |
1528 | and spaces in Python. | 1506 | to use tabs in shell functions. |
1529 | However, realize that some layers use a policy of all | 1507 | Realize that some layers have a policy to use spaces |
1530 | spaces. | 1508 | for all indentation. |
1531 | </para></listitem> | 1509 | </para></listitem> |
1532 | <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@...}</filename></emphasis> - | 1510 | <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<variable>}</filename></emphasis> - |
1533 | For more advanced processing, it is possible to use | 1511 | For more advanced processing, it is possible to use |
1534 | Python code during variable assignments (e.g. | 1512 | Python code during variable assignments (e.g. |
1535 | search and replacement on a variable).</para> | 1513 | search and replacement on a variable).</para> |
1536 | <para>You indicate Python code using a preceding | 1514 | <para>You indicate Python code using the |
1537 | <filename>@</filename> character in the variable | 1515 | <filename>${@<variable>}</filename> syntax for the |
1538 | assignment: | 1516 | variable assignment: |
1539 | <literallayout class='monospaced'> | 1517 | <literallayout class='monospaced'> |
1540 | CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}" | 1518 | SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz |
1541 | </literallayout> | 1519 | </literallayout> |
1542 | </para></listitem> | 1520 | </para></listitem> |
1543 | <listitem><para><emphasis>Shell Syntax:</emphasis> | 1521 | <listitem><para><emphasis>Shell Function Syntax:</emphasis> |
1544 | Use shell syntax as if you were writing a shell script | 1522 | Use shell function syntax as if you were writing a shell |
1545 | when you describe a list of actions to take. | 1523 | script when you describe a list of actions to take. |
1546 | You should ensure that your script works with a generic | 1524 | You should ensure that your script works with a generic |
1547 | <filename>sh</filename> and that it does not require | 1525 | <filename>sh</filename> and that it does not require |
1548 | any <filename>bash</filename> or other shell-specific | 1526 | any <filename>bash</filename> or other shell-specific |