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 <filename>IMAGE_FEATURES</filename> and + <filename>EXTRA_IMAGE_FEATURES</filename> + + + 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 <filename>local.conf</filename> + + + 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 <filename>IMAGE_FEATURES</filename> and - <filename>EXTRA_IMAGE_FEATURES</filename> - - - 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 <filename>local.conf</filename> - - - 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