summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-08-08 08:54:41 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-08-17 10:22:59 +0100
commit277a5a969fd7a35c8e5d112861ba6a815c0af0ec (patch)
tree246461904cfa2e748f04aea01ba20ca61422c910
parent3a1ae389663fea639e5e86ff76d20c23992736a2 (diff)
downloadpoky-277a5a969fd7a35c8e5d112861ba6a815c0af0ec.tar.gz
bitbake: bitbake-user-manual: Added more detail to anonymous Python functions.
Fixes [YOCTO #10093] Provided much more detail on how these functions work. (Bitbake rev: dbe25523d899850f85acb6986eca98bf1b0ef52a) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml87
1 files changed, 70 insertions, 17 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 4beb5a1d89..4fa51c446d 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -428,6 +428,10 @@
428 FOO := "${@foo()}" 428 FOO := "${@foo()}"
429 </literallayout> 429 </literallayout>
430 </note> 430 </note>
431 For a different way to set variables with Python code during
432 parsing, see the
433 "<link linkend='anonymous-python-functions'>Anonymous Python Functions</link>"
434 section.
431 </para> 435 </para>
432 </section> 436 </section>
433 437
@@ -1063,32 +1067,81 @@
1063 <title>Anonymous Python Functions</title> 1067 <title>Anonymous Python Functions</title>
1064 1068
1065 <para> 1069 <para>
1066 Sometimes it is useful to run some code during 1070 Sometimes it is useful to set variables or perform
1067 parsing to set variables or to perform other operations 1071 other operations programmatically during parsing.
1068 programmatically. 1072 To do this, you can define special Python functions,
1069 To do this, you can define an anonymous Python function. 1073 called anonymous Python functions, that run at the
1070 Here is an example that conditionally sets a 1074 end of parsing.
1071 variable based on the value of another variable: 1075 For example, the following conditionally sets a variable
1076 based on the value of another variable:
1072 <literallayout class='monospaced'> 1077 <literallayout class='monospaced'>
1073 python __anonymous () { 1078 python () {
1074 if d.getVar('SOMEVAR', True) == 'value': 1079 if d.getVar('SOMEVAR', True) == 'value':
1075 d.setVar('ANOTHERVAR', 'value2') 1080 d.setVar('ANOTHERVAR', 'value2')
1076 } 1081 }
1077 </literallayout> 1082 </literallayout>
1078 The "__anonymous" function name is optional, so the 1083 An equivalent way to mark a function as an anonymous
1079 following example is functionally equivalent to the above: 1084 function is to give it the name "__anonymous", rather
1085 than no name.
1086 </para>
1087
1088 <para>
1089 Anonymous Python functions always run at the end
1090 of parsing, regardless of where they are defined.
1091 If a recipe contains many anonymous functions, they
1092 run in the same order as they are defined within the
1093 recipe.
1094 As an example, consider the following snippet:
1080 <literallayout class='monospaced'> 1095 <literallayout class='monospaced'>
1081 python () { 1096 python () {
1082 if d.getVar('SOMEVAR', True) == 'value': 1097 d.setVar('FOO', 'foo 2')
1083 d.setVar('ANOTHERVAR', 'value2') 1098 }
1099
1100 FOO = "foo 1"
1101
1102 python () {
1103 d.appendVar('BAR', ' bar 2')
1104 }
1105
1106 BAR = "bar 1"
1107 </literallayout>
1108 The previous example is conceptually equivalent to the
1109 following snippet:
1110 <literallayout class='monospaced'>
1111 FOO = "foo 1"
1112 BAR = "bar 1"
1113 FOO = "foo 2"
1114 BAR += "bar 2"
1115 </literallayout>
1116 <filename>FOO</filename> ends up with the value "foo 2",
1117 and <filename>BAR</filename> with the value "bar 1 bar 2".
1118 Just as in the second snippet, the values set for the
1119 variables within the anonymous functions become available
1120 to tasks, which always run after parsing.
1121 </para>
1122
1123 <para>
1124 Overrides and override-style operators such as
1125 "<filename>_append</filename>" are applied before
1126 anonymous functions run.
1127 In the following example, <filename>FOO</filename> ends
1128 up with the value "foo from anonymous":
1129 <literallayout class='monospaced'>
1130 FOO = "foo"
1131 FOO_append = " from outside"
1132
1133 python () {
1134 d.setVar("FOO", "foo from anonymous")
1084 } 1135 }
1085 </literallayout> 1136 </literallayout>
1086 Because unlike other Python functions anonymous 1137 For methods you can use with anonymous Python functions,
1087 Python functions are executed during parsing, the 1138 see the
1088 "d" variable within an anonymous Python function represents 1139 "<link linkend='accessing-datastore-variables-using-python'>Accessing Datastore Variables Using Python</link>"
1089 the datastore for the entire recipe. 1140 section.
1090 Consequently, you can set variable values here and 1141 For a different method to run Python code during parsing,
1091 those values can be picked up by other functions. 1142 see the
1143 "<link linkend='inline-python-variable-expansion'>Inline Python Variable Expansion</link>"
1144 section.
1092 </para> 1145 </para>
1093 </section> 1146 </section>
1094 1147