summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-02-07 14:39:47 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-03-09 18:59:01 -0700
commit80127f433a90252ec6c376321b3c9b444bc55e74 (patch)
tree9e94c1affcf4f32d477ed11d0424243c89e1fe90 /bitbake/doc
parentae96cbb4c42fb047f1cd46d89110fe285a9c7dc6 (diff)
downloadpoky-80127f433a90252ec6c376321b3c9b444bc55e74.tar.gz
bitbake: user-manual-metadata.xml: Edits to "Variable Flags" section
Worked through this section with Richard providing an interactive review. The changes are after the review. There was also a small edit to the "Tasks" section. (Bitbake rev: cba57f8d900d7c3ed8da9fcab0697e3047476325) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml153
1 files changed, 115 insertions, 38 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 002e866d6b..9f172d4e65 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -678,17 +678,18 @@
678 <title>Functions</title> 678 <title>Functions</title>
679 679
680 <para> 680 <para>
681 As with most languages, functions are the building blocks 681 As with most languages, functions are the building blocks that
682 that define operations. 682 are used to build up operations into tasks.
683 BitBake supports three types of functions: 683 BitBake supports three types of functions:
684 <itemizedlist> 684 <itemizedlist>
685 <listitem><para><emphasis>Shell Functions:</emphasis> 685 <listitem><para><emphasis>Shell Functions:</emphasis>
686 Functions written in a shell language and 686 Functions written in shell script and executed either
687 executed by the shell. 687 directly as functions, tasks, or both.
688 They can also be called by other shell functions.
688 </para></listitem> 689 </para></listitem>
689 <listitem><para><emphasis>BitBake Functions:</emphasis> 690 <listitem><para><emphasis>BitBake Style Python Functions:</emphasis>
690 Functions written in Python but executed by BitBake using 691 Functions written in Python and executed by BitBake or other
691 <filename>bb.build.exec_func()</filename>. 692 Python functions using <filename>bb.build.exec_func()</filename>.
692 </para></listitem> 693 </para></listitem>
693 <listitem><para><emphasis>Python Functions:</emphasis> 694 <listitem><para><emphasis>Python Functions:</emphasis>
694 Functions written in Python and executed by Python. 695 Functions written in Python and executed by Python.
@@ -696,15 +697,17 @@
696 </itemizedlist> 697 </itemizedlist>
697 Regardless of the type of function, you can only 698 Regardless of the type of function, you can only
698 define them in class (<filename>.bbclass</filename>) 699 define them in class (<filename>.bbclass</filename>)
699 and recipe (<filename>.bb</filename>) files. 700 and recipe (<filename>.bb</filename> or <filename>.inc</filename>)
701 files.
700 </para> 702 </para>
701 703
702 <section id='shell-functions'> 704 <section id='shell-functions'>
703 <title>Shell Functions</title> 705 <title>Shell Functions</title>
704 706
705 <para> 707 <para>
706 These functions are written using a shell language and 708 Functions written in shell script and executed either
707 executed by the shell. 709 directly as functions, tasks, or both.
710 They can also be called by other shell functions.
708 Here is an example shell function definition: 711 Here is an example shell function definition:
709 <literallayout class='monospaced'> 712 <literallayout class='monospaced'>
710 some_function () { 713 some_function () {
@@ -714,14 +717,19 @@
714 When you create these types of functions in your recipe 717 When you create these types of functions in your recipe
715 or class files, you need to follow the shell programming 718 or class files, you need to follow the shell programming
716 rules. 719 rules.
720 The scripts are executed by <filename>/bin/sh</filename>,
721 which may not be a bash shell but might be something
722 such as <filename>dash</filename>.
723 You should not use Bash-specific script (bashisms).
717 </para> 724 </para>
718 </section> 725 </section>
719 726
720 <section id='bitbake-functions'> 727 <section id='bitbake-style-python-functions'>
721 <title>BitBake Functions</title> 728 <title>BitBake Style Python Functions</title>
722 729
723 <para> 730 <para>
724 These functions are written in Python and are executed using 731 These functions are written in Python and executed by
732 BitBake or other Python functions using
725 <filename>bb.build.exec_func()</filename>. 733 <filename>bb.build.exec_func()</filename>.
726 </para> 734 </para>
727 735
@@ -745,8 +753,8 @@
745 <title>Python Functions</title> 753 <title>Python Functions</title>
746 754
747 <para> 755 <para>
748 These functions are written in Python but are executed by 756 These functions are written in Python and are executed by
749 Python. 757 other Python code.
750 Examples of Python functions are utility functions 758 Examples of Python functions are utility functions
751 that you intend to call from in-line Python or 759 that you intend to call from in-line Python or
752 from within other Python functions. 760 from within other Python functions.
@@ -767,7 +775,7 @@
767 <para> 775 <para>
768 Here are some things to know about Python functions: 776 Here are some things to know about Python functions:
769 <itemizedlist> 777 <itemizedlist>
770 <listitem><para>Python functions take parameters. 778 <listitem><para>Python functions can take parameters.
771 </para></listitem> 779 </para></listitem>
772 <listitem><para>The BitBake datastore is not 780 <listitem><para>The BitBake datastore is not
773 automatically available. 781 automatically available.
@@ -790,8 +798,9 @@
790 Tasks are BitBake execution units that originate as 798 Tasks are BitBake execution units that originate as
791 functions and make up the steps that BitBake needs to run 799 functions and make up the steps that BitBake needs to run
792 for given recipe. 800 for given recipe.
793 Tasks are only supported in recipe (<filename>.bb</filename>) 801 Tasks are only supported in recipe (<filename>.bb</filename>
794 and class (<filename>.bbclass</filename>) files. 802 or <filename>.inc</filename>) and class
803 (<filename>.bbclass</filename>) files.
795 By convention, tasks begin with the string "do_". 804 By convention, tasks begin with the string "do_".
796 </para> 805 </para>
797 806
@@ -919,40 +928,108 @@
919 <title>Variable Flags</title> 928 <title>Variable Flags</title>
920 929
921 <para> 930 <para>
922 This section describes variable flags. 931 Variable flags (varflags) help control a task's functionality
932 and dependencies.
933 BitBake reads and writes varflags to the datastore using the following
934 command forms:
935 <literallayout class='monospaced'>
936 &lt;variable&gt; = d.getVarFlags("&lt;variable&gt;")
937 self.d.setVarFlags("FOO", {"func": True})
938 </literallayout>
923 </para> 939 </para>
924 </section>
925 940
926 <section id='task-flags'> 941 <para>
927 <title>Task Flags</title> 942 When working with varflags, the same syntax, with the exception of
943 overrides, applies.
944 In other words, you can set, append, and prepend varflags just like
945 variables.
946 See the
947 "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>"
948 section for details.
949 </para>
928 950
929 <para> 951 <para>
930 Tasks support a number of flags which control various 952 BitBake has a defined set of varflags available for recipes and
931 functionality of the task. 953 classes.
932 These are as follows: 954 You can discover the complete set by using <filename>grep</filename>
955 within a shell and search on the string "VarFlags".
956 </para>
957
958 <para>
959 Tasks support a number of these flags which control various
960 functionality of the task:
933 <itemizedlist> 961 <itemizedlist>
934 <listitem><para><emphasis>dirs:</emphasis> 962 <listitem><para><emphasis>dirs:</emphasis>
935 Directories which should be created before the task runs. 963 Directories that should be created before the task runs.
936 </para></listitem> 964 </para></listitem>
937 <listitem><para><emphasis>cleandirs:</emphasis> 965 <listitem><para><emphasis>cleandirs:</emphasis>
938 Directories which should created before the task runs 966 Empty directories that should created before the task runs.
939 but should be empty.</para></listitem> 967 </para></listitem>
940 <listitem><para><emphasis>noexec:</emphasis> 968 <listitem><para><emphasis>noexec:</emphasis>
941 Marks the tasks as being empty and no execution required. 969 Marks the tasks as being empty and no execution required.
942 These are used as dependency placeholders or used when added tasks 970 These flags are used as dependency placeholders or used when
943 need to be subsequently disabled.</para></listitem> 971 added tasks need to be subsequently disabled.
972 </para></listitem>
944 <listitem><para><emphasis>nostamp:</emphasis> 973 <listitem><para><emphasis>nostamp:</emphasis>
945 Do not generate a stamp file for a task. 974 Tells BitBake to not generate a stamp file for a task,
946 This means the task is always executed.</para></listitem> 975 which implies the task is always executed.
976 </para></listitem>
947 <listitem><para><emphasis>fakeroot:</emphasis> 977 <listitem><para><emphasis>fakeroot:</emphasis>
948 This task needs to be run in a fakeroot environment, 978 Causes a task to be run in a fakeroot environment,
949 obtained by adding the variables in <filename>FAKEROOTENV</filename> 979 obtained by adding the variables in
950 to the environment.</para></listitem> 980 <link linkend='var-FAKEROOTENV'><filename>FAKEROOTENV</filename></link>
981 to the environment.
982 </para></listitem>
951 <listitem><para><emphasis>umask:</emphasis> 983 <listitem><para><emphasis>umask:</emphasis>
952 The umask to run the task under.</para></listitem> 984 The umask to run the task under.
985 </para></listitem>
986 <listitem><para><emphasis>deptask:</emphasis>
987 Controls task build-time dependencies.
988 See the
989 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
990 variable and the
991 "<link linkend='build-dependencies'>Build Dependencies</link>"
992 section for more information.
993 </para></listitem>
994 <listitem><para><emphasis>rdeptask:</emphasis>
995 Controls task runtime dependencies.
996 See the
997 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
998 variable, the
999 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1000 variable, and the
1001 "<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
1002 section for more information.
1003 </para></listitem>
1004 <listitem><para><emphasis>recrdeptask:</emphasis>
1005 Controls task recursive runtime dependencies.
1006 See the
1007 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1008 variable, the
1009 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1010 variable, and the
1011 "<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
1012 section for more information.
1013 </para></listitem>
1014 <listitem><para><emphasis>depends:</emphasis>
1015 Controls inter-task dependencies.
1016 See the
1017 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1018 variable and the
1019 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1020 section for more information.
1021 </para></listitem>
1022 <listitem><para><emphasis>rdepends:</emphasis>
1023 Controls inter-task runtime dependencies.
1024 See the
1025 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1026 variable, the
1027 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1028 variable, and the
1029 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1030 section for more information.
1031 </para></listitem>
953 </itemizedlist> 1032 </itemizedlist>
954 For the 'deptask', 'rdeptask', 'depends', 'rdepends'and
955 'recrdeptask' flags, please see the dependencies section.
956 </para> 1033 </para>
957 </section> 1034 </section>
958 1035