diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 189a4ffe01..f55e99122b 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -445,6 +445,228 @@
+
+ Customizing Images
+
+
+ You can customize Yocto Project images to satisfy particular requirements.
+ This section describes several methods and provides guidelines for each.
+
+
+
+ Customizing Images Using Custom .bb Files
+
+
+ One way to get additional software into an image is to create a custom image.
+ The following example shows the form for the two lines you need:
+
+ IMAGE_INSTALL = "task-core-x11-base package1 package2"
+
+ inherit core-image
+
+
+
+
+ By creating a custom image, a developer has total control
+ over the contents of the image.
+ It is important to use the correct names of packages in the
+ IMAGE_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 modify an existing image.
+ For example, if a developer wants to add strace into
+ the core-image-sato image, they can use the following recipe:
+
+ require core-image-sato.bb
+
+ IMAGE_INSTALL += "strace"
+
+
+
+
+
+ Customizing Images Using Custom Tasks
+
+
+ For complex custom images, the best approach is to create a custom task package
+ that is used to build the image or images.
+ A good example of a tasks package is
+ meta/recipes-sato/tasks/task-poky.bb.
+ The
+ PACKAGES
+ variable lists the task packages to build along with the complementary
+ -dbg and -dev packages.
+ For each package added, 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 Tasks"
+
+ PACKAGES = "\
+ task-custom-apps \
+ task-custom-apps-dbg \
+ task-custom-apps-dev \
+ task-custom-tools \
+ task-custom-tools-dbg \
+ task-custom-tools-dev \
+ "
+
+ RDEPENDS_task-custom-apps = "\
+ dropbear \
+ portmap \
+ psplash"
+
+ RDEPENDS_task-custom-tools = "\
+ oprofile \
+ oprofileui-server \
+ lttng-control \
+ lttng-viewer"
+
+ RRECOMMENDS_task-custom-tools = "\
+ kernel-module-oprofile"
+
+
+
+
+ In the previous example, two task packages are created with their dependencies and their
+ recommended package dependencies listed: task-custom-apps, and
+ task-custom-tools.
+ To build an image using these task packages, you need to add
+ task-custom-apps and/or
+ task-custom-tools to
+ IMAGE_INSTALL.
+ For other forms of image dependencies see the other areas of this section.
+
+
+
+
+ Customizing Images Using Custom IMAGE_FEATURES and
+ EXTRA_IMAGE_FEATURES
+
+
+ Ultimately users might want to add extra image features to the set used by
+ Yocto Project with the
+ IMAGE_FEATURES
+ variable.
+ To create these features, the best reference is
+ meta/classes/core-image.bbclass, which shows how the
+ Yocto Project achieves this.
+ In summary, the file looks at the contents of the
+ IMAGE_FEATURES
+ variable and then maps that into a set of tasks or packages.
+ Based on this information the
+ IMAGE_INSTALL
+ variable is generated automatically.
+ Users can add extra features by extending the class or creating a custom class for use
+ with specialized image .bb files.
+ You can also add more features by configuring the
+ EXTRA_IMAGE_FEATURES
+ variable in the local.conf file found in the Yocto Project
+ files located in the build directory.
+
+
+
+ The Yocto Project ships with two SSH servers you can use in your images:
+ Dropbear and OpenSSH.
+ Dropbear is a minimal SSH server appropriate for resource-constrained environments,
+ while OpenSSH is a well-known standard SSH server implementation.
+ By default, the core-image-sato image is configured to use Dropbear.
+ The core-image-basic and core-image-lsb
+ images both include OpenSSH.
+ To change these defaults, edit the IMAGE_FEATURES variable
+ so that it sets the image you are working with to include
+ ssh-server-dropbear or ssh-server-openssh.
+
+
+
+
+ Customizing Images Using local.conf
+
+
+ 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
+
+
+ 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 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.
+
+
+
+
+ Excluding Packages
+
+
+ It is possible to filter or mask out .bb and
+ .bbappend files such that BitBake ignores them during
+ the build.
+ You can do this by providing an expression with the
+ BBMASK
+ variable.
+ Here is an example:
+
+ BBMASK = ".*/meta-mymachine/recipes-maybe/"
+
+ Here, all .bb and .bbappend files
+ in the directory that matches the expression are ignored during the build
+ process.
+
+
+
+
+
Adding a Package
@@ -774,228 +996,6 @@
-
- Customizing Images
-
-
- You can customize Yocto Project images to satisfy particular requirements.
- This section describes several methods and provides guidelines for each.
-
-
-
- Customizing Images Using Custom .bb Files
-
-
- One way to get additional software into an image is to create a custom image.
- The following example shows the form for the two lines you need:
-
- IMAGE_INSTALL = "task-core-x11-base package1 package2"
-
- inherit core-image
-
-
-
-
- By creating a custom image, a developer has total control
- over the contents of the image.
- It is important to use the correct names of packages in the
- IMAGE_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 modify an existing image.
- For example, if a developer wants to add strace into
- the core-image-sato image, they can use the following recipe:
-
- require core-image-sato.bb
-
- IMAGE_INSTALL += "strace"
-
-
-
-
-
- Customizing Images Using Custom Tasks
-
-
- For complex custom images, the best approach is to create a custom task package
- that is used to build the image or images.
- A good example of a tasks package is
- meta/recipes-sato/tasks/task-poky.bb.
- The
- PACKAGES
- variable lists the task packages to build along with the complementary
- -dbg and -dev packages.
- For each package added, 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 Tasks"
-
- PACKAGES = "\
- task-custom-apps \
- task-custom-apps-dbg \
- task-custom-apps-dev \
- task-custom-tools \
- task-custom-tools-dbg \
- task-custom-tools-dev \
- "
-
- RDEPENDS_task-custom-apps = "\
- dropbear \
- portmap \
- psplash"
-
- RDEPENDS_task-custom-tools = "\
- oprofile \
- oprofileui-server \
- lttng-control \
- lttng-viewer"
-
- RRECOMMENDS_task-custom-tools = "\
- kernel-module-oprofile"
-
-
-
-
- In the previous example, two task packages are created with their dependencies and their
- recommended package dependencies listed: task-custom-apps, and
- task-custom-tools.
- To build an image using these task packages, you need to add
- task-custom-apps and/or
- task-custom-tools to
- IMAGE_INSTALL.
- For other forms of image dependencies see the other areas of this section.
-
-
-
-
- Customizing Images Using Custom IMAGE_FEATURES and
- EXTRA_IMAGE_FEATURES
-
-
- Ultimately users might want to add extra image features to the set used by
- Yocto Project with the
- IMAGE_FEATURES
- variable.
- To create these features, the best reference is
- meta/classes/core-image.bbclass, which shows how the
- Yocto Project achieves this.
- In summary, the file looks at the contents of the
- IMAGE_FEATURES
- variable and then maps that into a set of tasks or packages.
- Based on this information the
- IMAGE_INSTALL
- variable is generated automatically.
- Users can add extra features by extending the class or creating a custom class for use
- with specialized image .bb files.
- You can also add more features by configuring the
- EXTRA_IMAGE_FEATURES
- variable in the local.conf file found in the Yocto Project
- files located in the build directory.
-
-
-
- The Yocto Project ships with two SSH servers you can use in your images:
- Dropbear and OpenSSH.
- Dropbear is a minimal SSH server appropriate for resource-constrained environments,
- while OpenSSH is a well-known standard SSH server implementation.
- By default, the core-image-sato image is configured to use Dropbear.
- The core-image-basic and core-image-lsb
- images both include OpenSSH.
- To change these defaults, edit the IMAGE_FEATURES variable
- so that it sets the image you are working with to include
- ssh-server-dropbear or ssh-server-openssh.
-
-
-
-
- Customizing Images Using local.conf
-
-
- 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
-
-
- 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 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.
-
-
-
-
- Excluding Packages
-
-
- It is possible to filter or mask out .bb and
- .bbappend files such that BitBake ignores them during
- the build.
- You can do this by providing an expression with the
- BBMASK
- variable.
- Here is an example:
-
- BBMASK = ".*/meta-mymachine/recipes-maybe/"
-
- Here, all .bb and .bbappend files
- in the directory that matches the expression are ignored during the build
- process.
-
-
-
-
-
Porting the Yocto Project to a New Machine