********************************
Setting up a CoreOS based distro
********************************

This chapter explains how to setup a distro based on CoreOS.

Repository structures
#####################

OpenEmbedded is a flexible tool, but we encourage each of our users to adopt
the same structure as CoreOS. In this chapter, replace each usage of `PRODUCT`
or `product` by a unique name related to your product.

.. code-block::

    product/
    ├── build/ (ignored by git)
    ├── documentation/
    ├── layers/
    |   └── coreos/ (submodule)
    |   |   └── bitbake/ (submodule)
    |   |   └── layers/
    |   |   |   ├── openembedded-core (submodule)
    |   |   |   ├── meta-belden-coreos
    |   |   |   ├── meta-belden-coreos-bsp
    |   |   |   └── ...
    |   |   └── ...
    |   ├── meta-product/
    |   ├── meta-other-layers/
    |   └── ...
    ├── scripts/
    ├── templates/
    ├── product-init-build-env
    ├── .gitignore

Creating the structures
#######################

.. code-block:: sh

    ~$  mkdir product
    ~$  cd product
    ~/product$ git init
    ~/product$ git submodule init

    ~/product$ mkdir layers
    ~/product$ mkdir scripts

    ~/product$ git submodule add -b <branch> ssh://git@bitbucket.gad.local:7999/ico/coreos.git layers/coreos
    ~/product$ git submodule update --init --recursive

    ~/product$ cp -r layers/coreos/templates ./templates
    ~/product$ cp layers/coreos/.gitignore ./.gitignore

    ~/product$ touch product-init-build-env
    ~/product$ chmod +x product-init-build-env
    ~/product$ nano product-init-build-env

.. note::

    By copying the .gitignore file of CoreOS, the build directory in the the product
    repository will not be tracked by Git, which is the recommended approach as using
    `devtool modify` modifies the local `bblayers.conf`. Instead we recommend to
    keep the template directory up to date so that a sane configuration can be
    created when fetching the repository for the first time.

Then you can enter the following inside the product-init-build-env file:

.. code-block:: sh

    #!/bin/sh

    # This script is used to setup the OE Build Envrionment
    # Normally this is called as '. ./product-init-build-env <builddir>'

    # On some shell, we can get the path of this script when sources. Otherwise we
    # use the current directory as a fallback
    if [ -z "$PRODUCT_ROOT" ]; then
        if [ -n "$BASH_SOURCE" ]; then
            PRODUCT_ROOT=$(dirname "$BASH_SOURCE")
        elif [ -n "$ZSH_NAME" ]; then
            PRODUCT_ROOT=$(dirname "$0")
        else
            PRODUCT_ROOT="$(pwd)"
        fi
    fi

    # Get a non relative path to the root directory
    PRODUCT_ROOT=$(readlink -f "${PRODUCT_ROOT}")

    # CoreOS init settings
    COREOS_ROOT="${PRODUCT_ROOT}/layers/coreos"
    TEMPLATECONF="${PRODUCT_ROOT}/templates"

    # Call the coreos-init-build-env scripts of CoreOS
    . "${COREOS_ROOT}/coreos-init-build-env" "${1:-$PRODUCT_ROOT/build}"

    # From here the scripts and functions defined by CoreOS and
    # OpenEmbedded-Core are available

    # Add support for ##PRODUCTS_LAYERSDIR## inside of bblayer template
    coreos-bblayers-envsub PRODUCT_LAYERSDIR "${PRODUCT_ROOT}/layers"

    # Add the scripts directory of the product to the path
    coreos_path_add "${PRODUCT_ROOT}/scripts"

Using your new project
######################

.. code-block:: sh

    ~product$  source product-init-build-env

Creating your product layers
############################

You can create a new layer and add it to your active bblayers.conf file like
this:

.. code-block:: sh

    ~product/build$ bitbake-layers create-layer ../layers/meta-belden-bsp
    ~product/build$ bitbake-layers add-layer ../layers/meta-product

Don't forget to update your templates `projects/templates/bblayers.conf.sample`
file. Inside this file use `##PRODUCT_LAYERSDIR##/meta-product` to have a
machine agnostic path.

Optional: Change some git settings
##################################

If you want to always `--recurse-submodules` when using `git pull`, you can
change your `submodule.recurse` git setting, either locally or globally

.. code-block:: sh

    ~/product$ git config submodule.recurse true # Only inside of product repo
    ~/product$ git config --global submodule.recurse true # Set it for all repos


Create your own distro based on CoreOS
######################################

Create a new file inside configuration file inside
`product/layers/meta-product/conf/distro`. For a distro named `product`, you will create
`product/layers/meta-product/conf/distro/product.conf`.

Open this file and enter the following:

.. code-block:: ini

    # This should come at the beginning of the file, to ensure that you use
    # CoreOS defaults
    require conf/distro/belden-coreos.conf

    # This should always be set in your own configuration file, to not use the
    # values of CoreOS
    DISTRO = "product"
    DISTRO_NAME = "Product Linux Distribution"
    MAINTAINER = "Belden Product Team"

    # You may want to add a version and a codename to your distro instead of
    # using the version and codename of CoreOS
    DISTRO_VERSION = "2022.05"
    DISTRO_CODENAME = "ProductOS Summer 2022 Edition"

    # Here you can override settings from the CoreOS distro or from
    # OpenEmbedded-core. But keep in mind that the CoreOS team doesn't support
    # all the features of OpenEmbedded-Core. We have added some checks for some
    # of the settings that we don't allow to change or that we don't support.
    # See the coreos-sanity.bbclass file for more info.

Then you can activate the distro by setting the `DISTRO` to `product` inside
your `product/build/conf/local.conf` file. You should also set it in the 
`product/templates/local.conf.sample` file so that it will be set as the default
when create the build envrionment for the first time.

What to do next
###############

How do I...
-----------

**...add a PRODUCT_ROOT variable usable in recipes files?**

Add this line inside your meta-product layer configuration file at 
`product/layers/meta-product/conf/layer.conf`:

.. code-block:: ini

    # Set a variable to get to the top of the metadata location
    PRODUCT_ROOT = '${@os.path.normpath("${LAYERDIR}/../../")}'

**... add PRODUCT_METADATA_BRANCH and PRODUCT_METADATA_REVISION variables to get the
current git branch and git sha of the PRODUCT repository?**
    
Create the file `product/layers/meta-product/classes/product_metadata_scm.bbclass`
and copy the content of the coreos_metadata_scm.bbclass file. Replacing all
reference to COREOS by PRODUCT should works.

Alternative repository structure
################################

It's also possible but not recommended to clone CoreOS without any submodule, to
create a more flat structure. But then you have to ensure and manage the 
Bitbake et OpenEmbedded-Core version by yourself.

.. important::

    CoreOS is only tested with the version of Bitbake and OpenEmbedded-Core used
    in the CoreOS repository as submodule. By doing this you have to ensure that
    you project stay in sync with CoreOS regarding CoreOS version and
    corresponding Bitbake and OpenEmbedded-Core version.


.. code-block::

    product/
    ├── build/ (ignored by git)
    ├── bitbake/ (submodule)
    ├── documentation/
    ├── layers/
    |   ├── openembedded-core (submodule)
    |   └── coreos/ (cloned without submodule)
    |   |   ├── layers/
    |   |   |   ├── meta-belden-coreos
    |   |   |   ├── meta-belden-coreos-bsp
    |   |   |   └── ...
    |   |   └── ...
    |   ├── meta-product/
    |   ├── meta-other-layers/
    |   └── ...
    ├── scripts/
    ├── templates/
    ├── product-init-build-env
    ├── .gitignore

Setting this structure is out of the scope for this documentation, but as a
hint, to implement it you have to set in `product-init-build-env`:

- `BITBAKEDIR` to the path of the Bitbake repository
- `OEROOT` to the path of the OpenEmbedded-Core repository

.. important::

    Calling directly oe-init-build-env from OpenEmbedded-Core is not supported!
    Ensure that your product-init-build-env call coreos-init-build-env egal if
    you use the recommended or alternative repository structures.