diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-03-06 09:48:37 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-03-09 18:59:04 -0700 |
commit | 40ab94036081f9fdc4ebf6126b077149c2a97c31 (patch) | |
tree | 65075fcb43ab2e731a9891063878d13addf0737e /bitbake/doc/user-manual/user-manual-metadata.xml | |
parent | 96294ee40748dd96da7203cedf93a42e34b2a468 (diff) | |
download | poky-40ab94036081f9fdc4ebf6126b077149c2a97c31.tar.gz |
bitbake: user-manual: Review edits applied from Paul Eggleton.
Review of the entire manual by Paul. I have implemented his
suggestions throughout.
(Bitbake rev: 5cd310d1df194cd171691a4bcfb98024e2bc66b8)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/user-manual/user-manual-metadata.xml')
-rw-r--r-- | bitbake/doc/user-manual/user-manual-metadata.xml | 87 |
1 files changed, 51 insertions, 36 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml index 748b959d98..3a19b96303 100644 --- a/bitbake/doc/user-manual/user-manual-metadata.xml +++ b/bitbake/doc/user-manual/user-manual-metadata.xml | |||
@@ -40,12 +40,15 @@ | |||
40 | BitBake supports variables referencing one another's | 40 | BitBake supports variables referencing one another's |
41 | contents using a syntax that is similar to shell scripting. | 41 | contents using a syntax that is similar to shell scripting. |
42 | Following is an example that results in <filename>A</filename> | 42 | Following is an example that results in <filename>A</filename> |
43 | containing "aval" and <filename>B</filename> containing | 43 | containing "aval" and <filename>B</filename> evaluating to |
44 | "preavalpost". | 44 | "preavalpost". |
45 | <literallayout class='monospaced'> | 45 | <literallayout class='monospaced'> |
46 | A = "aval" | 46 | A = "aval" |
47 | B = "pre${A}post" | 47 | B = "pre${A}post" |
48 | </literallayout> | 48 | </literallayout> |
49 | Because the expansion happens later, the value of | ||
50 | <filename>B</filename> expands differently if the value | ||
51 | of <filename>A</filename> changes. | ||
49 | </para> | 52 | </para> |
50 | </section> | 53 | </section> |
51 | 54 | ||
@@ -79,7 +82,7 @@ | |||
79 | <title>Setting a weak default value (??=)</title> | 82 | <title>Setting a weak default value (??=)</title> |
80 | 83 | ||
81 | <para> | 84 | <para> |
82 | It is possible to use a "weaker" assignment that in the | 85 | It is possible to use a "weaker" assignment than in the |
83 | previous section by using the "??=" operator. | 86 | previous section by using the "??=" operator. |
84 | This assignment behaves identical to "?=" except that the | 87 | This assignment behaves identical to "?=" except that the |
85 | assignment is made at the end of the parsing process rather | 88 | assignment is made at the end of the parsing process rather |
@@ -197,6 +200,13 @@ | |||
197 | override syntax. | 200 | override syntax. |
198 | </note> | 201 | </note> |
199 | </para> | 202 | </para> |
203 | |||
204 | <para> | ||
205 | The operators "_append" and "_prepend" differ from | ||
206 | the operators ".=" and "=." in that they are deferred | ||
207 | until after parsing completes rather than being immediately | ||
208 | applied. | ||
209 | </para> | ||
200 | </section> | 210 | </section> |
201 | 211 | ||
202 | <section id='removing-override-style-syntax'> | 212 | <section id='removing-override-style-syntax'> |
@@ -519,7 +529,7 @@ | |||
519 | recipes require. | 529 | recipes require. |
520 | For example, you can easily abstract out the tasks involved in | 530 | For example, you can easily abstract out the tasks involved in |
521 | building a package that uses Autoconf and Automake and put | 531 | building a package that uses Autoconf and Automake and put |
522 | those tasks into a class file that can be used by your package. | 532 | those tasks into a class file that can be used by your recipe. |
523 | </para> | 533 | </para> |
524 | 534 | ||
525 | <para> | 535 | <para> |
@@ -549,9 +559,10 @@ | |||
549 | directive. | 559 | directive. |
550 | This directive causes BitBake to parse whatever file you specify, | 560 | This directive causes BitBake to parse whatever file you specify, |
551 | and to insert that file at that location. | 561 | and to insert that file at that location. |
552 | The directive is much like Make except that if the path specified | 562 | The directive is much like its equivalent in Make except |
553 | on the include line is a relative path, BitBake locates | 563 | that if the path specified on the include line is a relative |
554 | the first file it can find within <filename>BBPATH</filename>. | 564 | path, BitBake locates the first file it can find |
565 | within <filename>BBPATH</filename>. | ||
555 | </para> | 566 | </para> |
556 | 567 | ||
557 | <para> | 568 | <para> |
@@ -588,7 +599,7 @@ | |||
588 | </para> | 599 | </para> |
589 | 600 | ||
590 | <para> | 601 | <para> |
591 | Similar to how BitBake uses | 602 | Similar to how BitBake handles |
592 | <link linkend='include-directive'><filename>include</filename></link>, | 603 | <link linkend='include-directive'><filename>include</filename></link>, |
593 | if the path specified | 604 | if the path specified |
594 | on the require line is a relative path, BitBake locates | 605 | on the require line is a relative path, BitBake locates |
@@ -776,16 +787,17 @@ | |||
776 | Tasks are only supported in recipe (<filename>.bb</filename> | 787 | Tasks are only supported in recipe (<filename>.bb</filename> |
777 | or <filename>.inc</filename>) and class | 788 | or <filename>.inc</filename>) and class |
778 | (<filename>.bbclass</filename>) files. | 789 | (<filename>.bbclass</filename>) files. |
779 | By convention, tasks begin with the string "do_". | 790 | By convention, task names begin with the string "do_". |
780 | </para> | 791 | </para> |
781 | 792 | ||
782 | <para> | 793 | <para> |
783 | Here is an example of a task that prints out the date: | 794 | Here is an example of a task that prints out the date: |
784 | <literallayout class='monospaced'> | 795 | <literallayout class='monospaced'> |
785 | python do_printdate () { | 796 | python do_printdate () { |
786 | import time print | 797 | import time |
787 | time.strftime('%Y%m%d', time.gmtime()) | 798 | print time.strftime('%Y%m%d', time.gmtime()) |
788 | } | 799 | } |
800 | addtask printdate after do_fetch before do_build | ||
789 | </literallayout> | 801 | </literallayout> |
790 | </para> | 802 | </para> |
791 | 803 | ||
@@ -802,8 +814,8 @@ | |||
802 | and defining some dependencies: | 814 | and defining some dependencies: |
803 | <literallayout class='monospaced'> | 815 | <literallayout class='monospaced'> |
804 | python do_printdate () { | 816 | python do_printdate () { |
805 | import time print | 817 | import time |
806 | time.strftime('%Y%m%d', time.gmtime()) | 818 | print time.strftime('%Y%m%d', time.gmtime()) |
807 | } | 819 | } |
808 | addtask printdate after do_fetch before do_build | 820 | addtask printdate after do_fetch before do_build |
809 | </literallayout> | 821 | </literallayout> |
@@ -942,11 +954,6 @@ | |||
942 | <para> | 954 | <para> |
943 | BitBake has a defined set of varflags available for recipes and | 955 | BitBake has a defined set of varflags available for recipes and |
944 | classes. | 956 | classes. |
945 | You can discover the complete set by using <filename>grep</filename> | ||
946 | within a shell and search on the string "VarFlags". | ||
947 | </para> | ||
948 | |||
949 | <para> | ||
950 | Tasks support a number of these flags which control various | 957 | Tasks support a number of these flags which control various |
951 | functionality of the task: | 958 | functionality of the task: |
952 | <itemizedlist> | 959 | <itemizedlist> |
@@ -958,12 +965,13 @@ | |||
958 | </para></listitem> | 965 | </para></listitem> |
959 | <listitem><para><emphasis>noexec:</emphasis> | 966 | <listitem><para><emphasis>noexec:</emphasis> |
960 | Marks the tasks as being empty and no execution required. | 967 | Marks the tasks as being empty and no execution required. |
961 | These flags are used as dependency placeholders or used when | 968 | The <filename>noexec</filename> flag can be used to set up |
962 | added tasks need to be subsequently disabled. | 969 | tasks as dependency placeholders, or to disable tasks defined |
970 | elsewhere that are not needed in a particular recipe. | ||
963 | </para></listitem> | 971 | </para></listitem> |
964 | <listitem><para><emphasis>nostamp:</emphasis> | 972 | <listitem><para><emphasis>nostamp:</emphasis> |
965 | Tells BitBake to not generate a stamp file for a task, | 973 | Tells BitBake to not generate a stamp file for a task, |
966 | which implies the task is always executed. | 974 | which implies the task should always be executed. |
967 | </para></listitem> | 975 | </para></listitem> |
968 | <listitem><para><emphasis>fakeroot:</emphasis> | 976 | <listitem><para><emphasis>fakeroot:</emphasis> |
969 | Causes a task to be run in a fakeroot environment, | 977 | Causes a task to be run in a fakeroot environment, |
@@ -1027,7 +1035,7 @@ | |||
1027 | List of functions to call before the task executes. | 1035 | List of functions to call before the task executes. |
1028 | </para></listitem> | 1036 | </para></listitem> |
1029 | <listitem><para><emphasis>stamp-extra-info:</emphasis> | 1037 | <listitem><para><emphasis>stamp-extra-info:</emphasis> |
1030 | Extra stamp information to append to the task's stamp | 1038 | Extra stamp information to append to the task's stamp. |
1031 | As an example, OpenEmbedded uses this flag to allow | 1039 | As an example, OpenEmbedded uses this flag to allow |
1032 | machine-specific tasks. | 1040 | machine-specific tasks. |
1033 | </para></listitem> | 1041 | </para></listitem> |
@@ -1380,15 +1388,18 @@ | |||
1380 | </row> | 1388 | </row> |
1381 | <row> | 1389 | <row> |
1382 | <entry align="left"><filename>d.setVar("X", value)</filename></entry> | 1390 | <entry align="left"><filename>d.setVar("X", value)</filename></entry> |
1383 | <entry align="left">Sets the variable "X" to "value".</entry> | 1391 | <entry align="left">Sets the variable "X" to the value of the Python |
1392 | variable called "value".</entry> | ||
1384 | </row> | 1393 | </row> |
1385 | <row> | 1394 | <row> |
1386 | <entry align="left"><filename>d.appendVar("X", value)</filename></entry> | 1395 | <entry align="left"><filename>d.appendVar("X", value)</filename></entry> |
1387 | <entry align="left">Adds "value" to the end of the variable "X".</entry> | 1396 | <entry align="left">Adds the value of the Python variable called |
1397 | "value" to the end of the variable "X".</entry> | ||
1388 | </row> | 1398 | </row> |
1389 | <row> | 1399 | <row> |
1390 | <entry align="left"><filename>d.prependVar("X", value)</filename></entry> | 1400 | <entry align="left"><filename>d.prependVar("X", value)</filename></entry> |
1391 | <entry align="left">Adds "value" to the start of the variable "X".</entry> | 1401 | <entry align="left">Adds the value of the Python variable called |
1402 | "value" to the start of the variable "X".</entry> | ||
1392 | </row> | 1403 | </row> |
1393 | <row> | 1404 | <row> |
1394 | <entry align="left"><filename>d.delVar("X")</filename></entry> | 1405 | <entry align="left"><filename>d.delVar("X")</filename></entry> |
@@ -1400,40 +1411,44 @@ | |||
1400 | </row> | 1411 | </row> |
1401 | <row> | 1412 | <row> |
1402 | <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry> | 1413 | <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry> |
1403 | <entry align="left">Gets "flag" from the variable "X". | 1414 | <entry align="left">Gets then named flag from the variable "X". |
1404 | Using "expand=True" expands the flag.</entry> | 1415 | Using "expand=True" expands the named flag.</entry> |
1405 | </row> | 1416 | </row> |
1406 | <row> | 1417 | <row> |
1407 | <entry align="left"><filename>d.setVarFlag("X", flag, value)</filename></entry> | 1418 | <entry align="left"><filename>d.setVarFlag("X", flag, value)</filename></entry> |
1408 | <entry align="left">Sets "flag" for variable "X" to "value". | 1419 | <entry align="left">Sets the named flag for variable "X" to the value |
1409 | <filename>setVarFlags</filename> does not clear previous flags. | 1420 | of the Python variable called "value".</entry> |
1410 | Think of this operation as <filename>addVarFlags</filename>.</entry> | ||
1411 | </row> | 1421 | </row> |
1412 | <row> | 1422 | <row> |
1413 | <entry align="left"><filename>d.appendVarFlag("X", flag, value)</filename></entry> | 1423 | <entry align="left"><filename>d.appendVarFlag("X", flag, value)</filename></entry> |
1414 | <entry align="left">Need description.</entry> | 1424 | <entry align="left">Appends a value to the named flag on the |
1425 | variable "X".</entry> | ||
1415 | </row> | 1426 | </row> |
1416 | <row> | 1427 | <row> |
1417 | <entry align="left"><filename>d.prependVarFlag("X", flag, value)</filename></entry> | 1428 | <entry align="left"><filename>d.prependVarFlag("X", flag, value)</filename></entry> |
1418 | <entry align="left">Need description.</entry> | 1429 | <entry align="left">Prepends a value to the named flag on |
1430 | the variable "X".</entry> | ||
1419 | </row> | 1431 | </row> |
1420 | <row> | 1432 | <row> |
1421 | <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry> | 1433 | <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry> |
1422 | <entry align="left">Need description.</entry> | 1434 | <entry align="left">Deletes the named flag on the variable |
1435 | "X" from the datastore.</entry> | ||
1423 | </row> | 1436 | </row> |
1424 | <row> | 1437 | <row> |
1425 | <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry> | 1438 | <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry> |
1426 | <entry align="left">Sets the flags specified in | 1439 | <entry align="left">Sets the flags specified in |
1427 | the <filename>dict()</filename> parameter.</entry> | 1440 | the <filename>flagsdict()</filename> parameter. |
1441 | <filename>setVarFlags</filename> does not clear previous flags. | ||
1442 | Think of this operation as <filename>addVarFlags</filename>.</entry> | ||
1428 | </row> | 1443 | </row> |
1429 | <row> | 1444 | <row> |
1430 | <entry align="left"><filename>d.getVarFlags("X")</filename></entry> | 1445 | <entry align="left"><filename>d.getVarFlags("X")</filename></entry> |
1431 | <entry align="left">Returns a <filename>dict</filename> of the flags for | 1446 | <entry align="left">Returns a <filename>flagsdict</filename> of the flags for |
1432 | the variable "X".</entry> | 1447 | the variable "X".</entry> |
1433 | </row> | 1448 | </row> |
1434 | <row> | 1449 | <row> |
1435 | <entry align="left"><filename>d.delVarFlags</filename></entry> | 1450 | <entry align="left"><filename>d.delVarFlags("X")</filename></entry> |
1436 | <entry align="left">Deletes all the flags for a variable.</entry> | 1451 | <entry align="left">Deletes all the flags for the variable "X".</entry> |
1437 | </row> | 1452 | </row> |
1438 | </tbody> | 1453 | </tbody> |
1439 | </tgroup> | 1454 | </tgroup> |