Skip to content
Permalink
Browse files

document Yoe Profile

Signed-off-by: Cliff Brake <cbrake@bec-systems.com>
  • Loading branch information
cbrake authored and kraj committed Mar 13, 2020
1 parent ee2d938 commit 820ac717d32d25ba23c2eafc990e0a18c2c5f877
Showing with 126 additions and 114 deletions.
  1. +78 −69 README.md
  2. +12 −11 docs/README.md
  3. +5 −34 docs/libc-init.md
  4. +31 −0 docs/yoe-profile.md
147 README.md
@@ -4,14 +4,14 @@

# Yoe Embedded Linux Distribution

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.
This distribution does not end at demo images but rather begins there.
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. This
distribution does not end at demo images but rather begins there.
## Example
This following is example of building and installing a linux system from
scratch on a Raspberry PI 3:
This following is example of building and installing a linux system from scratch
on a Raspberry PI 3:
## Install Pre-requisites
@@ -21,8 +21,8 @@ Install `docker` on host distribution
- RPM based systems - `sudo dnf install docker`
- Archlinux based systems - `sudo pacman -S docker`
Install nftable version of iptables on host distribution
this is needed for VNC port forwarding to work on docker
Install nftable version of iptables on host distribution this is needed for VNC
port forwarding to work on docker
- Archlinux based sytems - `sudo pacman -S iptables-nft`
@@ -45,46 +45,50 @@ this is needed for VNC port forwarding to work on docker
## Vision
There are many Embedded Linux distribution built on top of OpenEmbedded/Yocto.
There is the Poky reference distribution. Most SOC and SOM vendors provide
a Yocto variant that supports their products (often put together with repo).
While these all provide good ways to build demo images, we feel something
slightly different is needed for product development. Thus, the following
goals:
1. **simple**: directory layout is logical so it is easy to find things, and tooling
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. **modern**: generate a modern Linux root filesystem using the latest technologies.
1. **broad platform support**: support a range of single board computers (SBC), system on
chips (SoC), and system on modules (SOM). You should not have to use a different
build system for every SBC/SOC/SOM you might choose to use in your products.
Rather, one build system should easily support building images for a number of
different targets in one build tree. Most companies support multiple products with
SOCs from multiple vendors, thus the build system should be centered around the user's
products and software.
There is the Poky reference distribution. Most SOC and SOM vendors provide a
Yocto variant that supports their products (often put together with repo). While
these all provide good ways to build demo images, we feel something slightly
different is needed for product development. Thus, the following goals:
1. **simple**: directory layout is logical so it is easy to find things, and
tooling 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. **modern**: generate a modern Linux root filesystem using the latest
technologies.
1. **broad platform support**: support a range of single board computers (SBC),
system on chips (SoC), and system on modules (SOM). You should not have to
use a different build system for every SBC/SOC/SOM you might choose to use in
your products. Rather, one build system should easily support building images
for a number of different targets in one build tree. Most companies support
multiple products with SOCs from multiple vendors, thus the build system
should be centered around the user's products and software.
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.
The focus is not on 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](docs/docker.md) 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 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.
1. **extendable**: simple to modify and add your own custom software, scripts
and tooling. The focus is not on 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](docs/docker.md) 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 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.

## Supported Machines

See the \<machine\>-envsetup.sh files for examples of machines we regularly test with.
See the \<machine\>-envsetup.sh files for examples of machines we regularly test
with.

There is also [machine specific documentation](docs/README.md#machine-documentation)
There is also
[machine specific documentation](docs/README.md#machine-documentation)
available.

Additional machines can be added by including appropriate BSP layers.
@@ -93,30 +97,29 @@ Additional machines can be added by including appropriate BSP layers.

### envsetup.sh

This is where all the magic happens. In general, this build system
must be run in a bash shell. To set up the environment, source the following file:
This is where all the magic happens. In general, this build system must be run
in a bash shell. To set up the environment, source the following file:

`. ./<machine>-envsetup.sh`

Or, you can export a MACHINE environment variable, and then source envsetup.sh.

This file will create a bunch of functions in the environment
prefixed with yoe\_ that can be executed. Type yoe\_ <tab><tab>
to see them.
This file will create a bunch of functions in the environment prefixed with
yoe\_ that can be executed. Type yoe\_ <tab><tab> to see them.

### directories and key files

- _build_: temporary directory where build actually takes place
- _conf_: configuration files for the build
- _sources_: various sources used for the build. The entries
in this directory are git submodules. Note, by default, submodules
are shallow clones. If you need the the full git history of a submodule,
then run `git fetch --unshallow` in the submodule directory.
- _downloads_: contains files that are downloaded by various
recipes during builds.
- _sources_: various sources used for the build. The entries in this directory
are git submodules. Note, by default, submodules are shallow clones. If you
need the the full git history of a submodule, then run `git fetch --unshallow`
in the submodule directory.
- _downloads_: contains files that are downloaded by various recipes during
builds.
- _tools_: utility scripts
- _localconfig.sh_: file created by envsetup.sh that contains
directory specific variables based on the build system location.
- _localconfig.sh_: file created by envsetup.sh that contains directory specific
variables based on the build system location.
- _local.sh_: can be used to customize MACHINE, and other variables

### building for another machine
@@ -134,33 +137,39 @@ Remove meta-altera:

`yoe_remove_layer meta-altera`

### customizing settings
### Customizing the distribution

`conf/local.conf` contains settings that are commonly modified such
as parallel build options.
`conf/site.conf` contains settings that are common for the project. The
[YOE_PROFILE](docs/yoe-profile.md) templates make it easy to select common
options.

### customizing settings for your build machine

`conf/local.conf` contains settings that are commonly modified such as parallel
build options.

### starting a local feed server

Sometimes you want to install packages you build on the target system
without building and re-installing the entire rootfs. This can be done
using a [feed server](docs/packages.md).
Sometimes you want to install packages you build on the target system without
building and re-installing the entire rootfs. This can be done using a
[feed server](docs/packages.md).

This advantage of a feed server versus scp'ing opkg files to the target
and installing manually is that dependencies will automatically get installed.
This mechanism is very useful for packages that are only needed occasionally
during development (gdb, screen, strace, iperf, etc).
This advantage of a feed server versus scp'ing opkg files to the target and
installing manually is that dependencies will automatically get installed. This
mechanism is very useful for packages that are only needed occasionally during
development (gdb, screen, strace, iperf, etc).

### updating the submodules to the latest

Assuming you have a recent version of git, you can make use of the branch
values specified in .gitmodules to update each submodule branch to the
HEAD of the specified branch:
Assuming you have a recent version of git, you can make use of the branch values
specified in .gitmodules to update each submodule branch to the HEAD of the
specified branch:

`git submodule update --remote`

## License

This build system is licensed under the MIT license which is the
same license as oe-core, etc. See COPYING.MIT
This build system is licensed under the MIT license which is the same license as
oe-core, etc. See COPYING.MIT

Contributions are welcome: please open issues or pull requests.
@@ -1,7 +1,7 @@
# Yoe Documentation

See the Yoe [readme](../README.md) for an overview of the project.
This page is an index to more detailed documentation.
See the Yoe [readme](../README.md) for an overview of the project. This page is
an index to more detailed documentation.

## Machine Documentation

@@ -15,16 +15,17 @@ included for some of them below.
## Using Yoe

- [Docker Integration](docker.md)
- [Packages](packages.md) - information on installing packages from your build directory
in a development scenario.
- [Packages](packages.md) - information on installing packages from your build
directory in a development scenario.
- [Working with git submodules](git-submodules.md)

## Image Configuration

OpenEmbedded supports a wide range of technology choices. Some of these are documented
below.
OpenEmbedded supports a wide range of technology choices. Some of these are
documented below.

- [Configuration Files](conf-files.md)
- [Profile](yoe-profile.md)
- [libc/init system](libc-init.md)
- [adding GCC and development tools to target system](gcc.md)

@@ -33,11 +34,11 @@ below.
- [Superproject Management](superproject-management.md)
- [Layer Management](layer-management.md)

The Yoe documentation is kept with the project as simple markdown files in the docs/
subdirectory. We do not use the Github wiki, document generators, or other more
sophisticated methods for the following reasons:
The Yoe documentation is kept with the project as simple markdown files in the
docs/ subdirectory. We do not use the Github wiki, document generators, or other
more sophisticated methods for the following reasons:

- it is obvious where to find documentation
- the documentation for the version of Yoe you are using is always available, even
through long product life cycles
- the documentation for the version of Yoe you are using is always available,
even through long product life cycles
- simpler for others to contibute improvements
@@ -2,39 +2,10 @@

[up](README.md)

## Systemd
## Selection

SysVinit and Systemd are common init systems. SysVinit is the default, but Systemd can
be enabled be adding the following to `site.conf`:

```
DISTRO_FEATURES_append = " systemd"
VIRTUAL-RUNTIME_init_manager = "systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
VIRTUAL-RUNTIME_initscripts = ""
```

There is a significant size cost with systemd, so in some cases it may make sense to
use sysvinit if image size is a priority.

## Busybox Init

Busybox can also be used as an init system with the following in `site.conf`:

```
VIRTUAL-RUNTIME_init_manager = "busybox"
VIRTUAL-RUNTIME_dev_manager = "busybox-mdev"
VIRTUAL-RUNTIME_login_manager = "busybox"
```

## Libc selection

glibc is the default libc, but musl can also be used by setting the following in
`site.conf`:

```
TCLIBC = "musl"
```
Selection of the libc and init system can be done be selecting a
[Yoe Profile](yoe-profile.md).

## Comparison of disk spaced used

@@ -56,5 +27,5 @@ TCLIBC = "musl"
- number of files in image: 1,806

The space on disc used by a systemd image is much larger than adding the size of
the files in the image. We're not sure why this is -- perhaps there is filesystem
overhead for small files.
the files in the image. We're not sure why this is -- perhaps there is
filesystem overhead for small files.
@@ -0,0 +1,31 @@
# Yoe Profile

[up](README.md)

The Yoe Distribution makes it easy to select the libc, init, and graphics
subsystem for your project. To select a profile, set `YOE_PROFILE` in
`conf/site.conf` equal to one of the following:

- yoe-glibc-busyboxinit-eglfs
- yoe-glibc-busyboxinit-wayland
- yoe-glibc-busyboxinit-x11
- yoe-glibc-systemd-eglfs
- yoe-glibc-systemd-wayland
- yoe-glibc-systemd-x11
- yoe-glibc-sysvinit-eglfs
- yoe-glibc-sysvinit-wayland
- yoe-glibc-sysvinit-x11
- yoe-musl-busyboxinit-eglfs
- yoe-musl-busyboxinit-wayland
- yoe-musl-busyboxinit-x11
- yoe-musl-systemd-eglfs
- yoe-musl-systemd-wayland
- yoe-musl-systemd-x11
- yoe-musl-sysvinit-eglfs
- yoe-musl-sysvinit-wayland
- yoe-musl-sysvinit-x11

These profiles are provided for convenience. You can manually configure these
options as well -- use the files in the yoe
[conf directory](https://github.com/YoeDistro/meta-yoe/tree/master/conf/distro)
for reference.

0 comments on commit 820ac71

Please sign in to comment.
You can’t perform that action at this time.