diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 327 |
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 <name_of_package> | ||
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 <name_of_package> | ||
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 | ||