aboutsummaryrefslogtreecommitdiffstats
path: root/usermanual
diff options
context:
space:
mode:
authorJamie Lenehan <lenehan@twibble.org>2007-01-13 22:22:46 +0000
committerJamie Lenehan <lenehan@twibble.org>2007-01-13 22:22:46 +0000
commita78a9ac8ef49481269f7ef5822a4976e9f8f9d97 (patch)
tree43f7cd800c2350941b85e3d1f82c329e086ed445 /usermanual
parent7c578b1482ca68f64941dc4b9d3bba03dc2fe91c (diff)
downloadopenembedded-a78a9ac8ef49481269f7ef5822a4976e9f8f9d97.tar.gz
openembedded-a78a9ac8ef49481269f7ef5822a4976e9f8f9d97.tar.bz2
openembedded-a78a9ac8ef49481269f7ef5822a4976e9f8f9d97.zip
usermanual: Write the content for the "using python" section in the
recipes chapter.
Diffstat (limited to 'usermanual')
-rw-r--r--usermanual/chapters/recipes.xml231
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">