From ba0e818504408df89612c53ad5e45ffef846fa02 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 30 Jan 2012 17:11:38 -0600 Subject: 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 Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/extendpoky.xml | 120 ++++++++++-------------- documentation/poky-ref-manual/ref-variables.xml | 39 +++++++- 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 @@ Customizing Images Using <filename>local.conf</filename> - While not recommended, it is possible to include or exclude packages in the - image by setting variables in the conf/local.conf file in - the Yocto Project build directory. - - The best way to add packages to an image is to create a layer that contains - recipes to specifically add the packages. - Using variables with the local.conf to add things - to images could result in ordering problems or even leave you with a - build system that seemingly adds "random" packages to the image. - For example, if you use the same or a copied local.conf - for another project, you might have forgotten about something you added - for a previous project. - - This section describes some of the ways you could include or exclude packages - in the image through use of the conf/local.conf file. + It is possible to customize image contents by using variables from your + local configuration in your conf/local.conf file. + Because it is limited to local use, this method generally only allows you to + add packages and is not as flexible as creating your own customized image. + When you add packages using local variables this way, you need to realize that + these variable changes affect all images at the same time and might not be + what you require.
Adding Packages - Following are some methods to add packages to the image through the - use of variables in the conf/local.conf: - - IMAGE_INSTALL_append - - Some explanation - POKY_EXTRA_append - - Some explanation - POKY_EXTRA_INSTALL - - Some explanation - + The simplest way to add extra packages to all images is by using the + IMAGE_INSTALL + variable with the _append operator: + + IMAGE_INSTALL_append = " strace" + + Use of the syntax is important. + Specifically, the space between the quote and the package name, which is + strace in this example. + This space is required since the _append + operator does not add the space. + + + + Furthermore, you must use _append instead of the += + operator if you want to avoid ordering issues. + The reason for this is because doing so uncondtionally appends to the variable and + avoids ordering problems due to the variable being set in image recipes and + .bbclass files with operators like ?=. + Using _append ensures the operation takes affect. + + + + As shown in its simplest use, IMAGE_INSTALL_append affects + all images. + It is possible to extend the syntax so that the variable applies to a specific image only. + Here is an example: + + IMAGE_INSTALL_append_pn-core-image-minimal = " strace" + + This example adds strace to core-image-minimal + only. + + + + You can add packages using a similar approach through the + POKY_EXTRA_INSTALL + variable. + If you use this variable, only core-image-* images are affected.
@@ -513,7 +534,7 @@ It is possible to filter or mask out recipe and recipe append files such that BitBake ignores them. You can do this by providing an expression with the - BBMASK variable. + BBMASK variable. Here is an example: BBMASK = ".*/meta-mymachine/recipes-maybe/" @@ -523,53 +544,6 @@ process. - 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 @@ IMAGE_INSTALL - The list of packages used to build images. + + Specifies the packages to install into an image. + The IMAGE_INSTALL variable is a mechanism for an image + recipe and you should use it with care to avoid ordering issues. + + + + Image recipes set IMAGE_INSTALL to specify the + packages to install into an image through image.bbclass. + Additionally, "helper" classes exist, such as core-image.bbclass, + that can take + IMAGE_FEATURE lists + and turn these into auto-generated entries in + IMAGE_INSTALL in addition to its default contents. + + + + Using IMAGE_INSTALL with the += + operator from the /conf/local.conf file or from within + an image recipe is not recommended as it can cause ordering issues. + Since core-image.bbclass sets IMAGE_INSTALL + to a default value using the ?= operator, using a + += operation against IMAGE_INSTALL + previously from the /conf/local.conf will almost always fail. + Furthermore, the same operation from with an image recipe may or may not + succeed depending on the specific situation. + In both these cases, the behavior is contrary to how most users expect + the += append operator to work. + + + + When you use this variable, it is best to use it as follows: + + IMAGE_INSTALL_append " package-name" + + Be sure to include the space between the quotation character and the start of the + package name. + -- cgit v1.2.3-54-g00ecf