From 80d18030615ade4369d861328b5dabf726e2f7c2 Mon Sep 17 00:00:00 2001 From: Cliff Brake Date: Thu, 4 Oct 2018 17:08:44 -0400 Subject: [PATCH] more doc updates --- README.md | 15 +++++++++------ docs/superproject-management.md | 30 ++++++++++++------------------ 2 files changed, 21 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index c329488e8..89c14e37c 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,7 @@ Yoe is an Embedded Linux Distribution optimized for product development. It is built on **Y**octo and **O**pen**E**mbedded with a focus on simplicity. -Yoe aims to be a straightforward way to pull together various Yocto layers -and BSPs in a production grade build system. +This distribution does not end at demo images but rather begins there. ## Example @@ -38,22 +37,26 @@ goals: is as simple as possible. Emphasis is on logical organization, minimal magic, and good tooling where it makes sense. We try to minimize uneeded indirection or abstraction unless it really adds value. -1. **robust**: easy to lock down subprojects (layers) to known versions for - repeatable builds using git submodules. 1. **modern**: generate a modern Linux root filesystem using the latest technologies. 1. **broad platform support**: support a range of common development platforms, system on chips (SoC), and system on modules (SOM). You should not have to use a different build system for every SOC/SOM you might choose to use in your products. +1. **repeatable**: easy to lock down subprojects (layers) to known versions for + repeatable builds 1. **extendable**: simple to modify and add your own custom software, scripts and tooling. -1. **host independence**: product lifecycles run for many years, so we need a solution where + The focus is not in hiding or abstracting Yocto functionality, but rather provider simpler + and clearer ways to use it. +1. **maintainable**: product lifecycles run for many years, so we need a solution where we can build images on a number of different hosts as time marches on. We achieve this through a simple and transparent docker wrapper that contains all the host dependencies needed. This wrapper is invisible (the file system still lives on the host), and is optional if you choose not to use it. 1. **transparent**: we try to use industry standard tools (git, bitbake, etc) where possible - and not invent a lot of new tooling that needs to be learned to understand how things work. + and not invent a lot of new tooling that needs to be learned to use the system. As an example, much of the tooling (envsetup.sh) are simple bash functions and are easy to learn from. Using Yoe will teach you about Yocto. +1. **minimal**: Embedded Linux images can quickly become bloated so we support technologies + like musl libc, opkg package manager, etc. where appropriate. ## Tested Machines diff --git a/docs/superproject-management.md b/docs/superproject-management.md index 218776fd5..e5724d572 100644 --- a/docs/superproject-management.md +++ b/docs/superproject-management.md @@ -1,6 +1,6 @@ # Git Superproject Management -One controversial decisions in Yoe is the choice of +One controversial choice in Yoe is the use of Git Submodules vs Repo. Because we need to manage multiple Git repositories, something is needed. There are a number of solutions including: @@ -9,7 +9,7 @@ solutions including: * Google repo * Git subtree * custom scripts -* Poky style monorepo +* Poky style combo repo In this document, we will use the OE term "layers" to refer to git subrepositories (submodules). Superproject is the term that describes @@ -19,9 +19,9 @@ the project that manages all the subprojects (layers). Yoe is designed foremost for product development, or using Yocto/OE to build software that will be deployed in real products (vs a technology demo -build for a vendors CPU/SOM). It is also designed to be used by people who may +build). It is also designed to be used by people who may not be embedded Linux/Git experts, but yet want to create builds and make -incremental improvements over the long product lifecycle (can be 5 years or +incremental improvements over long product lifecycles (can be 5 years or more). From this, we derive Yoe's requirements (somewhat ordered by priority). 1. know exactly what version of all software (layers) were used in a particular @@ -61,7 +61,7 @@ one tools is best to accomplish all of these goals. http://bec-systems.com/site/696/git-submodules-what-to-do-when-you-commit-to-no-branch * removing submodules can be a little confusing * updating a submodule URL requires a "sync" to propagate changes to working - subodule. + submodule. ## Google Repo @@ -94,10 +94,10 @@ all the subprojects into one repo, and likely not optimal for managing layers, most of which will rarely change during a product lifecycle. It seems to be a tool for more advanced users. -## Poky style monorepo +## Poky style combo repo One popular trend these days are [monorepos](http://danluu.com/monorepo/) which -are popular these days in large companies. +are popular in various large companies (like Google and Facebook). [Poky](http://git.yoctoproject.org/cgit/cgit.cgi/poky) is somewhat of a monorepo in that it contains bitbake, oe-core, and some other things in one git repo. This makes it easy to checkout one repository and build a demo image if @@ -106,13 +106,12 @@ have to deal with multiple repositories or figure out the [combo-layer](http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/scripts/combo-layer) tool. Additionally, if you make changes to one of the pieces of Poky, extracting these changes to submit back upstream is not as easy as if the -repositories were simply split out in their original form. Also, it is an all -or nothing type setup -- if you need a bitbake fix, you can't move to a different -version of bitbake without moving the who thing. +repositories were simply split out in their original form. Also, it is less obvious +you might update just one port of the combo repo, but not others. It seems monorepos are best for projects where a company owns everything in the repo. With a Yocto build, most of the layers come from third parties. In this -scenario, it seems a superproject type setup is a better fit. And, we favor the +scenario, it seems a superproject type setup is a better fit. We favor the transparency of showing clearly where each layer came from so it is obvious where to go for support, etc. @@ -131,7 +130,7 @@ release except application code. These product cycles can be 5 years or more with 100's of releases. During this time, the layers may change from time to time to add new packages, tweak the system files, or update to a new version of Yocto, but these layer changes are relatively few compared to the application -changes. We want to optimize the experience for this use case where developer +changes. We want to optimize the experience for this use case where a developer using Yoe is not a Yocto expert, but knows enough to tweak recipes, run builds, etc. The ability to manage both configuration files, documentation, @@ -160,15 +159,10 @@ are not. (Note, I don't claim Yoe meets this lofty goal, but this is the vision.) -Tagging the build system for each release is also simpler with git submodules because -it is a simple git add/commit/tag routine that developers are familiar with. -With repo, tooling typically needs to be added to switch the layers in the manifest file -from floating branches to locked down versions. - It seems git submodules are still a better fit for the use case Yoe was designed for, however this is not set in stone, but simply where we are at this point. It is acknowledged that repo may make some things easier for OE/Layer core developers where -who are often updating layers, etc. So, if repo works great for you, by all means keep using +who are often modifying and updating layers. So, if repo works great for you, by all means keep using it. That is the beauty of OE layers -- you can put then together using whatever tools works best for you. Yoe is just an attempt at keeping things as simple as possible for product developers.