diff options
Diffstat (limited to 'bitbake/doc/user-manual/user-manual-metadata.xml')
-rw-r--r-- | bitbake/doc/user-manual/user-manual-metadata.xml | 333 |
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 | ||