diff options
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 327 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 374 |
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 <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 | ||
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 <name_of_package> | ||
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 <name_of_package> | ||
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 | ||