Merge branch 'feature/kas-kconfig-and-docs' into 'main'

Add kas menu-based config (Kconfig) and initial version of docs

See merge request sw/ked/meta-kontron!16

.gitignore

-build/
-layers/*
 !layers/meta-ktn
 !layers/meta-ktn-imx
 !layers/meta-ktn-stm32mp
+.config.yaml*
+build/
+layers/*

.gitlab-ci.yml

 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

Kconfig

+mainmenu "Meta Kontron Build Configuration"
+
+choice
+    prompt "Hardware Platform"
+    default HW_IMX6UL
+
+config HW_IMX6UL
+    bool "Kontron Electronics SL/BL i.MX6UL/ULL"
+
+config HW_IMX8MM
+    bool "Kontron Electronics SL/BL/OSM i.MX8MM"
+
+endchoice
+
+choice
+    prompt "Yocto/OE Series"
+    default SERIES_KIRKSTONE
+
+config SERIES_DUNFELL
+    bool "Yocto Dunfell"
+
+config SERIES_KIRKSTONE
+    bool "Yocto Kirkstone"
+
+endchoice
+
+config HEAD_BUILD
+    bool "Use latest HEAD of all layers"
+
+config SHARED_CACHE
+    bool "Use a shared sstate cache mirror"
+
+config PRODUCTION
+    bool "Enable Production Build Options"
+
+config KAS_INCLUDE_HW
+    string
+    default "kas/ktn-mx6ul.yml" if HW_IMX6UL
+    default "kas/ktn-mx8mm.yml" if HW_IMX8MM
+
+config KAS_INCLUDE_SERIES
+    string
+    default "kas/series/dunfell.yml" if SERIES_DUNFELL
+    default "kas/series/kirkstone.yml" if SERIES_KIRKSTONE
+
+config KAS_INCLUDE_HEAD
+    string
+    default "kas/dev/head-dunfell.yml" if SERIES_DUNFELL && HEAD_BUILD
+    default "kas/dev/head-kirkstone.yml" if SERIES_KIRKSTONE && HEAD_BUILD
+    depends on PRODUCTION
+
+config KAS_INCLUDE_CACHE
+    string
+    default "kas/dev/shared-cache.yml"
+    depends on SHARED_CACHE
+
+config KAS_INCLUDE_PROD
+    string
+    default "kas/production.yml"
+    depends on PRODUCTION

docs/mkdocs.yml

+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

docs/src/build.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.

docs/src/customization.md

+# 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`.

docs/src/prerequisites.md

+# 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.