summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml327
1 files changed, 4 insertions, 323 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
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-24 02:49:11 +0000