Skip to content
Snippets Groups Projects
Commit 1d627940 authored by Frieder Schrempf's avatar Frieder Schrempf
Browse files

docs: Add initial version of docs

parent a3174a15
No related branches found
No related tags found
1 merge request!16Add kas menu-based config (Kconfig) and initial version of docs
Pipeline #17452 passed
include:
- '/ci/yocto-ktn-build.yml'
- '/ci/container-build.yml'
- project: 'sw/ked/docs/mkdocs-ked'
ref: main
file: '/ci/docs-build.yml'
stages:
- build-container
- build
- deploy
# Build Yocto BSPs
.build-matrix: &build-matrix
......@@ -47,3 +51,14 @@ container:build:
container:build-deploy:
extends: .build-deploy-container
<<: *container-vars
# Build Documentation
docs:build:
extends: .docs:build
variables:
DOCS_SUBDIR: docs
docs:trigger:
extends: .docs:trigger
variables:
DOCS_SUBDIR: docs
site_name: Kontron Electronics Docs - Meta Kontron
repo_url: 'https://git.kontron-electronics.de/sw/ked/meta-kontron'
docs_dir: src
theme:
name: material
custom_dir: /ked-overrides
logo: assets/images/kontron.svg
favicon: assets/images/favicon.png
features:
- content.code.copy
- navigation.instant
- navigation.tracking
extra_css:
- assets/stylesheets/snt-fonts.css
- assets/stylesheets/snt-colors.css
markdown_extensions:
- admonition
- attr_list
- pymdownx.details
- pymdownx.highlight
- pymdownx.keys
- pymdownx.mark
- pymdownx.superfences
nav:
- Prerequisites: prerequisites.md
- Build: build.md
- Customization: customization.md
# Build
## Clone the BSP Repository
First of all you need a local copy of the BSP repository. This can be either
`meta-kontron` or a custom layer. This guide will use the public `meta-kontron`
BSP repository to build images for our standard and demo hardware.
```
cd ~
git clone https://git.kontron-electronics.de/sw/ked/meta-kontron.git
cd meta-kontron
```
## Use the Menu to Configure (Recommended)
!!! note "`kas` command"
In the following we will use the `kas-container` script to build inside of a
container. If you do native builds, you can use the `kas` command directly
instead.
Run the `menu` command:
```
kas-container menu
```
Navigate through the menu using ++arrow-up++++arrow-down++ and select the
options you need using ++space++.
Afterwards use ++tab++ to navigate to the button menu, select "Save & Build",
"Save & Exit" or "Exit" using ++arrow-left++++arrow-right++ and confirm with
++return++.
The configuration is saved to `.config.yaml` which is excluded from being
tracked in Git.
The configuration in `.config.yaml` will mainly consist of references to other
configuration files in the `kas` subdirectory.
## Run the Build
If you selected "Save & Build" in the configuration menu, a build will be
started automatically. Otherwise you can start a build with:
```
kas-container build .config.yaml
```
Now `kas` will fetch all repos specified in the configuration, initialize the
build environment and launch `bitbake`.
## Select Configuration Files Manually
Instead of using the `menu` command and creating a `.config.yaml` you can also
select the existing configuration file(s) manually.
The following command produces the same result as when selecting the options
"Kontron Electronics SL/BL/OSM i.MX8MM" and "Yocto Kirkstone" via the menu.
```
kas-container build kas/ktn-mx8mm.yml:kas/series/kirkstone.yml
```
## Using the `shell` Command
Instead of using the `build` command to start `bitbake`, you can also use the
`shell` command to instruct `kas` to drop you to a shell inside the build
environment.
```
kas-container shell .config.yaml
```
Once inside the shell, you can run any `bitbake` command you like.
# Customization
If you develop your own BSP using `meta-kontron` as a base, it is recommended to
setup your own Git repository to track all changes.
!!! note "Layer Naming"
We will use `meta-custom` as name for the custom layer. Use a name that
matches your project, product or whatever you want to describe in the layers
data.
```
cd ~
mkdir meta-custom
cd meta-custom
git init
```
## Custom `kas` Configuration
The first part of you new custom BSP repository should be a `kas` configuration
file. A minimal example for a BSP based on `meta-kontron` looks like this:
```yaml title="custom.yaml"
header:
version: 12
includes:
- repo: meta-kontron
file: kas/inc/imx.yml
- repo: meta-kontron
file: kas/series/kirkstone.yml
repos:
meta-kontron:
url: https://git.kontron-electronics.de/sw/ked/meta-kontron.git
refspec: 6.0.0
path: layers/meta-kontron
machine: kontron-mx8mm
target:
- image-ktn-minimal
```
## Custom Yocto Layer
In order to provide custom configuration and metadata to Yocto, you need to
create your own layer. You can use the `bitbake-layers` utility to do this.
First drop to a `bitbake` shell:
```
kas-container shell custom.yaml
```
Then create your new layer:
```
bitbake-layers create-layer /repo/layers/meta-custom
```
!!! info "Accessing the Repo from within the Container"
If you use `kas-container` the current base repository gets mounted to
`/repo` inside the container automatically.
The `bitbake-layers create-layer` command will tell you to use `bitbake-layers
add-layer` to add an entry for your new layer in `bblayers.conf`. As we are
letting `kas` manage the `bblayers-conf`, we will skip this step and instead
edit our `kas` configuration.
```diff
repos:
meta-kontron:
url: https://git.kontron-electronics.de/sw/ked/meta-kontron.git
refspec: 6.0.0
path: layers/meta-kontron
+ meta-custom:
+ layers:
+ layers/meta-custom:
```
Now with your custom layer setup you can add your customizations such as machine
or distro configs, image recipes or any other Yocto/OE metadata to the new layer
in `layers/meta-custom`.
# Prerequisites
## The `kas` Tool
Before using the Yocto/OE build system (`bitbake`) the metadata needs to be
downloaded from different sources and the build needs to be configured. This is
where the `kas` tool maintained by Siemens comes in handy.
!!! info "Official `kas` docs"
This guide will only cover the basic aspects of `kas` as needed. Please
consult the [official `kas` documentation](https://kas.readthedocs.io) for
further information.
## Choose a Build Host
Select a machine that has enough free disk space (> 50 GiB), a high amount of
memory (>= 32 GiB) and a fast internet connection.
Install an up-to-date Linux distribution of your choice.
!!! info "Yocto Supported Distros"
If you want to do native builds (see below), make sure the distribution is
supported by Yocto. See the
["System Requirements" chapter](https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#system-requirements)
in the official Yocto manual for a list of supported distributions.
!!! info "Virtual Machines or Windows Subsystem for Linux (WSL)"
You can use a virtual machine or WSL as your build host, but please note
that this might impact your build performance and might bring further
pitfalls that are not covered by this guide.
## Install Git
Install Git using your distribution's package manager. For Debian/Ubuntu the
following should do:
```
sudo apt install git
```
## Native or Containerized Builds
There are two ways to do builds using `kas` on your machine. Either natively,
which means you need to have all the dependencies used by Yocto/OE installed in
your OS. Or you can use an already available container image with all the
dependencies included.
### Setup for Containerized Builds (Recommended)
#### Install the Container Engine
We will use `podman` as a container engine. Install it using your distribution's
package manager. For Debian/Ubuntu the following should do:
```
sudo apt install podman
```
!!! info "Using `docker`"
You can use `docker` instead of `podman`, but please note that there might
be differences that are not covered by this guide. If you have both `docker`
and `podman` installed `kas-container` will currently prefer `docker`. You
can override this by setting the environment variable
`KAS_CONTAINER_ENGINE=podman`.
#### Download the `kas-container` Script
Download the `kas-container` script from the `kas` repository and install it to
your system so it can be accessed easily.
```
wget https://raw.githubusercontent.com/siemens/kas/master/kas-container
sudo mv kas-container /usr/bin/
sudo chmod a+x /usr/bin/kas-container
```
### Setup for Native Builds
#### Install `kas`
Install `kas` using the Python package manager `pip`:
```
pip install kas
```
#### Install Yocto Dependencies
This step depends on the Yocto Release you are targeting and your host
distribution. Please follow the ["System Requirements"
chapter](https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#system-requirements)
in the official Yocto manual. Make sure that you select the correct Yocto
release when you read the manual.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment