summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/user-manual/user-manual-metadata.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-02-11 13:45:54 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-03-09 18:59:02 -0700
commitb4b3bf56f60fab51f0c2c66ad34e39208d360d2e (patch)
treef1a10b014b2ad983d8d047d4ca2b743d38fc2d9f /bitbake/doc/user-manual/user-manual-metadata.xml
parent34bcd967969a9e31215c230c4a85fff9f2f3b520 (diff)
downloadpoky-b4b3bf56f60fab51f0c2c66ad34e39208d360d2e.tar.gz
bitbake: user-manual: Added new chapter to cover BB execution.
This commit added need files, cleaned up bogus links, and adjusted the build file, which is user-manual.xml. The new chapter file is "user-manual-execution.xml". The file has base text from the bitbake section from the "Closer Look" chapter of the YP ref-manual. This means that I had to initially include some figures from that book for now. I am not including them as part of this commit though as they will likely get renamed. I made sure that all links were removed that were specific to the YP ref-manual. Another change was in the user-manual.xml file to include the new chapter as part of the build. Another block of text for the new chapter was the "Running a Task" section from the user-manual-metadata.xml file. Consequently, that section was deleted from the "Metafile" chapter. Another block of text for the new chapter was the "Parsing and Execution" section from the user-manual-metadata.xml file. Consequently, that section was deleted from the "Metafile chapter. (Bitbake rev: f3b21d1fb711f9625d2ac92d4f4fe0f269242bd7) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/user-manual/user-manual-metadata.xml')
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml333
1 files changed, 0 insertions, 333 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 796d27b151..8d37f6bee1 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -895,35 +895,6 @@
895 </section> 895 </section>
896 </section> 896 </section>
897 897
898 <section id='running-a-task'>
899 <title>Running a Task</title>
900
901 <para>
902 Tasks can either be a shell task or a Python task.
903 For shell tasks, BitBake writes a shell script to
904 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename>
905 and then executes the script.
906 The generated shell script contains all the exported variables,
907 and the shell functions with all variables expanded.
908 Output from the shell script goes to the file
909 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
910 Looking at the expanded shell functions in the run file and
911 the output in the log files is a useful debugging technique.
912 </para>
913
914 <para>
915 For Python tasks, BitBake executes the task internally and logs
916 information to the controlling terminal.
917 Future versions of BitBake will write the functions to files
918 similar to the way shell tasks are handled.
919 Logging will be handled in a way similar to shell tasks as well.
920 </para>
921
922 <para>
923 Once all the tasks have been completed BitBake exits.
924 </para>
925 </section>
926
927 <section id='variable-flags'> 898 <section id='variable-flags'>
928 <title>Variable Flags</title> 899 <title>Variable Flags</title>
929 900
@@ -1033,310 +1004,6 @@
1033 </para> 1004 </para>
1034 </section> 1005 </section>
1035 1006
1036 <section id='parsing-and-execution'>
1037 <title>Parsing and Execution</title>
1038
1039 <section id='parsing-overview'>
1040 <title>Parsing Overview</title>
1041
1042 <para>
1043 BitBake parses configuration files, classes, recipes, and append
1044 files.
1045 </para>
1046
1047 <para>
1048 The first thing BitBake does is look for the
1049 <filename>bitbake.conf</filename> file.
1050 This file resides in the <filename>conf</filename>
1051 directory, which must be listed in
1052 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
1053 </para>
1054
1055 <para>
1056 The <filename>bitbake.conf</filename> file lists other configuration
1057 files to include from the <filename>conf</filename> directory below the
1058 directories listed in <filename>BBPATH</filename>.
1059 In general, the most important of these
1060 configuration files from a user's perspective
1061 is <filename>local.conf</filename>, which contains the user's
1062 customized settings for the build environment.
1063 </para>
1064
1065 <para>
1066 Other notable configuration files are the distribution configuration
1067 file and the machine configuration file.
1068 These configuration files are normally identified by
1069 variables unique to the build systems using BitBake.
1070 For example, the Yocto Project uses the
1071 <filename>DISTRO</filename> and <filename>MACHINE</filename>
1072 variables, respectively.
1073 </para>
1074
1075 <para>
1076 After parsing of the configuration files, some standard classes are
1077 included.
1078 The <filename>base.bbclass</filename> file
1079 is always included.
1080 Other classes that are specified in the configuration using the
1081 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
1082 variable are also included.
1083 BitBake searches for class files in a "classes" subdirectory under
1084 the paths in <filename>BBPATH</filename> in the same way as
1085 configuration files.
1086 </para>
1087
1088 <para>
1089 After classes are included, the variable
1090 <filename>BBFILES</filename> is set, usually in
1091 <filename>local.conf</filename>, and defines the list of
1092 places to search for recipe and append files.
1093 Adding extra content to <filename>BBFILES</filename> is best
1094 achieved through the use of BitBake layers.
1095 </para>
1096
1097 <para>
1098 BitBake parses each recipe and append file located with
1099 <filename>BBFILES</filename> and stores the values of various
1100 variables into the datastore.
1101 In summary, for each recipe and append file pairing, the configuration
1102 plus the base class of variables are set, followed by the data in the
1103 recipe file itself, followed by any inherit commands
1104 that the recipe file might contain.
1105 </para>
1106
1107 <para>
1108 Because parsing recipe and append files is a time consuming
1109 process, a cache, referred to as the "setscene"
1110 is kept to speed up subsequent parsing.
1111 The setscene is invalid if the timestamps of a recipe changes,
1112 any of the include files change, configuration files change,
1113 or class files on which the recipe file depends change.
1114 </para>
1115 </section>
1116
1117 <section id='parsing-configuration-files'>
1118 <title>Configuration files</title>
1119
1120 <para>
1121 Prior to parsing configuration files, Bitbake looks
1122 at certain variables, including:
1123 <itemizedlist>
1124 <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
1125 <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
1126 <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
1127 <listitem><para><link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link></para></listitem>
1128 <listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem>
1129 <listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem>
1130 </itemizedlist>
1131 </para>
1132
1133 <para>
1134 The first kind of metadata in BitBake is configuration metadata.
1135 This metadata is global, and therefore affects all packages and
1136 tasks that are executed.
1137 </para>
1138
1139 <para>
1140 BitBake will first search the current working directory for an
1141 optional <filename>conf/bblayers.conf</filename> configuration file.
1142 This file is expected to contain a
1143 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
1144 variable that is a space delimited list of 'layer' directories.
1145 For each directory in this list, a <filename>conf/layer.conf</filename>
1146 file will be searched for and parsed with the
1147 <link linkend='var-LAYERDIR'><filename>LAYERDIR</filename></link>
1148 variable being set to the directory where the layer was found.
1149 The idea is these files will setup
1150 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
1151 and other variables correctly for a given build directory automatically
1152 for the user.
1153 </para>
1154
1155 <para>
1156 BitBake will then expect to find <filename>conf/bitbake.conf</filename>
1157 file somewhere in the user specified <filename>BBPATH</filename>.
1158 That configuration file generally has include directives to pull
1159 in any other metadata (generally files specific to architecture,
1160 machine, local and so on).
1161 </para>
1162
1163 <para>
1164 Only variable definitions and include directives are allowed
1165 in <filename>.conf</filename> files.
1166 The following variables include:
1167 <itemizedlist>
1168 <listitem><para>
1169 <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
1170 </para></listitem>
1171 <listitem><para>
1172 <link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link>
1173 </para></listitem>
1174 <listitem><para>
1175 <link linkend='var-MULTI_PROVIDER_WHITELIST'><filename>MULTI_PROVIDER_WHITELIST</filename></link>
1176 </para></listitem>
1177 <listitem><para>
1178 <link linkend='var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></link>
1179 </para></listitem>
1180 <listitem><para>
1181 <filename>BBPKGS</filename>
1182 </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>
1216 </itemizedlist>
1217 </para>
1218
1219 <section id='layers'>
1220 <title>Layers</title>
1221
1222 <para>
1223 Layers allow you to isolate different types of
1224 customizations from each other.
1225 While you might find it tempting to keep everything in one layer
1226 when working on a single project, the more modular you organize
1227 your metadata, the easier it is to cope with future changes.
1228 </para>
1229
1230 <para>
1231 To illustrate how you can use layers to keep things modular,
1232 consider machine customizations.
1233 These types of customizations typically reside in a special layer,
1234 rather than a general layer, called a Board Specific Package (BSP) Layer.
1235 Furthermore, the machine customizations should be isolated from
1236 recipes and metadata that support a new GUI environment, for
1237 example.
1238 This situation gives you a couple of layers: one for the machine
1239 configurations and one for the GUI environment.
1240 It is important to understand, however, that the BSP layer can still
1241 make machine-specific additions to recipes within
1242 the GUI environment layer without polluting the GUI layer itself
1243 with those machine-specific changes.
1244 You can accomplish this through a recipe that is a BitBake append
1245 (<filename>.bbappend</filename>) file.
1246 </para>
1247
1248 <para>
1249 There are certain variables specific to layers:
1250 <itemizedlist>
1251 <listitem><para>
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>
1257 </itemizedlist>
1258 </para>
1259 </section>
1260
1261 <section id='schedulers'>
1262 <title>Schedulers</title>
1263
1264 <para>
1265 Variables specific to scheduling functionality exist:
1266 <itemizedlist>
1267 <listitem><para>
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>
1273 </itemizedlist>
1274 </para>
1275 </section>
1276 </section>
1277
1278 <section id='metadata-classes'>
1279 <title>Classes</title>
1280
1281 <para>
1282 BitBake's rudimentary inheritance mechanism is accomplished using
1283 classes.
1284 As briefly mentioned in the metadata introduction, BitBake
1285 parses a class when an inherit directive is encountered, and it
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.
1311 </para>
1312 </section>
1313
1314 <section id='append-bbappend-files'>
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>
1332
1333 <para>
1334 Information in append files overrides the information in the
1335 similarly-named recipe file.
1336 </para>
1337 </section>
1338 </section>
1339
1340 <section id='events'> 1007 <section id='events'>
1341 <title>Events</title> 1008 <title>Events</title>
1342 1009
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-22 05:56:26 +0000