This article describes how to create and add a new layer to your STM32MPU Embedded Software Distribution Package
for any development platform of STM32 Arm® Cortex® MPUs 
(for example an STM32MP157F-EV1 Evaluation board 
).
This can be done in order to modify some of its installed software, or to add new applications.
It first explains the OpenEmbedded principle for customization by distribution, and then gives a step-by-step approach to
creating a new layer and adding it it to your distribution.
Finally, it gives guidelines on how to upgrade (add, remove, configure, improve...) any piece of installed software.
1. Why create a layer?[edit | edit source]
The OpenEmbedded distribution comes with a set of layers that provide the different pieces of software used to build images.
Checking the layers included in your distribution is easy with the bitbake-layers command tool:
- From your top directory, source your BitBake env setup (if not already done):
source ./layers/meta-st/scripts/envsetup.sh
- List your layers and priority:
bitbake-layers show-layers layer path priority ========================================================================== meta /local/openstlinux-18-01-23/layers/openembedded-core/meta 5 meta-oe /local/openstlinux-18-01-23/layers/meta-openembedded/meta-oe 6 ...
When you want to integrate or modify a distribution , the OpenEmbedded principle is to append modifications/addons in a dedicated place outside of the already available distribution layers.
This place is a new layer that you add to the distribution layers and feed with your modifications or add-ons. Hence the first thing to do when you want to integrate your modifications into a distribution is to create a new layer.
2. How to proceed[edit | edit source]
2.1. Tools[edit | edit source]
The openembedded-core layer provides a utility tool called bitbake-layers, which performs actions associated with layers. It allows you to perform actions including the following:
- see the list of actual layers taken into account in your configuration
- add existing layers to your configuration
- create a new layer
For an exhaustive list of options and subcommands:
- From your top directory, source your BitBake env setup (if not already done):
source ./layers/meta-st/scripts/envsetup.sh
- Display bitbake-layers help:
bitbake-layers --help
NOTE: Starting bitbake server...
usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ...
BitBake layers utility
optional arguments:
-d, --debug Enable debug output
-q, --quiet Print only errors
-F, --force Force add without recipe parse verification
--color COLOR Colorize output (where COLOR is auto, always, never)
-h, --help Show this help message and exit
subcommands:
<subcommand>
show-layers Show current configured layers
show-overlayed List overlayed recipes (where the same recipe exists
in another layer)
show-recipes List available recipes, showing the layer by which they
are provided
show-appends List bbappend files and recipe files to which they apply
show-cross-depends Show dependencies between recipes that cross layer
boundaries
add-layer Add a layer to bblayers.conf
remove-layer Remove a layer from bblayers.conf
flatten flatten layer configuration into a separate output
directory
layerindex-fetch Fetches a layer from a layer index along with its
dependent layers, and adds them to conf/bblayers.conf
layerindex-show-depends
Find layer dependencies from layer index.
create-layer Create a basic layer
Use bitbake-layers <subcommand> --help to get help on a specific command
2.2. Creating a new layer[edit | edit source]
2.2.1. Available layers from configuration[edit | edit source]
You may first check the list of available layers from your configuration and their priority:
- From your top directory, source your BitBake env setup (if not already done):
source ./layers/meta-st/scripts/envsetup.sh
- Then get the list of layers for your configuration:
bitbake-layers show-layers layer path priority ========================================================================== meta-oe /local/openstlinux-18-01-23/layers/meta-openembedded/meta-oe 6 meta-gnome /local/openstlinux-18-01-23/layers/meta-openembedded/meta-gnome 7 meta-xfce /local/openstlinux-18-01-23/layers/meta-openembedded/meta-xfce 7 meta-initramfs /local/openstlinux-18-01-23/layers/meta-openembedded/meta-initramfs 8 meta-multimedia /local/openstlinux-18-01-23/layers/meta-openembedded/meta-multimedia 6 meta-networking /local/openstlinux-18-01-23/layers/meta-openembedded/meta-networking 5 meta-webserver /local/openstlinux-18-01-23/layers/meta-openembedded/meta-webserver 6 meta-filesystems /local/openstlinux-18-01-23/layers/meta-openembedded/meta-filesystems 6 meta-perl /local/openstlinux-18-01-23/layers/meta-openembedded/meta-perl 6 meta-python /local/openstlinux-18-01-23/layers/meta-openembedded/meta-python 7 meta-st-stm32mp /local/openstlinux-18-01-23/layers/meta-st/meta-st-stm32mp 6 meta-qt5 /local/openstlinux-18-01-23/layers/meta-qt5 7 meta-st-openstlinux /local/openstlinux-18-01-23/layers/meta-st/meta-st-openstlinux 5 meta /local/openstlinux-18-01-23/layers/openembedded-core/meta 5
 Information
|
| priority: indicates the order followed by bitbake to apply rules from layers. When two layers have a '.bbappend' file based on the same recipe, the rules defined by the layer having the lowest priority are applied first, and then the rules defined by the layer having the highest priority are applied. This allows a layer with higher priority than the other layers to override any rules defined by the other layers. For more information about priority see the documentation: Priority doc |
2.2.2. Create the new layer[edit | edit source]
To create a new layer you need to specify:
- the location of the new layer
- the name of the new layer
- (optionally) the priority of the new layer.
As an example, let's create the new layer meta-my-custo-layer on meta-st directory with priority set to 7:
bitbake-layers create-layer --priority 7 ../layers/meta-st/meta-my-custo-layer NOTE: Starting bitbake server... Add your new layer with 'bitbake-layers add-layer ../layers/meta-st/meta-my-custo-layer'
cd ../layers/meta-st
tree meta-my-custo-layer
meta-my-custo-layer
├── conf
│ └── layer.conf
├── COPYING.MIT
├── README
└── recipes-example
└── example
└── example.bb
3 directories, 4 files
2.2.3. Recommended actions on a new layer[edit | edit source]
- Update the README file
- Update the priority in the conf/layer.conf file (if it's not the expected one )
- Apply your own modifications and/or addons for the distribition
| Information
|
| Note: you can refer to OpenEmbedded - devtool to learn how to add new applications, modify existing applications and more. |
2.3. Add the new layer to your configuration[edit | edit source]
2.3.1. Generic case[edit | edit source]
You may first check the list of available layers from your configuration and their priority:
- From your top directory, source your BitBake env setup (if not already done):
source ./layers/meta-st/scripts/envsetup.sh
- Then get the list of layers for your configuration:
bitbake-layers show-layers layer path priority ========================================================================== meta-oe /local/openstlinux-18-01-23/layers/meta-openembedded/meta-oe 6 meta-gnome /local/openstlinux-18-01-23/layers/meta-openembedded/meta-gnome 7 meta-xfce /local/openstlinux-18-01-23/layers/meta-openembedded/meta-xfce 7 meta-initramfs /local/openstlinux-18-01-23/layers/meta-openembedded/meta-initramfs 8 meta-multimedia /local/openstlinux-18-01-23/layers/meta-openembedded/meta-multimedia 6 meta-networking /local/openstlinux-18-01-23/layers/meta-openembedded/meta-networking 5 meta-webserver /local/openstlinux-18-01-23/layers/meta-openembedded/meta-webserver 6 meta-filesystems /local/openstlinux-18-01-23/layers/meta-openembedded/meta-filesystems 6 meta-perl /local/openstlinux-18-01-23/layers/meta-openembedded/meta-perl 6 meta-python /local/openstlinux-18-01-23/layers/meta-openembedded/meta-python 7 meta-st-stm32mp /local/openstlinux-18-01-23/layers/meta-st/meta-st-stm32mp 6 meta-qt5 /local/openstlinux-18-01-23/layers/meta-qt5 7 meta-st-openstlinux /local/openstlinux-18-01-23/layers/meta-st/meta-st-openstlinux 5 meta /local/openstlinux-18-01-23/layers/openembedded-core/meta 5
- You can then add the new layer meta-my-custo-layer to your build configuration:
| Information
|
| Make sure that you run the command from your build directory |
bitbake-layers add-layer ../layers/meta-st/meta-my-custo-layer/
- Then check that it has been properly enabled for your configuration:
bitbake-layers show-layers layer path priority ========================================================================== meta-oe /local/openstlinux-18-01-23/layers/meta-openembedded/meta-oe 6 meta-gnome /local/openstlinux-18-01-23/layers/meta-openembedded/meta-gnome 7 meta-xfce /local/openstlinux-18-01-23/layers/meta-openembedded/meta-xfce 7 meta-initramfs /local/openstlinux-18-01-23/layers/meta-openembedded/meta-initramfs 8 meta-multimedia /local/openstlinux-18-01-23/layers/meta-openembedded/meta-multimedia 6 meta-networking /local/openstlinux-18-01-23/layers/meta-openembedded/meta-networking 5 meta-webserver /local/openstlinux-18-01-23/layers/meta-openembedded/meta-webserver 6 meta-filesystems /local/openstlinux-18-01-23/layers/meta-openembedded/meta-filesystems 6 meta-perl /local/openstlinux-18-01-23/layers/meta-openembedded/meta-perl 6 meta-python /local/openstlinux-18-01-23/layers/meta-openembedded/meta-python 7 meta-st-stm32mp /local/openstlinux-18-01-23/layers/meta-st/meta-st-stm32mp 6 meta-qt5 /local/openstlinux-18-01-23/layers/meta-qt5 7 meta-st-openstlinux /local/openstlinux-18-01-23/layers/meta-st/meta-st-openstlinux 5 meta /local/openstlinux-18-01-23/layers/openembedded-core/meta 5 meta-my-custo-layer /local/openstlinux-18-01-23/layers/meta-st/meta-my-custo-layer 7
2.3.2. With STMicroelectronics Distribution Package[edit | edit source]
Pre-requisite:
- Your custom layers are integrated in git.
To apply the new layer on top of fresh Distribution Package delivery:
- Download your layer using the git clone command under the Distribution Package delivery folder tree
- Source your build environment:
source ./layers/meta-st/scripts/envsetup.sh
- Add your layer meta-my-custo-layer to your build configuration
bitbake-layers add-layer ../layers/meta-st/meta-my-custo-layer/
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. 
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.