From c38b2de6305ea192096c0c9cad04bd12237f2fc1 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 2 Mar 2012 17:21:55 -0600 Subject: documentation/dev-manual: New Layer section and metadata link anchor The change to the dev-manual-newbie.xml file was minor. I added a link anchor for the term "metadata." The change to the dev-manual-common-tasks.xml was extensive. I have added an entirely new section on layers called "Understanding and Using Layers." The new material has several sub-sections. Information was based on emails from Paul Eggleton. (From yocto-docs rev: 4fb34abd60180fc2482ddb9f62e476763cee7679) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 392 ++++++++++++++++----- documentation/dev-manual/dev-manual-newbie.xml | 5 +- 2 files changed, 306 insertions(+), 91 deletions(-) (limited to 'documentation/dev-manual') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index ab140207aa..ad4a7613a9 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -16,58 +16,87 @@
Understanding and Creating Layers - - Often, developers want to extend the Yocto Project either by adding packages - or by overriding files contained within the Yocto Project to add their own - functionality. - BitBake has a powerful mechanism called - "layers", which provides a way to handle this extension in a fully - supported and non-invasive fashion. - - The Yocto Project files include several additional layers such as - meta-rt and meta-yocto - that demonstrate this functionality. - The meta-rt layer is not enabled by default. - However, the meta-yocto layer is. + The Yocto Project build system supports organizing metadata + into multiple layers. + Layers allow you to isolate different types of customizations from each other. + You might find it tempting to keep everything in one layer when working on a single project. + However, the more modular you organize your metadata, the easier it is to cope with future changes. - To enable a layer, you simply add the layer's path to the - BBLAYERS - variable in your - conf/bblayers.conf file, which is found in the - Yocto Project Build Directory. - The following example shows how to enable the meta-rt: - - LCONF_VERSION = "1" - - BBFILES ?= "" - BBLAYERS = " \ - /path/to/poky/meta \ - /path/to/poky/meta-yocto \ - /path/to/poky/meta-rt \ - " - + To illustrate how layers are used to keep things modular, consider machine customizations. + These types of customizations typically reside in a BSP Layer. + Furthermore, the machine customizations should be isolated from recipes and metadata that support + a new GUI environment, for example. + This situation gives you a couple a layers: one for the machine configurations, and one for the + GUI environment. + It is important to understand, however, that the BSP layer can still make machine-specific + additions to recipes within the GUI environment layer without polluting the GUI layer itself + with those machine-specific changes. + You can accomplish this through an appending recipe (a .bbappend file), + which is described later in this section. - BitBake parses each conf/layer.conf file for each layer in - BBLAYERS - and adds the recipes, classes and configurations contained within the layer to - the Yocto Project. - To create your own layer, independent of the Yocto Project files, - simply create a directory with a conf/layer.conf file and - add the directory to your bblayers.conf file. - - The meta-yocto/conf/layer.conf file demonstrates the - required syntax: - +
+ Yocto Project Layers + + + The Yocto Project contains several layers right out of the box. + You can easily identify a layer in the Yocto Project by the name of its folder. + Folders that are layers begin with the string meta. + For example, when you set up the Yocto Project Files + structure, you will see several layers: meta, meta-demoapps, + meta-skeleton, and meta-yocto. + Each of these folders is a layer. + + + + Furthermore, if you set up a local copy of the meta-intel Git repository + and then explore that folder, you will discover many BSP layers within the + meta-intel layer. + For more information on BSP layers, see the + "BSP Layers" + section in the Yocto Project Development Manual. + +
+ +
+ Creating Your Own Layer + + + It is very easy to create your own layer to use with the Yocto Project. + Follow these general steps to create your layer: + + Check Existing Layers: Before creating a new layer, + you should be sure someone has not already created a layer containing the metadata + you need. + You can see the + LayerIndex + to determine what types of layers already exist in the Yocto Project. + Create a Directory: Create the directory + for your layer. + Traditionally, prepend the name of the folder with the string + meta. + For example: + + meta-mylayer + meta-GUI_xyz + meta-mymachine + + Create a Layer Configuration File: Inside your new + layer folder, you need to create a conf/layer.conf file. + It is easiest to take an existing layer configuration file and copy that to your + layer's conf directory and then modify the file as needed. + The meta-yocto/conf/layer.conf file demonstrates the + required syntax: + # We have a conf and classes directory, add to BBPATH - BBPATH := "${BBPATH}:${LAYERDIR}" + BBPATH := "${LAYERDIR}:${BBPATH}" # We have a packages directory, add to BBFILES BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \ @@ -76,58 +105,243 @@ BBFILE_COLLECTIONS += "yocto" BBFILE_PATTERN_yocto := "^${LAYERDIR}/" BBFILE_PRIORITY_yocto = "5" - - + + In the previous example, the recipes for the layers are added to + BBFILES. + The + BBFILE_COLLECTIONS + variable is then appended with the layer name. + The + BBFILE_PATTERN + variable immediately expands with a regular expression used to match files from + BBFILES into a particular layer, in this case by using + the base pathname. + The + BBFILE_PRIORITY + variable then assigns different priorities to the files in different layers. + Applying priorities is useful in situations where the same package might appear in multiple + layers and allows you to choose what layer should take precedence. + Note the use of the + LAYERDIR + variable with the immediate expansion operator. + The LAYERDIR variable expands to the directory of the current layer and + requires the immediate expansion operator so that BitBake does not wait to expand the variable + when it's parsing a different directory. + BitBake can locate where other .bbclass and configuration files + are applied through the BBPATH environment variable. + For these cases, BitBake uses the first file with the matching name found in + BBPATH. + This is similar to the way the PATH variable is used for binaries. + We recommend, therefore, that you use unique .bbclass + and configuration file names in your custom layer. + Add Content: Depending on the type of layer, + add the content. + If the layer adds support for a machine, add the machine configuration in + a conf/machine/ file within the layer. + If the layer adds distro policy, add the distro configuration in a + conf/distro/ file with the layer. + If the layer introduces new recipes, put the recipes you need in + recipes-* subdirectories within the layer. + + - - In the previous example, the recipes for the layers are added to - BBFILES. - The - BBFILE_COLLECTIONS - variable is then appended with the layer name. - The - BBFILE_PATTERN - variable immediately expands with a regular expression used to match files from - BBFILES into - a particular layer, in this case by using the base pathname. - The - BBFILE_PRIORITY - variable - then assigns different priorities to the files in different layers. - Applying priorities is useful in situations where the same package might appear in multiple - layers and allows you to choose what layer should take precedence. - + + To create layers that are easier to maintain, you should consider the following: + + Avoid "overlaying" entire recipes from other layers in your + configuration. + In other words, don't copy an entire recipe into your layer and then modify it. + Use .bbappend files to override the parts of the + recipe you need to modify. + Avoid duplicating include files. + Use .bbappend files for each recipe that uses an include + file. + Or, if you are introducing a new recipe that requires the inc file, use the + full path to refer to the original. + For example, use require recipes-core/somepackage/somefile.inc + instead of require somefile.inc. + If you're finding you have to overlay the include file, it could indicate a + deficiency in the include file in the layer to which it originally belongs. + If this is the case, you need to address that deficiency instead of overlaying + the include file. + For example, consider how Qt 4 database support plugins are configured. + The Yocto Project does not have MySQL or PostgreSQL, however OpenEmbedded's + layer meta-oe does. + Consequently, meta-oe uses .bbappend + files to modify the QT_SQL_DRIVER_FLAGS variable to enable + the appropriate plugins. + This variable was added to the qt4.inc include file in + The Yocto Project specifically to allow the meta-oe layer + to be able to control which plugins are built. + + + + + We also recommend the following: + + Store custom layers in a Git repository that uses the + meta-prvt-XXXX format. + Clone the repository alongside other meta + directories in the Yocto Project source files area. + + Following these recommendations keeps your Yocto Project files area and + its configuration entirely inside the Yocto Project's core base. + +
- - Note the use of the - LAYERDIR - variable with the immediate expansion operator. - The LAYERDIR variable expands to the directory of the current layer and - requires the immediate expansion operator so that BitBake does not wait to expand the variable - when it's parsing a different directory. - +
+ Enabling Your Layer - - BitBake can locate where other .bbclass and configuration files - are applied through the BBPATH environment variable. - For these cases, BitBake uses the first file with the matching name found in - BBPATH. - This is similar to the way the PATH variable is used for binaries. - We recommend, therefore, that you use unique .bbclass - and configuration file names in your custom layer. - + + Before the Yocto Project build system can use your new layer, you need to enable it. + To enable your layer, simply add your layer's path to the + BBLAYERS + variable in your conf/bblayers.conf file, which is found in the + Yocto Project Build Directory. + The following example shows how to enable a layer named meta-mylayer: + + LCONF_VERSION = "1" - - We also recommend the following: - - Store custom layers in a Git repository that uses the - meta-prvt-XXXX format. - Clone the repository alongside other meta - directories in the Yocto Project source files area. - - Following these recommendations keeps your Yocto Project files area and - its configuration entirely inside the Yocto Project's core base. - + BBFILES ?= "" + BBLAYERS = " \ + /path/to/poky/meta \ + /path/to/poky/meta-yocto \ + /path/to/poky/meta-mylayer \ + " + + + + + BitBake parses each conf/layer.conf file as specified in the + BBLAYERS variable within the conf/bblayers.conf + file. + During the processing of each conf/layer.conf file, BitBake adds the + recipes, classes and configurations contained within the particular layer to the Yocto + Project. + To create your own layer, independent of the Yocto Project files, + simply create a directory with a conf/layer.conf file and + add the directory to your bblayers.conf file. + +
+ +
+ Using .bbappend Files + + + Recipe append files (.bbappend type) allow your layer to make additions or + changes to the content of another layer's recipe without having to copy the other recipe into + your layer. + Your .bbappend file resides in your layer, while the underlying recipe + to which you are appending resides in a different layer. + + + + Append files files must have the same name as the underlying recipe. + For example, the append file someapp_1.1.bbappend must + apply to someapp_1.1.bb. + This means the original recipe and append file names are version number specific. + If the underlying recipe is renamed to update to a newer version, the + corresponding .bbappend file must be renamed as well. + During the build process, BitBake displays warnings on starting if it detects a + .bbappend file that does not have an underlying recipe + with the proper name. + + + + Being able to append information to an existing recipe not only avoids duplication, + but also automatically applies recipe changes in a different layer to your layer. + If you were copying recipes, you would have to manually merge changes as they occur. + + + + As an example, consider the main formfactor recipe and a corresponding formfactor + append file both from the Yocto Project Files. + Here is the main formfactor recipe, which is named formfactor_0.0.bb and + located in the meta layer at meta/bsp-recipes/formfactor: + + DESCRIPTION = "Device formfactor information" + SECTION = "base" + LICENSE = "MIT" + LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \ + file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" + PR = "r19" + + SRC_URI = "file://config file://machconfig" + S = "${WORKDIR}" + + PACKAGE_ARCH = "${MACHINE_ARCH}" + INHIBIT_DEFAULT_DEPS = "1" + + do_install() { + # Only install file if it has a contents + install -d ${D}${sysconfdir}/formfactor/ + install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ + if [ -s "${S}/machconfig" ]; then + install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ + fi + } + + Here is the append file, which is named formfactor_0.0.bbappend and is from the + Crown Bay BSP Layer named meta-intel/meta-crownbay: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + PRINC = "1" + + This example adds or overrides files in + SRC_URI + within a bbappend by extending the path BitBake uses to search for files. + The most reliable way to do this is by prepending the + FILESEXTRAPATHS variable. + For example, if you have your files in a directory that is named the same as your package + (PN), + you can add this directory by adding the following to your bbappend file: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + Using the immediate expansion assignment operator := and the trailing colon + are important so that the resulting list of pathnames is syntactically correct. + BitBake automatically defines the THISDIR variable. + You should never set this variable yourself. + Using _prepend ensures your path will be searched prior to other + paths in the final list. + + +
+ +
+ Prioritizing Your Layer + + + Each layer is assigned a priority value. + Priority values control which layer takes precedence if there are recipe files with + the same name in multiple layers. + For these cases, the recipe file from the layer with a higher priority number taking precedence. + Priority values also affect the order in which multiple .bbappend files + for the same recipe are applied. + You can either specify the priority manually, or allow the build system to calculate it + based on the layer's dependencies. + + + + To specify the layer's priority manually, use the + BBFILE_PRIORITY + variable. + For example: + + BBFILE_PRIORITY := "1" + + + + + It is possible for a recipe with a lower version number + PV + in a layer that has a higher priority to take precedence. + Also, the layer priority does not currently affect the precedence order of + .conf or .bbclass files. + Future versions of BitBake might address this. + +
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index e076c8ff02..6df59983e7 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -177,12 +177,13 @@ For a list of the supported image types that the Yocto Project provides, see the "Reference: Images" appendix in The Yocto Project Reference Manual. - Layer: A collection of recipes representing the core, + Layer: A collection of recipes representing the core, a BSP, or an application stack. For a discussion on BSP Layers, see the "BSP Layers" section in the Yocto Project Board Support Packages (BSP) Developer's Guide. - Metadata: The files that BitBake parses when building an image. + Metadata: The files that BitBake parses when + building an image. Metadata includes recipes, classes, and configuration files. OE-Core: A core set of metadata originating with OpenEmbedded (OE) that is shared between OE and the Yocto Project. -- cgit v1.2.3-54-g00ecf