diff options
author | Jamie Lenehan <lenehan@twibble.org> | 2007-01-13 22:22:46 +0000 |
---|---|---|
committer | Jamie Lenehan <lenehan@twibble.org> | 2007-01-13 22:22:46 +0000 |
commit | a78a9ac8ef49481269f7ef5822a4976e9f8f9d97 (patch) | |
tree | 43f7cd800c2350941b85e3d1f82c329e086ed445 /usermanual/chapters/recipes.xml | |
parent | 7c578b1482ca68f64941dc4b9d3bba03dc2fe91c (diff) | |
download | openembedded-a78a9ac8ef49481269f7ef5822a4976e9f8f9d97.tar.gz |
usermanual: Write the content for the "using python" section in the
recipes chapter.
Diffstat (limited to 'usermanual/chapters/recipes.xml')
-rw-r--r-- | usermanual/chapters/recipes.xml | 231 |
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(<var>,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><variable>.replace(<key>, + <replacement>)</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(<filename>)</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><variable>.split(<key>)[<index>]</term> + + <listitem> + <para>Splits are variable around the specified key. Use <emphasis + role="bold">[<index>]</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('<variable-name>', '<value>', '<true-result>', <false-result>', 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('<array-name>', '<value>', '<true-result>', <false-result>', 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"> |