usermanual: Write the content for the "using python" section in the

recipes chapter.

1 files changed, 221 insertions, 10 deletions

diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml
index 7bab6a44ca..521dc27b0d 100644
--- a/usermanual/chapters/recipes.xml
+++ b/usermanual/chapters/recipes.xml
@@ -897,7 +897,7 @@ S = "${WORKDIR}/widgets"</screen></para>
       chapter.</para>
     </section>
 
-    <section>
+    <section id="bb_filespath_dir" xreflabel="FILESPATH/FILESDIR">
       <title>FILESPATH/FILESDIR: Finding local files</title>
 
       <para>The file related variables are used by bitbake to determine where
@@ -2836,17 +2836,228 @@ do_configure() {
   <section id="bb_advanced_python" xreflabel="advanced python">
     <title>Python: Advanced functionality with python</title>
 
-    <para>This section is to be completed.</para>
+    <para>Recipes permit the use of python code in order to perform complex
+    operations which are not possible with the normal recipe syntax and
+    variables. Python can be used in both variable assignments and in the
+    implementation of tasks.</para>
 
-    <itemizedlist>
-      <listitem>
-        <para>How to use python recipes</para>
-      </listitem>
+    <para>For variable assignments python code is indicated via the use of
+    <emphasis>${@...}</emphasis>, as shown in the following example:<screen>TAG = ${@bb.data.getVar('PV',d,1).replace('.', '_')}</screen></para>
 
-      <listitem>
-        <para>Examples of useful python code</para>
-      </listitem>
-    </itemizedlist>
+    <para>The above example retrieves the PV variable from the bitbake data
+    object, the replaces any dots with underscores. Therefore if the <emphasis
+    role="bold">PV</emphasis> was <emphasis role="bold">0.9.0</emphasis> then
+    <emphasis role="bold">TAG</emphasis> will be set to <emphasis
+    role="bold">0-9-0</emphasis>.</para>
+
+    <para>Some of the more common python code in use in existing recipes is
+    shown in the following table:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>bb.data.getVar(&lt;var&gt;,d,1)</term>
+
+        <listitem>
+          <para>Retrieve the data for the specified variable from the bitbake
+          database for the current recipe.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>&lt;variable&gt;.replace(&lt;key&gt;,
+        &lt;replacement&gt;)</term>
+
+        <listitem>
+          <para>Find each instance of the key and replace it with the
+          replacement value. This can also be used to remove part of a string
+          by specifying <emphasis role="bold">''</emphasis> (two single
+          quotes) as the replacement.</para>
+
+          <para>The following example would remove the <emphasis
+          role="bold">'-frename-registers'</emphasis> option from the
+          <emphasis role="bold">CFLAGS</emphasis> variable:<screen>CFLAGS := "${@'${CFLAGS}'.replace('-frename-registers', '')}"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>os.path.dirname(&lt;filename&gt;)</term>
+
+        <listitem>
+          <para>Return the directory only part of a filename.</para>
+
+          <para>This is most commonly seen in existing recipes when settings
+          the <emphasis role="bold">FILESDIR</emphasis> variable (as described
+          in the <xref linkend="bb_filespath_dir" /> section). By obtaining
+          name of the recipe file itself, <emphasis
+          role="bold">FILE</emphasis>, and then using os.path.dirname to strip
+          the filename part:<screen>FILESDIR = "${@os.path.dirname(bb.data.getVar('FILE',d,1))}/make-${PV}"</screen>Note
+          however that this is no longer required as <emphasis
+          role="bold">FILE_DIRNAME</emphasis> is automatically set to the
+          dirname of the <emphasis role="bold">FILE</emphasis> variable and
+          therefore this would be written in new recipes as:<screen>FILESDIR = "$FILE_DIRNAME/make-${PV}"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>&lt;variable&gt;.split(&lt;key&gt;)[&lt;index&gt;]</term>
+
+        <listitem>
+          <para>Splits are variable around the specified key. Use <emphasis
+          role="bold">[&lt;index&gt;]</emphasis> to select one of the matching
+          items from the array generated by the split command.</para>
+
+          <para>The following example from the recipe g<emphasis
+          role="bold">enext2fs_1.3+1.4rc1.bb</emphasis> would take the
+          <emphasis role="bold">PV</emphasis> of <emphasis
+          role="bold">1.3+1.4rc1</emphasis> and split it around the <emphasis
+          role="bold">+</emphasis> sign, resulting in an array containing
+          <emphasis role="bold">1.3</emphasis> and <emphasis
+          role="bold">1.4rc1</emphasis>. It then uses the index of <emphasis
+          role="bold">[1]</emphasis> to select the second item from the list
+          (the first item is at index <emphasis role="bold">0</emphasis>).
+          Therefore <emphasis role="bold">TRIMMEDV</emphasis> would be set to
+          <emphasis role="bold">1.4rc1</emphasis> for this recipe:</para>
+
+          <screen>TRIMMEDV = "${@bb.data.getVar('PV', d, 1).split('+')[1]}"</screen>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>As well as directly calling built-in python functions, those
+    functions defined by the existing classes may also be called. A set of
+    common functions is provided by the base class in <emphasis
+    role="bold">classes/base.bbclass</emphasis>:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>base_conditional</term>
+
+        <listitem>
+          <para>This functions is used to set a variable to one of two values
+          based on the definition of a third variable. The general usage
+          is:<screen>${@base_conditional('&lt;variable-name&gt;', '&lt;value&gt;', '&lt;true-result&gt;', &lt;false-result&gt;', d)}"</screen>where:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term>variable-name</term>
+
+              <listitem>
+                <para>This is the name of a variable to check.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>value</term>
+
+              <listitem>
+                <para>This is the value to compare the variable
+                against.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>true-result</term>
+
+              <listitem>
+                <para>If the variable equals the value then this is what is
+                returned by the function.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>false-result</term>
+
+              <listitem>
+                <para>If the variable does not equal the value then this is
+                what is returned by the function.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+
+          <para>The following example from the openssl recipe shows the
+          addition of either <emphasis role="bold">-DL_ENDING</emphasis> or
+          <emphasis role="bold">-DB_ENDIAN</emphasis> depending on the value
+          of <emphasis role="bold">SITEINFO_ENDIANESS</emphasis> which is set
+          to le for little endian targets and to be for big endian
+          targets:<screen>do_compile () {
+    ...
+    # Additional flag based on target endiness (see siteinfo.bbclass)
+    CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}"
+    ...</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>base_contains</term>
+
+        <listitem>
+          <para>Similar to base_conditional expect that it is checking for the
+          value being an element of an array. The general usage is:<screen>${@base_contains('&lt;array-name&gt;', '&lt;value&gt;', '&lt;true-result&gt;', &lt;false-result&gt;', d)}"</screen></para>
+
+          <para>where:<variablelist>
+              <varlistentry>
+                <term>array-name</term>
+
+                <listitem>
+                  <para>This is the name of the array to search.</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>value</term>
+
+                <listitem>
+                  <para>This is the value to check for in the array.</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>true-result</term>
+
+                <listitem>
+                  <para>If the value is found in the array then this is what
+                  is returned by the function.</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>false-result</term>
+
+                <listitem>
+                  <para>If the value is not found in the array then this is
+                  what is returned by the function.</para>
+                </listitem>
+              </varlistentry>
+            </variablelist>The following example from the task-angstrom-x11
+          recipe shows base_contains being used to add a recipe to the runtime
+          dependency list but only for machines which have a
+          touchscreen:</para>
+
+          <screen>RDEPENDS_angstrom-gpe-task-base := "\
+    ...
+    ${@base_contains("MACHINE_FEATURES", "touchscreen", "libgtkstylus", "",d)} \
+    ...</screen>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Tasks may be implemented in python by prefixing the task function
+    with "python ". In general this should not be needed and should be avoided
+    where possible. The following example from the devshell recipe shows how
+    the compile task is implemented python:<screen>python do_compile() {
+    import os
+    import os.path
+
+    workdir = bb.data.getVar('WORKDIR', d, 1)
+    shellfile = os.path.join(workdir, bb.data.expand("${TARGET_PREFIX}${DISTRO}-${MACHINE}-devshell", d))
+
+    f = open(shellfile, "w")
+
+    # emit variables and shell functions
+        devshell_emit_env(f, d, False, ["die", "oe", "autotools_do_configure"])
+
+    f.close()
+}</screen></para>
   </section>
 
   <section id="bb_defaultpreference" xreflabel="default preference">