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. During the build process, BitBake 474displays an error on starting if it detects a ``.bbappend`` file that 475does not have a corresponding recipe with a matching name. See the 476:term:`BB_DANGLINGAPPENDS_WARNONLY` 477variable for information on how to handle this error. 478 479Overlaying a File Using Your Layer 480---------------------------------- 481 482As an example, consider the main formfactor recipe and a corresponding 483formfactor append file both from the :term:`Source Directory`. 484Here is the main 485formfactor recipe, which is named ``formfactor_0.0.bb`` and located in 486the "meta" layer at ``meta/recipes-bsp/formfactor``:: 487 488 SUMMARY = "Device formfactor information" 489 DESCRIPTION = "A formfactor configuration file provides information about the \ 490 target hardware for which the image is being built and information that the \ 491 build system cannot obtain from other sources such as the kernel." 492 SECTION = "base" 493 LICENSE = "MIT" 494 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" 495 PR = "r45" 496 497 SRC_URI = "file://config file://machconfig" 498 S = "${WORKDIR}" 499 500 PACKAGE_ARCH = "${MACHINE_ARCH}" 501 INHIBIT_DEFAULT_DEPS = "1" 502 503 do_install() { 504 # Install file only if it has contents 505 install -d ${D}${sysconfdir}/formfactor/ 506 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ 507 if [ -s "${S}/machconfig" ]; then 508 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ 509 fi 510 } 511 512In the main recipe, note the :term:`SRC_URI` 513variable, which tells the OpenEmbedded build system where to find files 514during the build. 515 516Here is the append file, which is named ``formfactor_0.0.bbappend`` 517and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The 518file is in the layer at ``recipes-bsp/formfactor``:: 519 520 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 521 522By default, the build system uses the 523:term:`FILESPATH` variable to 524locate files. This append file extends the locations by setting the 525:term:`FILESEXTRAPATHS` 526variable. Setting this variable in the ``.bbappend`` file is the most 527reliable and recommended method for adding directories to the search 528path used by the build system to find files. 529 530The statement in this example extends the directories to include 531``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``, 532which resolves to a directory named ``formfactor`` in the same directory 533in which the append file resides (i.e. 534``meta-raspberrypi/recipes-bsp/formfactor``. This implies that you must 535have the supporting directory structure set up that will contain any 536files or patches you will be including from the layer. 537 538Using the immediate expansion assignment operator ``:=`` is important 539because of the reference to :term:`THISDIR`. The trailing colon character is 540important as it ensures that items in the list remain colon-separated. 541 542.. note:: 543 544 BitBake automatically defines the :term:`THISDIR` variable. You should 545 never set this variable yourself. Using ":prepend" as part of the 546 :term:`FILESEXTRAPATHS` ensures your path will be searched prior to other 547 paths in the final list. 548 549 Also, not all append files add extra files. Many append files simply 550 allow to add build options (e.g. ``systemd``). For these cases, your 551 append file would not even use the :term:`FILESEXTRAPATHS` statement. 552 553The end result of this ``.bbappend`` file is that on a Raspberry Pi, where 554``rpi`` will exist in the list of :term:`OVERRIDES`, the file 555``meta-raspberrypi/recipes-bsp/formfactor/formfactor/rpi/machconfig`` will be 556used during :ref:`ref-tasks-fetch` and the test for a non-zero file size in 557:ref:`ref-tasks-install` will return true, and the file will be installed. 558 559Installing Additional Files Using Your Layer 560-------------------------------------------- 561 562As another example, consider the main ``xserver-xf86-config`` recipe and a 563corresponding ``xserver-xf86-config`` append file both from the :term:`Source 564Directory`. Here is the main ``xserver-xf86-config`` recipe, which is named 565``xserver-xf86-config_0.1.bb`` and located in the "meta" layer at 566``meta/recipes-graphics/xorg-xserver``:: 567 568 SUMMARY = "X.Org X server configuration file" 569 HOMEPAGE = "http://www.x.org" 570 SECTION = "x11/base" 571 LICENSE = "MIT" 572 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" 573 PR = "r33" 574 575 SRC_URI = "file://xorg.conf" 576 577 S = "${WORKDIR}" 578 579 CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf" 580 581 PACKAGE_ARCH = "${MACHINE_ARCH}" 582 ALLOW_EMPTY:${PN} = "1" 583 584 do_install () { 585 if test -s ${WORKDIR}/xorg.conf; then 586 install -d ${D}/${sysconfdir}/X11 587 install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/ 588 fi 589 } 590 591Here is the append file, which is named ``xserver-xf86-config_%.bbappend`` 592and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The 593file is in the layer at ``recipes-graphics/xorg-xserver``:: 594 595 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 596 597 SRC_URI:append:rpi = " \ 598 file://xorg.conf.d/98-pitft.conf \ 599 file://xorg.conf.d/99-calibration.conf \ 600 " 601 do_install:append:rpi () { 602 PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}" 603 if [ "${PITFT}" = "1" ]; then 604 install -d ${D}/${sysconfdir}/X11/xorg.conf.d/ 605 install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ 606 install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ 607 fi 608 } 609 610 FILES:${PN}:append:rpi = " ${sysconfdir}/X11/xorg.conf.d/*" 611 612Building off of the previous example, we once again are setting the 613:term:`FILESEXTRAPATHS` variable. In this case we are also using 614:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in 615the list of :term:`OVERRIDES`. The :ref:`ref-tasks-install` task will then perform a 616check for an additional :term:`MACHINE_FEATURES` that if set will cause these 617additional files to be installed. These additional files are listed in 618:term:`FILES` so that they will be packaged. 619 620Prioritizing Your Layer 621======================= 622 623Each layer is assigned a priority value. Priority values control which 624layer takes precedence if there are recipe files with the same name in 625multiple layers. For these cases, the recipe file from the layer with a 626higher priority number takes precedence. Priority values also affect the 627order in which multiple ``.bbappend`` files for the same recipe are 628applied. You can either specify the priority manually, or allow the 629build system to calculate it based on the layer's dependencies. 630 631To specify the layer's priority manually, use the 632:term:`BBFILE_PRIORITY` 633variable and append the layer's root name:: 634 635 BBFILE_PRIORITY_mylayer = "1" 636 637.. note:: 638 639 It is possible for a recipe with a lower version number 640 :term:`PV` in a layer that has a higher 641 priority to take precedence. 642 643 Also, the layer priority does not currently affect the precedence 644 order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake 645 might address this. 646 647Managing Layers 648=============== 649 650You can use the BitBake layer management tool ``bitbake-layers`` to 651provide a view into the structure of recipes across a multi-layer 652project. Being able to generate output that reports on configured layers 653with their paths and priorities and on ``.bbappend`` files and their 654applicable recipes can help to reveal potential problems. 655 656For help on the BitBake layer management tool, use the following 657command:: 658 659 $ bitbake-layers --help 660 661The following list describes the available commands: 662 663- ``help:`` Displays general help or help on a specified command. 664 665- ``show-layers:`` Shows the current configured layers. 666 667- ``show-overlayed:`` Lists overlayed recipes. A recipe is overlayed 668 when a recipe with the same name exists in another layer that has a 669 higher layer priority. 670 671- ``show-recipes:`` Lists available recipes and the layers that 672 provide them. 673 674- ``show-appends:`` Lists ``.bbappend`` files and the recipe files to 675 which they apply. 676 677- ``show-cross-depends:`` Lists dependency relationships between 678 recipes that cross layer boundaries. 679 680- ``add-layer:`` Adds a layer to ``bblayers.conf``. 681 682- ``remove-layer:`` Removes a layer from ``bblayers.conf`` 683 684- ``flatten:`` Flattens the layer configuration into a separate 685 output directory. Flattening your layer configuration builds a 686 "flattened" directory that contains the contents of all layers, with 687 any overlayed recipes removed and any ``.bbappend`` files appended to 688 the corresponding recipes. You might have to perform some manual 689 cleanup of the flattened layer as follows: 690 691 - Non-recipe files (such as patches) are overwritten. The flatten 692 command shows a warning for these files. 693 694 - Anything beyond the normal layer setup has been added to the 695 ``layer.conf`` file. Only the lowest priority layer's 696 ``layer.conf`` is used. 697 698 - Overridden and appended items from ``.bbappend`` files need to be 699 cleaned up. The contents of each ``.bbappend`` end up in the 700 flattened recipe. However, if there are appended or changed 701 variable values, you need to tidy these up yourself. Consider the 702 following example. Here, the ``bitbake-layers`` command adds the 703 line ``#### bbappended ...`` so that you know where the following 704 lines originate:: 705 706 ... 707 DESCRIPTION = "A useful utility" 708 ... 709 EXTRA_OECONF = "--enable-something" 710 ... 711 712 #### bbappended from meta-anotherlayer #### 713 714 DESCRIPTION = "Customized utility" 715 EXTRA_OECONF += "--enable-somethingelse" 716 717 718 Ideally, you would tidy up these utilities as follows:: 719 720 ... 721 DESCRIPTION = "Customized utility" 722 ... 723 EXTRA_OECONF = "--enable-something --enable-somethingelse" 724 ... 725 726- ``layerindex-fetch``: Fetches a layer from a layer index, along 727 with its dependent layers, and adds the layers to the 728 ``conf/bblayers.conf`` file. 729 730- ``layerindex-show-depends``: Finds layer dependencies from the 731 layer index. 732 733- ``save-build-conf``: Saves the currently active build configuration 734 (``conf/local.conf``, ``conf/bblayers.conf``) as a template into a layer. 735 This template can later be used for setting up builds via :term:`TEMPLATECONF`. 736 For information about saving and using configuration templates, see 737 ":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`". 738 739- ``create-layer``: Creates a basic layer. 740 741- ``create-layers-setup``: Writes out a configuration file and/or a script that 742 can replicate the directory structure and revisions of the layers in a current build. 743 For more information, see ":ref:`dev-manual/layers:saving and restoring the layers setup`". 744 745Creating a General Layer Using the ``bitbake-layers`` Script 746============================================================ 747 748The ``bitbake-layers`` script with the ``create-layer`` subcommand 749simplifies creating a new general layer. 750 751.. note:: 752 753 - For information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" 754 section in the Yocto 755 Project Board Specific (BSP) Developer's Guide. 756 757 - In order to use a layer with the OpenEmbedded build system, you 758 need to add the layer to your ``bblayers.conf`` configuration 759 file. See the ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" 760 section for more information. 761 762The default mode of the script's operation with this subcommand is to 763create a layer with the following: 764 765- A layer priority of 6. 766 767- A ``conf`` subdirectory that contains a ``layer.conf`` file. 768 769- A ``recipes-example`` subdirectory that contains a further 770 subdirectory named ``example``, which contains an ``example.bb`` 771 recipe file. 772 773- A ``COPYING.MIT``, which is the license statement for the layer. The 774 script assumes you want to use the MIT license, which is typical for 775 most layers, for the contents of the layer itself. 776 777- A ``README`` file, which is a file describing the contents of your 778 new layer. 779 780In its simplest form, you can use the following command form to create a 781layer. The command creates a layer whose name corresponds to 782"your_layer_name" in the current directory:: 783 784 $ bitbake-layers create-layer your_layer_name 785 786As an example, the following command creates a layer named ``meta-scottrif`` 787in your home directory:: 788 789 $ cd /usr/home 790 $ bitbake-layers create-layer meta-scottrif 791 NOTE: Starting bitbake server... 792 Add your new layer with 'bitbake-layers add-layer meta-scottrif' 793 794If you want to set the priority of the layer to other than the default 795value of "6", you can either use the ``--priority`` option or you 796can edit the 797:term:`BBFILE_PRIORITY` value 798in the ``conf/layer.conf`` after the script creates it. Furthermore, if 799you want to give the example recipe file some name other than the 800default, you can use the ``--example-recipe-name`` option. 801 802The easiest way to see how the ``bitbake-layers create-layer`` command 803works is to experiment with the script. You can also read the usage 804information by entering the following:: 805 806 $ bitbake-layers create-layer --help 807 NOTE: Starting bitbake server... 808 usage: bitbake-layers create-layer [-h] [--priority PRIORITY] 809 [--example-recipe-name EXAMPLERECIPE] 810 layerdir 811 812 Create a basic layer 813 814 positional arguments: 815 layerdir Layer directory to create 816 817 optional arguments: 818 -h, --help show this help message and exit 819 --priority PRIORITY, -p PRIORITY 820 Layer directory to create 821 --example-recipe-name EXAMPLERECIPE, -e EXAMPLERECIPE 822 Filename of the example recipe 823 824Adding a Layer Using the ``bitbake-layers`` Script 825================================================== 826 827Once you create your general layer, you must add it to your 828``bblayers.conf`` file. Adding the layer to this configuration file 829makes the OpenEmbedded build system aware of your layer so that it can 830search it for metadata. 831 832Add your layer by using the ``bitbake-layers add-layer`` command:: 833 834 $ bitbake-layers add-layer your_layer_name 835 836Here is an example that adds a 837layer named ``meta-scottrif`` to the configuration file. Following the 838command that adds the layer is another ``bitbake-layers`` command that 839shows the layers that are in your ``bblayers.conf`` file:: 840 841 $ bitbake-layers add-layer meta-scottrif 842 NOTE: Starting bitbake server... 843 Parsing recipes: 100% |##########################################################| Time: 0:00:49 844 Parsing of 1441 .bb files complete (0 cached, 1441 parsed). 2055 targets, 56 skipped, 0 masked, 0 errors. 845 $ bitbake-layers show-layers 846 NOTE: Starting bitbake server... 847 layer path priority 848 ========================================================================== 849 meta /home/scottrif/poky/meta 5 850 meta-poky /home/scottrif/poky/meta-poky 5 851 meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5 852 workspace /home/scottrif/poky/build/workspace 99 853 meta-scottrif /home/scottrif/poky/build/meta-scottrif 6 854 855 856Adding the layer to this file 857enables the build system to locate the layer during the build. 858 859.. note:: 860 861 During a build, the OpenEmbedded build system looks in the layers 862 from the top of the list down to the bottom in that order. 863 864Saving and restoring the layers setup 865===================================== 866 867Once you have a working build with the correct set of layers, it is beneficial 868to capture the layer setup --- what they are, which repositories they come from 869and which SCM revisions they're at --- into a configuration file, so that this 870setup can be easily replicated later, perhaps on a different machine. Here's 871how to do this:: 872 873 $ bitbake-layers create-layers-setup /srv/work/alex/meta-alex/ 874 NOTE: Starting bitbake server... 875 NOTE: Created /srv/work/alex/meta-alex/setup-layers.json 876 NOTE: Created /srv/work/alex/meta-alex/setup-layers 877 878The tool needs a single argument which tells where to place the output, consisting 879of a json formatted layer configuration, and a ``setup-layers`` script that can use that configuration 880to restore the layers in a different location, or on a different host machine. The argument 881can point to a custom layer (which is then deemed a "bootstrap" layer that needs to be 882checked out first), or into a completely independent location. 883 884The replication of the layers is performed by running the ``setup-layers`` script provided 885above: 886 887#. Clone the bootstrap layer or some other repository to obtain 888 the json config and the setup script that can use it. 889 890#. Run the script directly with no options:: 891 892 alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers 893 Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override. 894 895 Setting up source meta-intel, revision 15.0-hardknott-3.3-310-g0a96edae, branch master 896 Running 'git init -q /srv/work/alex/my-build/meta-intel' 897 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 898 Running 'git fetch -q origin || true' in /srv/work/alex/my-build/meta-intel 899 Running 'git checkout -q 0a96edae609a3f48befac36af82cf1eed6786b4a' in /srv/work/alex/my-build/meta-intel 900 901 Setting up source poky, revision 4.1_M1-372-g55483d28f2, branch akanavin/setup-layers 902 Running 'git init -q /srv/work/alex/my-build/poky' 903 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 904 Running 'git fetch -q origin || true' in /srv/work/alex/my-build/poky 905 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 906 Running 'git fetch -q poky-contrib || true' in /srv/work/alex/my-build/poky 907 Running 'git checkout -q 11db0390b02acac1324e0f827beb0e2e3d0d1d63' in /srv/work/alex/my-build/poky 908 909.. note:: 910 This will work to update an existing checkout as well. 911 912.. note:: 913 The script is self-sufficient and requires only python3 914 and git on the build machine. 915 916.. note:: 917 Both the ``create-layers-setup`` and the ``setup-layers`` provided several additional options 918 that customize their behavior - you are welcome to study them via ``--help`` command line parameter. 919 920