summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-development-environment.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-08-09 17:15:15 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-09-02 00:52:47 +0100
commitd369f333836b70e4109113f41bad4fddf49e3aaa (patch)
tree07a1e72da50be7055f11c614f5a2f46d8a74a46d /documentation/ref-manual/ref-development-environment.xml
parentf3e80da1a7fab5a3bca0425ab868690804669fe9 (diff)
downloadpoky-d369f333836b70e4109113f41bad4fddf49e3aaa.tar.gz
dev-manual, ref-manual: Moved recipe syntax section to ref-manual
The section on recipe syntax that was buried in the creating a new recipe section was really a reference on syntax. I have moved it to the ref-manual. (From yocto-docs rev: cb55d1b5832cca6faa6e2a5b26f3add3032cade2) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-development-environment.xml')
-rw-r--r--documentation/ref-manual/ref-development-environment.xml307
1 files changed, 303 insertions, 4 deletions
diff --git a/documentation/ref-manual/ref-development-environment.xml b/documentation/ref-manual/ref-development-environment.xml
index d0b1f0f1d3..36de2d0a72 100644
--- a/documentation/ref-manual/ref-development-environment.xml
+++ b/documentation/ref-manual/ref-development-environment.xml
@@ -13,10 +13,12 @@
13 help you understand how work is accomplished in an open source environment, 13 help you understand how work is accomplished in an open source environment,
14 which is very different as compared to work accomplished in a closed, 14 which is very different as compared to work accomplished in a closed,
15 proprietary environment. 15 proprietary environment.
16 This chapter specifically addresses open source philosophy, using the 16</para>
17 Yocto Project in a team environment, source repositories, Yocto Project 17
18 terms, licensing, the open source distributed version control system Git, 18<para>
19 workflows, bug tracking, and how to submit changes. 19 Specifically, this chapter addresses open source philosophy, workflows,
20 Git, source repositories, licensing, recipe syntax, and development
21 syntax.
20</para> 22</para>
21 23
22<section id='open-source-philosophy'> 24<section id='open-source-philosophy'>
@@ -819,6 +821,303 @@
819 </para> 821 </para>
820</section> 822</section>
821 823
824<section id='recipe-syntax'>
825 <title>Recipe Syntax</title>
826
827 <para>
828 Understanding recipe file syntax is important for
829 writing recipes.
830 The following list overviews the basic items that make up a
831 BitBake recipe file.
832 For more complete BitBake syntax descriptions, see the
833 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
834 chapter of the BitBake User Manual.
835 <itemizedlist>
836 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
837 Variable assignments allow a value to be assigned to a
838 variable.
839 The assignment can be static text or might include
840 the contents of other variables.
841 In addition to the assignment, appending and prepending
842 operations are also supported.</para>
843 <para>The following example shows some of the ways
844 you can use variables in recipes:
845 <literallayout class='monospaced'>
846 S = "${WORKDIR}/postfix-${PV}"
847 CFLAGS += "-DNO_ASM"
848 SRC_URI_append = " file://fixup.patch"
849 </literallayout>
850 </para></listitem>
851 <listitem><para><emphasis>Functions:</emphasis>
852 Functions provide a series of actions to be performed.
853 You usually use functions to override the default
854 implementation of a task function or to complement
855 a default function (i.e. append or prepend to an
856 existing function).
857 Standard functions use <filename>sh</filename> shell
858 syntax, although access to OpenEmbedded variables and
859 internal methods are also available.</para>
860 <para>The following is an example function from the
861 <filename>sed</filename> recipe:
862 <literallayout class='monospaced'>
863 do_install () {
864 autotools_do_install
865 install -d ${D}${base_bindir}
866 mv ${D}${bindir}/sed ${D}${base_bindir}/sed
867 rmdir ${D}${bindir}/
868 }
869 </literallayout>
870 It is also possible to implement new functions that
871 are called between existing tasks as long as the
872 new functions are not replacing or complementing the
873 default functions.
874 You can implement functions in Python
875 instead of shell.
876 Both of these options are not seen in the majority of
877 recipes.</para></listitem>
878 <listitem><para><emphasis>Keywords:</emphasis>
879 BitBake recipes use only a few keywords.
880 You use keywords to include common
881 functions (<filename>inherit</filename>), load parts
882 of a recipe from other files
883 (<filename>include</filename> and
884 <filename>require</filename>) and export variables
885 to the environment (<filename>export</filename>).</para>
886 <para>The following example shows the use of some of
887 these keywords:
888 <literallayout class='monospaced'>
889 export POSTCONF = "${STAGING_BINDIR}/postconf"
890 inherit autoconf
891 require otherfile.inc
892 </literallayout>
893 </para></listitem>
894 <listitem><para><emphasis>Comments:</emphasis>
895 Any lines that begin with the hash character
896 (<filename>#</filename>) are treated as comment lines
897 and are ignored:
898 <literallayout class='monospaced'>
899 # This is a comment
900 </literallayout>
901 </para></listitem>
902 </itemizedlist>
903 </para>
904
905 <para>
906 This next list summarizes the most important and most commonly
907 used parts of the recipe syntax.
908 For more information on these parts of the syntax, you can
909 reference the
910 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
911 chapter in the BitBake User Manual.
912 <itemizedlist>
913 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
914 Use the backward slash (<filename>\</filename>)
915 character to split a statement over multiple lines.
916 Place the slash character at the end of the line that
917 is to be continued on the next line:
918 <literallayout class='monospaced'>
919 VAR = "A really long \
920 line"
921 </literallayout>
922 <note>
923 You cannot have any characters including spaces
924 or tabs after the slash character.
925 </note>
926 </para></listitem>
927 <listitem><para>
928 <emphasis>Using Variables: <filename>${...}</filename></emphasis> -
929 Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to
930 access the contents of a variable:
931 <literallayout class='monospaced'>
932 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
933 </literallayout>
934 <note>
935 It is important to understand that the value of a
936 variable expressed in this form does not get
937 substituted automatically.
938 The expansion of these expressions happens
939 on-demand later (e.g. usually when a function that
940 makes reference to the variable executes).
941 This behavior ensures that the values are most
942 appropriate for the context in which they are
943 finally used.
944 On the rare occasion that you do need the variable
945 expression to be expanded immediately, you can use
946 the <filename>:=</filename> operator instead of
947 <filename>=</filename> when you make the
948 assignment, but this is not generally needed.
949 </note>
950 </para></listitem>
951 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
952 Use double quotes around the value in all variable
953 assignments.
954 <literallayout class='monospaced'>
955 VAR1 = "${OTHERVAR}"
956 VAR2 = "The version is ${PV}"
957 </literallayout>
958 </para></listitem>
959 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
960 Conditional assignment is used to assign a value to
961 a variable, but only when the variable is currently
962 unset.
963 Use the question mark followed by the equal sign
964 (<filename>?=</filename>) to make a "soft" assignment
965 used for conditional assignment.
966 Typically, "soft" assignments are used in the
967 <filename>local.conf</filename> file for variables
968 that are allowed to come through from the external
969 environment.
970 </para>
971 <para>Here is an example where
972 <filename>VAR1</filename> is set to "New value" if
973 it is currently empty.
974 However, if <filename>VAR1</filename> has already been
975 set, it remains unchanged:
976 <literallayout class='monospaced'>
977 VAR1 ?= "New value"
978 </literallayout>
979 In this next example, <filename>VAR1</filename>
980 is left with the value "Original value":
981 <literallayout class='monospaced'>
982 VAR1 = "Original value"
983 VAR1 ?= "New value"
984 </literallayout>
985 </para></listitem>
986 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
987 Use the plus character followed by the equals sign
988 (<filename>+=</filename>) to append values to existing
989 variables.
990 <note>
991 This operator adds a space between the existing
992 content of the variable and the new content.
993 </note></para>
994 <para>Here is an example:
995 <literallayout class='monospaced'>
996 SRC_URI += "file://fix-makefile.patch"
997 </literallayout>
998 </para></listitem>
999 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1000 Use the equals sign followed by the plus character
1001 (<filename>=+</filename>) to prepend values to existing
1002 variables.
1003 <note>
1004 This operator adds a space between the new content
1005 and the existing content of the variable.
1006 </note></para>
1007 <para>Here is an example:
1008 <literallayout class='monospaced'>
1009 VAR =+ "Starts"
1010 </literallayout>
1011 </para></listitem>
1012 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1013 Use the <filename>_append</filename> operator to
1014 append values to existing variables.
1015 This operator does not add any additional space.
1016 Also, the operator is applied after all the
1017 <filename>+=</filename>, and
1018 <filename>=+</filename> operators have been applied and
1019 after all <filename>=</filename> assignments have
1020 occurred.
1021 </para>
1022 <para>The following example shows the space being
1023 explicitly added to the start to ensure the appended
1024 value is not merged with the existing value:
1025 <literallayout class='monospaced'>
1026 SRC_URI_append = " file://fix-makefile.patch"
1027 </literallayout>
1028 You can also use the <filename>_append</filename>
1029 operator with overrides, which results in the actions
1030 only being performed for the specified target or
1031 machine:
1032 <literallayout class='monospaced'>
1033 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1034 </literallayout>
1035 </para></listitem>
1036 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1037 Use the <filename>_prepend</filename> operator to
1038 prepend values to existing variables.
1039 This operator does not add any additional space.
1040 Also, the operator is applied after all the
1041 <filename>+=</filename>, and
1042 <filename>=+</filename> operators have been applied and
1043 after all <filename>=</filename> assignments have
1044 occurred.
1045 </para>
1046 <para>The following example shows the space being
1047 explicitly added to the end to ensure the prepended
1048 value is not merged with the existing value:
1049 <literallayout class='monospaced'>
1050 CFLAGS_prepend = "-I${S}/myincludes "
1051 </literallayout>
1052 You can also use the <filename>_prepend</filename>
1053 operator with overrides, which results in the actions
1054 only being performed for the specified target or
1055 machine:
1056 <literallayout class='monospaced'>
1057 CFLAGS_prepend_sh4 = "-I${S}/myincludes "
1058 </literallayout>
1059 </para></listitem>
1060 <listitem><para><emphasis>Overrides:</emphasis> -
1061 You can use overrides to set a value conditionally,
1062 typically based on how the recipe is being built.
1063 For example, to set the
1064 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
1065 variable's value to "standard/base" for any target
1066 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
1067 except for qemuarm where it should be set to
1068 "standard/arm-versatile-926ejs", you would do the
1069 following:
1070 <literallayout class='monospaced'>
1071 KBRANCH = "standard/base"
1072 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1073 </literallayout>
1074 Overrides are also used to separate alternate values
1075 of a variable in other situations.
1076 For example, when setting variables such as
1077 <link linkend='var-FILES'><filename>FILES</filename></link>
1078 and
1079 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1080 that are specific to individual packages produced by
1081 a recipe, you should always use an override that
1082 specifies the name of the package.
1083 </para></listitem>
1084 <listitem><para><emphasis>Indentation:</emphasis>
1085 Use spaces for indentation rather than than tabs.
1086 For shell functions, both currently work.
1087 However, it is a policy decision of the Yocto Project
1088 to use tabs in shell functions.
1089 Realize that some layers have a policy to use spaces
1090 for all indentation.
1091 </para></listitem>
1092 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
1093 For more advanced processing, it is possible to use
1094 Python code during variable assignments (e.g.
1095 search and replacement on a variable).</para>
1096 <para>You indicate Python code using the
1097 <filename>${@<replaceable>python_code</replaceable>}</filename>
1098 syntax for the variable assignment:
1099 <literallayout class='monospaced'>
1100 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1101 </literallayout>
1102 </para></listitem>
1103 <listitem><para><emphasis>Shell Function Syntax:</emphasis>
1104 Write shell functions as if you were writing a shell
1105 script when you describe a list of actions to take.
1106 You should ensure that your script works with a generic
1107 <filename>sh</filename> and that it does not require
1108 any <filename>bash</filename> or other shell-specific
1109 functionality.
1110 The same considerations apply to various system
1111 utilities (e.g. <filename>sed</filename>,
1112 <filename>grep</filename>, <filename>awk</filename>,
1113 and so forth) that you might wish to use.
1114 If in doubt, you should check with multiple
1115 implementations - including those from BusyBox.
1116 </para></listitem>
1117 </itemizedlist>
1118 </para>
1119</section>
1120
822<section id="development-concepts"> 1121<section id="development-concepts">
823 <title>Development Concepts</title> 1122 <title>Development Concepts</title>
824 1123