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 Following 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#. *Add Content:* Depending on the type of layer, add the content. If 132 the layer adds support for a machine, add the machine configuration 133 in a ``conf/machine/`` file within the layer. If the layer adds 134 distro policy, add the distro configuration in a ``conf/distro/`` 135 file within the layer. If the layer introduces new recipes, put the 136 recipes you need in ``recipes-*`` subdirectories within the layer. 137 138 .. note:: 139 140 For an explanation of layer hierarchy that is compliant with the 141 Yocto Project, see the ":ref:`bsp-guide/bsp:example filesystem layout`" 142 section in the Yocto Project Board Support Package (BSP) Developer's Guide. 143 144#. *Optionally Test for Compatibility:* If you want permission to use 145 the Yocto Project Compatibility logo with your layer or application 146 that uses your layer, perform the steps to apply for compatibility. 147 See the 148 ":ref:`dev-manual/layers:making sure your layer is compatible with yocto project`" 149 section for more information. 150 151Following Best Practices When Creating Layers 152============================================= 153 154To create layers that are easier to maintain and that will not impact 155builds for other machines, you should consider the information in the 156following list: 157 158- *Avoid "Overlaying" Entire Recipes from Other Layers in Your 159 Configuration:* In other words, do not copy an entire recipe into 160 your layer and then modify it. Rather, use an append file 161 (``.bbappend``) to override only those parts of the original recipe 162 you need to modify. 163 164- *Avoid Duplicating Include Files:* Use append files (``.bbappend``) 165 for each recipe that uses an include file. Or, if you are introducing 166 a new recipe that requires the included file, use the path relative 167 to the original layer directory to refer to the file. For example, 168 use ``require recipes-core/``\ `package`\ ``/``\ `file`\ ``.inc`` instead 169 of ``require`` `file`\ ``.inc``. If you're finding you have to overlay 170 the include file, it could indicate a deficiency in the include file 171 in the layer to which it originally belongs. If this is the case, you 172 should try to address that deficiency instead of overlaying the 173 include file. For example, you could address this by getting the 174 maintainer of the include file to add a variable or variables to make 175 it easy to override the parts needing to be overridden. 176 177- *Structure Your Layers:* Proper use of overrides within append files 178 and placement of machine-specific files within your layer can ensure 179 that a build is not using the wrong Metadata and negatively impacting 180 a build for a different machine. Following are some examples: 181 182 - *Modify Variables to Support a Different Machine:* Suppose you 183 have a layer named ``meta-one`` that adds support for building 184 machine "one". To do so, you use an append file named 185 ``base-files.bbappend`` and create a dependency on "foo" by 186 altering the :term:`DEPENDS` 187 variable:: 188 189 DEPENDS = "foo" 190 191 The dependency is created during any 192 build that includes the layer ``meta-one``. However, you might not 193 want this dependency for all machines. For example, suppose you 194 are building for machine "two" but your ``bblayers.conf`` file has 195 the ``meta-one`` layer included. During the build, the 196 ``base-files`` for machine "two" will also have the dependency on 197 ``foo``. 198 199 To make sure your changes apply only when building machine "one", 200 use a machine override with the :term:`DEPENDS` statement:: 201 202 DEPENDS:one = "foo" 203 204 You should follow the same strategy when using ``:append`` 205 and ``:prepend`` operations:: 206 207 DEPENDS:append:one = " foo" 208 DEPENDS:prepend:one = "foo " 209 210 As an actual example, here's a 211 snippet from the generic kernel include file ``linux-yocto.inc``, 212 wherein the kernel compile and link options are adjusted in the 213 case of a subset of the supported architectures:: 214 215 DEPENDS:append:aarch64 = " libgcc" 216 KERNEL_CC:append:aarch64 = " ${TOOLCHAIN_OPTIONS}" 217 KERNEL_LD:append:aarch64 = " ${TOOLCHAIN_OPTIONS}" 218 219 DEPENDS:append:nios2 = " libgcc" 220 KERNEL_CC:append:nios2 = " ${TOOLCHAIN_OPTIONS}" 221 KERNEL_LD:append:nios2 = " ${TOOLCHAIN_OPTIONS}" 222 223 DEPENDS:append:arc = " libgcc" 224 KERNEL_CC:append:arc = " ${TOOLCHAIN_OPTIONS}" 225 KERNEL_LD:append:arc = " ${TOOLCHAIN_OPTIONS}" 226 227 KERNEL_FEATURES:append:qemuall=" features/debug/printk.scc" 228 229 - *Place Machine-Specific Files in Machine-Specific Locations:* When 230 you have a base recipe, such as ``base-files.bb``, that contains a 231 :term:`SRC_URI` statement to a 232 file, you can use an append file to cause the build to use your 233 own version of the file. For example, an append file in your layer 234 at ``meta-one/recipes-core/base-files/base-files.bbappend`` could 235 extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows:: 236 237 FILESEXTRAPATHS:prepend := "${THISDIR}/${BPN}:" 238 239 The build for machine "one" will pick up your machine-specific file as 240 long as you have the file in 241 ``meta-one/recipes-core/base-files/base-files/``. However, if you 242 are building for a different machine and the ``bblayers.conf`` 243 file includes the ``meta-one`` layer and the location of your 244 machine-specific file is the first location where that file is 245 found according to :term:`FILESPATH`, builds for all machines will 246 also use that machine-specific file. 247 248 You can make sure that a machine-specific file is used for a 249 particular machine by putting the file in a subdirectory specific 250 to the machine. For example, rather than placing the file in 251 ``meta-one/recipes-core/base-files/base-files/`` as shown above, 252 put it in ``meta-one/recipes-core/base-files/base-files/one/``. 253 Not only does this make sure the file is used only when building 254 for machine "one", but the build process locates the file more 255 quickly. 256 257 In summary, you need to place all files referenced from 258 :term:`SRC_URI` in a machine-specific subdirectory within the layer in 259 order to restrict those files to machine-specific builds. 260 261- *Perform Steps to Apply for Yocto Project Compatibility:* If you want 262 permission to use the Yocto Project Compatibility logo with your 263 layer or application that uses your layer, perform the steps to apply 264 for compatibility. See the 265 ":ref:`dev-manual/layers:making sure your layer is compatible with yocto project`" 266 section for more information. 267 268- *Follow the Layer Naming Convention:* Store custom layers in a Git 269 repository that use the ``meta-layer_name`` format. 270 271- *Group Your Layers Locally:* Clone your repository alongside other 272 cloned ``meta`` directories from the :term:`Source Directory`. 273 274Making Sure Your Layer is Compatible With Yocto Project 275======================================================= 276 277When you create a layer used with the Yocto Project, it is advantageous 278to make sure that the layer interacts well with existing Yocto Project 279layers (i.e. the layer is compatible with the Yocto Project). Ensuring 280compatibility makes the layer easy to be consumed by others in the Yocto 281Project community and could allow you permission to use the Yocto 282Project Compatible Logo. 283 284.. note:: 285 286 Only Yocto Project member organizations are permitted to use the 287 Yocto Project Compatible Logo. The logo is not available for general 288 use. For information on how to become a Yocto Project member 289 organization, see the :yocto_home:`Yocto Project Website <>`. 290 291The Yocto Project Compatibility Program consists of a layer application 292process that requests permission to use the Yocto Project Compatibility 293Logo for your layer and application. The process consists of two parts: 294 295#. Successfully passing a script (``yocto-check-layer``) that when run 296 against your layer, tests it against constraints based on experiences 297 of how layers have worked in the real world and where pitfalls have 298 been found. Getting a "PASS" result from the script is required for 299 successful compatibility registration. 300 301#. Completion of an application acceptance form, which you can find at 302 :yocto_home:`/webform/yocto-project-compatible-registration`. 303 304To be granted permission to use the logo, you need to satisfy the 305following: 306 307- Be able to check the box indicating that you got a "PASS" when 308 running the script against your layer. 309 310- Answer "Yes" to the questions on the form or have an acceptable 311 explanation for any questions answered "No". 312 313- Be a Yocto Project Member Organization. 314 315The remainder of this section presents information on the registration 316form and on the ``yocto-check-layer`` script. 317 318Yocto Project Compatible Program Application 319-------------------------------------------- 320 321Use the form to apply for your layer's approval. Upon successful 322application, you can use the Yocto Project Compatibility Logo with your 323layer and the application that uses your layer. 324 325To access the form, use this link: 326:yocto_home:`/webform/yocto-project-compatible-registration`. 327Follow the instructions on the form to complete your application. 328 329The application consists of the following sections: 330 331- *Contact Information:* Provide your contact information as the fields 332 require. Along with your information, provide the released versions 333 of the Yocto Project for which your layer is compatible. 334 335- *Acceptance Criteria:* Provide "Yes" or "No" answers for each of the 336 items in the checklist. There is space at the bottom of the form for 337 any explanations for items for which you answered "No". 338 339- *Recommendations:* Provide answers for the questions regarding Linux 340 kernel use and build success. 341 342``yocto-check-layer`` Script 343---------------------------- 344 345The ``yocto-check-layer`` script provides you a way to assess how 346compatible your layer is with the Yocto Project. You should run this 347script prior to using the form to apply for compatibility as described 348in the previous section. You need to achieve a "PASS" result in order to 349have your application form successfully processed. 350 351The script divides tests into three areas: COMMON, BSP, and DISTRO. For 352example, given a distribution layer (DISTRO), the layer must pass both 353the COMMON and DISTRO related tests. Furthermore, if your layer is a BSP 354layer, the layer must pass the COMMON and BSP set of tests. 355 356To execute the script, enter the following commands from your build 357directory:: 358 359 $ source oe-init-build-env 360 $ yocto-check-layer your_layer_directory 361 362Be sure to provide the actual directory for your 363layer as part of the command. 364 365Entering the command causes the script to determine the type of layer 366and then to execute a set of specific tests against the layer. The 367following list overviews the test: 368 369- ``common.test_readme``: Tests if a ``README`` file exists in the 370 layer and the file is not empty. 371 372- ``common.test_parse``: Tests to make sure that BitBake can parse the 373 files without error (i.e. ``bitbake -p``). 374 375- ``common.test_show_environment``: Tests that the global or per-recipe 376 environment is in order without errors (i.e. ``bitbake -e``). 377 378- ``common.test_world``: Verifies that ``bitbake world`` works. 379 380- ``common.test_signatures``: Tests to be sure that BSP and DISTRO 381 layers do not come with recipes that change signatures. 382 383- ``common.test_layerseries_compat``: Verifies layer compatibility is 384 set properly. 385 386- ``bsp.test_bsp_defines_machines``: Tests if a BSP layer has machine 387 configurations. 388 389- ``bsp.test_bsp_no_set_machine``: Tests to ensure a BSP layer does not 390 set the machine when the layer is added. 391 392- ``bsp.test_machine_world``: Verifies that ``bitbake world`` works 393 regardless of which machine is selected. 394 395- ``bsp.test_machine_signatures``: Verifies that building for a 396 particular machine affects only the signature of tasks specific to 397 that machine. 398 399- ``distro.test_distro_defines_distros``: Tests if a DISTRO layer has 400 distro configurations. 401 402- ``distro.test_distro_no_set_distros``: Tests to ensure a DISTRO layer 403 does not set the distribution when the layer is added. 404 405Enabling Your Layer 406=================== 407 408Before the OpenEmbedded build system can use your new layer, you need to 409enable it. To enable your layer, simply add your layer's path to the 410:term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is 411found in the :term:`Build Directory`. The following example shows how to 412enable your new ``meta-mylayer`` layer (note how your new layer exists 413outside of the official ``poky`` repository which you would have checked 414out earlier):: 415 416 # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf 417 # changes incompatibly 418 POKY_BBLAYERS_CONF_VERSION = "2" 419 BBPATH = "${TOPDIR}" 420 BBFILES ?= "" 421 BBLAYERS ?= " \ 422 /home/user/poky/meta \ 423 /home/user/poky/meta-poky \ 424 /home/user/poky/meta-yocto-bsp \ 425 /home/user/mystuff/meta-mylayer \ 426 " 427 428BitBake parses each ``conf/layer.conf`` file from the top down as 429specified in the :term:`BBLAYERS` variable within the ``conf/bblayers.conf`` 430file. During the processing of each ``conf/layer.conf`` file, BitBake 431adds the recipes, classes and configurations contained within the 432particular layer to the source directory. 433 434Appending Other Layers Metadata With Your Layer 435=============================================== 436 437A recipe that appends Metadata to another recipe is called a BitBake 438append file. A BitBake append file uses the ``.bbappend`` file type 439suffix, while the corresponding recipe to which Metadata is being 440appended uses the ``.bb`` file type suffix. 441 442You can use a ``.bbappend`` file in your layer to make additions or 443changes to the content of another layer's recipe without having to copy 444the other layer's recipe into your layer. Your ``.bbappend`` file 445resides in your layer, while the main ``.bb`` recipe file to which you 446are appending Metadata resides in a different layer. 447 448Being able to append information to an existing recipe not only avoids 449duplication, but also automatically applies recipe changes from a 450different layer into your layer. If you were copying recipes, you would 451have to manually merge changes as they occur. 452 453When you create an append file, you must use the same root name as the 454corresponding recipe file. For example, the append file 455``someapp_3.1.bbappend`` must apply to ``someapp_3.1.bb``. This 456means the original recipe and append filenames are version 457number-specific. If the corresponding recipe is renamed to update to a 458newer version, you must also rename and possibly update the 459corresponding ``.bbappend`` as well. During the build process, BitBake 460displays an error on starting if it detects a ``.bbappend`` file that 461does not have a corresponding recipe with a matching name. See the 462:term:`BB_DANGLINGAPPENDS_WARNONLY` 463variable for information on how to handle this error. 464 465Overlaying a File Using Your Layer 466---------------------------------- 467 468As an example, consider the main formfactor recipe and a corresponding 469formfactor append file both from the :term:`Source Directory`. 470Here is the main 471formfactor recipe, which is named ``formfactor_0.0.bb`` and located in 472the "meta" layer at ``meta/recipes-bsp/formfactor``:: 473 474 SUMMARY = "Device formfactor information" 475 DESCRIPTION = "A formfactor configuration file provides information about the \ 476 target hardware for which the image is being built and information that the \ 477 build system cannot obtain from other sources such as the kernel." 478 SECTION = "base" 479 LICENSE = "MIT" 480 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" 481 PR = "r45" 482 483 SRC_URI = "file://config file://machconfig" 484 S = "${WORKDIR}" 485 486 PACKAGE_ARCH = "${MACHINE_ARCH}" 487 INHIBIT_DEFAULT_DEPS = "1" 488 489 do_install() { 490 # Install file only if it has contents 491 install -d ${D}${sysconfdir}/formfactor/ 492 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ 493 if [ -s "${S}/machconfig" ]; then 494 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ 495 fi 496 } 497 498In the main recipe, note the :term:`SRC_URI` 499variable, which tells the OpenEmbedded build system where to find files 500during the build. 501 502Following is the append file, which is named ``formfactor_0.0.bbappend`` 503and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The 504file is in the layer at ``recipes-bsp/formfactor``:: 505 506 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 507 508By default, the build system uses the 509:term:`FILESPATH` variable to 510locate files. This append file extends the locations by setting the 511:term:`FILESEXTRAPATHS` 512variable. Setting this variable in the ``.bbappend`` file is the most 513reliable and recommended method for adding directories to the search 514path used by the build system to find files. 515 516The statement in this example extends the directories to include 517``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``, 518which resolves to a directory named ``formfactor`` in the same directory 519in which the append file resides (i.e. 520``meta-raspberrypi/recipes-bsp/formfactor``. This implies that you must 521have the supporting directory structure set up that will contain any 522files or patches you will be including from the layer. 523 524Using the immediate expansion assignment operator ``:=`` is important 525because of the reference to :term:`THISDIR`. The trailing colon character is 526important as it ensures that items in the list remain colon-separated. 527 528.. note:: 529 530 BitBake automatically defines the :term:`THISDIR` variable. You should 531 never set this variable yourself. Using ":prepend" as part of the 532 :term:`FILESEXTRAPATHS` ensures your path will be searched prior to other 533 paths in the final list. 534 535 Also, not all append files add extra files. Many append files simply 536 allow to add build options (e.g. ``systemd``). For these cases, your 537 append file would not even use the :term:`FILESEXTRAPATHS` statement. 538 539The end result of this ``.bbappend`` file is that on a Raspberry Pi, where 540``rpi`` will exist in the list of :term:`OVERRIDES`, the file 541``meta-raspberrypi/recipes-bsp/formfactor/formfactor/rpi/machconfig`` will be 542used during :ref:`ref-tasks-fetch` and the test for a non-zero file size in 543:ref:`ref-tasks-install` will return true, and the file will be installed. 544 545Installing Additional Files Using Your Layer 546-------------------------------------------- 547 548As another example, consider the main ``xserver-xf86-config`` recipe and a 549corresponding ``xserver-xf86-config`` append file both from the :term:`Source 550Directory`. Here is the main ``xserver-xf86-config`` recipe, which is named 551``xserver-xf86-config_0.1.bb`` and located in the "meta" layer at 552``meta/recipes-graphics/xorg-xserver``:: 553 554 SUMMARY = "X.Org X server configuration file" 555 HOMEPAGE = "http://www.x.org" 556 SECTION = "x11/base" 557 LICENSE = "MIT" 558 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" 559 PR = "r33" 560 561 SRC_URI = "file://xorg.conf" 562 563 S = "${WORKDIR}" 564 565 CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf" 566 567 PACKAGE_ARCH = "${MACHINE_ARCH}" 568 ALLOW_EMPTY:${PN} = "1" 569 570 do_install () { 571 if test -s ${WORKDIR}/xorg.conf; then 572 install -d ${D}/${sysconfdir}/X11 573 install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/ 574 fi 575 } 576 577Following is the append file, which is named ``xserver-xf86-config_%.bbappend`` 578and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The 579file is in the layer at ``recipes-graphics/xorg-xserver``:: 580 581 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" 582 583 SRC_URI:append:rpi = " \ 584 file://xorg.conf.d/98-pitft.conf \ 585 file://xorg.conf.d/99-calibration.conf \ 586 " 587 do_install:append:rpi () { 588 PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}" 589 if [ "${PITFT}" = "1" ]; then 590 install -d ${D}/${sysconfdir}/X11/xorg.conf.d/ 591 install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ 592 install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ 593 fi 594 } 595 596 FILES:${PN}:append:rpi = " ${sysconfdir}/X11/xorg.conf.d/*" 597 598Building off of the previous example, we once again are setting the 599:term:`FILESEXTRAPATHS` variable. In this case we are also using 600:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in 601the list of :term:`OVERRIDES`. The :ref:`ref-tasks-install` task will then perform a 602check for an additional :term:`MACHINE_FEATURES` that if set will cause these 603additional files to be installed. These additional files are listed in 604:term:`FILES` so that they will be packaged. 605 606Prioritizing Your Layer 607======================= 608 609Each layer is assigned a priority value. Priority values control which 610layer takes precedence if there are recipe files with the same name in 611multiple layers. For these cases, the recipe file from the layer with a 612higher priority number takes precedence. Priority values also affect the 613order in which multiple ``.bbappend`` files for the same recipe are 614applied. You can either specify the priority manually, or allow the 615build system to calculate it based on the layer's dependencies. 616 617To specify the layer's priority manually, use the 618:term:`BBFILE_PRIORITY` 619variable and append the layer's root name:: 620 621 BBFILE_PRIORITY_mylayer = "1" 622 623.. note:: 624 625 It is possible for a recipe with a lower version number 626 :term:`PV` in a layer that has a higher 627 priority to take precedence. 628 629 Also, the layer priority does not currently affect the precedence 630 order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake 631 might address this. 632 633Managing Layers 634=============== 635 636You can use the BitBake layer management tool ``bitbake-layers`` to 637provide a view into the structure of recipes across a multi-layer 638project. Being able to generate output that reports on configured layers 639with their paths and priorities and on ``.bbappend`` files and their 640applicable recipes can help to reveal potential problems. 641 642For help on the BitBake layer management tool, use the following 643command:: 644 645 $ bitbake-layers --help 646 647The following list describes the available commands: 648 649- ``help:`` Displays general help or help on a specified command. 650 651- ``show-layers:`` Shows the current configured layers. 652 653- ``show-overlayed:`` Lists overlayed recipes. A recipe is overlayed 654 when a recipe with the same name exists in another layer that has a 655 higher layer priority. 656 657- ``show-recipes:`` Lists available recipes and the layers that 658 provide them. 659 660- ``show-appends:`` Lists ``.bbappend`` files and the recipe files to 661 which they apply. 662 663- ``show-cross-depends:`` Lists dependency relationships between 664 recipes that cross layer boundaries. 665 666- ``add-layer:`` Adds a layer to ``bblayers.conf``. 667 668- ``remove-layer:`` Removes a layer from ``bblayers.conf`` 669 670- ``flatten:`` Flattens the layer configuration into a separate 671 output directory. Flattening your layer configuration builds a 672 "flattened" directory that contains the contents of all layers, with 673 any overlayed recipes removed and any ``.bbappend`` files appended to 674 the corresponding recipes. You might have to perform some manual 675 cleanup of the flattened layer as follows: 676 677 - Non-recipe files (such as patches) are overwritten. The flatten 678 command shows a warning for these files. 679 680 - Anything beyond the normal layer setup has been added to the 681 ``layer.conf`` file. Only the lowest priority layer's 682 ``layer.conf`` is used. 683 684 - Overridden and appended items from ``.bbappend`` files need to be 685 cleaned up. The contents of each ``.bbappend`` end up in the 686 flattened recipe. However, if there are appended or changed 687 variable values, you need to tidy these up yourself. Consider the 688 following example. Here, the ``bitbake-layers`` command adds the 689 line ``#### bbappended ...`` so that you know where the following 690 lines originate:: 691 692 ... 693 DESCRIPTION = "A useful utility" 694 ... 695 EXTRA_OECONF = "--enable-something" 696 ... 697 698 #### bbappended from meta-anotherlayer #### 699 700 DESCRIPTION = "Customized utility" 701 EXTRA_OECONF += "--enable-somethingelse" 702 703 704 Ideally, you would tidy up these utilities as follows:: 705 706 ... 707 DESCRIPTION = "Customized utility" 708 ... 709 EXTRA_OECONF = "--enable-something --enable-somethingelse" 710 ... 711 712- ``layerindex-fetch``: Fetches a layer from a layer index, along 713 with its dependent layers, and adds the layers to the 714 ``conf/bblayers.conf`` file. 715 716- ``layerindex-show-depends``: Finds layer dependencies from the 717 layer index. 718 719- ``save-build-conf``: Saves the currently active build configuration 720 (``conf/local.conf``, ``conf/bblayers.conf``) as a template into a layer. 721 This template can later be used for setting up builds via :term:``TEMPLATECONF``. 722 For information about saving and using configuration templates, see 723 ":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`". 724 725- ``create-layer``: Creates a basic layer. 726 727- ``create-layers-setup``: Writes out a configuration file and/or a script that 728 can replicate the directory structure and revisions of the layers in a current build. 729 For more information, see ":ref:`dev-manual/layers:saving and restoring the layers setup`". 730 731Creating a General Layer Using the ``bitbake-layers`` Script 732============================================================ 733 734The ``bitbake-layers`` script with the ``create-layer`` subcommand 735simplifies creating a new general layer. 736 737.. note:: 738 739 - For information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" 740 section in the Yocto 741 Project Board Specific (BSP) Developer's Guide. 742 743 - In order to use a layer with the OpenEmbedded build system, you 744 need to add the layer to your ``bblayers.conf`` configuration 745 file. See the ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" 746 section for more information. 747 748The default mode of the script's operation with this subcommand is to 749create a layer with the following: 750 751- A layer priority of 6. 752 753- A ``conf`` subdirectory that contains a ``layer.conf`` file. 754 755- A ``recipes-example`` subdirectory that contains a further 756 subdirectory named ``example``, which contains an ``example.bb`` 757 recipe file. 758 759- A ``COPYING.MIT``, which is the license statement for the layer. The 760 script assumes you want to use the MIT license, which is typical for 761 most layers, for the contents of the layer itself. 762 763- A ``README`` file, which is a file describing the contents of your 764 new layer. 765 766In its simplest form, you can use the following command form to create a 767layer. The command creates a layer whose name corresponds to 768"your_layer_name" in the current directory:: 769 770 $ bitbake-layers create-layer your_layer_name 771 772As an example, the following command creates a layer named ``meta-scottrif`` 773in your home directory:: 774 775 $ cd /usr/home 776 $ bitbake-layers create-layer meta-scottrif 777 NOTE: Starting bitbake server... 778 Add your new layer with 'bitbake-layers add-layer meta-scottrif' 779 780If you want to set the priority of the layer to other than the default 781value of "6", you can either use the ``--priority`` option or you 782can edit the 783:term:`BBFILE_PRIORITY` value 784in the ``conf/layer.conf`` after the script creates it. Furthermore, if 785you want to give the example recipe file some name other than the 786default, you can use the ``--example-recipe-name`` option. 787 788The easiest way to see how the ``bitbake-layers create-layer`` command 789works is to experiment with the script. You can also read the usage 790information by entering the following:: 791 792 $ bitbake-layers create-layer --help 793 NOTE: Starting bitbake server... 794 usage: bitbake-layers create-layer [-h] [--priority PRIORITY] 795 [--example-recipe-name EXAMPLERECIPE] 796 layerdir 797 798 Create a basic layer 799 800 positional arguments: 801 layerdir Layer directory to create 802 803 optional arguments: 804 -h, --help show this help message and exit 805 --priority PRIORITY, -p PRIORITY 806 Layer directory to create 807 --example-recipe-name EXAMPLERECIPE, -e EXAMPLERECIPE 808 Filename of the example recipe 809 810Adding a Layer Using the ``bitbake-layers`` Script 811================================================== 812 813Once you create your general layer, you must add it to your 814``bblayers.conf`` file. Adding the layer to this configuration file 815makes the OpenEmbedded build system aware of your layer so that it can 816search it for metadata. 817 818Add your layer by using the ``bitbake-layers add-layer`` command:: 819 820 $ bitbake-layers add-layer your_layer_name 821 822Here is an example that adds a 823layer named ``meta-scottrif`` to the configuration file. Following the 824command that adds the layer is another ``bitbake-layers`` command that 825shows the layers that are in your ``bblayers.conf`` file:: 826 827 $ bitbake-layers add-layer meta-scottrif 828 NOTE: Starting bitbake server... 829 Parsing recipes: 100% |##########################################################| Time: 0:00:49 830 Parsing of 1441 .bb files complete (0 cached, 1441 parsed). 2055 targets, 56 skipped, 0 masked, 0 errors. 831 $ bitbake-layers show-layers 832 NOTE: Starting bitbake server... 833 layer path priority 834 ========================================================================== 835 meta /home/scottrif/poky/meta 5 836 meta-poky /home/scottrif/poky/meta-poky 5 837 meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5 838 workspace /home/scottrif/poky/build/workspace 99 839 meta-scottrif /home/scottrif/poky/build/meta-scottrif 6 840 841 842Adding the layer to this file 843enables the build system to locate the layer during the build. 844 845.. note:: 846 847 During a build, the OpenEmbedded build system looks in the layers 848 from the top of the list down to the bottom in that order. 849 850Saving and restoring the layers setup 851===================================== 852 853Once you have a working build with the correct set of layers, it is beneficial 854to capture the layer setup --- what they are, which repositories they come from 855and which SCM revisions they're at --- into a configuration file, so that this 856setup can be easily replicated later, perhaps on a different machine. Here's 857how to do this:: 858 859 $ bitbake-layers create-layers-setup /srv/work/alex/meta-alex/ 860 NOTE: Starting bitbake server... 861 NOTE: Created /srv/work/alex/meta-alex/setup-layers.json 862 NOTE: Created /srv/work/alex/meta-alex/setup-layers 863 864The tool needs a single argument which tells where to place the output, consisting 865of a json formatted layer configuration, and a ``setup-layers`` script that can use that configuration 866to restore the layers in a different location, or on a different host machine. The argument 867can point to a custom layer (which is then deemed a "bootstrap" layer that needs to be 868checked out first), or into a completely independent location. 869 870The replication of the layers is performed by running the ``setup-layers`` script provided 871above: 872 873#. Clone the bootstrap layer or some other repository to obtain 874 the json config and the setup script that can use it. 875 876#. Run the script directly with no options:: 877 878 alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers 879 Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override. 880 881 Setting up source meta-intel, revision 15.0-hardknott-3.3-310-g0a96edae, branch master 882 Running 'git init -q /srv/work/alex/my-build/meta-intel' 883 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 884 Running 'git fetch -q origin || true' in /srv/work/alex/my-build/meta-intel 885 Running 'git checkout -q 0a96edae609a3f48befac36af82cf1eed6786b4a' in /srv/work/alex/my-build/meta-intel 886 887 Setting up source poky, revision 4.1_M1-372-g55483d28f2, branch akanavin/setup-layers 888 Running 'git init -q /srv/work/alex/my-build/poky' 889 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 890 Running 'git fetch -q origin || true' in /srv/work/alex/my-build/poky 891 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 892 Running 'git fetch -q poky-contrib || true' in /srv/work/alex/my-build/poky 893 Running 'git checkout -q 11db0390b02acac1324e0f827beb0e2e3d0d1d63' in /srv/work/alex/my-build/poky 894 895.. note:: 896 This will work to update an existing checkout as well. 897 898.. note:: 899 The script is self-sufficient and requires only python3 900 and git on the build machine. 901 902.. note:: 903 Both the ``create-layers-setup`` and the ``setup-layers`` provided several additional options 904 that customize their behavior - you are welcome to study them via ``--help`` command line parameter. 905 906