summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-01-30 17:11:38 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-03-08 12:07:46 -0800
commitba0e818504408df89612c53ad5e45ffef846fa02 (patch)
tree2142871bcdd72f53f0c665500c78f294adf25ace
parent2a0a3d631a67dee5a2592fef64ea203c42da8f7d (diff)
downloadpoky-ba0e818504408df89612c53ad5e45ffef846fa02.tar.gz
documentation/poky-ref-manual: Updates to IMAGE_INSTALL
Updated the glossary entry for the IMAGE_INSTALL variable. It was not complete. I also updated the section that describes how to modify the image through the local.conf file. These edits are out on review with Richard and could undergo some further tweaks. Fixes [YOCTO #1897] (From yocto-docs rev: 41124cdd9e69b9f17300a609cce2ae4c9ce57b54) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml120
-rw-r--r--documentation/poky-ref-manual/ref-variables.xml39
2 files changed, 85 insertions, 74 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<!--
527THIS 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
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 1a958773b9..8efd46a848 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -533,7 +533,44 @@
533 533
534 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm> 534 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
535 <glossdef> 535 <glossdef>
536 <para>The list of packages used to build images.</para> 536 <para>
537 Specifies the packages to install into an image.
538 The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
539 recipe and you should use it with care to avoid ordering issues.
540 </para>
541
542 <para>
543 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
544 packages to install into an image through <filename>image.bbclass</filename>.
545 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
546 that can take
547 <filename><link linkend='var-IMAGE_FEATURE'>IMAGE_FEATURE</link></filename> lists
548 and turn these into auto-generated entries in
549 <filename>IMAGE_INSTALL</filename> in addition to its default contents.
550 </para>
551
552 <para>
553 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
554 operator from the <filename>/conf/local.conf</filename> file or from within
555 an image recipe is not recommended as it can cause ordering issues.
556 Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
557 to a default value using the <filename>?=</filename> operator, using a
558 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
559 previously from the <filename>/conf/local.conf</filename> will almost always fail.
560 Furthermore, the same operation from with an image recipe may or may not
561 succeed depending on the specific situation.
562 In both these cases, the behavior is contrary to how most users expect
563 the <filename>+=</filename> append operator to work.
564 </para>
565
566 <para>
567 When you use this variable, it is best to use it as follows:
568 <literallayout class='monospaced'>
569 IMAGE_INSTALL_append " package-name"
570 </literallayout>
571 Be sure to include the space between the quotation character and the start of the
572 package name.
573 </para>
537 </glossdef> 574 </glossdef>
538 </glossentry> 575 </glossentry>
539 576