summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml327
-rw-r--r--documentation/dev-manual/dev-manual-model.xml374
2 files changed, 351 insertions, 350 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index a3e0725808..f792c7694f 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -7,12 +7,11 @@
7<title>Common Tasks</title> 7<title>Common Tasks</title>
8 <para> 8 <para>
9 This chapter describes standard tasks such as adding new 9 This chapter describes standard tasks such as adding new
10 software packages, extending or customizing images or porting the Yocto Project to 10 software packages, extending or customizing images, and porting the Yocto Project to
11 new hardware (adding a new machine). 11 new hardware (adding a new machine).
12 The chapter also describes ways to modify package source code, combine multiple 12 The chapter also describes how to combine multiple
13 versions of library files into a single image, and handle a package name alias. 13 versions of library files into a single image, how to handle a package name alias, and
14 Finally, the chapter contains advice about how to make changes to the 14 gives advice about how to make changes to the Yocto Project to achieve the best results.
15 Yocto Project to achieve the best results.
16 </para> 15 </para>
17 16
18 <section id="understanding-and-creating-layers"> 17 <section id="understanding-and-creating-layers">
@@ -1189,324 +1188,6 @@ so that there are some definite steps on how to do this. I need more detail her
1189 </section> 1188 </section>
1190 </section> 1189 </section>
1191 1190
1192 <section id="modifying-temporary-source-code">
1193 <title>Modifying Temporary Source Code</title>
1194
1195 <para>
1196 Although the Yocto Project is typically used to build software, you might
1197 find it helpful during development to modify the temporary source code used by recipes
1198 to build packages.
1199 For example, suppose you are developing a patch and you need to experiment a bit
1200 to figure out your solution.
1201 After you have initially built the package, you can iteratively tweak the
1202 source code, which is located in the
1203 <link linkend='yocto-project-build-directory'>Yocto Project's Build Directory</link>, and then
1204 you can force a re-compile and quickly test your altered code.
1205 Once you settle on a solution, you can then preserve your changes in the form of
1206 patches.
1207 You can accomplish these steps all within either a
1208 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
1209 <link linkend='git'>Git</link> workflow.
1210 </para>
1211
1212 <section id='finding-the-temporary-source-code'>
1213 <title>Finding the Temporary Source Code</title>
1214
1215 <para>
1216 During a build, the unpacked temporary source code used by recipes
1217 to build packages is available in the Yocto Project Build Directory as
1218 defined by the
1219 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
1220 Below is the default value for the <filename>S</filename> variable as defined in the
1221 <filename>meta/conf/bitbake.conf</filename> configuration file in the
1222 <link linkend='yocto-project-files'>Yocto Project Files</link>:
1223 <literallayout class='monospaced'>
1224 S = ${WORKDIR}/${BP}
1225 </literallayout>
1226 You should be aware that many recipes override the <filename>S</filename> variable.
1227 For example, recipes that fetch their source from Git usually set
1228 <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
1229 <note>
1230 <filename>BP</filename> represents the "Base Package", which is the base package
1231 name and the package version:
1232 <literallayout class='monospaced'>
1233 BP = ${BPN}-${PV}
1234 </literallayout>
1235 </note>
1236 </para>
1237
1238 <para>
1239 The path to the work directory for the recipe
1240 (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) depends
1241 on the package name and the architecture of the target device.
1242 For example, here is the work directory for packages whose targets are not device-dependent:
1243 <literallayout class='monospaced'>
1244 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
1245 </literallayout>
1246 Let's look at an example without variables.
1247 Assuming a Yocto Project Files top-level directory named <filename>poky</filename>
1248 and a default Yocto Project Build Directory of <filename>poky/build</filename>,
1249 the following is the work directory for the <filename>acl</filename> package:
1250 <literallayout class='monospaced'>
1251 ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3
1252 </literallayout>
1253 </para>
1254
1255 <para>
1256 If your package is dependent on the target device, the work directory varies slightly:
1257 <literallayout class='monospaced'>
1258 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
1259 </literallayout>
1260 Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename>
1261 and a default Yocto Project Build Directory of <filename>poky/build</filename>, the
1262 following is the work directory for the <filename>acl</filename> package that is being
1263 built for a MIPS-based device:
1264 <literallayout class='monospaced'>
1265 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
1266 </literallayout>
1267 </para>
1268
1269 <note>
1270 To better understand how the Yocto Project build system resolves directories during the
1271 build process, see the glossary entries for the
1272 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>,
1273 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
1274 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>,
1275 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
1276 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>,
1277 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
1278 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
1279 and
1280 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
1281 variables in the Yocto Project Reference Manual.
1282 </note>
1283
1284 <para>
1285 Now that you know where to locate the directory that has the temporary source code, you can use a
1286 Quilt or Git workflow to make your edits, test the changes, and preserve the
1287 changes in the form of patches.
1288 </para>
1289 </section>
1290
1291 <section id="using-a-quilt-workflow">
1292 <title>Using a Quilt Workflow</title>
1293
1294 <para>
1295 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
1296 is a powerful tool that allows you to capture source code changes without having
1297 a clean source tree.
1298 This section outlines the typical workflow you can use to modify temporary source code,
1299 test changes, and then preserve the changes in the form of a patch all using Quilt.
1300 </para>
1301
1302 <para>
1303 Follow these general steps:
1304 <orderedlist>
1305 <listitem><para><emphasis>Find the Source Code:</emphasis>
1306 The temporary source code used by the Yocto Project build system is kept in the
1307 Yocto Project Build Directory.
1308 See the
1309 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1310 section to learn how to locate the directory that has the temporary source code for a
1311 particular package.</para></listitem>
1312 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1313 You need to be in the directory that has the temporary source code.
1314 That directory is defined by the
1315 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
1316 variable.</para></listitem>
1317 <listitem><para><emphasis>Create a New Patch:</emphasis>
1318 Before modifying source code, you need to create a new patch.
1319 To create a new patch file, use <filename>quilt new</filename> as below:
1320 <literallayout class='monospaced'>
1321 $ quilt new my_changes.patch
1322 </literallayout></para></listitem>
1323 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
1324 After creating the patch, you need to notify Quilt about the files you will
1325 be changing.
1326 Add the files you will be modifying into the patch you just created:
1327 <literallayout class='monospaced'>
1328 $ quilt add file1.c file2.c file3.c
1329 </literallayout></para></listitem>
1330 <listitem><para><emphasis>Edit the Files:</emphasis>
1331 Make the changes to the temporary source code.</para></listitem>
1332 <listitem><para><emphasis>Test Your Changes:</emphasis>
1333 Once you have modified the source code, the easiest way to test your changes
1334 is by calling the <filename>compile</filename> task as shown in the following example:
1335 <literallayout class='monospaced'>
1336 $ bitbake -c compile -f &lt;name_of_package&gt;
1337 </literallayout>
1338 The <filename>-f</filename> or <filename>--force</filename>
1339 option forces re-execution of the specified task.
1340 If you find problems with your code, you can just keep editing and
1341 re-testing iteratively until things work as expected.
1342 <note>All the modifications you make to the temporary source code
1343 disappear once you <filename>-c clean</filename> or
1344 <filename>-c cleanall</filename> with BitBake for the package.
1345 Modifications will also disappear if you use the <filename>rm_work</filename>
1346 feature as described in the
1347 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1348 section of the Yocto Project Quick Start.
1349 </note></para></listitem>
1350 <listitem><para><emphasis>Generate the Patch:</emphasis>
1351 Once your changes work as expected, you need to use Quilt to generate the final patch that
1352 contains all your modifications.
1353 <literallayout class='monospaced'>
1354 $ quilt refresh
1355 </literallayout>
1356 At this point the <filename>my_changes.patch</filename> file has all your edits made
1357 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1358 <filename>file3.c</filename> files.</para>
1359 <para>You can find the resulting patch file in the <filename>patches/</filename>
1360 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
1361 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1362 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1363 which you can create in the same directory as the recipe.
1364 Placing the patch here guarantees that the Yocto Project build system will find
1365 the patch.
1366 Next, add the patch into the
1367 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1368 of the recipe.
1369 Here is an example:
1370 <literallayout class='monospaced'>
1371 SRC_URI += "file://my_changes.patch"
1372 </literallayout></para></listitem>
1373 <listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
1374 Finally, don't forget to 'bump' the
1375 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1376 value in the same recipe since the resulting packages have changed.</para></listitem>
1377 </orderedlist>
1378 </para>
1379 </section>
1380
1381 <section id='using-a-git-workflow'>
1382 <title>Using a Git Workflow</title>
1383 <para>
1384 Git is an even more powerful tool that allows you to capture source code changes without having
1385 a clean source tree.
1386 This section outlines the typical workflow you can use to modify temporary source code,
1387 test changes, and then preserve the changes in the form of a patch all using Git.
1388 For general information on Git as it is used in the Yocto Project, see the
1389 "<link linkend='git'>Git</link>" section.
1390 </para>
1391
1392 <note>
1393 This workflow uses Git only for its ability to manage local changes to the source code
1394 and produce patches independent of any version control used on the Yocto Project
1395 Files.
1396 </note>
1397
1398 <para>
1399 Follow these general steps:
1400 <orderedlist>
1401 <listitem><para><emphasis>Find the Source Code:</emphasis>
1402 The temporary source code used by the Yocto Project build system is kept in the
1403 Yocto Project Build Directory.
1404 See the
1405 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1406 section to learn how to locate the directory that has the temporary source code for a
1407 particular package.</para></listitem>
1408 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1409 You need to be in the directory that has the temporary source code.
1410 That directory is defined by the
1411 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
1412 variable.</para></listitem>
1413 <listitem><para><emphasis>Initialize a Git Repository:</emphasis>
1414 Use the <filename>git init</filename> command to initialize a new local repository
1415 that is based on the work directory:
1416 <literallayout class='monospaced'>
1417 $ git init
1418 </literallayout></para></listitem>
1419 <listitem><para><emphasis>Stage all the files:</emphasis>
1420 Use the <filename>git add *</filename> command to stage all the files in the source
1421 code directory so that they can be committed:
1422 <literallayout class='monospaced'>
1423 $ git add *
1424 </literallayout></para></listitem>
1425 <listitem><para><emphasis>Commit the Source Files:</emphasis>
1426 Use the <filename>git commit</filename> command to initially commit all the files in
1427 the work directory:
1428 <literallayout class='monospaced'>
1429 $ git commit
1430 </literallayout>
1431 At this point, your Git repository is aware of all the source code files.
1432 Any edits you now make to files will be tracked by Git.</para></listitem>
1433 <listitem><para><emphasis>Edit the Files:</emphasis>
1434 Make the changes to the temporary source code.</para></listitem>
1435 <listitem><para><emphasis>Test Your Changes:</emphasis>
1436 Once you have modified the source code, the easiest way to test your changes
1437 is by calling the <filename>compile</filename> task as shown in the following example:
1438 <literallayout class='monospaced'>
1439 $ bitbake -c compile -f &lt;name_of_package&gt;
1440 </literallayout>
1441 The <filename>-f</filename> or <filename>--force</filename>
1442 option forces re-execution of the specified task.
1443 If you find problems with your code, you can just keep editing and
1444 re-testing iteratively until things work as expected.
1445 <note>All the modifications you make to the temporary source code
1446 disappear once you <filename>-c clean</filename> or
1447 <filename>-c cleanall</filename> with BitBake for the package.
1448 Modifications will also disappear if you use the <filename>rm_work</filename>
1449 feature as described in the
1450 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1451 section of the Yocto Project Quick Start.
1452 </note></para></listitem>
1453 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
1454 Use the <filename>git status</filename> command to see what files you have actually edited.
1455 The ability to have Git track the files you have changed is an advantage that this
1456 workflow has over the Quilt workflow.
1457 Here is the Git command to list your changed files:
1458 <literallayout class='monospaced'>
1459 $ git status
1460 </literallayout></para></listitem>
1461 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
1462 Use the <filename>git add</filename> command to stage the changed files so they
1463 can be committed as follows:
1464 <literallayout class='monospaced'>
1465 $ git add file1.c file2.c file3.c
1466 </literallayout></para></listitem>
1467 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
1468 Use the <filename>git commit</filename> command to commit the changes to the
1469 local repository.
1470 Once you have committed the files, you can use the <filename>git log</filename>
1471 command to see your changes:
1472 <literallayout class='monospaced'>
1473 $ git commit
1474 $ git log
1475 </literallayout></para></listitem>
1476 <listitem><para><emphasis>Generate the Patch:</emphasis>
1477 Once the changes are committed, use the <filename>git format-patch</filename>
1478 command to generate a patch file:
1479 <literallayout class='monospaced'>
1480 $ git format-patch HEAD~1
1481 </literallayout>
1482 The <filename>HEAD~1</filename> part of the command causes Git to generate the
1483 patch file for the most recent commit.</para>
1484 <para>At this point, the patch file has all your edits made
1485 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1486 <filename>file3.c</filename> files.
1487 You can find the resulting patch file in the current directory.
1488 The patch file ends with <filename>.patch</filename>.</para></listitem>
1489 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1490 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1491 which you can create in the same directory as the recipe.
1492 Placing the patch here guarantees that the Yocto Project build system will find
1493 the patch.
1494 Next, add the patch into the
1495 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1496 of the recipe.
1497 Here is an example:
1498 <literallayout class='monospaced'>
1499 SRC_URI += "file://my_changes.patch"
1500 </literallayout></para></listitem>
1501 <listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
1502 Finally, don't forget to 'bump' the
1503 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1504 value in the same recipe since the resulting packages have changed.</para></listitem>
1505 </orderedlist>
1506 </para>
1507 </section>
1508 </section>
1509
1510 <section id="building-multiple-architecture-libraries-into-one-image"> 1191 <section id="building-multiple-architecture-libraries-into-one-image">
1511 <title>Combining Multiple Versions of Library Files into One Image</title> 1192 <title>Combining Multiple Versions of Library Files into One Image</title>
1512 1193
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index bbedf6b5bd..69e09e6466 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -8,32 +8,35 @@
8 8
9<para> 9<para>
10 Many development models exist for which you can use the Yocto Project. 10 Many development models exist for which you can use the Yocto Project.
11 However, for the purposes of this manual we are going to focus on two common models: 11 This chapter overviews the following methods:
12 System Development and User Application Development. 12 <itemizedlist>
13 System Development covers Board Support Package (BSP) development and kernel modification 13 <listitem><para><emphasis>System Development:</emphasis>
14 or configuration. 14 System Development covers Board Support Package (BSP) development and kernel
15 User Application Development covers development of applications that you intend to run on some 15 modification or configuration.
16 target hardware. 16 If you want to examine specific examples of the system development models,
17</para> 17 see the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>"
18 18 appendix and the
19<para> 19 "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix.
20 This chapter presents overviews of both system and application models. 20 </para></listitem>
21 If you want to examine specific examples of the system development models, 21 <listitem><para><emphasis>User Application Development:</emphasis>
22 see the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>" 22 User Application Development covers development of applications that you intend
23 appendix and the 23 to run on some target hardware.
24 "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix. 24 For a user-space application development example that uses the
25 For a user-space application development example that uses the 25 <trademark class='trade'>Eclipse</trademark> IDE,
26 <trademark class='trade'>Eclipse</trademark> IDE, 26 see the
27 see the 27 <ulink url='&YOCTO_DOCS_ADT_URL;'>
28 <ulink url='&YOCTO_DOCS_ADT_URL;'> 28 The Yocto Project Application Development Toolkit (ADT) User's Guide</ulink>.
29 The Yocto Project Application Development Toolkit (ADT) User's Guide</ulink>. 29 </para></listitem>
30</para> 30 <listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
31 31 Direct modification of temporary source code is a convenient development model
32<para> 32 to quickly iterate and develop towards a solution.
33 Aside from these two models, this chapter will also briefly introduce and discuss 33 Once the solution has been implemented, you should of course take steps to
34 development using 34 get the changes upstream and applied in the affected recipes.</para></listitem>
35 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink>, which is a graphical interface 35 <listitem><para><emphasis>Image Development using Hob:</emphasis>
36 to the Yocto Project build system. 36 You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build
37 custom operating system images within the Yocto Project build environment.
38 Hob provides an efficient interface to the Yocto Project build system.</para></listitem>
39 </itemizedlist>
37</para> 40</para>
38 41
39<section id='system-development-model'> 42<section id='system-development-model'>
@@ -58,7 +61,7 @@
58 <title>Developing a Board Support Package (BSP)</title> 61 <title>Developing a Board Support Package (BSP)</title>
59 62
60 <para> 63 <para>
61 A BSP is a package of recipes that, when applied, during a build results in 64 A BSP is a packageof recipes that, when applied, during a build results in
62 an image that you can run on a particular board. 65 an image that you can run on a particular board.
63 Thus, the package, when compiled into the new image, supports the operation of the board. 66 Thus, the package, when compiled into the new image, supports the operation of the board.
64 </para> 67 </para>
@@ -700,6 +703,323 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
700 </section> 703 </section>
701</section> 704</section>
702 705
706<section id="modifying-temporary-source-code">
707 <title>Modifying Temporary Source Code</title>
708
709 <para>
710 Although the Yocto Project is typically used to build software, you might
711 find it helpful during development to modify the temporary source code used by recipes
712 to build packages.
713 For example, suppose you are developing a patch and you need to experiment a bit
714 to figure out your solution.
715 After you have initially built the package, you can iteratively tweak the
716 source code, which is located in the
717 <link linkend='yocto-project-build-directory'>Yocto Project's Build Directory</link>, and then
718 you can force a re-compile and quickly test your altered code.
719 Once you settle on a solution, you can then preserve your changes in the form of
720 patches.
721 You can accomplish these steps all within either a
722 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
723 <link linkend='git'>Git</link> workflow.
724 </para>
725
726 <section id='finding-the-temporary-source-code'>
727 <title>Finding the Temporary Source Code</title>
728
729 <para>
730 During a build, the unpacked temporary source code used by recipes
731 to build packages is available in the Yocto Project Build Directory as
732 defined by the
733 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
734 Below is the default value for the <filename>S</filename> variable as defined in the
735 <filename>meta/conf/bitbake.conf</filename> configuration file in the
736 <link linkend='yocto-project-files'>Yocto Project Files</link>:
737 <literallayout class='monospaced'>
738 S = ${WORKDIR}/${BP}
739 </literallayout>
740 You should be aware that many recipes override the <filename>S</filename> variable.
741 For example, recipes that fetch their source from Git usually set
742 <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
743 <note>
744 <filename>BP</filename> represents the "Base Package", which is the base package
745 name and the package version:
746 <literallayout class='monospaced'>
747 BP = ${BPN}-${PV}
748 </literallayout>
749 </note>
750 </para>
751
752 <para>
753 The path to the work directory for the recipe
754 (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) depends
755 on the package name and the architecture of the target device.
756 For example, here is the work directory for packages whose targets are not device-dependent:
757 <literallayout class='monospaced'>
758 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
759 </literallayout>
760 Let's look at an example without variables.
761 Assuming a Yocto Project Files top-level directory named <filename>poky</filename>
762 and a default Yocto Project Build Directory of <filename>poky/build</filename>,
763 the following is the work directory for the <filename>acl</filename> package:
764 <literallayout class='monospaced'>
765 ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3
766 </literallayout>
767 </para>
768
769 <para>
770 If your package is dependent on the target device, the work directory varies slightly:
771 <literallayout class='monospaced'>
772 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
773 </literallayout>
774 Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename>
775 and a default Yocto Project Build Directory of <filename>poky/build</filename>, the
776 following is the work directory for the <filename>acl</filename> package that is being
777 built for a MIPS-based device:
778 <literallayout class='monospaced'>
779 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
780 </literallayout>
781 </para>
782
783 <note>
784 To better understand how the Yocto Project build system resolves directories during the
785 build process, see the glossary entries for the
786 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>,
787 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
788 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>,
789 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
790 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>,
791 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
792 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
793 and
794 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
795 variables in the Yocto Project Reference Manual.
796 </note>
797
798 <para>
799 Now that you know where to locate the directory that has the temporary source code, you can use a
800 Quilt or Git workflow to make your edits, test the changes, and preserve the
801 changes in the form of patches.
802 </para>
803 </section>
804
805 <section id="using-a-quilt-workflow">
806 <title>Using a Quilt Workflow</title>
807
808 <para>
809 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
810 is a powerful tool that allows you to capture source code changes without having
811 a clean source tree.
812 This section outlines the typical workflow you can use to modify temporary source code,
813 test changes, and then preserve the changes in the form of a patch all using Quilt.
814 </para>
815
816 <para>
817 Follow these general steps:
818 <orderedlist>
819 <listitem><para><emphasis>Find the Source Code:</emphasis>
820 The temporary source code used by the Yocto Project build system is kept in the
821 Yocto Project Build Directory.
822 See the
823 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
824 section to learn how to locate the directory that has the temporary source code for a
825 particular package.</para></listitem>
826 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
827 You need to be in the directory that has the temporary source code.
828 That directory is defined by the
829 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
830 variable.</para></listitem>
831 <listitem><para><emphasis>Create a New Patch:</emphasis>
832 Before modifying source code, you need to create a new patch.
833 To create a new patch file, use <filename>quilt new</filename> as below:
834 <literallayout class='monospaced'>
835 $ quilt new my_changes.patch
836 </literallayout></para></listitem>
837 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
838 After creating the patch, you need to notify Quilt about the files you will
839 be changing.
840 Add the files you will be modifying into the patch you just created:
841 <literallayout class='monospaced'>
842 $ quilt add file1.c file2.c file3.c
843 </literallayout></para></listitem>
844 <listitem><para><emphasis>Edit the Files:</emphasis>
845 Make the changes to the temporary source code.</para></listitem>
846 <listitem><para><emphasis>Test Your Changes:</emphasis>
847 Once you have modified the source code, the easiest way to test your changes
848 is by calling the <filename>compile</filename> task as shown in the following example:
849 <literallayout class='monospaced'>
850 $ bitbake -c compile -f &lt;name_of_package&gt;
851 </literallayout>
852 The <filename>-f</filename> or <filename>--force</filename>
853 option forces re-execution of the specified task.
854 If you find problems with your code, you can just keep editing and
855 re-testing iteratively until things work as expected.
856 <note>All the modifications you make to the temporary source code
857 disappear once you <filename>-c clean</filename> or
858 <filename>-c cleanall</filename> with BitBake for the package.
859 Modifications will also disappear if you use the <filename>rm_work</filename>
860 feature as described in the
861 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
862 section of the Yocto Project Quick Start.
863 </note></para></listitem>
864 <listitem><para><emphasis>Generate the Patch:</emphasis>
865 Once your changes work as expected, you need to use Quilt to generate the final patch that
866 contains all your modifications.
867 <literallayout class='monospaced'>
868 $ quilt refresh
869 </literallayout>
870 At this point the <filename>my_changes.patch</filename> file has all your edits made
871 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
872 <filename>file3.c</filename> files.</para>
873 <para>You can find the resulting patch file in the <filename>patches/</filename>
874 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
875 <listitem><para><emphasis>Copy the Patch File:</emphasis>
876 For simplicity, copy the patch file into a directory named <filename>files</filename>,
877 which you can create in the same directory as the recipe.
878 Placing the patch here guarantees that the Yocto Project build system will find
879 the patch.
880 Next, add the patch into the
881 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
882 of the recipe.
883 Here is an example:
884 <literallayout class='monospaced'>
885 SRC_URI += "file://my_changes.patch"
886 </literallayout></para></listitem>
887 <listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
888 Finally, don't forget to 'bump' the
889 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
890 value in the same recipe since the resulting packages have changed.</para></listitem>
891 </orderedlist>
892 </para> </section>
893
894 <section id='using-a-git-workflow'>
895 <title>Using a Git Workflow</title>
896 <para>
897 Git is an even more powerful tool that allows you to capture source code changes without having
898 a clean source tree.
899 This section outlines the typical workflow you can use to modify temporary source code,
900 test changes, and then preserve the changes in the form of a patch all using Git.
901 For general information on Git as it is used in the Yocto Project, see the
902 "<link linkend='git'>Git</link>" section.
903 </para>
904
905 <note>
906 This workflow uses Git only for its ability to manage local changes to the source code
907 and produce patches independent of any version control used on the Yocto Project
908 Files.
909 </note>
910
911 <para>
912 Follow these general steps:
913 <orderedlist>
914 <listitem><para><emphasis>Find the Source Code:</emphasis>
915 The temporary source code used by the Yocto Project build system is kept in the
916 Yocto Project Build Directory.
917 See the
918 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
919 section to learn how to locate the directory that has the temporary source code for a
920 particular package.</para></listitem>
921 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
922 You need to be in the directory that has the temporary source code.
923 That directory is defined by the
924 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
925 variable.</para></listitem>
926 <listitem><para><emphasis>Initialize a Git Repository:</emphasis>
927 Use the <filename>git init</filename> command to initialize a new local repository
928 that is based on the work directory:
929 <literallayout class='monospaced'>
930 $ git init
931 </literallayout></para></listitem>
932 <listitem><para><emphasis>Stage all the files:</emphasis>
933 Use the <filename>git add *</filename> command to stage all the files in the source
934 code directory so that they can be committed:
935 <literallayout class='monospaced'>
936 $ git add *
937 </literallayout></para></listitem>
938 <listitem><para><emphasis>Commit the Source Files:</emphasis>
939 Use the <filename>git commit</filename> command to initially commit all the files in
940 the work directory:
941 <literallayout class='monospaced'>
942 $ git commit
943 </literallayout>
944 At this point, your Git repository is aware of all the source code files.
945 Any edits you now make to files will be tracked by Git.</para></listitem>
946 <listitem><para><emphasis>Edit the Files:</emphasis>
947 Make the changes to the temporary source code.</para></listitem>
948 <listitem><para><emphasis>Test Your Changes:</emphasis>
949 Once you have modified the source code, the easiest way to test your changes
950 is by calling the <filename>compile</filename> task as shown in the following example:
951 <literallayout class='monospaced'>
952 $ bitbake -c compile -f &lt;name_of_package&gt;
953 </literallayout>
954 The <filename>-f</filename> or <filename>--force</filename>
955 option forces re-execution of the specified task.
956 If you find problems with your code, you can just keep editing and
957 re-testing iteratively until things work as expected.
958 <note>All the modifications you make to the temporary source code
959 disappear once you <filename>-c clean</filename> or
960 <filename>-c cleanall</filename> with BitBake for the package.
961 Modifications will also disappear if you use the <filename>rm_work</filename>
962 feature as described in the
963 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
964 section of the Yocto Project Quick Start.
965 </note></para></listitem>
966 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
967 Use the <filename>git status</filename> command to see what files you have actually edited.
968 The ability to have Git track the files you have changed is an advantage that this
969 workflow has over the Quilt workflow.
970 Here is the Git command to list your changed files:
971 <literallayout class='monospaced'>
972 $ git status
973 </literallayout></para></listitem>
974 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
975 Use the <filename>git add</filename> command to stage the changed files so they
976 can be committed as follows:
977 <literallayout class='monospaced'>
978 $ git add file1.c file2.c file3.c
979 </literallayout></para></listitem>
980 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
981 Use the <filename>git commit</filename> command to commit the changes to the
982 local repository.
983 Once you have committed the files, you can use the <filename>git log</filename>
984 command to see your changes:
985 <literallayout class='monospaced'>
986 $ git commit
987 $ git log
988 </literallayout></para></listitem>
989 <listitem><para><emphasis>Generate the Patch:</emphasis>
990 Once the changes are committed, use the <filename>git format-patch</filename>
991 command to generate a patch file:
992 <literallayout class='monospaced'>
993 $ git format-patch HEAD~1
994 </literallayout>
995 The <filename>HEAD~1</filename> part of the command causes Git to generate the
996 patch file for the most recent commit.</para>
997 <para>At this point, the patch file has all your edits made
998 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
999 <filename>file3.c</filename> files.
1000 You can find the resulting patch file in the current directory.
1001 The patch file ends with <filename>.patch</filename>.</para></listitem>
1002 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1003 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1004 which you can create in the same directory as the recipe.
1005 Placing the patch here guarantees that the Yocto Project build system will find
1006 the patch.
1007 Next, add the patch into the
1008 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1009 of the recipe.
1010 Here is an example:
1011 <literallayout class='monospaced'>
1012 SRC_URI += "file://my_changes.patch"
1013 </literallayout></para></listitem>
1014 <listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
1015 Finally, don't forget to 'bump' the
1016 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1017 value in the same recipe since the resulting packages have changed.</para></listitem>
1018 </orderedlist>
1019 </para>
1020 </section>
1021</section>
1022
703<section id='image-development-using-hob'> 1023<section id='image-development-using-hob'>
704 <title>Image Development Using Hob</title> 1024 <title>Image Development Using Hob</title>
705 1025
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-24 04:58:32 +0000