diff options
Diffstat (limited to 'documentation/test-manual/yocto-project-compatible.rst')
| -rw-r--r-- | documentation/test-manual/yocto-project-compatible.rst | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/documentation/test-manual/yocto-project-compatible.rst b/documentation/test-manual/yocto-project-compatible.rst new file mode 100644 index 0000000000..65d924fad9 --- /dev/null +++ b/documentation/test-manual/yocto-project-compatible.rst @@ -0,0 +1,129 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +************************ +Yocto Project Compatible +************************ + +============ +Introduction +============ + +After the introduction of layers to OpenEmbedded, it quickly became clear +that while some layers were popular and worked well, others developed a +reputation for being "problematic". Those were layers which didn't +interoperate well with others and tended to assume they controlled all +the aspects of the final output. This usually isn't intentional but happens +because such layers are often created by developers with a particular focus +(e.g. a company's :term:`BSP<Board Support Package (BSP)>`) whilst the end +users have a different one (e.g. integrating that +:term:`BSP<Board Support Package (BSP)>` into a product). + +As a result of noticing such patterns and friction between layers, the project +developed the "Yocto Project Compatible" badge program, allowing layers +following the best known practises to be marked as being widely compatible +with other ones. This takes the form of a set of "yes/no" binary answer +questions where layers can declare if they meet the appropriate criteria. +In the second version of the program, a script was added to make validation +easier and clearer, the script is called ``yocto-check-layer`` and is +available in :term:`OpenEmbedded-Core (OE-Core)`. + +See :ref:`dev-manual/layers:making sure your layer is compatible with yocto project` +for details. + +======== +Benefits +======== + +:ref:`overview-manual/yp-intro:the yocto project layer model` is powerful +and flexible: it gives users the ultimate power to change pretty much any +aspect of the system but as with most things, power comes with responsibility. +The Yocto Project would like to see people able to mix and match BSPs with +distro configs or software stacks and be able to merge succesfully. +Over time, the project identified characteristics in layers that allow them +to operate well together. "anti-patterns" were also found, preventing layers +from working well together. + +The intent of the compatibility program is simple: if the layer passes the +compatibility tests, it is considered "well behaved" and should operate +and cooperate well with other compatible layers. + +The benefits of compatibility can be seen from multiple different user and +member perspectives. From a hardware perspective +(a :ref:`overview-manual/concepts:bsp layer`), compatibility means the +hardware can be used in many different products and use cases without +impacting the software stacks being run with it. For a company developing +a product, compatibility gives you a specification / standard you can +require in a contract and then know it will have certain desired +characteristics for interoperability. It also puts constraints on how invasive +the code bases are into the rest of the system, meaning that multiple +different separate hardware support layers can coexist (e.g. for multiple +product lines from different hardware manufacturers). This can also make it +easier for one or more parties to upgrade those system components for security +purposes during the lifecycle of a product. + +================== +Validating a layer +================== + +The badges are available to members of the Yocto Project (as member benefit) +and to open source projects run on a non-commercial basis. However, anyone can +answer the questions and run the script. + +The project encourages all layer maintainers to review the questions and the +output from the script against their layer, as the way some layers are +constructed often has unintended consequences. The questions and the script +are designed to highlight known issues which are often easy to solve. This +makes layers easier to use and therefore more popular. + +It is intended that over time, the tests will evolve as new best known +practices are identified, and as new interoperability issues are found, +unnecessarily restricting layer interoperability. If anyone becomes aware of +either type, please let the project know through the +:yocto_home:`technical calls </public-virtual-meetings/>`, +the :yocto_home:`mailing lists </community/mailing-lists/>` +or through the :oe_wiki:`Technical Steering Committee (TSC) </TSC>`. +The TSC is responsible for the technical criteria used by the program. + +Layers are divided into three types: + +- :ref:`"BSP" or "hardware support"<overview-manual/concepts:bsp layer>` + layers contain support for particular pieces of hardware. This includes + kernel and boot loader configuration, and any recipes for firmware or + kernel modules needed for the hardware. Such layers usually correspond + to a :term:`MACHINE` setting. + +- :ref:`"distro" layers<overview-manual/concepts:distro layer>` defined + as layers providing configuration options and settings such as the + choice of init system, compiler and optimisation options, and + configuration and choices of software components. This would usually + correspond to a :term:`DISTRO` setting. + +- "software" layers are usually recipes. A layer might target a + particular graphical UI or software stack component. + +Here are key best practices the program tries to encourage: + +- A layer should clearly show who maintains it, and who change + submissions and bug reports should be sent to. + +- Where multiple types of functionality are present, the layer should + be internally divided into sublayers to separate these components. + That's because some users may only need one of them and separability + is a key best practice. + +- Adding a layer to a build should not modify that build, unless the + user changes a configuration setting to activate the layer, by selecting + a :term:`MACHINE`, a :term:`DISTRO` or a :term:`DISTRO_FEATURES` setting. + +- Layers should be documenting where they don’t support normal "core" + functionality such as where debug symbols are disabled or missing, where + development headers and on-target library usage may not work or where + functionality like the SDK/eSDK would not be expected to work. + +The project does test the compatibility status of the core project layers on +its :doc:`Autobuilder </test-manual/understand-autobuilder>`. + +The official form to submit compatibility requests with is at +:yocto_home:`/ecosystem/branding/compatible-registration/`. +Applicants can display the badge they get when their application is successful. + |