diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index cd2808dfcf..02e77e8dd6 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -887,105 +887,68 @@
This section describes several methods and provides guidelines for each.
-
- Customizing Images Using Custom .bb Files
+
+ Customizing Images Using local.conf
- One way to customize an image is to create a custom recipe
- that defines additional software as part of the image.
- The following example shows the form for the two lines you need:
-
- IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
-
- inherit core-image
-
+ Probably the easiest way to customize an image is to add a
+ package by way of the local.conf
+ configuration 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.
- Defining the software using a custom recipe gives you total
- control over the contents of the image.
- It is important to use the correct names of packages in the
+ To add a package to your image using the local configuration
+ file, use 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 unconditionally 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
+ CORE_IMAGE_EXTRA_INSTALL
variable.
- You must use the OpenEmbedded notation and not the Debian notation for the names
- (e.g. eglibc-dev instead of libc6-dev).
-
-
-
- The other method for creating a custom image is to base it on an existing image.
- For example, if you want to create an image based on core-image-sato
- but add the additional package strace to the image,
- copy the meta/recipes-sato/images/core-image-sato.bb to a
- new .bb and add the following line to the end of the copy:
-
- IMAGE_INSTALL += "strace"
-
-
-
-
-
- Customizing Images Using Custom Package Groups
-
-
- For complex custom images, the best approach is to create a
- custom package group recipe that is used to build the image or
- images.
- A good example of a package group recipe is
- meta/recipes-core/packagegroups/packagegroup-core-boot.bb.
- The
- PACKAGES
- variable lists the package group packages you wish to produce.
- inherit packagegroup sets appropriate
- default values and automatically adds -dev,
- -dbg, and -ptest
- complementary packages for every package specified in
- PACKAGES.
- Note that the inherit line should be towards
- the top of the recipe, certainly before you set
- PACKAGES.
- For each package you specify in PACKAGES,
- you can use
- RDEPENDS
- and
- RRECOMMENDS
- entries to provide a list of packages the parent task package
- should contain.
- Following is an example:
-
- DESCRIPTION = "My Custom Package Groups"
-
- inherit packagegroup
-
- PACKAGES = "\
- packagegroup-custom-apps \
- packagegroup-custom-tools \
- "
-
- RDEPENDS_packagegroup-custom-apps = "\
- dropbear \
- portmap \
- psplash"
-
- RDEPENDS_packagegroup-custom-tools = "\
- oprofile \
- oprofileui-server \
- lttng-control \
- lttng-viewer"
-
- RRECOMMENDS_packagegroup-custom-tools = "\
- kernel-module-oprofile"
-
-
-
-
- In the previous example, two package group packages are created with their dependencies and their
- recommended package dependencies listed: packagegroup-custom-apps, and
- packagegroup-custom-tools.
- To build an image using these package group packages, you need to add
- packagegroup-custom-apps and/or
- packagegroup-custom-tools to
- IMAGE_INSTALL.
- For other forms of image dependencies see the other areas of this section.
+ If you use this variable, only
+ core-image-* images are affected.
@@ -994,8 +957,8 @@
EXTRA_IMAGE_FEATURES
- You might want to customize your image by enabling or
- disabling high-level image features by using the
+ Another method for customizing your image is to enable or
+ disable high-level image features by using the
IMAGE_FEATURES
and EXTRA_IMAGE_FEATURES
variables.
@@ -1070,59 +1033,105 @@
-
- Customizing Images Using local.conf
+
+ Customizing Images Using Custom .bb Files
- 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.
+ You can also customize an image by creating a custom recipe
+ that defines additional software as part of the image.
+ The following example shows the form for the two lines you need:
+
+ IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
+
+ inherit core-image
+
- The simplest way to add extra packages to all images is by using the
+ Defining the software using a custom recipe gives you total
+ control over the contents of the image.
+ It is important to use the correct names of packages in 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 unconditionally 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
- CORE_IMAGE_EXTRA_INSTALL
variable.
- If you use this variable, only core-image-* images are affected.
+ You must use the OpenEmbedded notation and not the Debian notation for the names
+ (e.g. eglibc-dev instead of libc6-dev).
+
+
+
+ The other method for creating a custom image is to base it on an existing image.
+ For example, if you want to create an image based on core-image-sato
+ but add the additional package strace to the image,
+ copy the meta/recipes-sato/images/core-image-sato.bb to a
+ new .bb and add the following line to the end of the copy:
+
+ IMAGE_INSTALL += "strace"
+
+
+
+
+
+ Customizing Images Using Custom Package Groups
+
+
+ For complex custom images, the best approach for customizing
+ an image is to create a custom package group recipe that is
+ used to build the image or images.
+ A good example of a package group recipe is
+ meta/recipes-core/packagegroups/packagegroup-core-boot.bb.
+ The
+ PACKAGES
+ variable lists the package group packages you wish to produce.
+ inherit packagegroup sets appropriate
+ default values and automatically adds -dev,
+ -dbg, and -ptest
+ complementary packages for every package specified in
+ PACKAGES.
+ Note that the inherit line should be towards
+ the top of the recipe, certainly before you set
+ PACKAGES.
+ For each package you specify in PACKAGES,
+ you can use
+ RDEPENDS
+ and
+ RRECOMMENDS
+ entries to provide a list of packages the parent task package
+ should contain.
+ Following is an example:
+
+ DESCRIPTION = "My Custom Package Groups"
+
+ inherit packagegroup
+
+ PACKAGES = "\
+ packagegroup-custom-apps \
+ packagegroup-custom-tools \
+ "
+
+ RDEPENDS_packagegroup-custom-apps = "\
+ dropbear \
+ portmap \
+ psplash"
+
+ RDEPENDS_packagegroup-custom-tools = "\
+ oprofile \
+ oprofileui-server \
+ lttng-control \
+ lttng-viewer"
+
+ RRECOMMENDS_packagegroup-custom-tools = "\
+ kernel-module-oprofile"
+
+
+
+
+ In the previous example, two package group packages are created with their dependencies and their
+ recommended package dependencies listed: packagegroup-custom-apps, and
+ packagegroup-custom-tools.
+ To build an image using these package group packages, you need to add
+ packagegroup-custom-apps and/or
+ packagegroup-custom-tools to
+ IMAGE_INSTALL.
+ For other forms of image dependencies see the other areas of this section.