1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3************************ 4Yocto Project Compatible 5************************ 6 7============ 8Introduction 9============ 10 11After the introduction of layers to OpenEmbedded, it quickly became clear 12that while some layers were popular and worked well, others developed a 13reputation for being "problematic". Those were layers which didn't 14interoperate well with others and tended to assume they controlled all 15the aspects of the final output. This usually isn't intentional but happens 16because such layers are often created by developers with a particular focus 17(e.g. a company's :term:`BSP<Board Support Package (BSP)>`) whilst the end 18users have a different one (e.g. integrating that 19:term:`BSP<Board Support Package (BSP)>` into a product). 20 21As a result of noticing such patterns and friction between layers, the project 22developed the "Yocto Project Compatible" badge program, allowing layers 23following the best known practises to be marked as being widely compatible 24with other ones. This takes the form of a set of "yes/no" binary answer 25questions where layers can declare if they meet the appropriate criteria. 26In the second version of the program, a script was added to make validation 27easier and clearer, the script is called ``yocto-check-layer`` and is 28available in :term:`OpenEmbedded-Core (OE-Core)`. 29 30See :ref:`dev-manual/common-tasks:making sure your layer is compatible with yocto project` 31for details. 32 33======== 34Benefits 35======== 36 37:ref:`overview-manual/yp-intro:the yocto project layer model` is powerful 38and flexible: it gives users the ultimate power to change pretty much any 39aspect of the system but as with most things, power comes with responsibility. 40The Yocto Project would like to see people able to mix and match BSPs with 41distro configs or software stacks and be able to merge succesfully. 42Over time, the project identified characteristics in layers that allow them 43to operate well together. "anti-patterns" were also found, preventing layers 44from working well together. 45 46The intent of the compatibility program is simple: if the layer passes the 47compatibility tests, it is considered "well behaved" and should operate 48and cooperate well with other compatible layers. 49 50The benefits of compatibility can be seen from multiple different user and 51member perspectives. From a hardware perspective 52(a :ref:`overview-manual/concepts:bsp layer`), compatibility means the 53hardware can be used in many different products and use cases without 54impacting the software stacks being run with it. For a company developing 55a product, compatibility gives you a specification / standard you can 56require in a contract and then know it will have certain desired 57characteristics for interoperability. It also puts constraints on how invasive 58the code bases are into the rest of the system, meaning that multiple 59different separate hardware support layers can coexist (e.g. for multiple 60product lines from different hardware manufacturers). This can also make it 61easier for one or more parties to upgrade those system components for security 62purposes during the lifecycle of a product. 63 64================== 65Validating a layer 66================== 67 68The badges are available to members of the Yocto Project (as member benefit) 69and to open source projects run on a non-commercial basis. However, anyone can 70answer the questions and run the script. 71 72The project encourages all layer maintainers to review the questions and the 73output from the script against their layer, as the way some layers are 74constructed often has unintended consequences. The questions and the script 75are designed to highlight known issues which are often easy to solve. This 76makes layers easier to use and therefore more popular. 77 78It is intended that over time, the tests will evolve as new best known 79practices are identified, and as new interoperability issues are found, 80unnecessarily restricting layer interoperability. If anyone becomes aware of 81either type, please let the project know through the 82:yocto_home:`technical calls </public-virtual-meetings/>`, 83the :yocto_home:`mailing lists </community/mailing-lists/>` 84or through the :oe_wiki:`Technical Steering Committee (TSC) </TSC>`. 85The TSC is responsible for the technical criteria used by the program. 86 87Layers are divided into three types: 88 89- :ref:`"BSP" or "hardware support"<overview-manual/concepts:bsp layer>` 90 layers contain support for particular pieces of hardware. This includes 91 kernel and boot loader configuration, and any recipes for firmware or 92 kernel modules needed for the hardware. Such layers usually correspond 93 to a :term:`MACHINE` setting. 94 95- :ref:`"distro" layers<overview-manual/concepts:distro layer>` defined 96 as layers providing configuration options and settings such as the 97 choice of init system, compiler and optimisation options, and 98 configuration and choices of software components. This would usually 99 correspond to a :term:`DISTRO` setting. 100 101- "software" layers are usually recipes. A layer might target a 102 particular graphical UI or software stack component. 103 104Here are key best practices the program tries to encourage: 105 106- A layer should clearly show who maintains it, and who change 107 submissions and bug reports should be sent to. 108 109- Where multiple types of functionality are present, the layer should 110 be internally divided into sublayers to separate these components. 111 That's because some users may only need one of them and separability 112 is a key best practice. 113 114- Adding a layer to a build should not modify that build, unless the 115 user changes a configuration setting to activate the layer, by selecting 116 a :term:`MACHINE`, a :term:`DISTRO` or a :term:`DISTRO_FEATURES` setting. 117 118- Layers should be documenting where they don’t support normal "core" 119 functionality such as where debug symbols are disabled or missing, where 120 development headers and on-target library usage may not work or where 121 functionality like the SDK/eSDK would not be expected to work. 122 123The project does test the compatibility status of the core project layers on 124its :doc:`Autobuilder </test-manual/understand-autobuilder>`. 125 126The official form to submit compatibility requests with is at 127:yocto_home:`/ecosystem/branding/compatible-registration/`. 128Applicants can display the badge they get when their application is successful. 129 130