summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml144
1 files changed, 85 insertions, 59 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 7c294008c0..c2342a2236 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -677,73 +677,81 @@
677 <section id='functions'> 677 <section id='functions'>
678 <title>Functions</title> 678 <title>Functions</title>
679 679
680 <note>
681 This is only supported in <filename>.bb</filename>
682 and <filename>.bbclass</filename> files.
683 </note>
684
685 <para> 680 <para>
686 As with most languages, functions are the building blocks 681 As with most languages, functions are the building blocks
687 that define operations. 682 that define operations.
688 Bitbake supports shell and Python functions. 683 BitBake supports three types of functions:
689 An example shell function definition is: 684 <itemizedlist>
690 <literallayout class='monospaced'> 685 <listitem><para><emphasis>Shell Functions:</emphasis>
686 Functions written in a shell language and
687 executed by the shell.
688 </para></listitem>
689 <listitem><para><emphasis>BitBake Functions:</emphasis>
690 Functions written in Python but executed by BitBake using
691 <filename>bb.build.exec_func()</filename>.
692 </para></listitem>
693 <listitem><para><emphasis>Python Functions:</emphasis>
694 Functions written in Python and executed by Python.
695 </para></listitem>
696 </itemizedlist>
697 Regardless of the type of function, you can only
698 define them in class (<filename>.bbclass</filename>)
699 and recipe (<filename>.bb</filename>) files.
700 </para>
701
702 <section id='shell-functions'>
703 <title>Shell Functions</title>
704
705 <para>
706 These functions are written using a shell language and
707 executed by the shell.
708 Here is an example shell function definition:
709 <literallayout class='monospaced'>
691 some_function () { 710 some_function () {
692 echo "Hello World" 711 echo "Hello World"
693 } 712 }
694 </literallayout> 713 </literallayout>
695 An example Python function definition is: 714 When you create these types of functions in your recipe
696 <literallayout class='monospaced'> 715 or class files, you need to follow the shell programming
716 rules.
717 </para>
718 </section>
719
720 <section id='bitbake-functions'>
721 <title>BitBake Functions</title>
722
723 <para>
724 These functions are written in Python and are executed using
725 <filename>bb.build.exec_func()</filename>.
726 </para>
727
728 <para>
729 An example BitBake function is:
730 <literallayout class='monospaced'>
697 python some_python_function () { 731 python some_python_function () {
698 d.setVar("TEXT", "Hello World") 732 d.setVar("TEXT", "Hello World")
699 print d.getVar("TEXT", True) 733 print d.getVar("TEXT", True)
700 } 734 }
701 </literallayout> 735 </literallayout>
702 In python functions, the "bb" and "os" modules are already 736 Because the Python "bb" and "os" modules are already
703 imported, there is no need to import those modules. 737 imported, you do not need to import these modules.
704 The datastore, "d" is also a global variable and always 738 Also in these types of functions, the datastore ("d")
705 available to these functions automatically. 739 is a global variable and is always automatically
706 </para> 740 available.
707 741 </para>
708 <para> 742 </section>
709 Bitbake will execute functions of this form using
710 the <filename>bb.build.exec_func()</filename>, which can also be
711 called from Python functions to execute other functions,
712 either shell or Python based.
713 Shell functions can only execute other shell functions.
714 </para>
715
716 <para>
717 There is also a second way to declare python functions with
718 parameters which takes the form:
719 <literallayout class='monospaced'>
720 def some_python_function(arg1, arg2):
721 print arg1 + " " + arg2
722 </literallayout>
723 The difference is that the second form takes parameters,
724 the datastore is not available automatically
725 and must be passed as a parameter and these functions are
726 not called with the <filename>exec_func()</filename> but are
727 executed with direct Python function calls.
728 The "bb" and "os" modules are still automatically available
729 and there is no need to import them.
730 </para>
731 </section>
732
733 <section id='defining-pure-python-functions'>
734 <title>Defining Pure Python functions</title>
735 743
736 <note> 744 <section id='python-functions'>
737 This is only supported in <filename>.bb</filename> 745 <title>Python Functions</title>
738 and <filename>.bbclass</filename> files.
739 </note>
740 746
741 <para> 747 <para>
742 For utility functions that you intend to call from 748 These functions are written in Python but are executed by
743 in-line Python or other Python functions, BitBake allows 749 Python.
744 you to define these as pure Python functions. 750 Examples of Python functions are utility functions
745 Here is an example: 751 that you intend to call from in-line Python or
746 <literallayout class='monospaced'> 752 from within other Python functions.
753 Here is an example:
754 <literallayout class='monospaced'>
747 def get_depends(d): 755 def get_depends(d):
748 if d.getVar('SOMECONDITION', True): 756 if d.getVar('SOMECONDITION', True):
749 return "dependencywithcond" 757 return "dependencywithcond"
@@ -751,10 +759,28 @@
751 return "dependency" 759 return "dependency"
752 SOMECONDITION = "1" 760 SOMECONDITION = "1"
753 DEPENDS = "${@get_depends(d)}" 761 DEPENDS = "${@get_depends(d)}"
754 </literallayout> 762 </literallayout>
755 This would result in <filename>DEPENDS</filename> 763 This would result in <filename>DEPENDS</filename>
756 containing <filename>dependencywithcond</filename>. 764 containing <filename>dependencywithcond</filename>.
757 </para> 765 </para>
766
767 <para>
768 Here are some things to know about Python functions:
769 <itemizedlist>
770 <listitem><para>Python functions take parameters.
771 </para></listitem>
772 <listitem><para>The BitBake datastore is not
773 automatically available.
774 Consequently, you must pass it in as a
775 parameter to the function.
776 </para></listitem>
777 <listitem><para>The "bb" and "os" Python modules are
778 automatically available.
779 You do not need to import them.
780 </para></listitem>
781 </itemizedlist>
782 </para>
783 </section>
758 </section> 784 </section>
759 785
760 <section id='tasks'> 786 <section id='tasks'>