249 lines
8.3 KiB
ReStructuredText
249 lines
8.3 KiB
ReStructuredText
********************************
|
|
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.
|