Yocto Project - User contributions [en]

User:Mhatle

2025-07-14T17:36:27Z

Mark Hatle:

Name: Mark Hatle

email: mark.hatle at amd dot com

freenode IRC: fray

----

Currently handling pseudo change requests.

Working on RISC-V base architecture (tune) definitions and related.

Maintainer of meta-xilinx and meta-xilinx-tools.

Binary Distro Prototype

2024-03-26T16:37:27Z

Mark Hatle: /* Process and policy for proposing adding new layers to the binary distro test artefacts process */

== Scope of a Yocto Binary Distribution Prototype ==

The Yocto Project has received funding for developing the processes and tooling for enabling binary distributions (see the [https://web.archive.org/web/20230620145823/https://www.yoctoproject.org/community/yocto-project-engineering-request-for-quotation/ Engineering Request for Quotation]). As part of that, the project would need some form of prototype test binary distro to develop and test this. The main goal of this would be to develop the tools, and documentation needed to build a binary distribution and allow application and system developers to progress through a hierarchy of different uses of the resulting environment:

* '''Beginner''' use case: begin by fetching a binary image, ready to boot on a target machine. Extend the system by installing extra applications through package feeds.
* '''Intermediate''' use case: tweak and rebuild existing packages, compile new applications and modify images by using an eSDK and other binary artifacts.
* '''Advanced''' use case: completely reorganize and optimize the system for a specific target, switching to building from source

The first step in this effort is to define the scope of the prototype we will develop. We are looking for feedback and comments about issues we may not have considered.

Bear in mind that a prototype has to be limited in scope. However, the developed tools, procedures and documentation will open a pathway for the Yocto Project and OpenEmbedded community to experiment with more architectures, features, recipes and images.

Also bear in mind that the effort is not planning to adopt, replace or repeat any existing distributions such as [[wikipedia:Ångström_distribution|Ångström]] or [https://www.yoedistro.org/ Yoe].

Notes from discussions:
* Alex Kanavin suggests as "Intermediate" step to use the [https://patchwork.yoctoproject.org/project/oe-core/patch/20231107105844.712846-1-alex@linutronix.de/ build bundles] that he submitted. However, this is closer to the "Advanced" use case as this already uses BitBake and OE/Yocto ([https://lists.openembedded.org/g/openembedded-architecture/message/1850 discussion]).

=== Target architectures and machines ===

The first prototype would only target the below architectures:
* "x86-64" architecture through the [https://git.yoctoproject.org/poky/tree/meta/conf/machine/qemux86-64.conf qemux86-64] machine.
* "arm64" architecture through the [https://git.yoctoproject.org/poky/tree/meta/conf/machine/qemuarm64.conf qemuarm64] machine.

Testing would happen through QEMU system emulation. The emulated architectures will be sufficient to test the outputs of this effort, but the developed tooling and documentation should allow the community to experiment with other target architectures and machines.

=== Target tunes ===

The binary images and other artifacts should be generated with the default tunes of the [https://git.yoctoproject.org/poky/tree/meta/conf/machine/qemux86-64.conf qemux86-64] and [https://git.yoctoproject.org/poky/tree/meta/conf/machine/qemuarm64.conf qemuarm64] machines.

See [https://docs.yoctoproject.org/ref-manual/variables.html#term-DEFAULTTUNE DEFAULTTUNE] for details.

=== Distribution, Init Manager, C library ===

Images and package feeds will be generated for the [https://git.yoctoproject.org/poky/tree/meta-poky/conf/distro/poky-altcfg.conf poky-altcfg] distribution, using the systemd init manager.

Choosing systemd makes the binary reference distribution as generic as possible, enabling the widest set of features, and being more familiar to more users. Of course, switching to other init managers and more restricted features will be possible by later compiling the system from source (advanced use case).

This also implies the choice of the GNU C library (glibc). Selecting glibc also makes sense to enable the widest possible selection of packages, and some packages have limited or no support for the Musl C library. That's typically the case of systemd, which upstream only supports glibc.

Last but not least, people who want to use the Musl C library probably do that to optimize the size of their system, which is a use case not well adapted to using ready-made binary images.
Such an advanced use case will be addressed by re-compiling from source, after testing initial prototypes with the binary image based on glibc.

=== Binary images ===

The prototype will provide as a reference, for each targeted architecture:
* The root filesystem binary image, generated by building the <code>core-image-full-cmdline</code> target.
* An image containing on-target development tools (e.g compiler, debugger)
* The corresponding SD card images to be booted through QEMU. Other boot methods will be possible, but will be outside of the scope of the reference distribution.

=== Package feeds ===

For each targeted architecture, several package feeds will be available to allow for bugfix or security updates or to extend the image with additional packages:
* Architecture independent feed
* Architecture dependent feed
* Machine dependent feed
See [https://docs.yoctoproject.org/dev-manual/packages.html#using-runtime-package-management Using Runtime Package Management] for details.

The feeds for the first prototype will contain all the packages which are supported by the [https://git.yoctoproject.org/poky/tree/meta-poky/conf/distro/poky-altcfg.conf poky-altcfg] distribution as produced by the <code>bitbake world</code> command for the set of layers supplied by Poky.

=== Available reference package formats ===

To keep the first prototype simple, we will only release images and package feeds based on the "ipk" format supported by [[wikipedia:opkg|opkg]] package manager.

Of course, the OpenEmbedded build system also supports the [[wikipedia:Deb_(file_format)|deb]] and [[wikipedia:RPM_Package_Manager|rpm]] package formats, so users will be able to generate their own images and feeds based on these other formats.

Another reason for not providing "deb" and "rpm" packages is that we do not want inexperienced users to expect to be able to grab and use such packages produced for regular Linux distributions (Debian, Fedora, etc.). Being built with different C library versions and toolchains, the corresponding binaries are most likely to be broken anyway.

=== Available reference binary artifacts and deliverables ===

The first prototype will make the below binary artifacts publicly available:
* Root filesystem images (as specified above)
* Binary package feeds (as specified above)
* [https://docs.yoctoproject.org/ref-manual/variables.html#term-PR PR] database, so that people can manage updates to packages, by importing the database in a local PR server.
* Prebuilt object data ("Shared State cache) through a public server (see [https://docs.yoctoproject.org/ref-manual/variables.html#term-SSTATE_MIRRORS SSTATE_MIRRORS]), to reuse binary output already built by the Yocto Project autobuilders, to reduce the compile time of additional packages.
* Hash Equivalence data through a public server (see [https://docs.yoctoproject.org/bitbake/2.4/bitbake-user-manual/bitbake-user-manual-ref-variables.html#term-BB_HASHSERVE_UPSTREAM BB_HASHSERVE_UPSTREAM]), to increase the reusability of prebuilt objects.

Share State and Hash Equivalence data would be only useful to "Intermediate" and "Advanced" use cases, to rebuild parts or the whole system from source.

Such artifacts will be served through a Content Delivery Network (CDN), to make sure that they can be downloaded fast enough from any location in the world, in a way that remains much faster than re-compiling such artifacts from sources.

Those binaries should also be released along with:
* Sources corresponding to the software used to build the image, as produced by the [https://docs.yoctoproject.org/ref-manual/classes.html#ref-classes-archiver archiver] class. Unlike standard GNU/Linux distributions, we won't ship source package feeds (such as SRPMs)<ref>Only Source RPMs are supported by the [https://docs.yoctoproject.org/ref-manual/classes.html#ref-classes-archiver archiver] class. To obtain them, you need to set <code>INHERIT += "archiver"</code>, <code>PACKAGE_CLASSES = "package_rpm"</code> and <code>ARCHIVER_MODE[srpm] = "1"</code>. The generation of source <code>deb</code> or <code>ipk</code> packages is currently not supported.</ref>.<ref>The <code>-src</code> packages which recipes can produce are only meant for debugging together with <code>-dbg</code> packages. See [https://docs.yoctoproject.org/dev/ref-manual/variables.html#term-PACKAGE_DEBUG_SPLIT_STYLE PACKAGE_DEBUG_SPLIT_STYLE].</ref>
* SPDX output for the initial image
* The build system and layer sources. A good fit would be Alex Kanavin's [https://patchwork.yoctoproject.org/project/oe-core/patch/20231107105844.712846-1-alex@linutronix.de/ build bundles].

=== Defining policies and processes ===

This reference binary distribution prototype will also drive the documentation of policies and process to address future work such as:
* What criteria should a new CPU architecture or platform tuning meet to be added / tested?
* What criteria should other layers meet to be tested, in addition to being already tested by the Autobuilder? Should these criteria only apply to specific recipes or to the entire layers containing them?

See the [[#Policies and Processes | Policies and Processes]].

=== Testing plans ===

Here are the tests we plan to implement:
* Producing and testing binary images through the autobuilder
* Making nightly builds available to testers
* Testing that package updates apply successfully:
** Within the current stable branch (nanbield): from one release update to the next, and from the latest release update to the tip of the branch
** Between release branches: from the latest update to our latest LTS (kirkstone), to the latest update to the current stable release (nanbield).
* Testing that it's also possible to build and deploy packages from the meta-openembedded and meta-virtualization layers, as a way to assess the relevance of our policies and process for additional layers or recipes. This would also be a way to demonstrate the ability to build container images, which would be a great way to ship binary distributions.

Here are other tests that would be worth implementing:
* Check that package upgrades don't cause configuration file changes to be lost. See [https://lore.kernel.org/openembedded-core/0e38566f-a1f9-4ebb-8492-2c50945eeeb4@gmail.com/T/#t this discussion].
* Check that the latest package upgrades successfully apply to any previous release, at least on the same branch. For example, upgrading directly from release x.y.n-2 to x.y may not work without going through x.y.n-1 as an intermediate. This could happen if a package has a really broken post-install script in n-2, which damage is repaired in n-1. Should n repair it too in case n-1 is skipped?

We will work with recipe maintainers to publish fixes for update issues that testing will find in recipes. Each issue will be reported in Bugzilla.

=== Open questions ===

* Issues with Yocto Project being pedantic in its use of arch strings such as "intel-x86-64" instead of "x86-64". This conflicts with typical use in the greater Linux and "binary" community, which may not recognize the "extended" arch strings. Examples: [https://github.com/openSUSE/libsolv/blob/master/src/poolarch.c#L23 libresolv] and [https://github.com/rpm5/libhif/blob/f9b798cadb6821f9cffd5c0331578b3f7c19d699/libdnf/dnf-context.c#L52 libdnf] (reported by Mark Asselstine).

== Policies and Processes ==

Open questions:
* When do we run updates? What does process look like?

=== Criteria for adding and testing a new CPU architecture or platform tuning ===

* Only tunes in Openembedded-Core should be supported.

=== Process and policy for proposing adding new layers to the binary distro test artifacts process ===

* Layers must be [https://docs.yoctoproject.org/current/dev-manual/layers.html#making-sure-your-layer-is-compatible-with-yocto-project Yocto Project Compatible]
* In addition, layers must be well written and be targetting project best practices like reproducibility, no network access outside fetching so mirroring and licensing auditing works and not skipping QA tests without good reason.
* Any dependency layers would already have to be included in the testing already or make a separate application for addition first.
* The layer being added must be suitably generic with a clear need/usage of the components provided by the layer in the ecosystem
* The layer maintainer must have a commitment to keeping recipe upgrades functional
* The proposal must make it clear which recipes within the layer are being proposed to be built
* Proposals would be made to the Yocto Project TSC covering the above topics

=== Process and policy for proposing addition of a new MACHINE target ===

* Layers to build the machine need to be [https://docs.yoctoproject.org/current/dev-manual/layers.html#making-sure-your-layer-is-compatible-with-yocto-project Yocto Project Compatible]
* Layers need to be buildable on the project autobuilder
* Needs to be Yocto Project membership sponsorship of the machine due to the project resource usage
* Needs to be a commitment to testing the images for the platform for releases and upgrades
* Proposals would be made to the Yocto Project TSC covering the above topics

=== Process and policy for proposing addition of new recipe to the build ===

* This process assumes the layer is already present but the recipe is not currently included in the test matrix
* The recipe would need to have demonstrated the ability to pass on target installation and upgrade
* Proposals would be made to the Yocto Project TSC covering the above topics
* The software needs to have a good maintenance track record including reasonable CVE response
* Note: The TSC is aiming to appoint a maintainer to take the lead on resolving binary distro testing issues and handling recipe addition requests.

=== TSC Criteria for change evaluation ===

* Does the project have resources (human and compute for build/test/QA/bugfixing) to support the change?
* Is the change widely useful to a significant portion of the user base?
* Does the change enhance the project's test matrix?
* Does the change significantly improve developer productivity?

== Achievements ==

=== Fixed bugs ===

* [https://bugzilla.yoctoproject.org/show_bug.cgi?id=15292 Bug 15292 - systemd-compat-units: error at package post-install time]

=== Yocto Project Documentation improvements ===

* [https://lore.kernel.org/yocto-docs/20231206155427.279612-1-michael.opdenacker@bootlin.com/T/#t Fixes and updates to the Test Environment Manual]

== Missing features ==

Not implemented yet:
* Ability to update the system SPDX description after installing extra packages or package updates. The current way SPDX is generated doesn't allow to generate <code>-spdx</code> packages, which would have made this possible ([https://lists.openembedded.org/g/openembedded-architecture/message/1855 discussion]).

== Out of scope ==

Features outside of the scope of this effort, but definitely worth keeping track of for future efforts, or for people already maintaining binary distributions.
* Binary distribution installer: not absolutely necessary but users may expect one. For example the [https://www.yoedistro.org/ Yoe] distro offers one, and so does [https://www.raspberrypi.com/news/raspberry-pi-imager-imaging-utility/ Raspberry Pi].

== Footnotes and references ==

Binary Distro Prototype

2024-03-26T16:31:19Z

Mark Hatle: /* Process and policy for proposing adding new layers to the bibary distro test artefacts process */

== Scope of a Yocto Binary Distribution Prototype ==

The Yocto Project has received funding for developing the processes and tooling for enabling binary distributions (see the [https://web.archive.org/web/20230620145823/https://www.yoctoproject.org/community/yocto-project-engineering-request-for-quotation/ Engineering Request for Quotation]). As part of that, the project would need some form of prototype test binary distro to develop and test this. The main goal of this would be to develop the tools, and documentation needed to build a binary distribution and allow application and system developers to progress through a hierarchy of different uses of the resulting environment:

* '''Beginner''' use case: begin by fetching a binary image, ready to boot on a target machine. Extend the system by installing extra applications through package feeds.
* '''Intermediate''' use case: tweak and rebuild existing packages, compile new applications and modify images by using an eSDK and other binary artifacts.
* '''Advanced''' use case: completely reorganize and optimize the system for a specific target, switching to building from source

The first step in this effort is to define the scope of the prototype we will develop. We are looking for feedback and comments about issues we may not have considered.

Bear in mind that a prototype has to be limited in scope. However, the developed tools, procedures and documentation will open a pathway for the Yocto Project and OpenEmbedded community to experiment with more architectures, features, recipes and images.

Also bear in mind that the effort is not planning to adopt, replace or repeat any existing distributions such as [[wikipedia:Ångström_distribution|Ångström]] or [https://www.yoedistro.org/ Yoe].

Notes from discussions:
* Alex Kanavin suggests as "Intermediate" step to use the [https://patchwork.yoctoproject.org/project/oe-core/patch/20231107105844.712846-1-alex@linutronix.de/ build bundles] that he submitted. However, this is closer to the "Advanced" use case as this already uses BitBake and OE/Yocto ([https://lists.openembedded.org/g/openembedded-architecture/message/1850 discussion]).

=== Target architectures and machines ===

The first prototype would only target the below architectures:
* "x86-64" architecture through the [https://git.yoctoproject.org/poky/tree/meta/conf/machine/qemux86-64.conf qemux86-64] machine.
* "arm64" architecture through the [https://git.yoctoproject.org/poky/tree/meta/conf/machine/qemuarm64.conf qemuarm64] machine.

Testing would happen through QEMU system emulation. The emulated architectures will be sufficient to test the outputs of this effort, but the developed tooling and documentation should allow the community to experiment with other target architectures and machines.

=== Target tunes ===

The binary images and other artifacts should be generated with the default tunes of the [https://git.yoctoproject.org/poky/tree/meta/conf/machine/qemux86-64.conf qemux86-64] and [https://git.yoctoproject.org/poky/tree/meta/conf/machine/qemuarm64.conf qemuarm64] machines.

See [https://docs.yoctoproject.org/ref-manual/variables.html#term-DEFAULTTUNE DEFAULTTUNE] for details.

=== Distribution, Init Manager, C library ===

Images and package feeds will be generated for the [https://git.yoctoproject.org/poky/tree/meta-poky/conf/distro/poky-altcfg.conf poky-altcfg] distribution, using the systemd init manager.

Choosing systemd makes the binary reference distribution as generic as possible, enabling the widest set of features, and being more familiar to more users. Of course, switching to other init managers and more restricted features will be possible by later compiling the system from source (advanced use case).

This also implies the choice of the GNU C library (glibc). Selecting glibc also makes sense to enable the widest possible selection of packages, and some packages have limited or no support for the Musl C library. That's typically the case of systemd, which upstream only supports glibc.

Last but not least, people who want to use the Musl C library probably do that to optimize the size of their system, which is a use case not well adapted to using ready-made binary images.
Such an advanced use case will be addressed by re-compiling from source, after testing initial prototypes with the binary image based on glibc.

=== Binary images ===

The prototype will provide as a reference, for each targeted architecture:
* The root filesystem binary image, generated by building the <code>core-image-full-cmdline</code> target.
* An image containing on-target development tools (e.g compiler, debugger)
* The corresponding SD card images to be booted through QEMU. Other boot methods will be possible, but will be outside of the scope of the reference distribution.

=== Package feeds ===

For each targeted architecture, several package feeds will be available to allow for bugfix or security updates or to extend the image with additional packages:
* Architecture independent feed
* Architecture dependent feed
* Machine dependent feed
See [https://docs.yoctoproject.org/dev-manual/packages.html#using-runtime-package-management Using Runtime Package Management] for details.

The feeds for the first prototype will contain all the packages which are supported by the [https://git.yoctoproject.org/poky/tree/meta-poky/conf/distro/poky-altcfg.conf poky-altcfg] distribution as produced by the <code>bitbake world</code> command for the set of layers supplied by Poky.

=== Available reference package formats ===

To keep the first prototype simple, we will only release images and package feeds based on the "ipk" format supported by [[wikipedia:opkg|opkg]] package manager.

Of course, the OpenEmbedded build system also supports the [[wikipedia:Deb_(file_format)|deb]] and [[wikipedia:RPM_Package_Manager|rpm]] package formats, so users will be able to generate their own images and feeds based on these other formats.

Another reason for not providing "deb" and "rpm" packages is that we do not want inexperienced users to expect to be able to grab and use such packages produced for regular Linux distributions (Debian, Fedora, etc.). Being built with different C library versions and toolchains, the corresponding binaries are most likely to be broken anyway.

=== Available reference binary artifacts and deliverables ===

The first prototype will make the below binary artifacts publicly available:
* Root filesystem images (as specified above)
* Binary package feeds (as specified above)
* [https://docs.yoctoproject.org/ref-manual/variables.html#term-PR PR] database, so that people can manage updates to packages, by importing the database in a local PR server.
* Prebuilt object data ("Shared State cache) through a public server (see [https://docs.yoctoproject.org/ref-manual/variables.html#term-SSTATE_MIRRORS SSTATE_MIRRORS]), to reuse binary output already built by the Yocto Project autobuilders, to reduce the compile time of additional packages.
* Hash Equivalence data through a public server (see [https://docs.yoctoproject.org/bitbake/2.4/bitbake-user-manual/bitbake-user-manual-ref-variables.html#term-BB_HASHSERVE_UPSTREAM BB_HASHSERVE_UPSTREAM]), to increase the reusability of prebuilt objects.

Share State and Hash Equivalence data would be only useful to "Intermediate" and "Advanced" use cases, to rebuild parts or the whole system from source.

Such artifacts will be served through a Content Delivery Network (CDN), to make sure that they can be downloaded fast enough from any location in the world, in a way that remains much faster than re-compiling such artifacts from sources.

Those binaries should also be released along with:
* Sources corresponding to the software used to build the image, as produced by the [https://docs.yoctoproject.org/ref-manual/classes.html#ref-classes-archiver archiver] class. Unlike standard GNU/Linux distributions, we won't ship source package feeds (such as SRPMs)<ref>Only Source RPMs are supported by the [https://docs.yoctoproject.org/ref-manual/classes.html#ref-classes-archiver archiver] class. To obtain them, you need to set <code>INHERIT += "archiver"</code>, <code>PACKAGE_CLASSES = "package_rpm"</code> and <code>ARCHIVER_MODE[srpm] = "1"</code>. The generation of source <code>deb</code> or <code>ipk</code> packages is currently not supported.</ref>.<ref>The <code>-src</code> packages which recipes can produce are only meant for debugging together with <code>-dbg</code> packages. See [https://docs.yoctoproject.org/dev/ref-manual/variables.html#term-PACKAGE_DEBUG_SPLIT_STYLE PACKAGE_DEBUG_SPLIT_STYLE].</ref>
* SPDX output for the initial image
* The build system and layer sources. A good fit would be Alex Kanavin's [https://patchwork.yoctoproject.org/project/oe-core/patch/20231107105844.712846-1-alex@linutronix.de/ build bundles].

=== Defining policies and processes ===

This reference binary distribution prototype will also drive the documentation of policies and process to address future work such as:
* What criteria should a new CPU architecture or platform tuning meet to be added / tested?
* What criteria should other layers meet to be tested, in addition to being already tested by the Autobuilder? Should these criteria only apply to specific recipes or to the entire layers containing them?

See the [[#Policies and Processes | Policies and Processes]].

=== Testing plans ===

Here are the tests we plan to implement:
* Producing and testing binary images through the autobuilder
* Making nightly builds available to testers
* Testing that package updates apply successfully:
** Within the current stable branch (nanbield): from one release update to the next, and from the latest release update to the tip of the branch
** Between release branches: from the latest update to our latest LTS (kirkstone), to the latest update to the current stable release (nanbield).
* Testing that it's also possible to build and deploy packages from the meta-openembedded and meta-virtualization layers, as a way to assess the relevance of our policies and process for additional layers or recipes. This would also be a way to demonstrate the ability to build container images, which would be a great way to ship binary distributions.

Here are other tests that would be worth implementing:
* Check that package upgrades don't cause configuration file changes to be lost. See [https://lore.kernel.org/openembedded-core/0e38566f-a1f9-4ebb-8492-2c50945eeeb4@gmail.com/T/#t this discussion].
* Check that the latest package upgrades successfully apply to any previous release, at least on the same branch. For example, upgrading directly from release x.y.n-2 to x.y may not work without going through x.y.n-1 as an intermediate. This could happen if a package has a really broken post-install script in n-2, which damage is repaired in n-1. Should n repair it too in case n-1 is skipped?

We will work with recipe maintainers to publish fixes for update issues that testing will find in recipes. Each issue will be reported in Bugzilla.

=== Open questions ===

* Issues with Yocto Project being pedantic in its use of arch strings such as "intel-x86-64" instead of "x86-64". This conflicts with typical use in the greater Linux and "binary" community, which may not recognize the "extended" arch strings. Examples: [https://github.com/openSUSE/libsolv/blob/master/src/poolarch.c#L23 libresolv] and [https://github.com/rpm5/libhif/blob/f9b798cadb6821f9cffd5c0331578b3f7c19d699/libdnf/dnf-context.c#L52 libdnf] (reported by Mark Asselstine).

== Policies and Processes ==

=== Criteria for adding and testing a new CPU architecture or platform tuning ===

* Only tunes in Openembedded-Core should be supported.

=== Process and policy for proposing adding new layers to the binary distro test artefacts process ===

* Layers must be [https://docs.yoctoproject.org/current/dev-manual/layers.html#making-sure-your-layer-is-compatible-with-yocto-project Yocto Project Compatible]
* In addition, layers must be well written and be targetting project best practices like reproducibility, no network access outside fetching so mirroring and licensing auditing works and not skipping QA tests without good reason.
* Any dependency layers would already have to be included in the testing already or make a separate application for addition first.
* The layer being added must be suitably generic with a clear need/usage of the components provided by the layer in the ecosystem
* The layer maintainer must have a commitment to keeping recipe upgrades functional
* The proposal must make it clear which recipes within the layer are being proposed to be built
* Proposals would be made to the Yocto Project TSC covering the above topics

=== Process and policy for proposing addition of a new MACHINE target ===

* Layers to build the machine need to be [https://docs.yoctoproject.org/current/dev-manual/layers.html#making-sure-your-layer-is-compatible-with-yocto-project Yocto Project Compatible]
* Layers need to be buildable on the project autobuilder
* Needs to be Yocto Project membership sponsorship of the machine due to the project resource usage
* Needs to be a commitment to testing the images for the platform for releases and upgrades
* Proposals would be made to the Yocto Project TSC covering the above topics

=== Process and policy for proposing addition of new recipe to the build ===

* This process assumes the layer is already present but the recipe is not currently included in the test matrix
* The recipe would need to have demonstrated the ability to pass on target installation and upgrade
* Proposals would be made to the Yocto Project TSC covering the above topics
* The software needs to have a good maintenance track record including reasonable CVE response
* Note: The TSC is aiming to appoint a maintainer to take the lead on resolving binary distro testing issues and handling recipe addition requests.

== Achievements ==

=== Fixed bugs ===

* [https://bugzilla.yoctoproject.org/show_bug.cgi?id=15292 Bug 15292 - systemd-compat-units: error at package post-install time]

=== Yocto Project Documentation improvements ===

* [https://lore.kernel.org/yocto-docs/20231206155427.279612-1-michael.opdenacker@bootlin.com/T/#t Fixes and updates to the Test Environment Manual]

== Missing features ==

Not implemented yet:
* Ability to update the system SPDX description after installing extra packages or package updates. The current way SPDX is generated doesn't allow to generate <code>-spdx</code> packages, which would have made this possible ([https://lists.openembedded.org/g/openembedded-architecture/message/1855 discussion]).

== Out of scope ==

Features outside of the scope of this effort, but definitely worth keeping track of for future efforts, or for people already maintaining binary distributions.
* Binary distribution installer: not absolutely necessary but users may expect one. For example the [https://www.yoedistro.org/ Yoe] distro offers one, and so does [https://www.raspberrypi.com/news/raspberry-pi-imager-imaging-utility/ Raspberry Pi].

== Footnotes and references ==

Binary Distro Process

2019-12-20T16:57:50Z

Mark Hatle:

Using the Yocto Project to define and build a binary distribution is possible, but to be useful and maintainable requires careful considerations for the configuration of the configuration, build process, and test procedures. This document will cover the general process, some of the recommended configurations and suggest where to insert your test procedures into the process.

This page covers the high level architecture, along with various requirements that need to be considered to create a successful binary distribution. The actual implementation of this architecture and requirements is left to future documents.

'''High Level Architecture'''

A binary distribution begins with creating a process that allows you to do consistent, deterministic builds. This process becomes cyclical over the life of the product. The general procedure involves: Setup the build (new configuration or restoration of the prior build configuration and artifacts), performing the build, verifying the results of the build, storing the artifacts for the next iteration, and publishing the artifacts for the end user to use.

[[File:Binary_Workflow.JPG]]

Everything starts with an overall system configuration. The following items will need to be captured as part of the Configs.

'''Description of Process'''

''Layer Setup & Configuration''

* Layer Setup
** URLs
** Commit IDs
* Configuration
** bblayers.conf
** local.conf
USER_CLASSES += "reproducible_build"
USER_CLASSES += "packagefeed-stability"
USER_CLASSES += "buildhistory"
DEFAULTTUNE = "<common tune>"
DISTRO = "..."
PACKAGE_CLASSES = "package_rpm"
EXTRA_IMAGE_FEATURES – REMOVE debug-tweaks!
BB_HASHSERVER = "auto"
BB_SIGNATURE_HANDLER = "OEEquivHash"
PRSERV_HOST = "localhost:0"
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
ARCHIVER_MODE[recipe] = "1"
ARCHIVER_MODE[dumpdata] = "1"
ARCHIVER_MODE[srpm] = "1"

''Build Project''

In order to get a consistent set of updated packages over the life of binary distribution, it is necessary to define which recipe targets will be built. These should be defined and captured as part of the overall build configuration. Each defined recipe target should be carefully considered, as it will be very difficult to remove a recipe target over the life of the binary distribution.

The targets may include individual package recipes, packagegroup recipes, image recipes or even world builds. It is recommended that packagegroups, and images are the usual defined targets. If you are expecting to use world builds, it may be necessary to add specific recipe blacklists to remove packages that should not be part of the binary distribution.

Removal of targets will result in binary packages that are stagnant, as there is no reasonable way to remove packages, as a distribution, once it has been made available to an user system. There are ways to deprecate and replace installed software during an upgrade but these should only be used if specifically needed and will require extensive usage testing to ensure that they do not create any runtime / software upgrade issues. These tests will need to be repeated for all future releases as well, possibly complicating testing.

The results of the build will be a series of artifacts.

''Artifacts''

The following artifacts will be generated and stored as part of the build:

* Configuration
** Layer URLs/Commit IDs (or copies of)
** project configuration files (local.conf/bblayers.conf)
** List of target recipes for the build
*** This may be captured in various logs
* Log(s)
** Console Logs
** Individual Build Logs
** buildhistory
* Sources
** Downloads
** ARCHIVER output
* Sstate
** prserver database
** sstate-cache
** hash equivalency database
* Package Repository
** Repository Configuration
** RPM Packages
* images
* eSDK / SDK

''Test''

A test pass is then executed. The first step should be an inspection of the logs (including build history) to verify the output is as expected. Next a series of tests will need to verify that the image(s) boot, RPM packages can be installed, upgrades from the first and last releases work properly, etc. Over time this test suite will need to be expanded to deal with issues found along the way.

''Fix''

In the case of a test failure, a fix for the failure will need to be created and committed. Failed artifacts will be discarded (not released) as part of this.

''Release''

In the case of a test pass, assuming it has been decided to release, the artifacts are published. Note, prior artifacts should never be removed from the publishing location. Some artifacts, like build history may be determined to be internal only, but generally everything can be released.

''Restore Last Released Artifacts''

Once a new build is determined to be needed, layers are updated, last released artifacts are restored and a new build is performed repeating the process.

''EOL''

Product End-Of-Life is declared and no further updates are released.

'''Requirements'''

The following requirements were identified as being needed for a binary distribution. Note, a specific distribution may not require all of these items, but they should all be considered as part of this development.

Stage 1 requirements:

* Prebuilt/bootable image for each board
* A repeatable process to generate a binary package feeds
** Process documentation
*** Each step of the process, as implemented, should be documented to ensure it can be reproduced in the future
*** Initial configuration, target recipes, and specific commands should be included in this documentation
** Process shall be worked on in conjunction with the community
** Process shall allow updated packages to be built and released in addition to prior builds
* A mechanism to capture the source to binary build information so a user can transition from binary distribution to source distribution
** local.conf
** prserver
*** Must be configurable to NOT clash with the prserver values for the official feed
** sstate-cache
*** hash equivalency
** documentation
*** how to transition to custom builds
**** eSDK, full bitbake
*** how to publish custom components (feeds)
* Should use Yocto Project helper classes
** reproducible_build
** packagefeed-stability (may not be required with hash equivalency)
* Must be secure!
** The default image must not have predefined passwords!
*** Passwords, ssh keys, etc should not be predefined
*** A 'first boot' mechanism to generate device specific information is needed
**** Host keys
**** root and/or user passwords
** All services (within reason) should be disabled by default
*** initial attack surface should be as small as reasonable
* Package feeds must be generic (reusable), and only 'specific' when necessary (machine)
** Generic architecture feeds
*** x86_64
*** armv7 hard-float
*** armv8 -- aarch64
*** etc
** SOC_FAMILY specific feeds (as necessary)
*** device drivers and other soc family items for groups of boards
** MACHINE (board) specific feeds
*** machine specific packages
** Supports one or more custom feeds (as configured and enabled by the device admin)
* Package Feeds must be cumulative, permitting a user to revert to a specific version
* Downloadable image or other mechanism to quickly boot, without needing an SDK
** Must be preconfigured to use the package feeds (where applicable)
*** System upgrade should be able to be an automated process (cronjob)
*** Manual updates must be supported
* PSIRT / Security Response process
** Define and document product lifespan (EOL)
** CVE Monitoring
*** Product a report of public known issues, issues under investigation, and issues that have been fixed
*** SLA (Service Level Agreements) defined for security fix/release to binary feed
*** Method for outside people to notify us of security issues (may not be CVE)
*** On-going kernel upgrades to deal with kernel defects
**** May be Yocto Project, LTS or 'master' kernels
* Test strategy for validating binary packages
** Buildhistory used to allow architects/leads to verify components before release
** API / ABI comparison tooling to verify system is unlikely to break due to a change
*** http://github.com/lvc/abi-dumper
*** http://github.com/lvc/abi-compliance-checker
** Package upgrade testing
*** First release to current version(s)
*** Last release to current version(s)
*** Random intermediate release to current version(s)
*** Should execute ptest and oe qa tests and/or other automated tests after upgrading
**** Goal is as good or better then prior test pass

Stage 2 requirements:

* Cryptographic signed sstate-cache
** Sstate-cache objects are signed and verified prior to usage
* Cryptographic Signed packages and package feeds
** Package manager must validate signatures before installing
** User must be able to add their own signature to extend the package feeds
* Increase available packages to new components

Possible future work, based on user feedback:

* Desktop environment
** XFCE
** KDE
** Gnome
* Ability to migrate an image from one board to another
** Reconfigure feeds
** Load new boot image
** Swap to a new board
* Web interfaces to install packages and get a device package manifest
** May also involve remote device management
* Package feed viewer
** Something like rpmfind to view and inspect package info
* Increase available packages to new components

Binary Distro Process

2019-12-19T20:33:57Z

Mark Hatle:

Using the Yocto Project to define and build a binary distribution is possible, but to be useful and maintainable requires careful considerations for the configuration of the configuration, build process, and test procedures. This document will cover the general process, some of the recommended configurations and suggest where to insert your test procedures into the process.

'''High Level Architecture'''

A binary distribution begins with creating a process that allows you to do consistent, deterministic builds. This process becomes cyclical over the life of the product. The general procedure involves: Setup the build (new configuration or restoration of the prior build configuration and artifacts), performing the build, verifying the results of the build, storing the artifacts for the next iteration, and publishing the artifacts for the end user to use.

[[File:Binary_Workflow.JPG]]

Everything starts with an overall system configuration. The following items will need to be captured as part of the Configs.

'''Description of Process'''

''Layer Setup & Configuration''

* Layer Setup
** URLs
** Commit IDs
* Configuration
** bblayers.conf
** local.conf
USER_CLASSES += "reproducible_build"
USER_CLASSES += "packagefeed-stability"
USER_CLASSES += "buildhistory"
DEFAULTTUNE = "<common tune>"
DISTRO = "..."
PACKAGE_CLASSES = "package_rpm"
EXTRA_IMAGE_FEATURES – REMOVE debug-tweaks!
BB_HASHSERVER = "auto"
BB_SIGNATURE_HANDLER = "OEEquivHash"
PRSERV_HOST = "localhost:0"
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
ARCHIVER_MODE[recipe] = "1"
ARCHIVER_MODE[dumpdata] = "1"
ARCHIVER_MODE[srpm] = "1"

''Build Project''

In order to get a consistent set of updated packages over the life of binary distribution, it is necessary to define which recipe targets will be built. These should be defined and captured as part of the overall build configuration. Each defined recipe target should be carefully considered, as it will be very difficult to remove a recipe target over the life of the binary distribution.

The targets may include individual package recipes, packagegroup recipes, image recipes or even world builds. It is recommended that packagegroups, and images are the usual defined targets. If you are expecting to use world builds, it may be necessary to add specific recipe blacklists to remove packages that should not be part of the binary distribution.

Removal of targets will result in binary packages that are stagnant, as there is no reasonable way to remove packages, as a distribution, once it has been made available to an user system. There are ways to deprecate and replace installed software during an upgrade but these should only be used if specifically needed and will require extensive usage testing to ensure that they do not create any runtime / software upgrade issues. These tests will need to be repeated for all future releases as well, possibly complicating testing.

The results of the build will be a series of artifacts.

''Artifacts''

The following artifacts will be generated and stored as part of the build:

* Configuration
** Layer URLs/Commit IDs (or copies of)
** project configuration files (local.conf/bblayers.conf)
** List of target recipes for the build
*** This may be captured in various logs
* Log(s)
** Console Logs
** Individual Build Logs
** buildhistory
* Sources
** Downloads
** ARCHIVER output
* Sstate
** prserver database
** sstate-cache
** hash equivalency database
* Package Repository
** Repository Configuration
** RPM Packages
* images
* eSDK / SDK

''Test''

A test pass is then executed. The first step should be an inspection of the logs (including build history) to verify the output is as expected. Next a series of tests will need to verify that the image(s) boot, RPM packages can be installed, upgrades from the first and last releases work properly, etc. Over time this test suite will need to be expanded to deal with issues found along the way.

''Fix''

In the case of a test failure, a fix for the failure will need to be created and committed. Failed artifacts will be discarded (not released) as part of this.

''Release''

In the case of a test pass, assuming it has been decided to release, the artifacts are published. Note, prior artifacts should never be removed from the publishing location. Some artifacts, like build history may be determined to be internal only, but generally everything can be released.

''Restore Last Released Artifacts''

Once a new build is determined to be needed, layers are updated, last released artifacts are restored and a new build is performed repeating the process.

''EOL''

Product End-Of-Life is declared and no further updates are released.

'''Requirements'''

The following requirements were identified as being needed for a binary distribution. Note, a specific distribution may not require all of these items, but they should all be considered as part of this development.

Stage 1 requirements:

* Prebuilt/bootable image for each board
* A repeatable process to generate a binary package feeds
** Process documentation
*** Each step of the process, as implemented, should be documented to ensure it can be reproduced in the future
*** Initial configuration, target recipes, and specific commands should be included in this documentation
** Process shall be worked on in conjunction with the community
** Process shall allow updated packages to be built and released in addition to prior builds
* A mechanism to capture the source to binary build information so a user can transition from binary distribution to source distribution
** local.conf
** prserver
*** Must be configurable to NOT clash with the prserver values for the official feed
** sstate-cache
*** hash equivalency
** documentation
*** how to transition to custom builds
**** eSDK, full bitbake
*** how to puyblish custom components (feeds)
* Should use Yocto Project helper classes
** reproducible_build
** packagefeed-stability (may not be required with hash equivalency)
* Must be secure!
** The default image must not have predefined passwords!
*** Passwords, ssh keys, etc should not be predefined
*** A 'first boot' mechanism to generate device specific information is needed
**** Host keys
**** root and/or user passwords
** All services (within reason) should be disabled by default
*** initial attack surface should be as small as reasonable
* Package feeds must be generic (reusable), and only 'specific' when necessary (machine)
** Generic architecture feeds
*** x86_64
*** armv7 hard-float
*** armv8 -- aarch64
*** etc
** SOC_FAMILY specific feeds (as necessary)
*** device drivers and other soc family items for groups of boards
** MACHINE (board) specific feeds
*** machine specific packages
** Supports one or more custom feeds (as configured and enabled by the device admin)
* Package Feeds must be cumulative, permitting a user to revert to a specific version
* Downloadable image or other mechanism to quickly boot, without needing an SDK
** Must be preconfigured to use the package feeds (where applicable)
*** System upgrade should be able to be an automated process (cronjob)
*** Manual updates must be supported
* PSIRT / Security Response process
** Define and document product lifespan (EOL)
** CVE Monitoring
*** Product a report of public known issues, issues under investigation, and issues that have been fixed
*** SLA (Service Level Agreements) defined for security fix/release to binary feed
*** Method for outside people to notify us of security issues (may not be CVE)
*** On-going kernel upgrades to deal with kernel defects
**** May be Yocto Project, LTS or 'master' kernels
* Test strategy for validating binary packages
** Buildhistory used to allow architects/leads to verify components before release
** API / ABI comparison tooling to verify system is unlikely to break due to a change
*** http://github.com/lvc/abi-dumper
*** http://github.com/lvc/abi-compliance-checker
** Package upgrade testing
*** First release to current version(s)
*** Last release to current version(s)
*** Random intermediate release to current version(s)
*** Should execute ptest and oe qa tests and/or other automated tests after upgrading
**** Goal is as good or better then prior test pass

Stage 2 requirements:

* Cryptographic signed sstate-cache
** Sstate-cache objects are signed and verified prior to usage
* Cryptographic Signed packages and package feeds
** Package manager must validate signatures before installing
** User must be able to add their own signature to extend the package feeds
* Increase available packages to new components

Possible future work, based on user feedback:

* Desktop environment
** XFCE
** KDE
** Gnome
* Ability to migrate an image from one board to another
** Reconfigure feeds
** Load new boot image
** Swap to a new board
* Web interfaces to install packages and get a device package manifest
** May also involve remote device management
* Package feed viewer
** Something like rpmfind to view and inspect package info
* Increase available packages to new components

Binary Distro Process

2019-12-18T15:45:50Z

Mark Hatle:

Using the Yocto Project to define and build a binary distribution is possible, but to be useful and maintainable requires careful considerations for the configuration of the configuration, build process, and test procedures. This document will cover the general process, some of the recommended configurations and suggest where to insert your test procedures into the process.

'''High Level Architecture'''

A binary distribution begins with creating a process that allows you to do consistent, deterministic builds. This process becomes cyclical over the life of the product. The general procedure involves: Setup the build (new configuration or restoration of the prior build configuration and artifacts), performing the build, verifying the results of the build, storing the artifacts for the next iteration, and publishing the artifacts for the end user to use.

[[File:Binary_Workflow.JPG]]
Everything starts with an overall system configuration. The following items will need to be captured as part of the Configs.

'''Description of Process'''

''Layer Setup & Configuration''

* Layer Setup
** URLs
** Commit IDs
* Configuration
** bblayers.conf
** local.conf
USER_CLASSES += "reproducible_build"
USER_CLASSES += "packagefeed-stability"
USER_CLASSES += "buildhistory"
DEFAULTTUNE = "<common tune>"
DISTRO = "..."
PACKAGE_CLASSES = "package_rpm"
EXTRA_IMAGE_FEATURES – REMOVE debug-tweaks!
BB_HASHSERVER = "auto"
BB_SIGNATURE_HANDLER = "OEEquivHash"
PRSERV_HOST = "localhost:0"
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
ARCHIVER_MODE[recipe] = "1"
ARCHIVER_MODE[dumpdata] = "1"
ARCHIVER_MODE[srpm] = "1"

''Build Project''

In order to get a consistent set of updated packages over the life of binary distribution, it is necessary to define which recipe targets will be built. These should be defined and captured as part of the overall build configuration. Each defined recipe target should be carefully considered, as it will be very difficult to remove a recipe target over the life of the binary distribution.

The targets may include individual package recipes, packagegroup recipes, image recipes or even world builds. It is recommended that packagegroups, and images are the usual defined targets. If you are expecting to use world builds, it may be necessary to add specific recipe blacklists to remove packages that should not be part of the binary distribution.

Removal of targets will result in binary packages that are stagnant, as there is no reasonable way to remove packages, as a distribution, once it has been made available to an user system. There are ways to deprecate and replace installed software during an upgrade but these should only be used if specifically needed and will require extensive usage testing to ensure that they do not create any runtime / software upgrade issues. These tests will need to be repeated for all future releases as well, possibly complicating testing.

The results of the build will be a series of artifacts.

''Artifacts''

The following artifacts will be generated and stored as part of the build:

* Configuration
** Layer URLs/Commit IDs (or copies of)
** project configuration files (local.conf/bblayers.conf)
** List of target recipes for the build
*** This may be captured in various logs
* Log(s)
** Console Logs
** Individual Build Logs
** buildhistory
* Sources
** Downloads
** ARCHIVER output
* Sstate
** prserver database
** sstate-cache
** hash equivalency database
* Package Repository
** Repository Configuration
** RPM Packages
* images
* eSDK / SDK

''Test''

A test pass is then executed. The first step should be an inspection of the logs (including build history) to verify the output is as expected. Next a series of tests will need to verify that the image(s) boot, RPM packages can be installed, upgrades from the first and last releases work properly, etc. Over time this test suite will need to be expanded to deal with issues found along the way.

''Fix''

In the case of a test failure, a fix for the failure will need to be created and committed. Failed artifacts will be discarded (not released) as part of this.

''Release''

In the case of a test pass, assuming it has been decided to release, the artifacts are published. Note, prior artifacts should never be removed from the publishing location. Some artifacts, like build history may be determined to be internal only, but generally everything can be released.

''Restore Last Released Artifacts''

Once a new build is determined to be needed, layers are updated, last released artifacts are restored and a new build is performed repeating the process.

''EOL''

Product End-Of-Life is declared and no further updates are released.

'''Requirements'''

The following requirements were identified as being needed for a binary distribution. Note, a specific distribution may not require all of these items, but they should all be considered as part of this development.

Stage 1 requirements:

* Prebuilt/bootable image for each board
* A repeatable process to generate a binary package feeds
** Process documentation
*** Each step of the process, as implemented, should be documented to ensure it can be reproduced in the future
*** Initial configuration, target recipes, and specific commands should be included in this documentation
** Process shall be worked on in conjunction with the community
** Process shall allow updated packages to be built and released in addition to prior builds
* A mechanism to capture the source to binary build information so a user can transition from binary distribution to source distribution
** local.conf
** prserver
*** Must be configurable to NOT clash with the prserver values for the official feed
** sstate-cache
*** hash equivalency
** documentation
*** how to transition to custom builds
**** eSDK, full bitbake
*** how to puyblish custom components (feeds)
* Should use Yocto Project helper classes
** reproducible_build
** packagefeed-stability (may not be required with hash equivalency)
* Must be secure!
** The default image must not have predefined passwords!
*** Passwords, ssh keys, etc should not be predefined
*** A 'first boot' mechanism to generate device specific information is needed
**** Host keys
**** root and/or user passwords
** All services (within reason) should be disabled by default
*** initial attack surface should be as small as reasonable
* Package feeds must be generic (reusable), and only 'specific' when necessary (machine)
** Generic architecture feeds
*** x86_64
*** armv7 hard-float
*** armv8 -- aarch64
*** etc
** SOC_FAMILY specific feeds (as necessary)
*** device drivers and other soc family items for groups of boards
** MACHINE (board) specific feeds
*** machine specific packages
** Supports one or more custom feeds (as configured and enabled by the device admin)
* Package Feeds must be cumulative, permitting a user to revert to a specific version
* Downloadable image or other mechanism to quickly boot, without needing an SDK
** Must be preconfigured to use the package feeds (where applicable)
*** System upgrade should be able to be an automated process (cronjob)
*** Manual updates must be supported
* PSIRT / Security Response process
** Define and document product lifespan (EOL)
** CVE Monitoring
*** Product a report of public known issues, issues under investigation, and issues that have been fixed
*** SLA (Service Level Agreements) defined for security fix/release to binary feed
*** Method for outside people to notify us of security issues (may not be CVE)
*** On-going kernel upgrades to deal with kernel defects
**** May be Yocto Project, LTS or 'master' kernels
* Test strategy for validating binary packages
** Buildhistory used to allow architects/leads to verify components before release
** API / ABI comparison tooling to verify system is unlikely to break due to a change
*** http://github.com/lvc/abi-dumper
*** http://github.com/lvc/abi-compliance-checker
** Package upgrade testing
*** First release to current version(s)
*** Last release to current version(s)
*** Random intermediate release to current version(s)
*** Should execute ptest and oe qa tests and/or other automated tests after upgrading
**** Goal is as good or better then prior test pass

Stage 2 requirements:

* Cryptographic signed sstate-cache
** Sstate-cache objects are signed and verified prior to usage
* Cryptographic Signed packages and package feeds
** Package manager must validate signatures before installing
** User must be able to add their own signature to extend the package feeds
* Increase available packages to new components

Possible future work, based on user feedback:

* Desktop environment
** XFCE
** KDE
** Gnome
* Ability to migrate an image from one board to another
** Reconfigure feeds
** Load new boot image
** Swap to a new board
* Web interfaces to install packages and get a device package manifest
** May also involve remote device management
* Package feed viewer
** Something like rpmfind to view and inspect package info
* Increase available packages to new components

Binary Distro Process

2019-12-18T15:30:11Z

Mark Hatle:

Using the Yocto Project to define and build a binary distribution is possible, but to be useful and maintainable requires careful considerations for the configuration of the configuration, build process, and test procedures. This document will cover the general process, some of the recommended configurations and suggest where to insert your test procedures into the process.

'''High Level Architecture'''

A binary distribution begins with creating a process that allows you to do consistent, deterministic builds. This process becomes cyclical over the life of the product. The general procedure involves: Setup the build (new configuration or restoration of the prior build configuration and artifacts), performing the build, verifying the results of the build, storing the artifacts for the next iteration, and publishing the artifacts for the end user to use.

[[File:Binary_Workflow.JPG]]
Everything starts with an overall system configuration. The following items will need to be captured as part of the Configs.

'''Description of Process'''

''Layer Setup & Configuration''

* Layer Setup
** URLs
** Commit IDs
* Configuration
** bblayers.conf
** local.conf
USER_CLASSES += "reproducible_build"
USER_CLASSES += "packagefeed-stability"
USER_CLASSES += "buildhistory"
DEFAULTTUNE = "<common tune>"
DISTRO = "..."
PACKAGE_CLASSES = "package_rpm"
EXTRA_IMAGE_FEATURES – REMOVE debug-tweaks!
BB_HASHSERVER = "auto"
BB_SIGNATURE_HANDLER = "OEEquivHash"
PRSERV_HOST = "localhost:0"
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
ARCHIVER_MODE[recipe] = "1"
ARCHIVER_MODE[dumpdata] = "1"
ARCHIVER_MODE[srpm] = "1"

''Build Project''

The project is built using a standard process/target. Depending on the purposes of the binary distribution, it may require one or more recipe targets or even a world build.

The results of the build will be a series of artifacts.

''Artifacts''

The following artifacts will be generated and stored as part of the build:

* Configuration
** Layer URLs/Commit IDs (or copies of)
** project configuration files (local.conf/bblayers.conf)
* Log(s)
** Console Logs
** Individual Build Logs
** buildhistory
* Sources
** Downloads
** ARCHIVER output
* Sstate
** prserver database
** sstate-cache
** hash equivalency database
* Package Repository
** Repository Configuration
** RPM Packages
* images
* eSDK / SDK

''Test''

A test pass is then executed. The first step should be an inspection of the logs (including build history) to verify the output is as expected. Next a series of tests will need to verify that the image(s) boot, RPM packages can be installed, upgrades from the first and last releases work properly, etc. Over time this test suite will need to be expanded to deal with issues found along the way.

''Fix''

In the case of a test failure, a fix for the failure will need to be created and committed. Failed artifacts will be discarded (not released) as part of this.

''Release''

In the case of a test pass, assuming it has been decided to release, the artifacts are published. Note, prior artifacts should never be removed from the publishing location. Some artifacts, like build history may be determined to be internal only, but generally everything can be released.

''Restore Last Released Artifacts''

Once a new build is determined to be needed, layers are updated, last released artifacts are restored and a new build is performed repeating the process.

''EOL''

Product End-Of-Life is declared and no further updates are released.

'''Requirements'''

The following requirements were identified as being needed for a binary distribution. Note, a specific distribution may not require all of these items, but they should all be considered as part of this development.

Stage 1 requirements:

* Prebuilt/bootable image for each board
* A repeatable process to generate a binary package feeds
** Process shall be worked on in conjunction with the community
** Process shall allow updated packages to be built and released in addition to prior builds
* A mechanism to capture the source to binary build information so a user can transition from binary distribution to source distribution
** local.conf
** prserver
*** Must be configurable to NOT clash with the prserver values for the official feed
** sstate-cache
*** hash equivalency
** documentation
*** how to transition to custom builds
**** eSDK, full bitbake
*** how to puyblish custom components (feeds)
* Should use Yocto Project helper classes
** reproducible_build
** packagefeed-stability (may not be required with hash equivalency)
* Must be secure!
** The default image must not have predefined passwords!
*** Passwords, ssh keys, etc should not be predefined
*** A 'first boot' mechanism to generate device specific information is needed
**** Host keys
**** root and/or user passwords
** All services (within reason) should be disabled by default
*** initial attack surface should be as small as reasonable
* Package feeds must be generic (reusable), and only 'specific' when necessary (machine)
** Generic architecture feeds
*** x86_64
*** armv7 hard-float
*** armv8 -- aarch64
*** etc
** SOC_FAMILY specific feeds (as necessary)
*** device drivers and other soc family items for groups of boards
** MACHINE (board) specific feeds
*** machine specific packages
** Supports one or more custom feeds (as configured and enabled by the device admin)
* Package Feeds must be cumulative, permitting a user to revert to a specific version
* Downloadable image or other mechanism to quickly boot, without needing an SDK
** Must be preconfigured to use the package feeds (where applicable)
*** System upgrade should be able to be an automated process (cronjob)
*** Manual updates must be supported
* PSIRT / Security Response process
** Define and document product lifespan (EOL)
** CVE Monitoring
*** Product a report of public known issues, issues under investigation, and issues that have been fixed
*** SLA (Service Level Agreements) defined for security fix/release to binary feed
*** Method for outside people to notify us of security issues (may not be CVE)
*** On-going kernel upgrades to deal with kernel defects
**** May be Yocto Project, LTS or 'master' kernels
* Test strategy for validating binary packages
** Buildhistory used to allow architects/leads to verify components before release
** API / ABI comparison tooling to verify system is unlikely to break due to a change
*** http://github.com/lvc/abi-dumper
*** http://github.com/lvc/abi-compliance-checker
** Package upgrade testing
*** First release to current version(s)
*** Last release to current version(s)
*** Random intermediate release to current version(s)
*** Should execute ptest and oe qa tests and/or other automated tests after upgrading
**** Goal is as good or better then prior test pass

Stage 2 requirements:

* Cryptographic signed sstate-cache
** Sstate-cache objects are signed and verified prior to usage
* Cryptographic Signed packages and package feeds
** Package manager must validate signatures before installing
** User must be able to add their own signature to extend the package feeds
* Increase available packages to new components

Possible future work, based on user feedback:

* Desktop environment
** XFCE
** KDE
** Gnome
* Ability to migrate an image from one board to another
** Reconfigure feeds
** Load new boot image
** Swap to a new board
* Web interfaces to install packages and get a device package manifest
** May also involve remote device management
* Package feed viewer
** Something like rpmfind to view and inspect package info
* Increase available packages to new components

Binary Distro Process

2019-12-13T18:43:48Z

Mark Hatle:

'''High Level Architecture'''

A binary distribution begins with creating a process that allows you to do consistent, deterministic builds. This process becomes cyclical over the life of the product. The general procedure involves: Setup the build (new configuration or restoration of the prior build configuration and artifacts), performing the build, verifying the results of the build, storing the artifacts for the next iteration, and publishing the artifacts for the end user to use.

[[File:Binary_Workflow.JPG]]
Everything starts with an overall system configuration. The following items will need to be captured as part of the Configs.

'''Description of Process'''

''Layer Setup & Configuration''

* Layer Setup
** URLs
** Commit IDs
* Configuration
** bblayers.conf
** local.conf
USER_CLASSES += "reproducible_build"
USER_CLASSES += "packagefeed-stability"
USER_CLASSES += "buildhistory"
DEFAULTTUNE = "<common tune>"
DISTRO = "..."
PACKAGE_CLASSES = "package_rpm"
EXTRA_IMAGE_FEATURES – REMOVE debug-tweaks!
BB_HASHSERVER = "auto"
BB_SIGNATURE_HANDLER = "OEEquivHash"
PRSERV_HOST = "localhost:0"
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
ARCHIVER_MODE[recipe] = "1"
ARCHIVER_MODE[dumpdata] = "1"
ARCHIVER_MODE[srpm] = "1"

''Build Project''

The project is built using a standard process/target. Depending on the purposes of the binary distribution, it may require one or more recipe targets or even a world build.

The results of the build will be a series of artifacts.

''Artifacts''

The following artifacts will be generated and stored as part of the build:

* Configuration
** Layer URLs/Commit IDs (or copies of)
** project configuration files (local.conf/bblayers.conf)
* Log(s)
** Console Logs
** Individual Build Logs
** buildhistory
* Sources
** Downloads
** ARCHIVER output
* Sstate
** prserver database
** sstate-cache
** hash equivalency database
* Package Repository
** Repository Configuration
** RPM Packages
* images
* eSDK / SDK

''Test''

A test pass is then executed. The first step should be an inspection of the logs (including build history) to verify the output is as expected. Next a series of tests will need to verify that the image(s) boot, RPM packages can be installed, upgrades from the first and last releases work properly, etc. Over time this test suite will need to be expanded to deal with issues found along the way.

''Fix''

In the case of a test failure, a fix for the failure will need to be created and committed. Failed artifacts will be discarded (not released) as part of this.

''Release''

In the case of a test pass, assuming it has been decided to release, the artifacts are published. Note, prior artifacts should never be removed from the publishing location. Some artifacts, like build history may be determined to be internal only, but generally everything can be released.

''Restore Last Released Artifacts''

Once a new build is determined to be needed, layers are updated, last released artifacts are restored and a new build is performed repeating the process.

''EOL''

Product End-Of-Life is declared and no further updates are released.

'''Requirements'''

The following requirements were identified as being needed for a binary distribution. Note, a specific distribution may not require all of these items, but they should all be considered as part of this development.

Stage 1 requirements:

* Prebuilt/bootable image for each board
* A repeatable process to generate a binary package feeds
** Process shall be worked on in conjunction with the community
** Process shall allow updated packages to be built and released in addition to prior builds
* A mechanism to capture the source to binary build information so a user can transition from binary distribution to source distribution
** local.conf
** prserver
*** Must be configurable to NOT clash with the prserver values for the official feed
** sstate-cache
*** hash equivalency
** documentation
*** how to transition to custom builds
**** eSDK, full bitbake
*** how to puyblish custom components (feeds)
* Should use Yocto Project helper classes
** reproducible_build
** packagefeed-stability (may not be required with hash equivalency)
* Must be secure!
** The default image must not have predefined passwords!
*** Passwords, ssh keys, etc should not be predefined
*** A 'first boot' mechanism to generate device specific information is needed
**** Host keys
**** root and/or user passwords
** All services (within reason) should be disabled by default
*** initial attack surface should be as small as reasonable
* Package feeds must be generic (reusable), and only 'specific' when necessary (machine)
** Generic architecture feeds
*** x86_64
*** armv7 hard-float
*** armv8 -- aarch64
*** etc
** SOC_FAMILY specific feeds (as necessary)
*** device drivers and other soc family items for groups of boards
** MACHINE (board) specific feeds
*** machine specific packages
** Supports one or more custom feeds (as configured and enabled by the device admin)
* Package Feeds must be cumulative, permitting a user to revert to a specific version
* Downloadable image or other mechanism to quickly boot, without needing an SDK
** Must be preconfigured to use the package feeds (where applicable)
*** System upgrade should be able to be an automated process (cronjob)
*** Manual updates must be supported
* PSIRT / Security Response process
** Define and document product lifespan (EOL)
** CVE Monitoring
*** Product a report of public known issues, issues under investigation, and issues that have been fixed
*** SLA (Service Level Agreements) defined for security fix/release to binary feed
*** Method for outside people to notify us of security issues (may not be CVE)
*** On-going kernel upgrades to deal with kernel defects
**** May be Yocto Project, LTS or 'master' kernels
* Test strategy for validating binary packages
** Buildhistory used to allow architects/leads to verify components before release
** API / ABI comparison tooling to verify system is unlikely to break due to a change
*** http://github.com/lvc/abi-dumper
*** http://github.com/lvc/abi-compliance-checker
** Package upgrade testing
*** First release to current version(s)
*** Last release to current version(s)
*** Random intermediate release to current version(s)
*** Should execute ptest and oe qa tests and/or other automated tests after upgrading
**** Goal is as good or better then prior test pass

Stage 2 requirements:

* Cryptographic signed sstate-cache
** Sstate-cache objects are signed and verified prior to usage
* Cryptographic Signed packages and package feeds
** Package manager must validate signatures before installing
** User must be able to add their own signature to extend the package feeds
* Increase available packages to new components

Possible future work, based on user feedback:

* Desktop environment
** XFCE
** KDE
** Gnome
* Ability to migrate an image from one board to another
** Reconfigure feeds
** Load new boot image
** Swap to a new board
* Web interfaces to install packages and get a device package manifest
** May also involve remote device management
* Package feed viewer
** Something like rpmfind to view and inspect package info
* Increase available packages to new components

File:Binary Workflow.JPG

2019-12-13T18:26:05Z

Mark Hatle: Binary Distribution Process Workflow

Binary Distribution Process Workflow

Binary Distro Process

2019-12-13T18:23:47Z

Mark Hatle:

Binary Distro Process

2019-12-13T18:21:04Z

Mark Hatle: Binary Distribution Process