blob: 96c12ac083400874d6ba746c25ce891b4c926bdb [file] [log] [blame]
Andrew Geissler09036742021-06-25 14:25:14 -05001.. 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
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500118- 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
Andrew Geissler09036742021-06-25 14:25:14 -0500123The 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