Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK |
| 2 | |
| 3 | ************************ |
| 4 | Yocto Project Compatible |
| 5 | ************************ |
| 6 | |
| 7 | ============ |
| 8 | Introduction |
| 9 | ============ |
| 10 | |
| 11 | After the introduction of layers to OpenEmbedded, it quickly became clear |
| 12 | that while some layers were popular and worked well, others developed a |
| 13 | reputation for being "problematic". Those were layers which didn't |
| 14 | interoperate well with others and tended to assume they controlled all |
| 15 | the aspects of the final output. This usually isn't intentional but happens |
| 16 | because 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 |
| 18 | users have a different one (e.g. integrating that |
| 19 | :term:`BSP<Board Support Package (BSP)>` into a product). |
| 20 | |
| 21 | As a result of noticing such patterns and friction between layers, the project |
| 22 | developed the "Yocto Project Compatible" badge program, allowing layers |
| 23 | following the best known practises to be marked as being widely compatible |
| 24 | with other ones. This takes the form of a set of "yes/no" binary answer |
| 25 | questions where layers can declare if they meet the appropriate criteria. |
| 26 | In the second version of the program, a script was added to make validation |
| 27 | easier and clearer, the script is called ``yocto-check-layer`` and is |
| 28 | available in :term:`OpenEmbedded-Core (OE-Core)`. |
| 29 | |
| 30 | See :ref:`dev-manual/common-tasks:making sure your layer is compatible with yocto project` |
| 31 | for details. |
| 32 | |
| 33 | ======== |
| 34 | Benefits |
| 35 | ======== |
| 36 | |
| 37 | :ref:`overview-manual/yp-intro:the yocto project layer model` is powerful |
| 38 | and flexible: it gives users the ultimate power to change pretty much any |
| 39 | aspect of the system but as with most things, power comes with responsibility. |
| 40 | The Yocto Project would like to see people able to mix and match BSPs with |
| 41 | distro configs or software stacks and be able to merge succesfully. |
| 42 | Over time, the project identified characteristics in layers that allow them |
| 43 | to operate well together. "anti-patterns" were also found, preventing layers |
| 44 | from working well together. |
| 45 | |
| 46 | The intent of the compatibility program is simple: if the layer passes the |
| 47 | compatibility tests, it is considered "well behaved" and should operate |
| 48 | and cooperate well with other compatible layers. |
| 49 | |
| 50 | The benefits of compatibility can be seen from multiple different user and |
| 51 | member perspectives. From a hardware perspective |
| 52 | (a :ref:`overview-manual/concepts:bsp layer`), compatibility means the |
| 53 | hardware can be used in many different products and use cases without |
| 54 | impacting the software stacks being run with it. For a company developing |
| 55 | a product, compatibility gives you a specification / standard you can |
| 56 | require in a contract and then know it will have certain desired |
| 57 | characteristics for interoperability. It also puts constraints on how invasive |
| 58 | the code bases are into the rest of the system, meaning that multiple |
| 59 | different separate hardware support layers can coexist (e.g. for multiple |
| 60 | product lines from different hardware manufacturers). This can also make it |
| 61 | easier for one or more parties to upgrade those system components for security |
| 62 | purposes during the lifecycle of a product. |
| 63 | |
| 64 | ================== |
| 65 | Validating a layer |
| 66 | ================== |
| 67 | |
| 68 | The badges are available to members of the Yocto Project (as member benefit) |
| 69 | and to open source projects run on a non-commercial basis. However, anyone can |
| 70 | answer the questions and run the script. |
| 71 | |
| 72 | The project encourages all layer maintainers to review the questions and the |
| 73 | output from the script against their layer, as the way some layers are |
| 74 | constructed often has unintended consequences. The questions and the script |
| 75 | are designed to highlight known issues which are often easy to solve. This |
| 76 | makes layers easier to use and therefore more popular. |
| 77 | |
| 78 | It is intended that over time, the tests will evolve as new best known |
| 79 | practices are identified, and as new interoperability issues are found, |
| 80 | unnecessarily restricting layer interoperability. If anyone becomes aware of |
| 81 | either type, please let the project know through the |
| 82 | :yocto_home:`technical calls </public-virtual-meetings/>`, |
| 83 | the :yocto_home:`mailing lists </community/mailing-lists/>` |
| 84 | or through the :oe_wiki:`Technical Steering Committee (TSC) </TSC>`. |
| 85 | The TSC is responsible for the technical criteria used by the program. |
| 86 | |
| 87 | Layers 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 | |
| 104 | Here 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 Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 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 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 123 | The project does test the compatibility status of the core project layers on |
| 124 | its :doc:`Autobuilder </test-manual/understand-autobuilder>`. |
| 125 | |
| 126 | The official form to submit compatibility requests with is at |
| 127 | :yocto_home:`/ecosystem/branding/compatible-registration/`. |
| 128 | Applicants can display the badge they get when their application is successful. |
| 129 | |