diff options
Diffstat (limited to 'documentation/poky-ref-manual/extendpoky.xml')
-rw-r--r-- | documentation/poky-ref-manual/extendpoky.xml | 120 |
1 files changed, 47 insertions, 73 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml index 8c1e343889..4fef075360 100644 --- a/documentation/poky-ref-manual/extendpoky.xml +++ b/documentation/poky-ref-manual/extendpoky.xml | |||
@@ -472,37 +472,58 @@ | |||
472 | <title>Customizing Images Using <filename>local.conf</filename></title> | 472 | <title>Customizing Images Using <filename>local.conf</filename></title> |
473 | 473 | ||
474 | <para> | 474 | <para> |
475 | While not recommended, it is possible to include or exclude packages in the | 475 | It is possible to customize image contents by using variables from your |
476 | image by setting variables in the <filename>conf/local.conf</filename> file in | 476 | local configuration in your <filename>conf/local.conf</filename> file. |
477 | the Yocto Project build directory. | 477 | Because it is limited to local use, this method generally only allows you to |
478 | <note> | 478 | add packages and is not as flexible as creating your own customized image. |
479 | The best way to add packages to an image is to create a layer that contains | 479 | When you add packages using local variables this way, you need to realize that |
480 | recipes to specifically add the packages. | 480 | these variable changes affect all images at the same time and might not be |
481 | Using variables with the <filename>local.conf</filename> to add things | 481 | what you require. |
482 | to images could result in ordering problems or even leave you with a | ||
483 | build system that seemingly adds "random" packages to the image. | ||
484 | For example, if you use the same or a copied <filename>local.conf</filename> | ||
485 | for another project, you might have forgotten about something you added | ||
486 | for a previous project. | ||
487 | </note> | ||
488 | This section describes some of the ways you could include or exclude packages | ||
489 | in the image through use of the <filename>conf/local.conf</filename> file. | ||
490 | </para> | 482 | </para> |
491 | 483 | ||
492 | <section id='adding-packages'> | 484 | <section id='adding-packages'> |
493 | <title>Adding Packages</title> | 485 | <title>Adding Packages</title> |
494 | 486 | ||
495 | <para> | 487 | <para> |
496 | Following are some methods to add packages to the image through the | 488 | The simplest way to add extra packages to all images is by using the |
497 | use of variables in the <filename>conf/local.conf</filename>: | 489 | <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename> |
498 | <itemizedlist> | 490 | variable with the <filename>_append</filename> operator: |
499 | <listitem><para><emphasis><filename>IMAGE_INSTALL_append</filename> - </emphasis> | 491 | <literallayout class='monospaced'> |
500 | Some explanation</para></listitem> | 492 | IMAGE_INSTALL_append = " strace" |
501 | <listitem><para><emphasis><filename>POKY_EXTRA_append</filename> - </emphasis> | 493 | </literallayout> |
502 | Some explanation</para></listitem> | 494 | Use of the syntax is important. |
503 | <listitem><para><emphasis><filename>POKY_EXTRA_INSTALL</filename> - </emphasis> | 495 | Specifically, the space between the quote and the package name, which is |
504 | Some explanation</para></listitem> | 496 | <filename>strace</filename> in this example. |
505 | </itemizedlist> | 497 | This space is required since the <filename>_append</filename> |
498 | operator does not add the space. | ||
499 | </para> | ||
500 | |||
501 | <para> | ||
502 | Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename> | ||
503 | operator if you want to avoid ordering issues. | ||
504 | The reason for this is because doing so uncondtionally appends to the variable and | ||
505 | avoids ordering problems due to the variable being set in image recipes and | ||
506 | <filename>.bbclass</filename> files with operators like <filename>?=</filename>. | ||
507 | Using <filename>_append</filename> ensures the operation takes affect. | ||
508 | </para> | ||
509 | |||
510 | <para> | ||
511 | As shown in its simplest use, <filename>IMAGE_INSTALL_append</filename> affects | ||
512 | all images. | ||
513 | It is possible to extend the syntax so that the variable applies to a specific image only. | ||
514 | Here is an example: | ||
515 | <literallayout class='monospaced'> | ||
516 | IMAGE_INSTALL_append_pn-core-image-minimal = " strace" | ||
517 | </literallayout> | ||
518 | This example adds <filename>strace</filename> to <filename>core-image-minimal</filename> | ||
519 | only. | ||
520 | </para> | ||
521 | |||
522 | <para> | ||
523 | You can add packages using a similar approach through the | ||
524 | <filename><link linkend='var-POKY_EXTRA_INSTALL'>POKY_EXTRA_INSTALL</link></filename> | ||
525 | variable. | ||
526 | If you use this variable, only <filename>core-image-*</filename> images are affected. | ||
506 | </para> | 527 | </para> |
507 | </section> | 528 | </section> |
508 | 529 | ||
@@ -513,7 +534,7 @@ | |||
513 | It is possible to filter or mask out recipe and recipe append files such that | 534 | It is possible to filter or mask out recipe and recipe append files such that |
514 | BitBake ignores them. | 535 | BitBake ignores them. |
515 | You can do this by providing an expression with the | 536 | You can do this by providing an expression with the |
516 | <filename>BBMASK</filename> variable. | 537 | <filename><link linkend='var-BBMASK'>BBMASK</link></filename> variable. |
517 | Here is an example: | 538 | Here is an example: |
518 | <literallayout class='monospaced'> | 539 | <literallayout class='monospaced'> |
519 | BBMASK = ".*/meta-mymachine/recipes-maybe/" | 540 | BBMASK = ".*/meta-mymachine/recipes-maybe/" |
@@ -523,53 +544,6 @@ | |||
523 | process. | 544 | process. |
524 | </para> | 545 | </para> |
525 | </section> | 546 | </section> |
526 | <!-- | ||
527 | THIS IS THE ORIGINAL STUFF | ||
528 | |||
529 | <section id='usingpoky-extend-customimage-localconf'> | ||
530 | <title>Customizing Images Using <filename>local.conf</filename></title> | ||
531 | |||
532 | <para> | ||
533 | It is possible to customize image contents by using variables used by distribution | ||
534 | maintainers in the <filename>local.conf</filename> found in the Yocto Project | ||
535 | build directory. | ||
536 | This method only allows the addition of packages and is not recommended. | ||
537 | </para> | ||
538 | |||
539 | <para> | ||
540 | For example, to add the <filename>strace</filename> package into the image, | ||
541 | you would add this package to the <filename>local.conf</filename> file: | ||
542 | <literallayout class='monospaced'> | ||
543 | DISTRO_EXTRA_RDEPENDS += "strace" | ||
544 | </literallayout> | ||
545 | </para> | ||
546 | |||
547 | <para> | ||
548 | However, since the | ||
549 | <filename><link linkend='var-DISTRO_EXTRA_RDEPENDS'>DISTRO_EXTRA_RDEPENDS</link></filename> | ||
550 | variable is for distribution maintainers, adding packages using this method is not | ||
551 | as simple as adding them using a custom <filename>.bb</filename> file. | ||
552 | Using the <filename>local.conf</filename> file method could result in some packages | ||
553 | needing to be recreated. | ||
554 | For example, if packages were previously created and the image was rebuilt, then the packages | ||
555 | would need to be recreated. | ||
556 | </para> | ||
557 | |||
558 | <para> | ||
559 | Cleaning <filename>task-*</filename> packages are required because they use the | ||
560 | <filename>DISTRO_EXTRA_RDEPENDS</filename> variable. | ||
561 | You do not have to build them by hand because Yocto Project images depend on the | ||
562 | packages they contain. | ||
563 | This means dependencies are automatically built when the image builds. | ||
564 | For this reason we do not use the <filename>rebuild</filename> task. | ||
565 | In this case the <filename>rebuild</filename> task does not care about | ||
566 | dependencies - it only rebuilds the specified package. | ||
567 | <literallayout class='monospaced'> | ||
568 | $ bitbake -c clean task-boot task-base task-poky | ||
569 | $ bitbake core-image-sato | ||
570 | </literallayout> | ||
571 | </para> | ||
572 | </section> --> | ||
573 | </section> | 547 | </section> |
574 | </section> | 548 | </section> |
575 | 549 | ||