summaryrefslogtreecommitdiffstats
path: root/documentation/getting-started/getting-started-development-environment.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-02-02 10:11:58 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:31 +0000
commit813772451fe9045e78b94015950aa26380e46440 (patch)
tree9e2a888df23e4e2bb494c7cd65c87b159aa036f1 /documentation/getting-started/getting-started-development-environment.xml
parentb509d336c757300b1fc9312f755b3bfd8707bf79 (diff)
downloadpoky-813772451fe9045e78b94015950aa26380e46440.tar.gz
documentation: Moved the detailed build section to concepts-manual.
The section that provides a closer look into the build system has moved from the getting-started manaul to the concepts-manual. I fixed all the links, provided some coded formatting of the entire section, and made general updates. The other manuals had links that needed fixed due to the move. (From yocto-docs rev: b83a5619f56ebd9879fdcadcf474859e68b26d58) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/getting-started/getting-started-development-environment.xml')
-rw-r--r--documentation/getting-started/getting-started-development-environment.xml1650
1 files changed, 0 insertions, 1650 deletions
diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml
index 096517b729..5d6491c51b 100644
--- a/documentation/getting-started/getting-started-development-environment.xml
+++ b/documentation/getting-started/getting-started-development-environment.xml
@@ -937,1656 +937,6 @@
937 section in the Yocto Project Development Tasks Manual. 937 section in the Yocto Project Development Tasks Manual.
938 </para> 938 </para>
939</section> 939</section>
940
941<section id="development-concepts">
942 <title>Development Concepts</title>
943
944 <para>
945 This section takes a more detailed look inside the development
946 process.
947 The following diagram represents development at a high level.
948 The remainder of this chapter expands on the fundamental input, output,
949 process, and
950 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>) blocks
951 that make up development in the Yocto Project environment.
952 </para>
953
954 <para id='general-yocto-environment-figure'>
955 <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
956 </para>
957
958 <para>
959 In general, development consists of several functional areas:
960 <itemizedlist>
961 <listitem><para><emphasis>User Configuration:</emphasis>
962 Metadata you can use to control the build process.
963 </para></listitem>
964 <listitem><para><emphasis>Metadata Layers:</emphasis>
965 Various layers that provide software, machine, and
966 distro Metadata.</para></listitem>
967 <listitem><para><emphasis>Source Files:</emphasis>
968 Upstream releases, local projects, and SCMs.</para></listitem>
969 <listitem><para><emphasis>Build System:</emphasis>
970 Processes under the control of
971 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
972 This block expands on how BitBake fetches source, applies
973 patches, completes compilation, analyzes output for package
974 generation, creates and tests packages, generates images, and
975 generates cross-development tools.</para></listitem>
976 <listitem><para><emphasis>Package Feeds:</emphasis>
977 Directories containing output packages (RPM, DEB or IPK),
978 which are subsequently used in the construction of an image or
979 SDK, produced by the build system.
980 These feeds can also be copied and shared using a web server or
981 other means to facilitate extending or updating existing
982 images on devices at runtime if runtime package management is
983 enabled.</para></listitem>
984 <listitem><para><emphasis>Images:</emphasis>
985 Images produced by the development process.
986 </para></listitem>
987 <listitem><para><emphasis>Application Development SDK:</emphasis>
988 Cross-development tools that are produced along with an image
989 or separately with BitBake.</para></listitem>
990 </itemizedlist>
991 </para>
992
993 <section id="user-configuration">
994 <title>User Configuration</title>
995
996 <para>
997 User configuration helps define the build.
998 Through user configuration, you can tell BitBake the
999 target architecture for which you are building the image,
1000 where to store downloaded source, and other build properties.
1001 </para>
1002
1003 <para>
1004 The following figure shows an expanded representation of the
1005 "User Configuration" box of the
1006 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
1007 </para>
1008
1009 <para>
1010 <imagedata fileref="figures/user-configuration.png" align="center" width="8in" depth="4.5in" />
1011 </para>
1012
1013 <para>
1014 BitBake needs some basic configuration files in order to complete
1015 a build.
1016 These files are <filename>*.conf</filename> files.
1017 The minimally necessary ones reside as example files in the
1018 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1019 For simplicity, this section refers to the Source Directory as
1020 the "Poky Directory."
1021 </para>
1022
1023 <para>
1024 When you clone the <filename>poky</filename> Git repository or you
1025 download and unpack a Yocto Project release, you can set up the
1026 Source Directory to be named anything you want.
1027 For this discussion, the cloned repository uses the default
1028 name <filename>poky</filename>.
1029 <note>
1030 The Poky repository is primarily an aggregation of existing
1031 repositories.
1032 It is not a canonical upstream source.
1033 </note>
1034 </para>
1035
1036 <para>
1037 The <filename>meta-poky</filename> layer inside Poky contains
1038 a <filename>conf</filename> directory that has example
1039 configuration files.
1040 These example files are used as a basis for creating actual
1041 configuration files when you source the build environment
1042 script
1043 (i.e.
1044 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
1045 </para>
1046
1047 <para>
1048 Sourcing the build environment script creates a
1049 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
1050 if one does not already exist.
1051 BitBake uses the Build Directory for all its work during builds.
1052 The Build Directory has a <filename>conf</filename> directory that
1053 contains default versions of your <filename>local.conf</filename>
1054 and <filename>bblayers.conf</filename> configuration files.
1055 These default configuration files are created only if versions
1056 do not already exist in the Build Directory at the time you
1057 source the build environment setup script.
1058 </para>
1059
1060 <para>
1061 Because the Poky repository is fundamentally an aggregation of
1062 existing repositories, some users might be familiar with running
1063 the <filename>&OE_INIT_FILE;</filename> script in the context
1064 of separate OpenEmbedded-Core and BitBake repositories rather than a
1065 single Poky repository.
1066 This discussion assumes the script is executed from within a cloned
1067 or unpacked version of Poky.
1068 </para>
1069
1070 <para>
1071 Depending on where the script is sourced, different sub-scripts
1072 are called to set up the Build Directory (Yocto or OpenEmbedded).
1073 Specifically, the script
1074 <filename>scripts/oe-setup-builddir</filename> inside the
1075 poky directory sets up the Build Directory and seeds the directory
1076 (if necessary) with configuration files appropriate for the
1077 Yocto Project development environment.
1078 <note>
1079 The <filename>scripts/oe-setup-builddir</filename> script
1080 uses the <filename>$TEMPLATECONF</filename> variable to
1081 determine which sample configuration files to locate.
1082 </note>
1083 </para>
1084
1085 <para>
1086 The <filename>local.conf</filename> file provides many
1087 basic variables that define a build environment.
1088 Here is a list of a few.
1089 To see the default configurations in a <filename>local.conf</filename>
1090 file created by the build environment script, see the
1091 <filename>local.conf.sample</filename> in the
1092 <filename>meta-poky</filename> layer:
1093 <itemizedlist>
1094 <listitem><para><emphasis>Parallelism Options:</emphasis>
1095 Controlled by the
1096 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
1097 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
1098 and
1099 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
1100 variables.</para></listitem>
1101 <listitem><para><emphasis>Target Machine Selection:</emphasis>
1102 Controlled by the
1103 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
1104 variable.</para></listitem>
1105 <listitem><para><emphasis>Download Directory:</emphasis>
1106 Controlled by the
1107 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1108 variable.</para></listitem>
1109 <listitem><para><emphasis>Shared State Directory:</emphasis>
1110 Controlled by the
1111 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
1112 variable.</para></listitem>
1113 <listitem><para><emphasis>Build Output:</emphasis>
1114 Controlled by the
1115 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
1116 variable.</para></listitem>
1117 </itemizedlist>
1118 <note>
1119 Configurations set in the <filename>conf/local.conf</filename>
1120 file can also be set in the
1121 <filename>conf/site.conf</filename> and
1122 <filename>conf/auto.conf</filename> configuration files.
1123 </note>
1124 </para>
1125
1126 <para>
1127 The <filename>bblayers.conf</filename> file tells BitBake what
1128 layers you want considered during the build.
1129 By default, the layers listed in this file include layers
1130 minimally needed by the build system.
1131 However, you must manually add any custom layers you have created.
1132 You can find more information on working with the
1133 <filename>bblayers.conf</filename> file in the
1134 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1135 section in the Yocto Project Development Tasks Manual.
1136 </para>
1137
1138 <para>
1139 The files <filename>site.conf</filename> and
1140 <filename>auto.conf</filename> are not created by the environment
1141 initialization script.
1142 If you want the <filename>site.conf</filename> file, you need to
1143 create that yourself.
1144 The <filename>auto.conf</filename> file is typically created by
1145 an autobuilder:
1146 <itemizedlist>
1147 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
1148 You can use the <filename>conf/site.conf</filename>
1149 configuration file to configure multiple build directories.
1150 For example, suppose you had several build environments and
1151 they shared some common features.
1152 You can set these default build properties here.
1153 A good example is perhaps the packaging format to use
1154 through the
1155 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
1156 variable.</para>
1157 <para>One useful scenario for using the
1158 <filename>conf/site.conf</filename> file is to extend your
1159 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
1160 variable to include the path to a
1161 <filename>conf/site.conf</filename>.
1162 Then, when BitBake looks for Metadata using
1163 <filename>BBPATH</filename>, it finds the
1164 <filename>conf/site.conf</filename> file and applies your
1165 common configurations found in the file.
1166 To override configurations in a particular build directory,
1167 alter the similar configurations within that build
1168 directory's <filename>conf/local.conf</filename> file.
1169 </para></listitem>
1170 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
1171 The file is usually created and written to by
1172 an autobuilder.
1173 The settings put into the file are typically the same as
1174 you would find in the <filename>conf/local.conf</filename>
1175 or the <filename>conf/site.conf</filename> files.
1176 </para></listitem>
1177 </itemizedlist>
1178 </para>
1179
1180 <para>
1181 You can edit all configuration files to further define
1182 any particular build environment.
1183 This process is represented by the "User Configuration Edits"
1184 box in the figure.
1185 </para>
1186
1187 <para>
1188 When you launch your build with the
1189 <filename>bitbake <replaceable>target</replaceable></filename>
1190 command, BitBake sorts out the configurations to ultimately
1191 define your build environment.
1192 It is important to understand that the OpenEmbedded build system
1193 reads the configuration files in a specific order:
1194 <filename>site.conf</filename>, <filename>auto.conf</filename>,
1195 and <filename>local.conf</filename>.
1196 And, the build system applies the normal assignment statement
1197 rules.
1198 Because the files are parsed in a specific order, variable
1199 assignments for the same variable could be affected.
1200 For example, if the <filename>auto.conf</filename> file and
1201 the <filename>local.conf</filename> set
1202 <replaceable>variable1</replaceable> to different values, because
1203 the build system parses <filename>local.conf</filename> after
1204 <filename>auto.conf</filename>,
1205 <replaceable>variable1</replaceable> is assigned the value from
1206 the <filename>local.conf</filename> file.
1207 </para>
1208 </section>
1209
1210 <section id="metadata-machine-configuration-and-policy-configuration">
1211 <title>Metadata, Machine Configuration, and Policy Configuration</title>
1212
1213 <para>
1214 The previous section described the user configurations that
1215 define BitBake's global behavior.
1216 This section takes a closer look at the layers the build system
1217 uses to further control the build.
1218 These layers provide Metadata for the software, machine, and
1219 policy.
1220 </para>
1221
1222 <para>
1223 In general, three types of layer input exist:
1224 <itemizedlist>
1225 <listitem><para><emphasis>Policy Configuration:</emphasis>
1226 Distribution Layers provide top-level or general
1227 policies for the image or SDK being built.
1228 For example, this layer would dictate whether BitBake
1229 produces RPM or IPK packages.</para></listitem>
1230 <listitem><para><emphasis>Machine Configuration:</emphasis>
1231 Board Support Package (BSP) layers provide machine
1232 configurations.
1233 This type of information is specific to a particular
1234 target architecture.</para></listitem>
1235 <listitem><para><emphasis>Metadata:</emphasis>
1236 Software layers contain user-supplied recipe files,
1237 patches, and append files.
1238 </para></listitem>
1239 </itemizedlist>
1240 </para>
1241
1242 <para>
1243 The following figure shows an expanded representation of the
1244 Metadata, Machine Configuration, and Policy Configuration input
1245 (layers) boxes of the
1246 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
1247 </para>
1248
1249 <para>
1250 <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
1251 </para>
1252
1253 <para>
1254 In general, all layers have a similar structure.
1255 They all contain a licensing file
1256 (e.g. <filename>COPYING</filename>) if the layer is to be
1257 distributed, a <filename>README</filename> file as good practice
1258 and especially if the layer is to be distributed, a
1259 configuration directory, and recipe directories.
1260 </para>
1261
1262 <para>
1263 The Yocto Project has many layers that can be used.
1264 You can see a web-interface listing of them on the
1265 <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
1266 page.
1267 The layers are shown at the bottom categorized under
1268 "Yocto Metadata Layers."
1269 These layers are fundamentally a subset of the
1270 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
1271 which lists all layers provided by the OpenEmbedded community.
1272 <note>
1273 Layers exist in the Yocto Project Source Repositories that
1274 cannot be found in the OpenEmbedded Metadata Index.
1275 These layers are either deprecated or experimental in nature.
1276 </note>
1277 </para>
1278
1279 <para>
1280 BitBake uses the <filename>conf/bblayers.conf</filename> file,
1281 which is part of the user configuration, to find what layers it
1282 should be using as part of the build.
1283 </para>
1284
1285 <para>
1286 For more information on layers, see the
1287 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1288 section in the Yocto Project Development Tasks Manual.
1289 </para>
1290
1291 <section id="distro-layer">
1292 <title>Distro Layer</title>
1293
1294 <para>
1295 The distribution layer provides policy configurations for your
1296 distribution.
1297 Best practices dictate that you isolate these types of
1298 configurations into their own layer.
1299 Settings you provide in
1300 <filename>conf/distro/<replaceable>distro</replaceable>.conf</filename> override
1301 similar
1302 settings that BitBake finds in your
1303 <filename>conf/local.conf</filename> file in the Build
1304 Directory.
1305 </para>
1306
1307 <para>
1308 The following list provides some explanation and references
1309 for what you typically find in the distribution layer:
1310 <itemizedlist>
1311 <listitem><para><emphasis>classes:</emphasis>
1312 Class files (<filename>.bbclass</filename>) hold
1313 common functionality that can be shared among
1314 recipes in the distribution.
1315 When your recipes inherit a class, they take on the
1316 settings and functions for that class.
1317 You can read more about class files in the
1318 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>"
1319 section of the Yocto Reference Manual.
1320 </para></listitem>
1321 <listitem><para><emphasis>conf:</emphasis>
1322 This area holds configuration files for the
1323 layer (<filename>conf/layer.conf</filename>),
1324 the distribution
1325 (<filename>conf/distro/<replaceable>distro</replaceable>.conf</filename>),
1326 and any distribution-wide include files.
1327 </para></listitem>
1328 <listitem><para><emphasis>recipes-*:</emphasis>
1329 Recipes and append files that affect common
1330 functionality across the distribution.
1331 This area could include recipes and append files
1332 to add distribution-specific configuration,
1333 initialization scripts, custom image recipes,
1334 and so forth.</para></listitem>
1335 </itemizedlist>
1336 </para>
1337 </section>
1338
1339 <section id="bsp-layer">
1340 <title>BSP Layer</title>
1341
1342 <para>
1343 The BSP Layer provides machine configurations.
1344 Everything in this layer is specific to the machine for which
1345 you are building the image or the SDK.
1346 A common structure or form is defined for BSP layers.
1347 You can learn more about this structure in the
1348 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
1349 <note>
1350 In order for a BSP layer to be considered compliant with the
1351 Yocto Project, it must meet some structural requirements.
1352 </note>
1353 </para>
1354
1355 <para>
1356 The BSP Layer's configuration directory contains
1357 configuration files for the machine
1358 (<filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>) and,
1359 of course, the layer (<filename>conf/layer.conf</filename>).
1360 </para>
1361
1362 <para>
1363 The remainder of the layer is dedicated to specific recipes
1364 by function: <filename>recipes-bsp</filename>,
1365 <filename>recipes-core</filename>,
1366 <filename>recipes-graphics</filename>, and
1367 <filename>recipes-kernel</filename>.
1368 Metadata can exist for multiple formfactors, graphics
1369 support systems, and so forth.
1370 <note>
1371 While the figure shows several <filename>recipes-*</filename>
1372 directories, not all these directories appear in all
1373 BSP layers.
1374 </note>
1375 </para>
1376 </section>
1377
1378 <section id="software-layer">
1379 <title>Software Layer</title>
1380
1381 <para>
1382 The software layer provides the Metadata for additional
1383 software packages used during the build.
1384 This layer does not include Metadata that is specific to the
1385 distribution or the machine, which are found in their
1386 respective layers.
1387 </para>
1388
1389 <para>
1390 This layer contains any new recipes that your project needs
1391 in the form of recipe files.
1392 </para>
1393 </section>
1394 </section>
1395
1396 <section id="sources-dev-environment">
1397 <title>Sources</title>
1398
1399 <para>
1400 In order for the OpenEmbedded build system to create an image or
1401 any target, it must be able to access source files.
1402 The
1403 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1404 represents source files using the "Upstream Project Releases",
1405 "Local Projects", and "SCMs (optional)" boxes.
1406 The figure represents mirrors, which also play a role in locating
1407 source files, with the "Source Mirror(s)" box.
1408 </para>
1409
1410 <para>
1411 The method by which source files are ultimately organized is
1412 a function of the project.
1413 For example, for released software, projects tend to use tarballs
1414 or other archived files that can capture the state of a release
1415 guaranteeing that it is statically represented.
1416 On the other hand, for a project that is more dynamic or
1417 experimental in nature, a project might keep source files in a
1418 repository controlled by a Source Control Manager (SCM) such as
1419 Git.
1420 Pulling source from a repository allows you to control
1421 the point in the repository (the revision) from which you want to
1422 build software.
1423 Finally, a combination of the two might exist, which would give the
1424 consumer a choice when deciding where to get source files.
1425 </para>
1426
1427 <para>
1428 BitBake uses the
1429 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1430 variable to point to source files regardless of their location.
1431 Each recipe must have a <filename>SRC_URI</filename> variable
1432 that points to the source.
1433 </para>
1434
1435 <para>
1436 Another area that plays a significant role in where source files
1437 come from is pointed to by the
1438 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1439 variable.
1440 This area is a cache that can hold previously downloaded source.
1441 You can also instruct the OpenEmbedded build system to create
1442 tarballs from Git repositories, which is not the default behavior,
1443 and store them in the <filename>DL_DIR</filename> by using the
1444 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
1445 variable.
1446 </para>
1447
1448 <para>
1449 Judicious use of a <filename>DL_DIR</filename> directory can
1450 save the build system a trip across the Internet when looking
1451 for files.
1452 A good method for using a download directory is to have
1453 <filename>DL_DIR</filename> point to an area outside of your
1454 Build Directory.
1455 Doing so allows you to safely delete the Build Directory
1456 if needed without fear of removing any downloaded source file.
1457 </para>
1458
1459 <para>
1460 The remainder of this section provides a deeper look into the
1461 source files and the mirrors.
1462 Here is a more detailed look at the source file area of the
1463 base figure:
1464 <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
1465 </para>
1466
1467 <section id='upstream-project-releases'>
1468 <title>Upstream Project Releases</title>
1469
1470 <para>
1471 Upstream project releases exist anywhere in the form of an
1472 archived file (e.g. tarball or zip file).
1473 These files correspond to individual recipes.
1474 For example, the figure uses specific releases each for
1475 BusyBox, Qt, and Dbus.
1476 An archive file can be for any released product that can be
1477 built using a recipe.
1478 </para>
1479 </section>
1480
1481 <section id='local-projects'>
1482 <title>Local Projects</title>
1483
1484 <para>
1485 Local projects are custom bits of software the user provides.
1486 These bits reside somewhere local to a project - perhaps
1487 a directory into which the user checks in items (e.g.
1488 a local directory containing a development source tree
1489 used by the group).
1490 </para>
1491
1492 <para>
1493 The canonical method through which to include a local project
1494 is to use the
1495 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
1496 class to include that local project.
1497 You use either the <filename>local.conf</filename> or a
1498 recipe's append file to override or set the
1499 recipe to point to the local directory on your disk to pull
1500 in the whole source tree.
1501 </para>
1502
1503 <para>
1504 For information on how to use the
1505 <filename>externalsrc</filename> class, see the
1506 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>"
1507 section.
1508 </para>
1509 </section>
1510
1511 <section id='scms'>
1512 <title>Source Control Managers (Optional)</title>
1513
1514 <para>
1515 Another place the build system can get source files from is
1516 through an SCM such as Git or Subversion.
1517 In this case, a repository is cloned or checked out.
1518 The
1519 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1520 task inside BitBake uses
1521 the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1522 variable and the argument's prefix to determine the correct
1523 fetcher module.
1524 </para>
1525
1526 <note>
1527 For information on how to have the OpenEmbedded build system
1528 generate tarballs for Git repositories and place them in the
1529 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1530 directory, see the
1531 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
1532 variable.
1533 </note>
1534
1535 <para>
1536 When fetching a repository, BitBake uses the
1537 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1538 variable to determine the specific revision from which to
1539 build.
1540 </para>
1541 </section>
1542
1543 <section id='source-mirrors'>
1544 <title>Source Mirror(s)</title>
1545
1546 <para>
1547 Two kinds of mirrors exist: pre-mirrors and regular mirrors.
1548 The
1549 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
1550 and
1551 <ulink url='&YOCTO_DOCS_REF_URL;#var-MIRRORS'><filename>MIRRORS</filename></ulink>
1552 variables point to these, respectively.
1553 BitBake checks pre-mirrors before looking upstream for any
1554 source files.
1555 Pre-mirrors are appropriate when you have a shared directory
1556 that is not a directory defined by the
1557 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1558 variable.
1559 A Pre-mirror typically points to a shared directory that is
1560 local to your organization.
1561 </para>
1562
1563 <para>
1564 Regular mirrors can be any site across the Internet that is
1565 used as an alternative location for source code should the
1566 primary site not be functioning for some reason or another.
1567 </para>
1568 </section>
1569 </section>
1570
1571 <section id="package-feeds-dev-environment">
1572 <title>Package Feeds</title>
1573
1574 <para>
1575 When the OpenEmbedded build system generates an image or an SDK,
1576 it gets the packages from a package feed area located in the
1577 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1578 The
1579 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1580 shows this package feeds area in the upper-right corner.
1581 </para>
1582
1583 <para>
1584 This section looks a little closer into the package feeds area used
1585 by the build system.
1586 Here is a more detailed look at the area:
1587 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
1588 </para>
1589
1590 <para>
1591 Package feeds are an intermediary step in the build process.
1592 The OpenEmbedded build system provides classes to generate
1593 different package types, and you specify which classes to enable
1594 through the
1595 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
1596 variable.
1597 Before placing the packages into package feeds,
1598 the build process validates them with generated output quality
1599 assurance checks through the
1600 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
1601 class.
1602 </para>
1603
1604 <para>
1605 The package feed area resides in the Build Directory.
1606 The directory the build system uses to temporarily store packages
1607 is determined by a combination of variables and the particular
1608 package manager in use.
1609 See the "Package Feeds" box in the illustration and note the
1610 information to the right of that area.
1611 In particular, the following defines where package files are
1612 kept:
1613 <itemizedlist>
1614 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
1615 Defined as <filename>tmp/deploy</filename> in the Build
1616 Directory.
1617 </para></listitem>
1618 <listitem><para><filename>DEPLOY_DIR_*</filename>:
1619 Depending on the package manager used, the package type
1620 sub-folder.
1621 Given RPM, IPK, or DEB packaging and tarball creation, the
1622 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></ulink>,
1623 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></ulink>,
1624 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></ulink>,
1625 or
1626 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></ulink>,
1627 variables are used, respectively.
1628 </para></listitem>
1629 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>:
1630 Defines architecture-specific sub-folders.
1631 For example, packages could exist for the i586 or qemux86
1632 architectures.
1633 </para></listitem>
1634 </itemizedlist>
1635 </para>
1636
1637 <para>
1638 BitBake uses the <filename>do_package_write_*</filename> tasks to
1639 generate packages and place them into the package holding area (e.g.
1640 <filename>do_package_write_ipk</filename> for IPK packages).
1641 See the
1642 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></ulink>",
1643 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink>",
1644 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></ulink>",
1645 and
1646 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></ulink>"
1647 sections for additional information.
1648 As an example, consider a scenario where an IPK packaging manager
1649 is being used and package architecture support for both i586
1650 and qemux86 exist.
1651 Packages for the i586 architecture are placed in
1652 <filename>build/tmp/deploy/ipk/i586</filename>, while packages for
1653 the qemux86 architecture are placed in
1654 <filename>build/tmp/deploy/ipk/qemux86</filename>.
1655 </para>
1656 </section>
1657
1658 <section id='bitbake-dev-environment'>
1659 <title>BitBake</title>
1660
1661 <para>
1662 The OpenEmbedded build system uses
1663 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
1664 to produce images.
1665 You can see from the
1666 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
1667 the BitBake area consists of several functional areas.
1668 This section takes a closer look at each of those areas.
1669 </para>
1670
1671 <para>
1672 Separate documentation exists for the BitBake tool.
1673 See the
1674 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>
1675 for reference material on BitBake.
1676 </para>
1677
1678 <section id='source-fetching-dev-environment'>
1679 <title>Source Fetching</title>
1680
1681 <para>
1682 The first stages of building a recipe are to fetch and unpack
1683 the source code:
1684 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
1685 </para>
1686
1687 <para>
1688 The
1689 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1690 and
1691 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1692 tasks fetch the source files and unpack them into the work
1693 directory.
1694 <note>
1695 For every local file (e.g. <filename>file://</filename>)
1696 that is part of a recipe's
1697 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1698 statement, the OpenEmbedded build system takes a checksum
1699 of the file for the recipe and inserts the checksum into
1700 the signature for the <filename>do_fetch</filename>.
1701 If any local file has been modified, the
1702 <filename>do_fetch</filename> task and all tasks that
1703 depend on it are re-executed.
1704 </note>
1705 By default, everything is accomplished in the
1706 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
1707 which has a defined structure.
1708 For additional general information on the Build Directory,
1709 see the
1710 "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-build'><filename>build/</filename></ulink>"
1711 section in the Yocto Project Reference Manual.
1712 </para>
1713
1714 <para>
1715 Unpacked source files are pointed to by the
1716 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1717 variable.
1718 Each recipe has an area in the Build Directory where the
1719 unpacked source code resides.
1720 The name of that directory for any given recipe is defined from
1721 several different variables.
1722 You can see the variables that define these directories
1723 by looking at the figure:
1724 <itemizedlist>
1725 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> -
1726 The base directory where the OpenEmbedded build system
1727 performs all its work during the build.
1728 </para></listitem>
1729 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> -
1730 The architecture of the built package or packages.
1731 </para></listitem>
1732 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink> -
1733 The operating system of the target device.
1734 </para></listitem>
1735 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> -
1736 The name of the built package.
1737 </para></listitem>
1738 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> -
1739 The version of the recipe used to build the package.
1740 </para></listitem>
1741 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> -
1742 The revision of the recipe used to build the package.
1743 </para></listitem>
1744 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> -
1745 The location within <filename>TMPDIR</filename> where
1746 a specific package is built.
1747 </para></listitem>
1748 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> -
1749 Contains the unpacked source files for a given recipe.
1750 </para></listitem>
1751 </itemizedlist>
1752 </para>
1753 </section>
1754
1755 <section id='patching-dev-environment'>
1756 <title>Patching</title>
1757
1758 <para>
1759 Once source code is fetched and unpacked, BitBake locates
1760 patch files and applies them to the source files:
1761 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
1762 </para>
1763
1764 <para>
1765 The
1766 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1767 task processes recipes by
1768 using the
1769 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1770 variable to locate applicable patch files, which by default
1771 are <filename>*.patch</filename> or
1772 <filename>*.diff</filename> files, or any file if
1773 "apply=yes" is specified for the file in
1774 <filename>SRC_URI</filename>.
1775 </para>
1776
1777 <para>
1778 BitBake finds and applies multiple patches for a single recipe
1779 in the order in which it finds the patches.
1780 Patches are applied to the recipe's source files located in the
1781 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1782 directory.
1783 </para>
1784
1785 <para>
1786 For more information on how the source directories are
1787 created, see the
1788 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
1789 section.
1790 </para>
1791 </section>
1792
1793 <section id='configuration-and-compilation-dev-environment'>
1794 <title>Configuration and Compilation</title>
1795
1796 <para>
1797 After source code is patched, BitBake executes tasks that
1798 configure and compile the source code:
1799 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
1800 </para>
1801
1802 <para>
1803 This step in the build process consists of three tasks:
1804 <itemizedlist>
1805 <listitem><para>
1806 <emphasis><ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></ulink>:</emphasis>
1807 This task sets up the two sysroots in
1808 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
1809 (i.e. <filename>recipe-sysroot</filename> and
1810 <filename>recipe-sysroot-native</filename>) so that
1811 the sysroots contain the contents of the
1812 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
1813 tasks of the recipes on which the recipe
1814 containing the tasks depends.
1815 A sysroot exists for both the target and for the native
1816 binaries, which run on the host system.
1817 </para></listitem>
1818 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
1819 This task configures the source by enabling and
1820 disabling any build-time and configuration options for
1821 the software being built.
1822 Configurations can come from the recipe itself as well
1823 as from an inherited class.
1824 Additionally, the software itself might configure itself
1825 depending on the target for which it is being built.
1826 </para>
1827
1828 <para>The configurations handled by the
1829 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
1830 task are specific
1831 to source code configuration for the source code
1832 being built by the recipe.</para>
1833
1834 <para>If you are using the
1835 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
1836 class,
1837 you can add additional configuration options by using
1838 the
1839 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1840 or
1841 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1842 variables.
1843 For information on how this variable works within
1844 that class, see the
1845 <filename>meta/classes/autotools.bbclass</filename> file.
1846 </para></listitem>
1847 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
1848 Once a configuration task has been satisfied, BitBake
1849 compiles the source using the
1850 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
1851 task.
1852 Compilation occurs in the directory pointed to by the
1853 <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink>
1854 variable.
1855 Realize that the <filename>B</filename> directory is, by
1856 default, the same as the
1857 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1858 directory.</para></listitem>
1859 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
1860 Once compilation is done, BitBake executes the
1861 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1862 task.
1863 This task copies files from the <filename>B</filename>
1864 directory and places them in a holding area pointed to
1865 by the
1866 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
1867 variable.</para></listitem>
1868 </itemizedlist>
1869 </para>
1870 </section>
1871
1872 <section id='package-splitting-dev-environment'>
1873 <title>Package Splitting</title>
1874
1875 <para>
1876 After source code is configured and compiled, the
1877 OpenEmbedded build system analyzes
1878 the results and splits the output into packages:
1879 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
1880 </para>
1881
1882 <para>
1883 The
1884 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1885 and
1886 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
1887 tasks combine to analyze
1888 the files found in the
1889 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> directory
1890 and split them into subsets based on available packages and
1891 files.
1892 The analyzing process involves the following as well as other
1893 items: splitting out debugging symbols,
1894 looking at shared library dependencies between packages,
1895 and looking at package relationships.
1896 The <filename>do_packagedata</filename> task creates package
1897 metadata based on the analysis such that the
1898 OpenEmbedded build system can generate the final packages.
1899 Working, staged, and intermediate results of the analysis
1900 and package splitting process use these areas:
1901 <itemizedlist>
1902 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGD'><filename>PKGD</filename></ulink> -
1903 The destination directory for packages before they are
1904 split.
1905 </para></listitem>
1906 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> -
1907 A shared, global-state directory that holds data
1908 generated during the packaging process.
1909 </para></listitem>
1910 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDESTWORK'><filename>PKGDESTWORK</filename></ulink> -
1911 A temporary work area used by the
1912 <filename>do_package</filename> task.
1913 </para></listitem>
1914 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDEST'><filename>PKGDEST</filename></ulink> -
1915 The parent directory for packages after they have
1916 been split.
1917 </para></listitem>
1918 </itemizedlist>
1919 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1920 variable defines the files that go into each package in
1921 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>.
1922 If you want details on how this is accomplished, you can
1923 look at the
1924 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package</filename></ulink>
1925 class.
1926 </para>
1927
1928 <para>
1929 Depending on the type of packages being created (RPM, DEB, or
1930 IPK), the <filename>do_package_write_*</filename> task
1931 creates the actual packages and places them in the
1932 Package Feed area, which is
1933 <filename>${TMPDIR}/deploy</filename>.
1934 You can see the
1935 "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
1936 section for more detail on that part of the build process.
1937 <note>
1938 Support for creating feeds directly from the
1939 <filename>deploy/*</filename> directories does not exist.
1940 Creating such feeds usually requires some kind of feed
1941 maintenance mechanism that would upload the new packages
1942 into an official package feed (e.g. the
1943 Ångström distribution).
1944 This functionality is highly distribution-specific
1945 and thus is not provided out of the box.
1946 </note>
1947 </para>
1948 </section>
1949
1950 <section id='image-generation-dev-environment'>
1951 <title>Image Generation</title>
1952
1953 <para>
1954 Once packages are split and stored in the Package Feeds area,
1955 the OpenEmbedded build system uses BitBake to generate the
1956 root filesystem image:
1957 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
1958 </para>
1959
1960 <para>
1961 The image generation process consists of several stages and
1962 depends on several tasks and variables.
1963 The
1964 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>
1965 task creates the root filesystem (file and directory structure)
1966 for an image.
1967 This task uses several key variables to help create the list
1968 of packages to actually install:
1969 <itemizedlist>
1970 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
1971 Lists out the base set of packages to install from
1972 the Package Feeds area.</para></listitem>
1973 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
1974 Specifies packages that should not be installed.
1975 </para></listitem>
1976 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
1977 Specifies features to include in the image.
1978 Most of these features map to additional packages for
1979 installation.</para></listitem>
1980 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>:
1981 Specifies the package backend to use and consequently
1982 helps determine where to locate packages within the
1983 Package Feeds area.</para></listitem>
1984 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></ulink>:
1985 Determines the language(s) for which additional
1986 language support packages are installed.
1987 </para></listitem>
1988 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>:
1989 The final list of packages passed to the package manager
1990 for installation into the image.
1991 </para></listitem>
1992 </itemizedlist>
1993 </para>
1994
1995 <para>
1996 With
1997 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></ulink>
1998 pointing to the location of the filesystem under construction and
1999 the <filename>PACKAGE_INSTALL</filename> variable providing the
2000 final list of packages to install, the root file system is
2001 created.
2002 </para>
2003
2004 <para>
2005 Package installation is under control of the package manager
2006 (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or
2007 not package management is enabled for the target.
2008 At the end of the process, if package management is not
2009 enabled for the target, the package manager's data files
2010 are deleted from the root filesystem.
2011 As part of the final stage of package installation, postinstall
2012 scripts that are part of the packages are run.
2013 Any scripts that fail to run
2014 on the build host are run on the target when the target system
2015 is first booted.
2016 If you are using a
2017 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
2018 all the post installation scripts must succeed during the
2019 package installation phase since the root filesystem is
2020 read-only.
2021 </para>
2022
2023 <para>
2024 The final stages of the <filename>do_rootfs</filename> task
2025 handle post processing.
2026 Post processing includes creation of a manifest file and
2027 optimizations.
2028 </para>
2029
2030 <para>
2031 The manifest file (<filename>.manifest</filename>) resides
2032 in the same directory as the root filesystem image.
2033 This file lists out, line-by-line, the installed packages.
2034 The manifest file is useful for the
2035 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
2036 class, for example, to determine whether or not to run
2037 specific tests.
2038 See the
2039 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></ulink>
2040 variable for additional information.
2041 </para>
2042
2043 <para>
2044 Optimizing processes run across the image include
2045 <filename>mklibs</filename>, <filename>prelink</filename>,
2046 and any other post-processing commands as defined by the
2047 <ulink url='&YOCTO_DOCS_REF_URL;#var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></ulink>
2048 variable.
2049 The <filename>mklibs</filename> process optimizes the size
2050 of the libraries, while the
2051 <filename>prelink</filename> process optimizes the dynamic
2052 linking of shared libraries to reduce start up time of
2053 executables.
2054 </para>
2055
2056 <para>
2057 After the root filesystem is built, processing begins on
2058 the image through the
2059 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink>
2060 task.
2061 The build system runs any pre-processing commands as defined
2062 by the
2063 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></ulink>
2064 variable.
2065 This variable specifies a list of functions to call before
2066 the OpenEmbedded build system creates the final image output
2067 files.
2068 </para>
2069
2070 <para>
2071 The OpenEmbedded build system dynamically creates
2072 <filename>do_image_*</filename> tasks as needed, based
2073 on the image types specified in the
2074 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
2075 variable.
2076 The process turns everything into an image file or a set of
2077 image files and compresses the root filesystem image to reduce
2078 the overall size of the image.
2079 The formats used for the root filesystem depend on the
2080 <filename>IMAGE_FSTYPES</filename> variable.
2081 </para>
2082
2083 <para>
2084 As an example, a dynamically created task when creating a
2085 particular image <replaceable>type</replaceable> would take the
2086 following form:
2087 <literallayout class='monospaced'>
2088 do_image_<replaceable>type</replaceable>[depends]
2089 </literallayout>
2090 So, if the <replaceable>type</replaceable> as specified by the
2091 <filename>IMAGE_FSTYPES</filename> were
2092 <filename>ext4</filename>, the dynamically generated task
2093 would be as follows:
2094 <literallayout class='monospaced'>
2095 do_image_ext4[depends]
2096 </literallayout>
2097 </para>
2098
2099 <para>
2100 The final task involved in image creation is the
2101 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image-complete'><filename>do_image_complete</filename></ulink>
2102 task.
2103 This task completes the image by applying any image
2104 post processing as defined through the
2105 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></ulink>
2106 variable.
2107 The variable specifies a list of functions to call once the
2108 OpenEmbedded build system has created the final image output
2109 files.
2110 </para>
2111
2112 <note>
2113 The entire image generation process is run under Pseudo.
2114 Running under Pseudo ensures that the files in the root
2115 filesystem have correct ownership.
2116 </note>
2117 </section>
2118
2119 <section id='sdk-generation-dev-environment'>
2120 <title>SDK Generation</title>
2121
2122 <para>
2123 The OpenEmbedded build system uses BitBake to generate the
2124 Software Development Kit (SDK) installer script for both the
2125 standard and extensible SDKs:
2126 <imagedata fileref="figures/sdk-generation.png" align="center" />
2127 </para>
2128
2129 <note>
2130 For more information on the cross-development toolchain
2131 generation, see the
2132 "<ulink url='&YOCTO_DOCS_CM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
2133 section in the Yocto Project Concepts Manual.
2134 For information on advantages gained when building a
2135 cross-development toolchain using the
2136 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink>
2137 task, see the
2138 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
2139 section in the Yocto Project Application Development and the
2140 Extensible Software Development Kit (SDK) manual.
2141 </note>
2142
2143 <para>
2144 Like image generation, the SDK script process consists of
2145 several stages and depends on many variables.
2146 The <filename>do_populate_sdk</filename> and
2147 <filename>do_populate_sdk_ext</filename> tasks use these
2148 key variables to help create the list of packages to actually
2149 install.
2150 For information on the variables listed in the figure, see the
2151 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
2152 section.
2153 </para>
2154
2155 <para>
2156 The <filename>do_populate_sdk</filename> task helps create
2157 the standard SDK and handles two parts: a target part and a
2158 host part.
2159 The target part is the part built for the target hardware and
2160 includes libraries and headers.
2161 The host part is the part of the SDK that runs on the
2162 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>.
2163 </para>
2164
2165 <para>
2166 The <filename>do_populate_sdk_ext</filename> task helps create
2167 the extensible SDK and handles host and target parts
2168 differently than its counter part does for the standard SDK.
2169 For the extensible SDK, the task encapsulates the build system,
2170 which includes everything needed (host and target) for the SDK.
2171 </para>
2172
2173 <para>
2174 Regardless of the type of SDK being constructed, the
2175 tasks perform some cleanup after which a cross-development
2176 environment setup script and any needed configuration files
2177 are created.
2178 The final output is the Cross-development
2179 toolchain installation script (<filename>.sh</filename> file),
2180 which includes the environment setup script.
2181 </para>
2182 </section>
2183
2184 <section id='stamp-files-and-the-rerunning-of-tasks'>
2185 <title>Stamp Files and the Rerunning of Tasks</title>
2186
2187 <para>
2188 For each task that completes successfully, BitBake writes a
2189 stamp file into the
2190 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
2191 directory.
2192 The beginning of the stamp file's filename is determined by the
2193 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMP'><filename>STAMP</filename></ulink>
2194 variable, and the end of the name consists of the task's name
2195 and current
2196 <ulink url='&YOCTO_DOCS_CM_URL;#overview-checksums'>input checksum</ulink>.
2197 <note>
2198 This naming scheme assumes that
2199 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink>
2200 is "OEBasicHash", which is almost always the case in
2201 current OpenEmbedded.
2202 </note>
2203 To determine if a task needs to be rerun, BitBake checks if a
2204 stamp file with a matching input checksum exists for the task.
2205 If such a stamp file exists, the task's output is assumed to
2206 exist and still be valid.
2207 If the file does not exist, the task is rerun.
2208 <note>
2209 <para>The stamp mechanism is more general than the shared
2210 state (sstate) cache mechanism described in the
2211 "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>"
2212 section.
2213 BitBake avoids rerunning any task that has a valid
2214 stamp file, not just tasks that can be accelerated through
2215 the sstate cache.</para>
2216 <para>However, you should realize that stamp files only
2217 serve as a marker that some work has been done and that
2218 these files do not record task output.
2219 The actual task output would usually be somewhere in
2220 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
2221 (e.g. in some recipe's
2222 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.)
2223 What the sstate cache mechanism adds is a way to cache task
2224 output that can then be shared between build machines.
2225 </para>
2226 </note>
2227 Since <filename>STAMPS_DIR</filename> is usually a subdirectory
2228 of <filename>TMPDIR</filename>, removing
2229 <filename>TMPDIR</filename> will also remove
2230 <filename>STAMPS_DIR</filename>, which means tasks will
2231 properly be rerun to repopulate <filename>TMPDIR</filename>.
2232 </para>
2233
2234 <para>
2235 If you want some task to always be considered "out of date",
2236 you can mark it with the
2237 <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink>
2238 varflag.
2239 If some other task depends on such a task, then that task will
2240 also always be considered out of date, which might not be what
2241 you want.
2242 </para>
2243
2244 <para>
2245 For details on how to view information about a task's
2246 signature, see the
2247 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
2248 section in the Yocto Project Development Tasks Manual.
2249 </para>
2250 </section>
2251
2252 <section id='setscene-tasks-and-shared-state'>
2253 <title>Setscene Tasks and Shared State</title>
2254
2255 <para>
2256 The description of tasks so far assumes that BitBake needs to
2257 build everything and there are no prebuilt objects available.
2258 BitBake does support skipping tasks if prebuilt objects are
2259 available.
2260 These objects are usually made available in the form of a
2261 shared state (sstate) cache.
2262 <note>
2263 For information on variables affecting sstate, see the
2264 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
2265 and
2266 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>
2267 variables.
2268 </note>
2269 </para>
2270
2271 <para>
2272 The idea of a setscene task (i.e
2273 <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>)
2274 is a version of the task where
2275 instead of building something, BitBake can skip to the end
2276 result and simply place a set of files into specific locations
2277 as needed.
2278 In some cases, it makes sense to have a setscene task variant
2279 (e.g. generating package files in the
2280 <filename>do_package_write_*</filename> task).
2281 In other cases, it does not make sense, (e.g. a
2282 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
2283 task or
2284 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
2285 task) since the work involved would be equal to or greater than
2286 the underlying task.
2287 </para>
2288
2289 <para>
2290 In the OpenEmbedded build system, the common tasks that have
2291 setscene variants are
2292 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>,
2293 <filename>do_package_write_*</filename>,
2294 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>,
2295 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>,
2296 and
2297 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>.
2298 Notice that these are most of the tasks whose output is an
2299 end result.
2300 </para>
2301
2302 <para>
2303 The OpenEmbedded build system has knowledge of the relationship
2304 between these tasks and other tasks that precede them.
2305 For example, if BitBake runs
2306 <filename>do_populate_sysroot_setscene</filename> for
2307 something, there is little point in running any of the
2308 <filename>do_fetch</filename>, <filename>do_unpack</filename>,
2309 <filename>do_patch</filename>,
2310 <filename>do_configure</filename>,
2311 <filename>do_compile</filename>, and
2312 <filename>do_install</filename> tasks.
2313 However, if <filename>do_package</filename> needs to be run,
2314 BitBake would need to run those other tasks.
2315 </para>
2316
2317 <para>
2318 It becomes more complicated if everything can come from an
2319 sstate cache because some objects are simply not required at
2320 all.
2321 For example, you do not need a compiler or native tools, such
2322 as quilt, if there is nothing to compile or patch.
2323 If the <filename>do_package_write_*</filename> packages are
2324 available from sstate, BitBake does not need the
2325 <filename>do_package</filename> task data.
2326 </para>
2327
2328 <para>
2329 To handle all these complexities, BitBake runs in two phases.
2330 The first is the "setscene" stage.
2331 During this stage, BitBake first checks the sstate cache for
2332 any targets it is planning to build.
2333 BitBake does a fast check to see if the object exists rather
2334 than a complete download.
2335 If nothing exists, the second phase, which is the setscene
2336 stage, completes and the main build proceeds.
2337 </para>
2338
2339 <para>
2340 If objects are found in the sstate cache, the OpenEmbedded
2341 build system works backwards from the end targets specified
2342 by the user.
2343 For example, if an image is being built, the OpenEmbedded build
2344 system first looks for the packages needed for that image and
2345 the tools needed to construct an image.
2346 If those are available, the compiler is not needed.
2347 Thus, the compiler is not even downloaded.
2348 If something was found to be unavailable, or the download or
2349 setscene task fails, the OpenEmbedded build system then tries
2350 to install dependencies, such as the compiler, from the cache.
2351 </para>
2352
2353 <para>
2354 The availability of objects in the sstate cache is handled by
2355 the function specified by the
2356 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
2357 variable and returns a list of the objects that are available.
2358 The function specified by the
2359 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink>
2360 variable is the function that determines whether a given
2361 dependency needs to be followed, and whether for any given
2362 relationship the function needs to be passed.
2363 The function returns a True or False value.
2364 </para>
2365 </section>
2366 </section>
2367
2368 <section id='images-dev-environment'>
2369 <title>Images</title>
2370
2371 <para>
2372 The images produced by the OpenEmbedded build system
2373 are compressed forms of the
2374 root filesystem that are ready to boot on a target device.
2375 You can see from the
2376 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
2377 that BitBake output, in part, consists of images.
2378 This section is going to look more closely at this output:
2379 <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
2380 </para>
2381
2382 <para>
2383 For a list of example images that the Yocto Project provides,
2384 see the
2385 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
2386 chapter in the Yocto Project Reference Manual.
2387 </para>
2388
2389 <para>
2390 Images are written out to the
2391 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
2392 inside the
2393 <filename>tmp/deploy/images/<replaceable>machine</replaceable>/</filename>
2394 folder as shown in the figure.
2395 This folder contains any files expected to be loaded on the
2396 target device.
2397 The
2398 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>
2399 variable points to the <filename>deploy</filename> directory,
2400 while the
2401 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></ulink>
2402 variable points to the appropriate directory containing images for
2403 the current configuration.
2404 <itemizedlist>
2405 <listitem><para><filename><replaceable>kernel-image</replaceable></filename>:
2406 A kernel binary file.
2407 The
2408 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>
2409 variable setting determines the naming scheme for the
2410 kernel image file.
2411 Depending on that variable, the file could begin with
2412 a variety of naming strings.
2413 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2414 directory can contain multiple image files for the
2415 machine.</para></listitem>
2416 <listitem><para><filename><replaceable>root-filesystem-image</replaceable></filename>:
2417 Root filesystems for the target device (e.g.
2418 <filename>*.ext3</filename> or <filename>*.bz2</filename>
2419 files).
2420 The
2421 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
2422 variable setting determines the root filesystem image
2423 type.
2424 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2425 directory can contain multiple root filesystems for the
2426 machine.</para></listitem>
2427 <listitem><para><filename><replaceable>kernel-modules</replaceable></filename>:
2428 Tarballs that contain all the modules built for the kernel.
2429 Kernel module tarballs exist for legacy purposes and
2430 can be suppressed by setting the
2431 <ulink url='&YOCTO_DOCS_REF_URL;#var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></ulink>
2432 variable to "0".
2433 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2434 directory can contain multiple kernel module tarballs
2435 for the machine.</para></listitem>
2436 <listitem><para><filename><replaceable>bootloaders</replaceable></filename>:
2437 Bootloaders supporting the image, if applicable to the
2438 target machine.
2439 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2440 directory can contain multiple bootloaders for the
2441 machine.</para></listitem>
2442 <listitem><para><filename><replaceable>symlinks</replaceable></filename>:
2443 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2444 folder contains
2445 a symbolic link that points to the most recently built file
2446 for each machine.
2447 These links might be useful for external scripts that
2448 need to obtain the latest version of each file.
2449 </para></listitem>
2450 </itemizedlist>
2451 </para>
2452 </section>
2453
2454 <section id='sdk-dev-environment'>
2455 <title>Application Development SDK</title>
2456
2457 <para>
2458 In the
2459 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
2460 the output labeled "Application Development SDK" represents an
2461 SDK.
2462 The SDK generation process differs depending on whether you build
2463 a standard SDK
2464 (e.g. <filename>bitbake -c populate_sdk</filename> <replaceable>imagename</replaceable>)
2465 or an extensible SDK
2466 (e.g. <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>).
2467 This section is going to take a closer look at this output:
2468 <imagedata fileref="figures/sdk.png" align="center" width="9in" depth="7.25in" />
2469 </para>
2470
2471 <para>
2472 The specific form of this output is a self-extracting
2473 SDK installer (<filename>*.sh</filename>) that, when run,
2474 installs the SDK, which consists of a cross-development
2475 toolchain, a set of libraries and headers, and an SDK
2476 environment setup script.
2477 Running this installer essentially sets up your
2478 cross-development environment.
2479 You can think of the cross-toolchain as the "host"
2480 part because it runs on the SDK machine.
2481 You can think of the libraries and headers as the "target"
2482 part because they are built for the target hardware.
2483 The environment setup script is added so that you can initialize
2484 the environment before using the tools.
2485 </para>
2486
2487 <note><title>Notes</title>
2488 <itemizedlist>
2489 <listitem><para>
2490 The Yocto Project supports several methods by which you can
2491 set up this cross-development environment.
2492 These methods include downloading pre-built SDK installers
2493 or building and installing your own SDK installer.
2494 </para></listitem>
2495 <listitem><para>
2496 For background information on cross-development toolchains
2497 in the Yocto Project development environment, see the
2498 "<ulink url='&YOCTO_DOCS_CM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
2499 section in the Yocto Projects Concepts Manual.
2500 </para></listitem>
2501 <listitem><para>
2502 For information on setting up a cross-development
2503 environment, see the
2504 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
2505 manual.
2506 </para></listitem>
2507 </itemizedlist>
2508 </note>
2509
2510 <para>
2511 Once built, the SDK installers are written out to the
2512 <filename>deploy/sdk</filename> folder inside the
2513 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
2514 as shown in the figure at the beginning of this section.
2515 Depending on the type of SDK, several variables exist that help
2516 configure these files.
2517 The following list shows the variables associated with a standard
2518 SDK:
2519 <itemizedlist>
2520 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
2521 Points to the <filename>deploy</filename>
2522 directory.</para></listitem>
2523 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>:
2524 Specifies the architecture of the machine
2525 on which the cross-development tools are run to
2526 create packages for the target hardware.
2527 </para></listitem>
2528 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></ulink>:
2529 Lists the features to include in the "target" part
2530 of the SDK.
2531 </para></listitem>
2532 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>:
2533 Lists packages that make up the host
2534 part of the SDK (i.e. the part that runs on
2535 the <filename>SDKMACHINE</filename>).
2536 When you use
2537 <filename>bitbake -c populate_sdk <replaceable>imagename</replaceable></filename>
2538 to create the SDK, a set of default packages
2539 apply.
2540 This variable allows you to add more packages.
2541 </para></listitem>
2542 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>:
2543 Lists packages that make up the target part
2544 of the SDK (i.e. the part built for the
2545 target hardware).
2546 </para></listitem>
2547 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKPATH'><filename>SDKPATH</filename></ulink>:
2548 Defines the default SDK installation path offered by the
2549 installation script.
2550 </para></listitem>
2551 </itemizedlist>
2552 This next list, shows the variables associated with an extensible
2553 SDK:
2554 <itemizedlist>
2555 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
2556 Points to the <filename>deploy</filename> directory.
2557 </para></listitem>
2558 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>:
2559 Controls whether or not shared state artifacts are copied
2560 into the extensible SDK.
2561 By default, all required shared state artifacts are copied
2562 into the SDK.
2563 </para></listitem>
2564 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>:
2565 Specifies whether or not packagedata will be included in
2566 the extensible SDK for all recipes in the "world" target.
2567 </para></listitem>
2568 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>:
2569 Specifies whether or not the toolchain will be included
2570 when building the extensible SDK.
2571 </para></listitem>
2572 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>:
2573 A list of variables allowed through from the build system
2574 configuration into the extensible SDK configuration.
2575 </para></listitem>
2576 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>:
2577 A list of variables not allowed through from the build
2578 system configuration into the extensible SDK configuration.
2579 </para></listitem>
2580 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>:
2581 A list of classes to remove from the
2582 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
2583 value globally within the extensible SDK configuration.
2584 </para></listitem>
2585 </itemizedlist>
2586 </para>
2587 </section>
2588</section>
2589
2590</chapter> 940</chapter>
2591<!-- 941<!--
2592vim: expandtab tw=80 ts=4 942vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-10 14:12:00 +0000