summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-04-02 12:26:02 +0000
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-04-02 14:15:35 +0100
commita5775abb1951ec6cdc7afacd1ae87189e398cff8 (patch)
tree1af23405da8d61e3ecb23105708460f87ad3c076
parent3e528d3e4bc542ca2f654c54363c56af0fb9f61b (diff)
downloadpoky-a5775abb1951ec6cdc7afacd1ae87189e398cff8.tar.gz
bitbake: user-manual-metadata.xml: Added new section on mapping functions.
Fixes [YOCTO #5472] Fixes [YOCTO #1973] Created a new section called "Automatically Mapping Functions Within the Context of a Class". This section addresses the EXPORT_FUNCTIONS "operator", which was the last of the adjustments to the variables bug against the BB manual (1973). The related bug (5472) is a general bug against enhancing the BB manual, which this change caps off. The section here was reviewed and approved by Richard Purdie. (Bitbake rev: cec33d4fdc05db3a41e978f3a1ab977730c443eb) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml76
1 files changed, 76 insertions, 0 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 3864c008d2..a57fe0c814 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -792,6 +792,82 @@
792 </itemizedlist> 792 </itemizedlist>
793 </para> 793 </para>
794 </section> 794 </section>
795
796 <section id='automatically-mapping-functions-within-the-context-of-a-class'>
797 <title>Automatically Mapping Functions Within the Context of a Class</title>
798
799 <para>
800 Through coding techniques and the use of
801 <filename>EXPORT_FUNCTIONS</filename>, BitBake supports
802 automatic mapping for functions within the context of
803 a class.
804 </para>
805
806 <para>
807 To understand the benefits of this feature, consider the basic scenario
808 where a class defines a function and your recipe inherits the class.
809 In this basic scenario, your recipe has access to the function in the
810 class by way of inheritance and can freely call and use the function
811 as defined in the class.
812 However, if you need to have a modified version of that function
813 in your recipe you are limited to using either your modified version
814 of the function or using "prepend_" or "_append" operators to add
815 code to be executed before or after the original function in the
816 class.
817 Your recipe cannot use both versions of the fucntion.
818 </para>
819
820 <para>
821 Function mapping allows you to access both your custom function
822 function that is defined in the recipe and the original function that
823 is defined in the class.
824 You have this access all from within your recipe.
825 To accomplish this, you need some things in place:
826 <itemizedlist>
827 <listitem><para>
828 The class needs to define the function as follows:
829 <literallayout class='monospaced'>
830 &lt;classname&gt;_&lt;functionname&gt;
831 </literallayout>
832 For example, if you have a class file
833 <filename>bar.bbclass</filename> and a function named
834 <filename>do_foo</filename>, the class must define the function
835 as follows:
836 <literallayout class='monospaced'>
837 bar_do_foo
838 </literallayout>
839 </para></listitem>
840 <listitem><para>
841 The class needs to contain the <filename>EXPORT_FUNCTIONS</filename>
842 statement as follows:
843 <literallayout class='monospaced'>
844 EXPORT_FUNCTIONS &lt;functionname&gt;
845 </literallayout>
846 For example, continuing with the same example, the
847 statement in the <filename>bar.bbclass</filename> would be
848 as follows:
849 <literallayout class='monospaced'>
850 EXPORT_FUNCTIONS do_foo
851 </literallayout>
852 </para></listitem>
853 <listitem><para>
854 You need to call the function appropriately from within your
855 recipe.
856 Continuing with the same example,
857 your recipe would call the <filename>do_foo</filename> function
858 from the recipe by referring to it as
859 <filename>bar_do_foo</filename>.
860 To call your modified version of the function as defined in your
861 recipe, call it as <filename>do_foo</filename>.
862 </para></listitem>
863 </itemizedlist>
864 With these conditions met, your single recipe
865 can freely choose between the original function
866 as defined in the class file and the modified function in your recipe.
867 If you do not set up these conditions, you are limited to using one function
868 or the other.
869 </para>
870 </section>
795 </section> 871 </section>
796 872
797 <section id='tasks'> 873 <section id='tasks'>