Layers

  • Each project should have its own layer called meta-<projectname> to hold any and all changes and additions needed for that project.

  • Each project should also define an image named <projectname>-image (rather than appending ost-image et al).

  • Any changes to recipes of other layers (e.g. meta-ost) are carried out by appending the recipe in meta-<projectname> and should only be upstreamed later if deemed appropriate.

General layer structure

  • meta-ost

    • meta-ost-ros

    • meta-ost-toradex

    • (meta-ost-ethercat (internal use only))

      • meta-<projectname>

meta-ost is the core layer for OST specific changes and should only contain recipes applicable to the MACHINES in it. It should not rely on BSPs that are not part of poky.

Recipes and MACHINES that rely on external BSPs should get their own layer named meta-ost-<vendor>, e.g. meta-ost-toradex for the colibri-imx6 based cb20, that requires the Toradex BSP. This second layer also contains layers such as meta-ost-ros and meta-ost-ethercat which don't rely on external BSPs, but provide optional software features. Recipes that require large or numerous dependencies – such as meta-ost-ros – should be split into its own layer as to keep the core build slim. Lastly, there is the meta-<projectname> layer. Every project using yocto should have its own layer to hold recipes and changes that are specific to that project. This structure ensures modularity and allows every project to customize the build without changing meta-ost or its companions.



CI/CD

The CI/CD pipeline is integrated into Gitlab and split into 2 parts: the layer and general configuration data.

The general configuration is located in its own repository under ci/yocto. It contains the scripts and config files necessary to easily build the images, as well as the gitlab CI template yocto.gitlab-ci.yml that serves as the basis for the layer's CI config.

The simplest way to enable CI yocto builds for a layer repository is to include single-machine.yml from ci/yocto. This defines all the jobs and stages only needing a few variables to set up the MACHINE, Image, etc (see e.g. meta-bsc-os). Alternatively, yocto.gitlab-ci.yml can be included for more complex scenarios. For example, meta-ost requires builds for 4 (at the time of writing) different MACHINEs and thus uses yocto.gitlab-ci.yml to define jobs for every platform.

When Pipelines are run

CI pIpelines are only run for:

  • Merge Requests
  • Schedules
  • Tags

While pipelines could run for every commit, this would involve a lot of redundant pipelines: A pipeline would run for a commit when it is pushed, then again when a merge request is opened and then again when that request gets merged. Only running the pipeline on merge requests means only one pipeline will run. Only allowing a request to be merged after a pipeline succeeded ensures the target branch is always in a working state. 

Submitting changes

Any and all changes needed should first be made in meta-projectname>. This includes updating libraries from meta-ost et al. to a newer version than what is currently included in meta-ost.

Any recipes or changes that are specific to the project will stay in meta-<projectname>, while more general changes such as adding debug utilities to the image may be upstreamed to meta-ost or the appropriate vendor/technology specific layer (e.g. meta-ost-toradex).

Note that as stated above, meta-ost itself should only have minimal dependencies and its contents should apply to most (ideally all) builds. If in doubt, create a technology/vendor specific layer first. It can always be merged into meta-ost later.

Technology/vendor specific layers follow the same principle as meta-ost in terms of submitting changes: Any changes should be implemented locally first – using meta-<projectname> – before they are upstreamed and/or a new layer is created.


Git(lab) Workflow

The stable branches are named after the yocto release: e.g. scarthgap, krikstone, dunfell. Do not push changes to these branches directly. Create a merge request instead. By convention, changes are generally pushed to a '-next'  branch (e.g. scarthgap-next to merge into scarthgap or kirkstone-next for kirkstone) that then serves as the source of  a merge request. However, this is not a strict rule. Requests are merged using fast-forward only, ensuring  a linear history and no merge commits (hence no need for  a particularly descriptive source branch name). Creating a merge request automatically triggers a CI pipeline and the request can only be merged once the pipeline has succeeded. This ensures the stability of the stable branches.

Summary

  • create new branch (e.g. git checkout -b scarthgap-next) 
  • make and commit changes
  • push -next branch (e.g. git push scarthgap-next)
  • create merge request
    • wait for CI to succeed
    • merge
  • checkout stable branch (e.g. git checkout scarthgap)
  • git pull
  • Keine Stichwörter