====== Setup and Building ======

===== Supported Operating Systems =====

[[ https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html | The Yocto Project website]] outlines the following requirements:



  * At least 90 Gbytes of free disk space, though much more will help to run multiple builds and increase performance by reusing build artifacts.

  * At least 8 Gbytes of RAM, though a modern modern build host with as much RAM and as many CPU cores as possible is strongly recommended to maximize build performance.

  * Runs a supported Linux distribution (i.e. recent releases of Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux distributions that support the Yocto Project, see the Supported Linux Distributions section in the Yocto Project Reference Manual. For detailed information on preparing your build host, see the Preparing the Build Host section in the Yocto Project Development Tasks Manual.

  * Git 1.8.3.1 or greater

  * tar 1.28 or greater

  * Python 3.8.0 or greater.

  * gcc 8.0 or greater.

  * GNU make 4.0 or greater


**Note that Yocto is not compatible with the Windows Subsystem for Linux (WSL)**

===== Download =====

Everything necessary to build a basic image can be downloaded from the yocto project git server. Yocto projects are self contained and can therefore live anywhere on the filesystem.
This guide will assume that everything related to the build will live in a directory called ''yocto'' in the ''ubuntu'' user's home directory, i.e. ''/home/ubuntu/yocto/''.

<code>
mkdir  ~/yocto
cd ~/yocto
git clone -b <release> git://git.yoctoproject.org/poky
</code>

Where <release> corresponds to the desired branch or tag. At the time of writing the latest LTS release is ''kirkstone''.
Note that while checking out a branch also works, checking out a particular tag is recommended to produce reproducible builds.
Check [[ http://git.yoctoproject.org/cgit/cgit.cgi/poky/ | the poky repository for all available releases ]].

===== Setup ======

Bitbake, yocto's build system, let's the user pick their own directory to store all output in. This includes (among others) downloads, packages configuration files, and the final image(s).
This means that the same poky download can be used for multiple independent builds (for different hardware for example).
The first thing to do is to create that directory, usually called ''build'', inside the ''yocto'' directory.

<code>
mkdir ~/yocto/build
</code>

Now the ''yocto'' directory should contain ''poky'' and ''build''.
Next, initialize the build environment using the following command (we are still in ''~/yocto''):

<code>
. poky/oe-init-build-env build
</code>

Note the space between the dot and ''poky''.
This should result in output similar to the sample below.

<code>
### Shell environment set up for builds. ###

You can now run 'bitbake <target>'

Common targets are:
    core-image-minimal
    core-image-sato
    meta-toolchain
    meta-ide-support

You can also run generated qemu images with a command like 'runqemu qemux86'

Other commonly useful commands are:
 - 'devtool' and 'recipetool' handle common recipe tasks
 - 'bitbake-layers' handles common layer tasks
 - 'oe-pkgdata-util' handles common target package tasks

</code>


===== Adding Additional Layers =====

Often it is necessary to add further layers to the build to customize the resulting image, or build for specific hardware (a specific ''MACHINE'').
For example, to use the OST images, the [[ meta-ost ]] layers need to be added to the build.

While layers can be included from any directory, it makes sense to keep all the layers in one place. In this case they will be kept in the parent directory, next to the ''poky'' folder.

To clone [[ meta-ost ]]
<code>
# get out of 'build' directory
cd ..
# clone layers
git clone git://git.openembedded.org/meta-openembedded -b <yocto-release>
git clone https://gitlab.ost.ch/tech/inf/public/meta-ost -b <yocto-release>
</code>

Note that many layer repositories will have different branches for different yocto releases. For example, meta-openembedded has a ''kirstone'' branch to be used with the ''kirstone'' yocto releases. Note: use the kirkstone branch and not a tag.

===== Build Configuration =====

When running ''oe-init-env'' a ''conf'' folder was created inside the build directory: ''build/conf'' in this case.
This folder contains two files: ''local.conf'' and ''bblayers.conf''.

==== Adding Custom Layers ====

''bblayers.conf'' contains the full path of all layers that are referenced during the build inside the ''BBLAYERS'' variable.
If additional layers are needed, they need to be added to the list for bitbake to find them and their recipes.

This is the place to add the path to the custom layers that were ''clone''d previously (if any).
Some repositories such as [[ meta-ost ]] contain multiple layers.
In these cases each layers must be added separately.
For example, ''meta-ost/meta-ost'' and ''meta-ost/meta-ost-ros'' rather than just ''meta-ost'' as shown below.

<code>
BBLAYERS ?= " \
   /home/ubuntu/yocto/poky/meta \
   /home/ubuntu/yocto/poky/meta-poky \
   /home/ubuntu/yocto/poky/meta-yocto-bsp \
   \
   /home/ubuntu/yocto/meta-openembedded/meta-oe \
   /home/ubuntu/yocto/meta-ost/meta-ost \
   "
</code>
The paths of the entries above must match your actual paths.

==== local.conf ====

''local.conf'' contains configuration settings and modifications relevant to this build.
The most common setting to set is the ''MACHINE'', i.e. the hardware platform you want to build the image for.
By default yocto builds for ''genericx86_64'', which should run on a normal (64bit) PC.
Another possibility is to add additional packages to the image using ''CORE_IMAGE_INSTALL_append''.

Another thing that may come in handy is manually setting the kernel used.
This can be achieved by setting ''PREFERRED_PROVIDER_virtual/kernel'' to the desired kernel.
By default, yocto provides a kernel as ''linux-yocto''.

For a typical build using [[ meta-ost ]] the following should be appended to ''local.conf''
<code>
MACHINE = "<machine>"
DISTRO = "ost-devel"
</code>

This will build a development image. If you would rather build a production image, change ''DISTRO'' to ''ost-distro''.
The difference between the 2 distro's are documented in the "ost-distro vs. ost-devel" section in [[meta-ost]].

=== Internal Mirrors ===


Bitbake has the ability to use external mirrors both for downloading package sources and the shared state cache (sstate-cache) to speed up builds.

The downloads and sstate-cache generated by the CI builds for [[meta-ost]] are provided internally.

OST INTERNAL ONLY: To configure bitbake to use the internal mirror, check {{ https://wiki.bu.ost.ch/inf/yocto/start | the internal docs }}.

===== Running a Build =====

Packages and images can be built by running ''bitbake <recipe-name>''.
Note that images are just recipes as far as bitbake is concerned.
To build the default image run:

<code>
bitbake ost-image
</code>

Bitbake also has the ability to run commands that are part of a recipe.
For example, to remove build output from a recipe run
<code>
bitbake <recipe-name> -c clean
</code>

''-c'' tells bitbake to only run a particular command rather than building the package(s) in the recipe.
In this case that command is ''clean'', another example is ''fetch'' to fetch the necessary sources required by the recipe.

Results will be placed in ''build/tmp/deploy/'', e.g. images will be in ''build/tmp/deploy/images''.