summaryrefslogtreecommitdiffstats
path: root/documentation/getting-started
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/getting-started')
-rw-r--r--documentation/getting-started/getting-started-development-environment.xml299
1 files changed, 1 insertions, 298 deletions
diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml
index 03a807e4a5..096517b729 100644
--- a/documentation/getting-started/getting-started-development-environment.xml
+++ b/documentation/getting-started/getting-started-development-environment.xml
@@ -17,7 +17,7 @@
17 17
18<para> 18<para>
19 Specifically, this chapter addresses open source philosophy, workflows, 19 Specifically, this chapter addresses open source philosophy, workflows,
20 Git, source repositories, licensing, recipe syntax, and development 20 Git, source repositories, licensing, and development
21 syntax. 21 syntax.
22</para> 22</para>
23 23
@@ -938,303 +938,6 @@
938 </para> 938 </para>
939</section> 939</section>
940 940
941<section id='recipe-syntax'>
942 <title>Recipe Syntax</title>
943
944 <para>
945 Understanding recipe file syntax is important for
946 writing recipes.
947 The following list overviews the basic items that make up a
948 BitBake recipe file.
949 For more complete BitBake syntax descriptions, see the
950 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
951 chapter of the BitBake User Manual.
952 <itemizedlist>
953 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
954 Variable assignments allow a value to be assigned to a
955 variable.
956 The assignment can be static text or might include
957 the contents of other variables.
958 In addition to the assignment, appending and prepending
959 operations are also supported.</para>
960 <para>The following example shows some of the ways
961 you can use variables in recipes:
962 <literallayout class='monospaced'>
963 S = "${WORKDIR}/postfix-${PV}"
964 CFLAGS += "-DNO_ASM"
965 SRC_URI_append = " file://fixup.patch"
966 </literallayout>
967 </para></listitem>
968 <listitem><para><emphasis>Functions:</emphasis>
969 Functions provide a series of actions to be performed.
970 You usually use functions to override the default
971 implementation of a task function or to complement
972 a default function (i.e. append or prepend to an
973 existing function).
974 Standard functions use <filename>sh</filename> shell
975 syntax, although access to OpenEmbedded variables and
976 internal methods are also available.</para>
977 <para>The following is an example function from the
978 <filename>sed</filename> recipe:
979 <literallayout class='monospaced'>
980 do_install () {
981 autotools_do_install
982 install -d ${D}${base_bindir}
983 mv ${D}${bindir}/sed ${D}${base_bindir}/sed
984 rmdir ${D}${bindir}/
985 }
986 </literallayout>
987 It is also possible to implement new functions that
988 are called between existing tasks as long as the
989 new functions are not replacing or complementing the
990 default functions.
991 You can implement functions in Python
992 instead of shell.
993 Both of these options are not seen in the majority of
994 recipes.</para></listitem>
995 <listitem><para><emphasis>Keywords:</emphasis>
996 BitBake recipes use only a few keywords.
997 You use keywords to include common
998 functions (<filename>inherit</filename>), load parts
999 of a recipe from other files
1000 (<filename>include</filename> and
1001 <filename>require</filename>) and export variables
1002 to the environment (<filename>export</filename>).</para>
1003 <para>The following example shows the use of some of
1004 these keywords:
1005 <literallayout class='monospaced'>
1006 export POSTCONF = "${STAGING_BINDIR}/postconf"
1007 inherit autoconf
1008 require otherfile.inc
1009 </literallayout>
1010 </para></listitem>
1011 <listitem><para><emphasis>Comments:</emphasis>
1012 Any lines that begin with the hash character
1013 (<filename>#</filename>) are treated as comment lines
1014 and are ignored:
1015 <literallayout class='monospaced'>
1016 # This is a comment
1017 </literallayout>
1018 </para></listitem>
1019 </itemizedlist>
1020 </para>
1021
1022 <para>
1023 This next list summarizes the most important and most commonly
1024 used parts of the recipe syntax.
1025 For more information on these parts of the syntax, you can
1026 reference the
1027 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
1028 chapter in the BitBake User Manual.
1029 <itemizedlist>
1030 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
1031 Use the backward slash (<filename>\</filename>)
1032 character to split a statement over multiple lines.
1033 Place the slash character at the end of the line that
1034 is to be continued on the next line:
1035 <literallayout class='monospaced'>
1036 VAR = "A really long \
1037 line"
1038 </literallayout>
1039 <note>
1040 You cannot have any characters including spaces
1041 or tabs after the slash character.
1042 </note>
1043 </para></listitem>
1044 <listitem><para>
1045 <emphasis>Using Variables: <filename>${...}</filename></emphasis> -
1046 Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to
1047 access the contents of a variable:
1048 <literallayout class='monospaced'>
1049 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1050 </literallayout>
1051 <note>
1052 It is important to understand that the value of a
1053 variable expressed in this form does not get
1054 substituted automatically.
1055 The expansion of these expressions happens
1056 on-demand later (e.g. usually when a function that
1057 makes reference to the variable executes).
1058 This behavior ensures that the values are most
1059 appropriate for the context in which they are
1060 finally used.
1061 On the rare occasion that you do need the variable
1062 expression to be expanded immediately, you can use
1063 the <filename>:=</filename> operator instead of
1064 <filename>=</filename> when you make the
1065 assignment, but this is not generally needed.
1066 </note>
1067 </para></listitem>
1068 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
1069 Use double quotes around the value in all variable
1070 assignments.
1071 <literallayout class='monospaced'>
1072 VAR1 = "${OTHERVAR}"
1073 VAR2 = "The version is ${PV}"
1074 </literallayout>
1075 </para></listitem>
1076 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
1077 Conditional assignment is used to assign a value to
1078 a variable, but only when the variable is currently
1079 unset.
1080 Use the question mark followed by the equal sign
1081 (<filename>?=</filename>) to make a "soft" assignment
1082 used for conditional assignment.
1083 Typically, "soft" assignments are used in the
1084 <filename>local.conf</filename> file for variables
1085 that are allowed to come through from the external
1086 environment.
1087 </para>
1088 <para>Here is an example where
1089 <filename>VAR1</filename> is set to "New value" if
1090 it is currently empty.
1091 However, if <filename>VAR1</filename> has already been
1092 set, it remains unchanged:
1093 <literallayout class='monospaced'>
1094 VAR1 ?= "New value"
1095 </literallayout>
1096 In this next example, <filename>VAR1</filename>
1097 is left with the value "Original value":
1098 <literallayout class='monospaced'>
1099 VAR1 = "Original value"
1100 VAR1 ?= "New value"
1101 </literallayout>
1102 </para></listitem>
1103 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
1104 Use the plus character followed by the equals sign
1105 (<filename>+=</filename>) to append values to existing
1106 variables.
1107 <note>
1108 This operator adds a space between the existing
1109 content of the variable and the new content.
1110 </note></para>
1111 <para>Here is an example:
1112 <literallayout class='monospaced'>
1113 SRC_URI += "file://fix-makefile.patch"
1114 </literallayout>
1115 </para></listitem>
1116 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1117 Use the equals sign followed by the plus character
1118 (<filename>=+</filename>) to prepend values to existing
1119 variables.
1120 <note>
1121 This operator adds a space between the new content
1122 and the existing content of the variable.
1123 </note></para>
1124 <para>Here is an example:
1125 <literallayout class='monospaced'>
1126 VAR =+ "Starts"
1127 </literallayout>
1128 </para></listitem>
1129 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1130 Use the <filename>_append</filename> operator to
1131 append values to existing variables.
1132 This operator does not add any additional space.
1133 Also, the operator is applied after all the
1134 <filename>+=</filename>, and
1135 <filename>=+</filename> operators have been applied and
1136 after all <filename>=</filename> assignments have
1137 occurred.
1138 </para>
1139 <para>The following example shows the space being
1140 explicitly added to the start to ensure the appended
1141 value is not merged with the existing value:
1142 <literallayout class='monospaced'>
1143 SRC_URI_append = " file://fix-makefile.patch"
1144 </literallayout>
1145 You can also use the <filename>_append</filename>
1146 operator with overrides, which results in the actions
1147 only being performed for the specified target or
1148 machine:
1149 <literallayout class='monospaced'>
1150 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1151 </literallayout>
1152 </para></listitem>
1153 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1154 Use the <filename>_prepend</filename> operator to
1155 prepend values to existing variables.
1156 This operator does not add any additional space.
1157 Also, the operator is applied after all the
1158 <filename>+=</filename>, and
1159 <filename>=+</filename> operators have been applied and
1160 after all <filename>=</filename> assignments have
1161 occurred.
1162 </para>
1163 <para>The following example shows the space being
1164 explicitly added to the end to ensure the prepended
1165 value is not merged with the existing value:
1166 <literallayout class='monospaced'>
1167 CFLAGS_prepend = "-I${S}/myincludes "
1168 </literallayout>
1169 You can also use the <filename>_prepend</filename>
1170 operator with overrides, which results in the actions
1171 only being performed for the specified target or
1172 machine:
1173 <literallayout class='monospaced'>
1174 CFLAGS_prepend_sh4 = "-I${S}/myincludes "
1175 </literallayout>
1176 </para></listitem>
1177 <listitem><para><emphasis>Overrides:</emphasis> -
1178 You can use overrides to set a value conditionally,
1179 typically based on how the recipe is being built.
1180 For example, to set the
1181 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
1182 variable's value to "standard/base" for any target
1183 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
1184 except for qemuarm where it should be set to
1185 "standard/arm-versatile-926ejs", you would do the
1186 following:
1187 <literallayout class='monospaced'>
1188 KBRANCH = "standard/base"
1189 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1190 </literallayout>
1191 Overrides are also used to separate alternate values
1192 of a variable in other situations.
1193 For example, when setting variables such as
1194 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1195 and
1196 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
1197 that are specific to individual packages produced by
1198 a recipe, you should always use an override that
1199 specifies the name of the package.
1200 </para></listitem>
1201 <listitem><para><emphasis>Indentation:</emphasis>
1202 Use spaces for indentation rather than than tabs.
1203 For shell functions, both currently work.
1204 However, it is a policy decision of the Yocto Project
1205 to use tabs in shell functions.
1206 Realize that some layers have a policy to use spaces
1207 for all indentation.
1208 </para></listitem>
1209 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
1210 For more advanced processing, it is possible to use
1211 Python code during variable assignments (e.g.
1212 search and replacement on a variable).</para>
1213 <para>You indicate Python code using the
1214 <filename>${@<replaceable>python_code</replaceable>}</filename>
1215 syntax for the variable assignment:
1216 <literallayout class='monospaced'>
1217 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1218 </literallayout>
1219 </para></listitem>
1220 <listitem><para><emphasis>Shell Function Syntax:</emphasis>
1221 Write shell functions as if you were writing a shell
1222 script when you describe a list of actions to take.
1223 You should ensure that your script works with a generic
1224 <filename>sh</filename> and that it does not require
1225 any <filename>bash</filename> or other shell-specific
1226 functionality.
1227 The same considerations apply to various system
1228 utilities (e.g. <filename>sed</filename>,
1229 <filename>grep</filename>, <filename>awk</filename>,
1230 and so forth) that you might wish to use.
1231 If in doubt, you should check with multiple
1232 implementations - including those from BusyBox.
1233 </para></listitem>
1234 </itemizedlist>
1235 </para>
1236</section>
1237
1238<section id="development-concepts"> 941<section id="development-concepts">
1239 <title>Development Concepts</title> 942 <title>Development Concepts</title>
1240 943
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 17:34:31 +0000