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