summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml260
1 files changed, 164 insertions, 96 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 9f172d4e65..ab3dcb19e4 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -1040,41 +1040,36 @@
1040 <title>Parsing Overview</title> 1040 <title>Parsing Overview</title>
1041 1041
1042 <para> 1042 <para>
1043 BitBake parses configuration files, classes, and 1043 BitBake parses configuration files, classes, recipes, and append
1044 <filename>.bb</filename> files. 1044 files.
1045 </para> 1045 </para>
1046 1046
1047 <para> 1047 <para>
1048 The first thing BitBake does is look for the 1048 The first thing BitBake does is look for the
1049 <filename>bitbake.conf</filename> file. 1049 <filename>bitbake.conf</filename> file.
1050 This file resides in the within the <filename>conf/</filename> 1050 This file resides in the <filename>conf</filename>
1051 directory. 1051 directory, which must be listed in
1052 BitBake finds it by examining its <filename>BBPATH</filename> 1052 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
1053 environment variable and looking for the
1054 <filename>conf/</filename> directory.
1055 </para> 1053 </para>
1056 1054
1057 <para> 1055 <para>
1058 The <filename>bitbake.conf</filename> file lists other configuration 1056 The <filename>bitbake.conf</filename> file lists other configuration
1059 files to include from a <filename>conf/</filename> directory below the 1057 files to include from the <filename>conf</filename> directory below the
1060 directories listed in <filename>BBPATH</filename>. 1058 directories listed in <filename>BBPATH</filename>.
1061 In general, the most important configuration file from a user's perspective 1059 In general, the most important of these
1062 is <filename>local.conf</filename>, which contains a user's 1060 configuration files from a user's perspective
1061 is <filename>local.conf</filename>, which contains the user's
1063 customized settings for the build environment. 1062 customized settings for the build environment.
1063 </para>
1064
1065 <para>
1064 Other notable configuration files are the distribution configuration 1066 Other notable configuration files are the distribution configuration
1065 file (set by the <filename>DISTRO</filename> variable) and the machine 1067 file and the machine configuration file.
1066 configuration file (set by the <filename>MACHINE</filename> variable). 1068 These configuration files are normally identified by
1067 The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake 1069 variables unique to the build systems using BitBake.
1068 environment variables are both usually set in the 1070 For example, the Yocto Project uses the
1069 <filename>local.conf file</filename>. 1071 <filename>DISTRO</filename> and <filename>MACHINE</filename>
1070 Valid distribution configuration files are available 1072 variables, respectively.
1071 in the <filename>conf/distro/</filename> directory and valid machine
1072 configuration files in the <filename>meta/conf/machine/</filename>
1073 directory.
1074 Within the <filename>conf/machine/include/</filename> directory are
1075 various <filename>tune-*.inc</filename> configuration files
1076 that provide common "tuning" settings specific to and shared between
1077 particular architectures and machines.
1078 </para> 1073 </para>
1079 1074
1080 <para> 1075 <para>
@@ -1083,8 +1078,9 @@
1083 The <filename>base.bbclass</filename> file 1078 The <filename>base.bbclass</filename> file
1084 is always included. 1079 is always included.
1085 Other classes that are specified in the configuration using the 1080 Other classes that are specified in the configuration using the
1086 <filename>INHERIT</filename> variable are also included. 1081 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
1087 Class files are searched for in a classes subdirectory under 1082 variable are also included.
1083 BitBake searches for class files in a "classes" subdirectory under
1088 the paths in <filename>BBPATH</filename> in the same way as 1084 the paths in <filename>BBPATH</filename> in the same way as
1089 configuration files. 1085 configuration files.
1090 </para> 1086 </para>
@@ -1093,29 +1089,28 @@
1093 After classes are included, the variable 1089 After classes are included, the variable
1094 <filename>BBFILES</filename> is set, usually in 1090 <filename>BBFILES</filename> is set, usually in
1095 <filename>local.conf</filename>, and defines the list of 1091 <filename>local.conf</filename>, and defines the list of
1096 places to search for <filename>.bb</filename> files. 1092 places to search for recipe and append files.
1097 Adding extra content to <filename>BBFILES</filename> is best 1093 Adding extra content to <filename>BBFILES</filename> is best
1098 achieved through the use of BitBake layers as described in the 1094 achieved through the use of BitBake layers.
1099 Layers section below.
1100 </para> 1095 </para>
1101 1096
1102 <para> 1097 <para>
1103 BitBake parses each <filename>.bb</filename> file in 1098 BitBake parses each recipe and append file located with
1104 <filename>BBFILES</filename> and stores the values of various 1099 <filename>BBFILES</filename> and stores the values of various
1105 variables. 1100 variables into the datastore.
1106 In summary, for each <filename>.bb</filename> file the configuration 1101 In summary, for each recipe and append file pairing, the configuration
1107 plus the base class of variables are set, followed by the data in the 1102 plus the base class of variables are set, followed by the data in the
1108 <filename>.bb</filename> file itself, followed by any inherit commands 1103 recipe file itself, followed by any inherit commands
1109 that <filename>.bb</filename> file might contain. 1104 that the recipe file might contain.
1110 </para> 1105 </para>
1111 1106
1112 <para> 1107 <para>
1113 Because parsing <filename>.bb</filename> files is a time consuming 1108 Because parsing recipe and append files is a time consuming
1114 process, a cache is kept to speed up subsequent parsing. 1109 process, a cache, referred to as the "setscene"
1115 This cache is invalid if the timestamp of the 1110 is kept to speed up subsequent parsing.
1116 <filename>.bb</filename> file itself changes, or if the timestamps of 1111 The setscene is invalid if the timestamps of a recipe changes,
1117 any of the include, configuration files or class files on which 1112 any of the include files change, configuration files change,
1118 the <filename>.bb</filename> file depends change. 1113 or class files on which the recipe file depends change.
1119 </para> 1114 </para>
1120 </section> 1115 </section>
1121 1116
@@ -1126,12 +1121,12 @@
1126 Prior to parsing configuration files, Bitbake looks 1121 Prior to parsing configuration files, Bitbake looks
1127 at certain variables, including: 1122 at certain variables, including:
1128 <itemizedlist> 1123 <itemizedlist>
1129 <listitem><para><filename>BB-ENV-WHITELIST</filename></para></listitem> 1124 <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
1130 <listitem><para><filename>BB_PRESERVE-ENV</filename></para></listitem> 1125 <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
1131 <listitem><para><filename>BB_ENV_EXTRAWHITE</filename></para></listitem> 1126 <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
1132 <listitem><para><filename>BB_ORIG_ENV</filename></para></listitem> 1127 <listitem><para><link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link></para></listitem>
1133 <listitem><para><filename>PREFERRED_VERSIONS</filename></para></listitem> 1128 <listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem>
1134 <listitem><para><filename>PREFERRED_PROVIDERS</filename></para></listitem> 1129 <listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem>
1135 </itemizedlist> 1130 </itemizedlist>
1136 </para> 1131 </para>
1137 1132
@@ -1144,13 +1139,15 @@
1144 <para> 1139 <para>
1145 BitBake will first search the current working directory for an 1140 BitBake will first search the current working directory for an
1146 optional <filename>conf/bblayers.conf</filename> configuration file. 1141 optional <filename>conf/bblayers.conf</filename> configuration file.
1147 This file is expected to contain a <filename>BBLAYERS</filename> 1142 This file is expected to contain a
1143 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
1148 variable that is a space delimited list of 'layer' directories. 1144 variable that is a space delimited list of 'layer' directories.
1149 For each directory in this list, a <filename>conf/layer.conf</filename> 1145 For each directory in this list, a <filename>conf/layer.conf</filename>
1150 file will be searched for and parsed with the 1146 file will be searched for and parsed with the
1151 <filename>LAYERDIR</filename> variable being set to the directory where 1147 <link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link>
1152 the layer was found. 1148 variable being set to the directory where the layer was found.
1153 The idea is these files will setup <filename>BBPATH</filename> 1149 The idea is these files will setup
1150 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
1154 and other variables correctly for a given build directory automatically 1151 and other variables correctly for a given build directory automatically
1155 for the user. 1152 for the user.
1156 </para> 1153 </para>
@@ -1168,22 +1165,54 @@
1168 in <filename>.conf</filename> files. 1165 in <filename>.conf</filename> files.
1169 The following variables include: 1166 The following variables include:
1170 <itemizedlist> 1167 <itemizedlist>
1171 <listitem><para><filename>BITBAKE_UI</filename></para></listitem> 1168 <listitem><para>
1172 <listitem><para><filename>BBDEBUG</filename></para></listitem> 1169 <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
1173 <listitem><para><filename>MULTI_PROVIDER_WHITELIST</filename></para></listitem> 1170 </para></listitem>
1174 <listitem><para><filename>BB_NUMBER_PARSE_THREADS</filename></para></listitem> 1171 <listitem><para>
1175 <listitem><para><filename>BBPKGS</filename></para></listitem> 1172 <link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link>
1176 <listitem><para><filename>BB_DEFAULT_TASK</filename></para></listitem> 1173 </para></listitem>
1177 <listitem><para><filename>TOPDIR</filename></para></listitem> 1174 <listitem><para>
1178 <listitem><para><filename>BB_VERBOSE_LOGS</filename></para></listitem> 1175 <link linkend='var-MULTI_PROVIDER_WHITELIST'><filename>MULTI_PROVIDER_WHITELIST</filename></link>
1179 <listitem><para><filename>BB_NICE_LEVEL</filename></para></listitem> 1176 </para></listitem>
1180 <listitem><para><filename>BBFILE_COLLECTIONS</filename></para></listitem> 1177 <listitem><para>
1181 <listitem><para><filename>ASSUME_PROVIDED</filename></para></listitem> 1178 <link linkend='var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></link>
1182 <listitem><para><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></para></listitem> 1179 </para></listitem>
1183 <listitem><para><filename>BBINCLUDED</filename></para></listitem> 1180 <listitem><para>
1184 <listitem><para><filename>BBFILE_PRIORITY</filename></para></listitem> 1181 <filename>BBPKGS</filename>
1185 <listitem><para><filename>BUILDNAME</filename></para></listitem> 1182 </para></listitem>
1186 <listitem><para><filename>BBMASK</filename></para></listitem> 1183 <listitem><para>
1184 <link linkend='var-BB_DEFAULT_TASK'><filename>BB_DEFAULT_TASK</filename></link>
1185 </para></listitem>
1186 <listitem><para>
1187 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
1188 </para></listitem>
1189 <listitem><para>
1190 <link linkend='var-BB_VERBOSE_LOGS'><filename>BB_VERBOSE_LOGS</filename></link>
1191 </para></listitem>
1192 <listitem><para>
1193 <link linkend='var-BB_NICE_LEVEL'><filename>BB_NICE_LEVEL</filename></link>
1194 </para></listitem>
1195 <listitem><para>
1196 <link linkend='var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></link>
1197 </para></listitem>
1198 <listitem><para>
1199 <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
1200 </para></listitem>
1201 <listitem><para>
1202 <link linkend='var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></link>
1203 </para></listitem>
1204 <listitem><para>
1205 <link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link>
1206 </para></listitem>
1207 <listitem><para>
1208 <link linkend='var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></link>
1209 </para></listitem>
1210 <listitem><para>
1211 <link linkend='var-BUILDNAME'><filename>BUILDNAME</filename></link>
1212 </para></listitem>
1213 <listitem><para>
1214 <link linkend='var-BBMASK'><filename>BBMASK</filename></link>
1215 </para></listitem>
1187 </itemizedlist> 1216 </itemizedlist>
1188 </para> 1217 </para>
1189 1218
@@ -1193,36 +1222,38 @@
1193 <para> 1222 <para>
1194 Layers allow you to isolate different types of 1223 Layers allow you to isolate different types of
1195 customizations from each other. 1224 customizations from each other.
1196 You might find it tempting to keep everything in one layer 1225 While you might find it tempting to keep everything in one layer
1197 when working on a single project. 1226 when working on a single project, the more modular you organize
1198 However, the more modular you organize your Metadata, the 1227 your metadata, the easier it is to cope with future changes.
1199 easier it is to cope with future changes.
1200 </para> 1228 </para>
1201 1229
1202 <para> 1230 <para>
1203 To illustrate how layers are used to keep things modular, 1231 To illustrate how you can use layers to keep things modular,
1204 consider machine customizations. 1232 consider machine customizations.
1205 These types of customizations typically reside in a special layer, 1233 These types of customizations typically reside in a special layer,
1206 rather than a general layer, called a Board Specific Package (BSP) Layer. 1234 rather than a general layer, called a Board Specific Package (BSP) Layer.
1207 Furthermore, the machine customizations should be isolated from 1235 Furthermore, the machine customizations should be isolated from
1208 recipes and Metadata that support a new GUI environment, for 1236 recipes and metadata that support a new GUI environment, for
1209 example. 1237 example.
1210 This situation gives you a couple of layers: one for the machine 1238 This situation gives you a couple of layers: one for the machine
1211 configurations, and one for the GUI environment. 1239 configurations and one for the GUI environment.
1212 It is important to understand, however, that the BSP layer can still 1240 It is important to understand, however, that the BSP layer can still
1213 make machine-specific additions to recipes within 1241 make machine-specific additions to recipes within
1214 the GUI environment layer without polluting the GUI layer itself 1242 the GUI environment layer without polluting the GUI layer itself
1215 with those machine-specific changes. 1243 with those machine-specific changes.
1216 You can accomplish this through a recipe that is a BitBake append 1244 You can accomplish this through a recipe that is a BitBake append
1217 (<filename>.bbappend</filename>) file, which is described 1245 (<filename>.bbappend</filename>) file.
1218 later in this section.
1219 </para> 1246 </para>
1220 1247
1221 <para> 1248 <para>
1222 There are certain variable specific to layers, including: 1249 There are certain variables specific to layers:
1223 <itemizedlist> 1250 <itemizedlist>
1224 <listitem><para><filename>LAYERDEPENDS</filename></para></listitem> 1251 <listitem><para>
1225 <listitem><para><filename>LAYERVERSION</filename></para></listitem> 1252 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
1253 </para></listitem>
1254 <listitem><para>
1255 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link>
1256 </para></listitem>
1226 </itemizedlist> 1257 </itemizedlist>
1227 </para> 1258 </para>
1228 </section> 1259 </section>
@@ -1231,11 +1262,14 @@
1231 <title>Schedulers</title> 1262 <title>Schedulers</title>
1232 1263
1233 <para> 1264 <para>
1234 There are variables specific to scheduling functionality 1265 Variables specific to scheduling functionality exist:
1235 including:
1236 <itemizedlist> 1266 <itemizedlist>
1237 <listitem><para><filename>BB_SCHEDULER</filename></para></listitem> 1267 <listitem><para>
1238 <listitem><para><filename>BB_SCHEDULERS</filename></para></listitem> 1268 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
1269 </para></listitem>
1270 <listitem><para>
1271 <link linkend='var-BB_SCHEDULERS'><filename>BB_SCHEDULERS</filename></link>
1272 </para></listitem>
1239 </itemizedlist> 1273 </itemizedlist>
1240 </para> 1274 </para>
1241 </section> 1275 </section>
@@ -1245,26 +1279,60 @@
1245 <title>Classes</title> 1279 <title>Classes</title>
1246 1280
1247 <para> 1281 <para>
1248 BitBake classes are our rudimentary inheritance mechanism. 1282 BitBake's rudimentary inheritance mechanism is accomplished using
1249 As briefly mentioned in the metadata introduction, they're 1283 classes.
1250 parsed when an inherit directive is encountered, and they 1284 As briefly mentioned in the metadata introduction, BitBake
1251 are located in the <filename>classes/</filename> directory 1285 parses a class when an inherit directive is encountered, and it
1252 relative to the directories in <filename>BBPATH</filename>. 1286 is located in the <filename>classes</filename> directory
1287 relative to the directories in
1288 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
1289 </para>
1290 </section>
1291
1292 <section id='recipe-bb-files'>
1293 <title>Recipe (<filename>.bb</filename>) Files</title>
1294
1295 <para>
1296 Recipe files, which are files that have the
1297 <filename>.bb</filename> file extension, are logical units of
1298 tasks for execution.
1299 Normally, that logical unit is a package that needs to be
1300 built.
1301 </para>
1302
1303 <para>
1304 BitBake obeys all inter-recipe dependencies.
1305 </para>
1306
1307 <para>
1308 Recipe files must reside in locations found in the
1309 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
1310 variable.
1253 </para> 1311 </para>
1254 </section> 1312 </section>
1255 1313
1256 <section id='bb-files'> 1314 <section id='append-bbappend-files'>
1257 <title><filename>.bb</filename> Files</title> 1315 <title>Append (<filename>.bbappend</filename>) Files</title>
1316
1317 <para>
1318 Append files, which are files that have the
1319 <filename>.bbappend</filename> file extension, add or
1320 extend build information to an existing
1321 <link linkend='recipe-bb-files'>recipe file</link>.
1322 </para>
1323
1324 <para>
1325 BitBake expects every append file to have a corresponding recipe file.
1326 Furthermore, the append file and corresponding recipe file
1327 must use the same root filename.
1328 The filenames can differ only in the file type suffix used
1329 (e.g. <filename>formfactor_0.0.bb</filename> and
1330 <filename>formfactor_0.0.bbappend</filename>).
1331 </para>
1258 1332
1259 <para> 1333 <para>
1260 A BitBake (<filename>.bb</filename>) file is a logical unit 1334 Information in append files overrides the information in the
1261 of tasks to be executed. 1335 similarly-named recipe file.
1262 Normally this is a package to be built.
1263 Inter-<filename>.bb</filename> dependencies are obeyed.
1264 The files themselves are located via the
1265 <filename>BBFILES</filename> variable, which
1266 is set to a space separated list of <filename>.bb</filename>
1267 files, and does handle wildcards.
1268 </para> 1336 </para>
1269 </section> 1337 </section>
1270 </section> 1338 </section>