1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Understanding and Creating Layers 4********************************* 5 6The OpenEmbedded build system supports organizing 7:term:`Metadata` into multiple layers. 8Layers allow you to isolate different types of customizations from each 9other. For introductory information on the Yocto Project Layer Model, 10see the 11":ref:`overview-manual/yp-intro:the yocto project layer model`" 12section in the Yocto Project Overview and Concepts Manual. 13 14Creating Your Own Layer 15======================= 16 17.. note:: 18 19 It is very easy to create your own layers to use with the OpenEmbedded 20 build system, as the Yocto Project ships with tools that speed up creating 21 layers. This section describes the steps you perform by hand to create 22 layers so that you can better understand them. For information about the 23 layer-creation tools, see the 24 ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" 25 section in the Yocto Project Board Support Package (BSP) Developer's 26 Guide and the ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" 27 section further down in this manual. 28 29Follow these general steps to create your layer without using tools: 30 31#. *Check Existing Layers:* Before creating a new layer, you should be 32 sure someone has not already created a layer containing the Metadata 33 you need. You can see the :oe_layerindex:`OpenEmbedded Metadata Index <>` 34 for a list of layers from the OpenEmbedded community that can be used in 35 the Yocto Project. You could find a layer that is identical or close 36 to what you need. 37 38#. *Create a Directory:* Create the directory for your layer. When you 39 create the layer, be sure to create the directory in an area not 40 associated with the Yocto Project :term:`Source Directory` 41 (e.g. the cloned ``poky`` repository). 42 43 While not strictly required, prepend the name of the directory with 44 the string "meta-". For example:: 45 46 meta-mylayer 47 meta-GUI_xyz 48 meta-mymachine 49 50 With rare exceptions, a layer's name follows this form:: 51 52 meta-root_name 53 54 Following this layer naming convention can save 55 you trouble later when tools, components, or variables "assume" your 56 layer name begins with "meta-". A notable example is in configuration 57 files as shown in the following step where layer names without the 58 "meta-" string are appended to several variables used in the 59 configuration. 60 61#. *Create a Layer Configuration File:* Inside your new layer folder, 62 you need to create a ``conf/layer.conf`` file. It is easiest to take 63 an existing layer configuration file and copy that to your layer's 64 ``conf`` directory and then modify the file as needed. 65 66 The ``meta-yocto-bsp/conf/layer.conf`` file in the Yocto Project 67 :yocto_git:`Source Repositories </poky/tree/meta-yocto-bsp/conf>` 68 demonstrates the required syntax. For your layer, you need to replace 69 "yoctobsp" with a unique identifier for your layer (e.g. "machinexyz" 70 for a layer named "meta-machinexyz"):: 71 72 # We have a conf and classes directory, add to BBPATH 73 BBPATH .= ":${LAYERDIR}" 74 75 # We have recipes-* directories, add to BBFILES 76 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ 77 ${LAYERDIR}/recipes-*/*/*.bbappend" 78 79 BBFILE_COLLECTIONS += "yoctobsp" 80 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" 81 BBFILE_PRIORITY_yoctobsp = "5" 82 LAYERVERSION_yoctobsp = "4" 83 LAYERSERIES_COMPAT_yoctobsp = "dunfell" 84 85 Here is an explanation of the layer configuration file: 86 87 - :term:`BBPATH`: Adds the layer's 88 root directory to BitBake's search path. Through the use of the 89 :term:`BBPATH` variable, BitBake locates class files (``.bbclass``), 90 configuration files, and files that are included with ``include`` 91 and ``require`` statements. For these cases, BitBake uses the 92 first file that matches the name found in :term:`BBPATH`. This is 93 similar to the way the ``PATH`` variable is used for binaries. It 94 is recommended, therefore, that you use unique class and 95 configuration filenames in your custom layer. 96 97 - :term:`BBFILES`: Defines the 98 location for all recipes in the layer. 99 100 - :term:`BBFILE_COLLECTIONS`: 101 Establishes the current layer through a unique identifier that is 102 used throughout the OpenEmbedded build system to refer to the 103 layer. In this example, the identifier "yoctobsp" is the 104 representation for the container layer named "meta-yocto-bsp". 105 106 - :term:`BBFILE_PATTERN`: 107 Expands immediately during parsing to provide the directory of the 108 layer. 109 110 - :term:`BBFILE_PRIORITY`: 111 Establishes a priority to use for recipes in the layer when the 112 OpenEmbedded build finds recipes of the same name in different 113 layers. 114 115 - :term:`LAYERVERSION`: 116 Establishes a version number for the layer. You can use this 117 version number to specify this exact version of the layer as a 118 dependency when using the 119 :term:`LAYERDEPENDS` 120 variable. 121 122 - :term:`LAYERDEPENDS`: 123 Lists all layers on which this layer depends (if any). 124 125 - :term:`LAYERSERIES_COMPAT`: 126 Lists the :yocto_wiki:`Yocto Project </Releases>` 127 releases for which the current version is compatible. This 128 variable is a good way to indicate if your particular layer is 129 current. 130 131 132 .. note:: 133 134 A layer does not have to contain only recipes ``.bb`` or append files 135 ``.bbappend``. Generally, developers create layers using 136 ``bitbake-layers create-layer``. 137 See ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`", 138 explaining how the ``layer.conf`` file is created from a template located in 139 ``meta/lib/bblayers/templates/layer.conf``. 140 In fact, none of the variables set in ``layer.conf`` are mandatory, 141 except when :term:`BBFILE_COLLECTIONS` is present. In this case 142 :term:`LAYERSERIES_COMPAT` and :term:`BBFILE_PATTERN` have to be 143 defined too. 144 145#. *Add Content:* Depending on the type of layer, add the content. If 146 the layer adds support for a machine, add the machine configuration 147 in a ``conf/machine/`` file within the layer. If the layer adds 148 distro policy, add the distro configuration in a ``conf/distro/`` 149 file within the layer. If the layer introduces new recipes, put the 150 recipes you need in ``recipes-*`` subdirectories within the layer. 151 152 .. note:: 153 154 For an explanation of layer hierarchy that is compliant with the 155 Yocto Project, see the ":ref:`bsp-guide/bsp:example filesystem layout`" 156 section in the Yocto Project Board Support Package (BSP) Developer's Guide. 157 158#. *Optionally Test for Compatibility:* If you want permission to use 159 the Yocto Project Compatibility logo with your layer or application 160 that uses your layer, perform the steps to apply for compatibility. 161 See the 162 ":ref:`dev-manual/layers:making sure your layer is compatible with yocto project`" 163 section for more information. 164 165Following Best Practices When Creating Layers 166============================================= 167 168To create layers that are easier to maintain and that will not impact 169builds for other machines, you should consider the information in the 170following list: 171 172- *Avoid "Overlaying" Entire Recipes from Other Layers in Your 173 Configuration:* In other words, do not copy an entire recipe into 174 your layer and then modify it. Rather, use an append file 175 (``.bbappend``) to override only those parts of the original recipe 176 you need to modify. 177 178- *Avoid Duplicating Include Files:* Use append files (``.bbappend``) 179 for each recipe that uses an include file. Or, if you are introducing 180 a new recipe that requires the included file, use the path relative 181 to the original layer directory to refer to the file. For example, 182 use ``require recipes-core/``\ `package`\ ``/``\ `file`\ ``.inc`` instead 183 of ``require`` `file`\ ``.inc``. If you're finding you have to overlay 184 the include file, it could indicate a deficiency in the include file 185 in the layer to which it originally belongs. If this is the case, you 186 should try to address that deficiency instead of overlaying the 187 include file. For example, you could address this by getting the 188 maintainer of the include file to add a variable or variables to make 189 it easy to override the parts needing to be overridden. 190 191- *Structure Your Layers:* Proper use of overrides within append files 192 and placement of machine-specific files within your layer can ensure 193 that a build is not using the wrong Metadata and negatively impacting 194 a build for a different machine. Here are some examples: 195 196 - *Modify Variables to Support a Different Machine:* Suppose you 197 have a layer named ``meta-one`` that adds support for building 198 machine "one". To do so, you use an append file named 199 ``base-files.bbappend`` and create a dependency on "foo" by 200 altering the :term:`DEPENDS` 201 variable:: 202 203 DEPENDS = "foo" 204 205 The dependency is created during any 206 build that includes the layer ``meta-one``. However, you might not 207 want this dependency for all machines. For example, suppose you 208 are building for machine "two" but your ``bblayers.conf`` file has 209 the ``meta-one`` layer included. During the build, the 210 ``base-files`` for machine "two" will also have the dependency on 211 ``foo``. 212 213 To make sure your changes apply only when building machine "one", 214 use a machine override with the :term:`DEPENDS` statement:: 215 216 DEPENDS:one = "foo" 217 218 You should follow the same strategy when using ``:append`` 219 and ``:prepend`` operations:: 220 221 DEPENDS:append:one = " foo" 222 DEPENDS:prepend:one = "foo " 223 224 As an actual example, here's a 225 snippet from the generic kernel include file ``linux-yocto.inc``, 226 wherein the kernel compile and link options are adjusted in the 227 case of a subset of the supported architectures:: 228 229 DEPENDS:append:aarch64 = " libgcc" 230 KERNEL_CC:append:aarch64 = " ${TOOLCHAIN_OPTIONS}" 231 KERNEL_LD:append:aarch64 = " ${TOOLCHAIN_OPTIONS}" 232 233 DEPENDS:append:nios2 = " libgcc" 234 KERNEL_CC:append:nios2 = " ${TOOLCHAIN_OPTIONS}" 235 KERNEL_LD:append:nios2 = " ${TOOLCHAIN_OPTIONS}" 236 237 DEPENDS:append:arc = " libgcc" 238 KERNEL_CC:append:arc = " ${TOOLCHAIN_OPTIONS}" 239 KERNEL_LD:append:arc = " ${TOOLCHAIN_OPTIONS}" 240 241 KERNEL_FEATURES:append:qemuall=" features/debug/printk.scc" 242 243 - *Place Machine-Specific Files in Machine-Specific Locations:* When 244 you have a base recipe, such as ``base-files.bb``, that contains a 245 :term:`SRC_URI` statement to a 246 file, you can use an append file to cause the build to use your 247 own version of the file. For example, an append file in your layer 248 at ``meta-one/recipes-core/base-files/base-files.bbappend`` could 249 extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows:: 250 251 FILESEXTRAPATHS:prepend := "${THISDIR}/${BPN}:" 252 253 The build for machine "one" will pick up your machine-specific file as 254 long as you have the file in 255 ``meta-one/recipes-core/base-files/base-files/``. However, if you 256 are building for a different machine and the ``bblayers.conf`` 257 file includes the ``meta-one`` layer and the location of your 258 machine-specific file is the first location where that file is 259 found according to :term:`FILESPATH`, builds for all machines will 260 also use that machine-specific file. 261 262 You can make sure that a machine-specific file is used for a 263 particular machine by putting the file in a subdirectory specific 264 to the machine. For example, rather than placing the file in 265 ``meta-one/recipes-core/base-files/base-files/`` as shown above, 266 put it in ``meta-one/recipes-core/base-files/base-files/one/``. 267 Not only does this make sure the file is used only when building 268 for machine "one", but the build process locates the file more 269 quickly. 270 271 In summary, you need to place all files referenced from 272 :term:`SRC_URI` in a machine-specific subdirectory within the layer in 273 order to restrict those files to machine-specific builds. 274 275- *Perform Steps to Apply for Yocto Project Compatibility:* If you want 276 permission to use the Yocto Project Compatibility logo with your 277 layer or application that uses your layer, perform the steps to apply 278 for compatibility. See the 279 ":ref:`dev-manual/layers:making sure your layer is compatible with yocto project`" 280 section for more information. 281 282- *Follow the Layer Naming Convention:* Store custom layers in a Git 283 repository that use the ``meta-layer_name`` format. 284 285- *Group Your Layers Locally:* Clone your repository alongside other 286 cloned ``meta`` directories from the :term:`Source Directory`. 287 288Making Sure Your Layer is Compatible With Yocto Project 289======================================================= 290 291When you create a layer used with the Yocto Project, it is advantageous 292to make sure that the layer interacts well with existing Yocto Project 293layers (i.e. the layer is compatible with the Yocto Project). Ensuring 294compatibility makes the layer easy to be consumed by others in the Yocto 295Project community and could allow you permission to use the Yocto 296Project Compatible Logo. 297 298.. note:: 299 300 Only Yocto Project member organizations are permitted to use the 301 Yocto Project Compatible Logo. The logo is not available for general 302 use. For information on how to become a Yocto Project member 303 organization, see the :yocto_home:`Yocto Project Website <>`. 304 305The Yocto Project Compatibility Program consists of a layer application 306process that requests permission to use the Yocto Project Compatibility 307Logo for your layer and application. The process consists of two parts: 308 309#. Successfully passing a script (``yocto-check-layer``) that when run 310 against your layer, tests it against constraints based on experiences 311 of how layers have worked in the real world and where pitfalls have 312 been found. Getting a "PASS" result from the script is required for 313 successful compatibility registration. 314 315#. Completion of an application acceptance form, which you can find at 316 :yocto_home:`/compatible-registration/`. 317 318To be granted permission to use the logo, you need to satisfy the 319following: 320 321- Be able to check the box indicating that you got a "PASS" when 322 running the script against your layer. 323 324- Answer "Yes" to the questions on the form or have an acceptable 325 explanation for any questions answered "No". 326 327- Be a Yocto Project Member Organization. 328 329The remainder of this section presents information on the registration 330form and on the ``yocto-check-layer`` script. 331 332Yocto Project Compatible Program Application 333-------------------------------------------- 334 335Use the form to apply for your layer's approval. Upon successful 336application, you can use the Yocto Project Compatibility Logo with your 337layer and the application that uses your layer. 338 339To access the form, use this link: 340:yocto_home:`/compatible-registration`. 341Follow the instructions on the form to complete your application. 342 343The application consists of the following sections: 344 345- *Contact Information:* Provide your contact information as the fields 346 require. Along with your information, provide the released versions 347 of the Yocto Project for which your layer is compatible. 348 349- *Acceptance Criteria:* Provide "Yes" or "No" answers for each of the 350 items in the checklist. There is space at the bottom of the form for 351 any explanations for items for which you answered "No". 352 353- *Recommendations:* Provide answers for the questions regarding Linux 354 kernel use and build success. 355 356``yocto-check-layer`` Script 357---------------------------- 358 359The ``yocto-check-layer`` script provides you a way to assess how 360compatible your layer is with the Yocto Project. You should run this 361script prior to using the form to apply for compatibility as described 362in the previous section. You need to achieve a "PASS" result in order to 363have your application form successfully processed. 364 365The script divides tests into three areas: COMMON, BSP, and DISTRO. For 366example, given a distribution layer (DISTRO), the layer must pass both 367the COMMON and DISTRO related tests. Furthermore, if your layer is a BSP 368layer, the layer must pass the COMMON and BSP set of tests. 369 370To execute the script, enter the following commands from your build 371directory:: 372 373 $ source oe-init-build-env 374 $ yocto-check-layer your_layer_directory 375 376Be sure to provide the actual directory for your 377layer as part of the command. 378 379Entering the command causes the script to determine the type of layer 380and then to execute a set of specific tests against the layer. The 381following list overviews the test: 382 383- ``common.test_readme``: Tests if a ``README`` file exists in the 384 layer and the file is not empty. 385 386- ``common.test_parse``: Tests to make sure that BitBake can parse the 387 files without error (i.e. ``bitbake -p``). 388 389- ``common.test_show_environment``: Tests that the global or per-recipe 390 environment is in order without errors (i.e. ``bitbake -e``). 391 392- ``common.test_world``: Verifies that ``bitbake world`` works. 393 394- ``common.test_signatures``: Tests to be sure that BSP and DISTRO 395 layers do not come with recipes that change signatures. 396 397- ``common.test_layerseries_compat``: Verifies layer compatibility is 398 set properly. 399 400- ``bsp.test_bsp_defines_machines``: Tests if a BSP layer has machine 401 configurations. 402 403- ``bsp.test_bsp_no_set_machine``: Tests to ensure a BSP layer does not 404 set the machine when the layer is added. 405 406- ``bsp.test_machine_world``: Verifies that ``bitbake world`` works 407 regardless of which machine is selected. 408 409- ``bsp.test_machine_signatures``: Verifies that building for a 410 particular machine affects only the signature of tasks specific to 411 that machine. 412 413- ``distro.test_distro_defines_distros``: Tests if a DISTRO layer has 414 distro configurations. 415 416- ``distro.test_distro_no_set_distros``: Tests to ensure a DISTRO layer 417 does not set the distribution when the layer is added. 418 419Enabling Your Layer 420=================== 421 422Before the OpenEmbedded build system can use your new layer, you need to 423enable it. To enable your layer, simply add your layer's path to the 424:term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is 425found in the :term:`Build Directory`. The following example shows how to 426enable your new ``meta-mylayer`` layer (note how your new layer exists 427outside of the official ``poky`` repository which you would have checked 428out earlier):: 429 430 # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf 431 # changes incompatibly 432 POKY_BBLAYERS_CONF_VERSION = "2" 433 BBPATH = "${TOPDIR}" 434 BBFILES ?= "" 435 BBLAYERS ?= " \ 436 /home/user/poky/meta \ 437 /home/user/poky/meta-poky \ 438 /home/user/poky/meta-yocto-bsp \ 439 /home/user/mystuff/meta-mylayer \ 440 " 441 442BitBake parses each ``conf/layer.conf`` file from the top down as 443specified in the :term:`BBLAYERS` variable within the ``conf/bblayers.conf`` 444file. During the processing of each ``conf/layer.conf`` file, BitBake 445adds the recipes, classes and configurations contained within the 446particular layer to the source directory. 447 448Appending Other Layers Metadata With Your Layer 449=============================================== 450 451A recipe that appends Metadata to another recipe is called a BitBake 452append file. A BitBake append file uses the ``.bbappend`` file type 453suffix, while the corresponding recipe to which Metadata is being 454appended uses the ``.bb`` file type suffix. 455 456You can use a ``.bbappend`` file in your layer to make additions or 457changes to the content of another layer's recipe without having to copy 458the other layer's recipe into your layer. Your ``.bbappend`` file 459resides in your layer, while the main ``.bb`` recipe file to which you 460are appending Metadata resides in a different layer. 461 462Being able to append information to an existing recipe not only avoids 463duplication, but also automatically applies recipe changes from a 464different layer into your layer. If you were copying recipes, you would 465have to manually merge changes as they occur. 466 467When you create an append file, you must use the same root name as the 468corresponding recipe file. For example, the append file 469``someapp_3.1.bbappend`` must apply to ``someapp_3.1.bb``. This 470means the original recipe and append filenames are version 471number-specific. If the corresponding recipe is renamed to update to a 472newer version, you must also rename and possibly update the 473corresponding ``.bbappend`` as well. 474 475During the build process, BitBake displays an error on startup if it detects a 476``.bbappend`` file that does not have a corresponding recipe with a matching 477name. To handle these errors, the best practice is to rename the ``.bbappend`` 478to match the original recipe version. This also gives you the opportunity to see 479if the ``.bbappend`` is still relevant for the new version of the recipe. 480 481Another method it to use the character ``%`` in the ``.bbappend`` filename. For 482example, to append information to every ``6.*`` minor versions of the recipe 483``someapp``, the ``someapp_6.%.bbappend`` file can be created. This way, an 484error will only be triggered if the ``someapp`` recipe has a major version 485update. 486 487Finally, another method to deal with these errors is to use the variable 488:term:`BBMASK`, especially in cases where modifying the ``.bbappend`` is not 489possible. 490 491Overlaying a File Using Your Layer 492---------------------------------- 493 494As an example, consider the main formfactor recipe and a corresponding 495formfactor append file both from the :term:`Source Directory`. 496Here is the main 497formfactor recipe, which is named ``formfactor_0.0.bb`` and located in 498the "meta" layer at ``meta/recipes-bsp/formfactor``:: 499 500 SUMMARY = "Device formfactor information" 501 DESCRIPTION = "A formfactor configuration file provides information about the \ 502 target hardware for which the image is being built and information that the \ 503 build system cannot obtain from other sources such as the kernel." 504 SECTION = "base" 505 LICENSE = "MIT" 506 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" 507 PR = "r45" 508 509 SRC_URI = "file://config file://machconfig" 510 S = "${WORKDIR}" 511 512 PACKAGE_ARCH = "${MACHINE_ARCH}" 513 INHIBIT_DEFAULT_DEPS = "1" 514 515 do_install() { 516 # Install file only if it has contents 517 install -d ${D}${sysconfdir}/formfactor/ 518 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ 519 if [ -s "${S}/machconfig" ]; then 520 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ 521 fi 522 } 523 524In the main recipe, note the :term:`SRC_URI` 525variable, which tells the OpenEmbedded build system where to find files 526during the build. 527 528Here is the append file, which is named ``formfactor_0.0.bbappend`` 529and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The 530file is in the layer at ``recipes-bsp/formfactor``:: 531 532 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 533 534By default, the build system uses the 535:term:`FILESPATH` variable to 536locate files. This append file extends the locations by setting the 537:term:`FILESEXTRAPATHS` 538variable. Setting this variable in the ``.bbappend`` file is the most 539reliable and recommended method for adding directories to the search 540path used by the build system to find files. 541 542The statement in this example extends the directories to include 543``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``, 544which resolves to a directory named ``formfactor`` in the same directory 545in which the append file resides (i.e. 546``meta-raspberrypi/recipes-bsp/formfactor``. This implies that you must 547have the supporting directory structure set up that will contain any 548files or patches you will be including from the layer. 549 550Using the immediate expansion assignment operator ``:=`` is important 551because of the reference to :term:`THISDIR`. The trailing colon character is 552important as it ensures that items in the list remain colon-separated. 553 554.. note:: 555 556 BitBake automatically defines the :term:`THISDIR` variable. You should 557 never set this variable yourself. Using ":prepend" as part of the 558 :term:`FILESEXTRAPATHS` ensures your path will be searched prior to other 559 paths in the final list. 560 561 Also, not all append files add extra files. Many append files simply 562 allow to add build options (e.g. ``systemd``). For these cases, your 563 append file would not even use the :term:`FILESEXTRAPATHS` statement. 564 565The end result of this ``.bbappend`` file is that on a Raspberry Pi, where 566``rpi`` will exist in the list of :term:`OVERRIDES`, the file 567``meta-raspberrypi/recipes-bsp/formfactor/formfactor/rpi/machconfig`` will be 568used during :ref:`ref-tasks-fetch` and the test for a non-zero file size in 569:ref:`ref-tasks-install` will return true, and the file will be installed. 570 571Installing Additional Files Using Your Layer 572-------------------------------------------- 573 574As another example, consider the main ``xserver-xf86-config`` recipe and a 575corresponding ``xserver-xf86-config`` append file both from the :term:`Source 576Directory`. Here is the main ``xserver-xf86-config`` recipe, which is named 577``xserver-xf86-config_0.1.bb`` and located in the "meta" layer at 578``meta/recipes-graphics/xorg-xserver``:: 579 580 SUMMARY = "X.Org X server configuration file" 581 HOMEPAGE = "http://www.x.org" 582 SECTION = "x11/base" 583 LICENSE = "MIT" 584 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" 585 PR = "r33" 586 587 SRC_URI = "file://xorg.conf" 588 589 S = "${WORKDIR}" 590 591 CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf" 592 593 PACKAGE_ARCH = "${MACHINE_ARCH}" 594 ALLOW_EMPTY:${PN} = "1" 595 596 do_install () { 597 if test -s ${WORKDIR}/xorg.conf; then 598 install -d ${D}/${sysconfdir}/X11 599 install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/ 600 fi 601 } 602 603Here is the append file, which is named ``xserver-xf86-config_%.bbappend`` 604and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The 605file is in the layer at ``recipes-graphics/xorg-xserver``:: 606 607 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 608 609 SRC_URI:append:rpi = " \ 610 file://xorg.conf.d/98-pitft.conf \ 611 file://xorg.conf.d/99-calibration.conf \ 612 " 613 do_install:append:rpi () { 614 PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}" 615 if [ "${PITFT}" = "1" ]; then 616 install -d ${D}/${sysconfdir}/X11/xorg.conf.d/ 617 install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ 618 install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ 619 fi 620 } 621 622 FILES:${PN}:append:rpi = " ${sysconfdir}/X11/xorg.conf.d/*" 623 624Building off of the previous example, we once again are setting the 625:term:`FILESEXTRAPATHS` variable. In this case we are also using 626:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in 627the list of :term:`OVERRIDES`. The :ref:`ref-tasks-install` task will then perform a 628check for an additional :term:`MACHINE_FEATURES` that if set will cause these 629additional files to be installed. These additional files are listed in 630:term:`FILES` so that they will be packaged. 631 632Prioritizing Your Layer 633======================= 634 635Each layer is assigned a priority value. Priority values control which 636layer takes precedence if there are recipe files with the same name in 637multiple layers. For these cases, the recipe file from the layer with a 638higher priority number takes precedence. Priority values also affect the 639order in which multiple ``.bbappend`` files for the same recipe are 640applied. You can either specify the priority manually, or allow the 641build system to calculate it based on the layer's dependencies. 642 643To specify the layer's priority manually, use the 644:term:`BBFILE_PRIORITY` 645variable and append the layer's root name:: 646 647 BBFILE_PRIORITY_mylayer = "1" 648 649.. note:: 650 651 It is possible for a recipe with a lower version number 652 :term:`PV` in a layer that has a higher 653 priority to take precedence. 654 655 Also, the layer priority does not currently affect the precedence 656 order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake 657 might address this. 658 659Providing Global-level Configurations With Your Layer 660----------------------------------------------------- 661 662When creating a layer, you may need to define configurations that should take 663effect globally in your build environment when the layer is part of the build. 664The ``layer.conf`` file is a :term:`configuration file` that affects the build 665system globally, so it is a candidate for this use-case. 666 667.. warning:: 668 669 Providing unconditional global level configuration from the ``layer.conf`` 670 file is *not* a good practice, and should be avoided. For this reason, the 671 section :ref:`ref-conditional-layer-confs` below shows how the ``layer.conf`` 672 file can be used to provide configurations only if a certain condition is 673 met. 674 675For example, if your layer provides a Linux kernel recipe named 676``linux-custom``, you may want to make :term:`PREFERRED_PROVIDER_virtual/kernel 677<PREFERRED_PROVIDER>` point to ``linux-custom``:: 678 679 PREFERRED_PROVIDER_virtual/kernel = "linux-custom" 680 681This can be defined in the ``layer.conf`` file. If your layer is at the last 682position in the :term:`BBLAYERS` list, it will take precedence over previous 683``PREFERRED_PROVIDER_virtual/kernel`` assignments (unless one is set from a 684:term:`configuration file` that is parsed later, such as machine or distro 685configuration files). 686 687.. _ref-conditional-layer-confs: 688 689Conditionally Provide Global-level Configurations With Your Layer 690^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 691 692In some cases, your layer may provide global configurations only if some 693features it provides are enabled. Since the ``layer.conf`` file is parsed at an 694earlier stage in the parsing process, the :term:`DISTRO_FEATURES` and 695:term:`MACHINE_FEATURES` variables are not yet available to ``layer.conf``, and 696declaring conditional assignments based on these variables is not possible. The 697following technique shows a way to bypass this limitation by using the 698:term:`USER_CLASSES` variable and a conditional ``require`` command. 699 700In the following steps, let's assume our layer is named ``meta-mylayer`` and 701that this layer defines a custom :ref:`distro feature <ref-features-distro>` 702named ``mylayer-kernel``. We will set the :term:`PREFERRED_PROVIDER` variable 703for the kernel only if our feature ``mylayer-kernel`` is part of the 704:term:`DISTRO_FEATURES`: 705 706#. Create an include file in the directory 707 ``meta-mylayer/conf/distro/include/``, for example a file named 708 ``mylayer-kernel-provider.inc`` that sets the kernel provider to 709 ``linux-custom``:: 710 711 PREFERRED_PROVIDER_virtual/kernel = "linux-custom" 712 713#. Provide a path to this include file in your ``layer.conf``:: 714 715 META_MYLAYER_KERNEL_PROVIDER_PATH = "${LAYERDIR}/conf/distro/include/mylayer-kernel-provider.inc" 716 717#. Create a new class in ``meta-mylayer/classes-global/``, for example a class 718 ``meta-mylayer-cfg.bbclass``. Make it conditionally require the file 719 ``mylayer-kernel-provider.inc`` defined above, using the variable 720 ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``:: 721 722 require ${@bb.utils.contains('DISTRO_FEATURES', 'mylayer-kernel', '${META_MYLAYER_KERNEL_PROVIDER_PATH}', '', d)} 723 724 For details on the ``bb.utils.contains`` function, see its definition in 725 :bitbake_git:`lib/bb/utils.py </tree/lib/bb/utils.py>`. 726 727 .. note:: 728 729 The ``require`` command is designed to not fail if the function 730 ``bb.utils.contains`` returns an empty string. 731 732#. Back to your ``layer.conf`` file, add the class ``meta-mylayer-cfg`` class to 733 the :term:`USER_CLASSES` variable:: 734 735 USER_CLASSES:append = " meta-mylayer-cfg" 736 737 This will add the class ``meta-mylayer-cfg`` to the list of classes to 738 globally inherit. Since the ``require`` command is conditional in 739 ``meta-mylayer-cfg.bbclass``, even though inherited the class will have no 740 effect unless the feature ``mylayer-kernel`` is enabled through 741 :term:`DISTRO_FEATURES`. 742 743This technique can also be used for :ref:`Machine features 744<ref-features-machine>` by following the same steps. Though not mandatory, it is 745recommended to put include files for :term:`DISTRO_FEATURES` in your layer's 746``conf/distro/include`` and the ones for :term:`MACHINE_FEATURES` in your 747layer's ``conf/machine/include``. 748 749Managing Layers 750=============== 751 752You can use the BitBake layer management tool ``bitbake-layers`` to 753provide a view into the structure of recipes across a multi-layer 754project. Being able to generate output that reports on configured layers 755with their paths and priorities and on ``.bbappend`` files and their 756applicable recipes can help to reveal potential problems. 757 758For help on the BitBake layer management tool, use the following 759command:: 760 761 $ bitbake-layers --help 762 763The following list describes the available commands: 764 765- ``help:`` Displays general help or help on a specified command. 766 767- ``show-layers:`` Shows the current configured layers. 768 769- ``show-overlayed:`` Lists overlayed recipes. A recipe is overlayed 770 when a recipe with the same name exists in another layer that has a 771 higher layer priority. 772 773- ``show-recipes:`` Lists available recipes and the layers that 774 provide them. 775 776- ``show-appends:`` Lists ``.bbappend`` files and the recipe files to 777 which they apply. 778 779- ``show-cross-depends:`` Lists dependency relationships between 780 recipes that cross layer boundaries. 781 782- ``add-layer:`` Adds a layer to ``bblayers.conf``. 783 784- ``remove-layer:`` Removes a layer from ``bblayers.conf`` 785 786- ``flatten:`` Flattens the layer configuration into a separate 787 output directory. Flattening your layer configuration builds a 788 "flattened" directory that contains the contents of all layers, with 789 any overlayed recipes removed and any ``.bbappend`` files appended to 790 the corresponding recipes. You might have to perform some manual 791 cleanup of the flattened layer as follows: 792 793 - Non-recipe files (such as patches) are overwritten. The flatten 794 command shows a warning for these files. 795 796 - Anything beyond the normal layer setup has been added to the 797 ``layer.conf`` file. Only the lowest priority layer's 798 ``layer.conf`` is used. 799 800 - Overridden and appended items from ``.bbappend`` files need to be 801 cleaned up. The contents of each ``.bbappend`` end up in the 802 flattened recipe. However, if there are appended or changed 803 variable values, you need to tidy these up yourself. Consider the 804 following example. Here, the ``bitbake-layers`` command adds the 805 line ``#### bbappended ...`` so that you know where the following 806 lines originate:: 807 808 ... 809 DESCRIPTION = "A useful utility" 810 ... 811 EXTRA_OECONF = "--enable-something" 812 ... 813 814 #### bbappended from meta-anotherlayer #### 815 816 DESCRIPTION = "Customized utility" 817 EXTRA_OECONF += "--enable-somethingelse" 818 819 820 Ideally, you would tidy up these utilities as follows:: 821 822 ... 823 DESCRIPTION = "Customized utility" 824 ... 825 EXTRA_OECONF = "--enable-something --enable-somethingelse" 826 ... 827 828- ``layerindex-fetch``: Fetches a layer from a layer index, along 829 with its dependent layers, and adds the layers to the 830 ``conf/bblayers.conf`` file. 831 832- ``layerindex-show-depends``: Finds layer dependencies from the 833 layer index. 834 835- ``save-build-conf``: Saves the currently active build configuration 836 (``conf/local.conf``, ``conf/bblayers.conf``) as a template into a layer. 837 This template can later be used for setting up builds via :term:`TEMPLATECONF`. 838 For information about saving and using configuration templates, see 839 ":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`". 840 841- ``create-layer``: Creates a basic layer. 842 843- ``create-layers-setup``: Writes out a configuration file and/or a script that 844 can replicate the directory structure and revisions of the layers in a current build. 845 For more information, see ":ref:`dev-manual/layers:saving and restoring the layers setup`". 846 847Creating a General Layer Using the ``bitbake-layers`` Script 848============================================================ 849 850The ``bitbake-layers`` script with the ``create-layer`` subcommand 851simplifies creating a new general layer. 852 853.. note:: 854 855 - For information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" 856 section in the Yocto 857 Project Board Specific (BSP) Developer's Guide. 858 859 - In order to use a layer with the OpenEmbedded build system, you 860 need to add the layer to your ``bblayers.conf`` configuration 861 file. See the ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" 862 section for more information. 863 864The default mode of the script's operation with this subcommand is to 865create a layer with the following: 866 867- A layer priority of 6. 868 869- A ``conf`` subdirectory that contains a ``layer.conf`` file. 870 871- A ``recipes-example`` subdirectory that contains a further 872 subdirectory named ``example``, which contains an ``example.bb`` 873 recipe file. 874 875- A ``COPYING.MIT``, which is the license statement for the layer. The 876 script assumes you want to use the MIT license, which is typical for 877 most layers, for the contents of the layer itself. 878 879- A ``README`` file, which is a file describing the contents of your 880 new layer. 881 882In its simplest form, you can use the following command form to create a 883layer. The command creates a layer whose name corresponds to 884"your_layer_name" in the current directory:: 885 886 $ bitbake-layers create-layer your_layer_name 887 888As an example, the following command creates a layer named ``meta-scottrif`` 889in your home directory:: 890 891 $ cd /usr/home 892 $ bitbake-layers create-layer meta-scottrif 893 NOTE: Starting bitbake server... 894 Add your new layer with 'bitbake-layers add-layer meta-scottrif' 895 896If you want to set the priority of the layer to other than the default 897value of "6", you can either use the ``--priority`` option or you 898can edit the 899:term:`BBFILE_PRIORITY` value 900in the ``conf/layer.conf`` after the script creates it. Furthermore, if 901you want to give the example recipe file some name other than the 902default, you can use the ``--example-recipe-name`` option. 903 904The easiest way to see how the ``bitbake-layers create-layer`` command 905works is to experiment with the script. You can also read the usage 906information by entering the following:: 907 908 $ bitbake-layers create-layer --help 909 NOTE: Starting bitbake server... 910 usage: bitbake-layers create-layer [-h] [--priority PRIORITY] 911 [--example-recipe-name EXAMPLERECIPE] 912 layerdir 913 914 Create a basic layer 915 916 positional arguments: 917 layerdir Layer directory to create 918 919 optional arguments: 920 -h, --help show this help message and exit 921 --priority PRIORITY, -p PRIORITY 922 Layer directory to create 923 --example-recipe-name EXAMPLERECIPE, -e EXAMPLERECIPE 924 Filename of the example recipe 925 926Adding a Layer Using the ``bitbake-layers`` Script 927================================================== 928 929Once you create your general layer, you must add it to your 930``bblayers.conf`` file. Adding the layer to this configuration file 931makes the OpenEmbedded build system aware of your layer so that it can 932search it for metadata. 933 934Add your layer by using the ``bitbake-layers add-layer`` command:: 935 936 $ bitbake-layers add-layer your_layer_name 937 938Here is an example that adds a 939layer named ``meta-scottrif`` to the configuration file. Following the 940command that adds the layer is another ``bitbake-layers`` command that 941shows the layers that are in your ``bblayers.conf`` file:: 942 943 $ bitbake-layers add-layer meta-scottrif 944 NOTE: Starting bitbake server... 945 Parsing recipes: 100% |##########################################################| Time: 0:00:49 946 Parsing of 1441 .bb files complete (0 cached, 1441 parsed). 2055 targets, 56 skipped, 0 masked, 0 errors. 947 $ bitbake-layers show-layers 948 NOTE: Starting bitbake server... 949 layer path priority 950 ========================================================================== 951 meta /home/scottrif/poky/meta 5 952 meta-poky /home/scottrif/poky/meta-poky 5 953 meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5 954 workspace /home/scottrif/poky/build/workspace 99 955 meta-scottrif /home/scottrif/poky/build/meta-scottrif 6 956 957 958Adding the layer to this file 959enables the build system to locate the layer during the build. 960 961.. note:: 962 963 During a build, the OpenEmbedded build system looks in the layers 964 from the top of the list down to the bottom in that order. 965 966Saving and restoring the layers setup 967===================================== 968 969Once you have a working build with the correct set of layers, it is beneficial 970to capture the layer setup --- what they are, which repositories they come from 971and which SCM revisions they're at --- into a configuration file, so that this 972setup can be easily replicated later, perhaps on a different machine. Here's 973how to do this:: 974 975 $ bitbake-layers create-layers-setup /srv/work/alex/meta-alex/ 976 NOTE: Starting bitbake server... 977 NOTE: Created /srv/work/alex/meta-alex/setup-layers.json 978 NOTE: Created /srv/work/alex/meta-alex/setup-layers 979 980The tool needs a single argument which tells where to place the output, consisting 981of a json formatted layer configuration, and a ``setup-layers`` script that can use that configuration 982to restore the layers in a different location, or on a different host machine. The argument 983can point to a custom layer (which is then deemed a "bootstrap" layer that needs to be 984checked out first), or into a completely independent location. 985 986The replication of the layers is performed by running the ``setup-layers`` script provided 987above: 988 989#. Clone the bootstrap layer or some other repository to obtain 990 the json config and the setup script that can use it. 991 992#. Run the script directly with no options:: 993 994 alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers 995 Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override. 996 997 Setting up source meta-intel, revision 15.0-hardknott-3.3-310-g0a96edae, branch master 998 Running 'git init -q /srv/work/alex/my-build/meta-intel' 999 Running 'git remote remove origin > /dev/null 2>&1; git remote add origin git://git.yoctoproject.org/meta-intel' in /srv/work/alex/my-build/meta-intel 1000 Running 'git fetch -q origin || true' in /srv/work/alex/my-build/meta-intel 1001 Running 'git checkout -q 0a96edae609a3f48befac36af82cf1eed6786b4a' in /srv/work/alex/my-build/meta-intel 1002 1003 Setting up source poky, revision 4.1_M1-372-g55483d28f2, branch akanavin/setup-layers 1004 Running 'git init -q /srv/work/alex/my-build/poky' 1005 Running 'git remote remove origin > /dev/null 2>&1; git remote add origin git://git.yoctoproject.org/poky' in /srv/work/alex/my-build/poky 1006 Running 'git fetch -q origin || true' in /srv/work/alex/my-build/poky 1007 Running 'git remote remove poky-contrib > /dev/null 2>&1; git remote add poky-contrib ssh://git@push.yoctoproject.org/poky-contrib' in /srv/work/alex/my-build/poky 1008 Running 'git fetch -q poky-contrib || true' in /srv/work/alex/my-build/poky 1009 Running 'git checkout -q 11db0390b02acac1324e0f827beb0e2e3d0d1d63' in /srv/work/alex/my-build/poky 1010 1011.. note:: 1012 This will work to update an existing checkout as well. 1013 1014.. note:: 1015 The script is self-sufficient and requires only python3 1016 and git on the build machine. 1017 1018.. note:: 1019 Both the ``create-layers-setup`` and the ``setup-layers`` provided several additional options 1020 that customize their behavior - you are welcome to study them via ``--help`` command line parameter. 1021 1022