Skip to main content

Distribution Package

The Distribution Package builds the whole OpenSTLinux system from source with Yocto / OpenEmbedded. It is the heaviest of the three but the only one that lets you change any component, add packages and produce your own image. Compare with the prebuilt Starter Package and the SDK-based Developer Package.

Workflow​

Getting to a running custom image:

  • Check the host prerequisites.
  • Install the Starter Package for your board.
  • Install the OpenSTLinux distribution (this page).
  • Build the distribution with BitBake.
  • Flash the built image and check the boot sequence.

Once that works you can:

  • Modify software running on the Arm Cortex-A.
  • Modify software running on the Arm Cortex-M (STM32MP15x only — see Boot chain).
  • Create your own Linux distribution.
  • Generate your own Starter and Developer Packages.

Install the distribution​

Fetch the OpenSTLinux manifest with repo:

# e.g. ~/STM32MPU_workspace/STM32MP1-Ecosystem-v5.0.0
cd DISTRIBUTION_DIR/Distribution-Package

repo init -u https://github.com/STMicroelectronics/oe-manifest.git \
  -b refs/tags/openstlinux-6.1-yocto-mickledore-mp1-v23.06.21
repo sync      # slow; let it run

Initialise the build environment​

Source the setup script once per terminal that runs BitBake or devtool. It selects the distro and machine and drops you into the build directory:

sudo apt-get install -y libegl1-mesa libsdl1.2-dev pylint python3-git python3-jinja2 xterm

DISTRO=openstlinux-weston MACHINE=stm32mp13-disco source layers/meta-st/scripts/envsetup.sh

MACHINE must match your board. Building stm32mp13-disco images and flashing them to an MP135-DK is fine (same SoC family), but the machine name has to be a real one from meta-st, or envsetup refuses to configure the build.

Build​

bitbake st-image-weston

The first build compiles everything from source and takes hours. Output lands under build-<distro>-<machine>/tmp-glibc/deploy/images/<machine>/, which receives the complete set of filesystem images and the flash layout files. Flash them exactly as for the Starter Package.

Generate your own packages​

To regenerate the Starter and Developer Packages from your customised distribution, enable the archiver and rebuild:

DISTRO=openstlinux-weston MACHINE=stm32mp1 source layers/meta-st/scripts/envsetup.sh

In build-<distro>-<machine>/conf/local.conf:

ST_ARCHIVER_ENABLE = "1"

Then build with the archive tasks so the "source code" packages for the Developer Package are produced alongside the image:

bitbake st-image-weston --runall=deploy_archives

Create a custom layer​

Never edit ST's layers in place. OpenEmbedded's model is to append your changes in a dedicated layer that sits on top of the delivered ones — that way an ecosystem update does not clobber your work, and your changes are contained and reviewable.

Set up the environment and list the current layers and their priorities:

cd "$HOME/STM32MPU_workspace/STM32MP1-Ecosystem-v5.0.0/Distribution-Package"
source ./layers/meta-st/scripts/envsetup.sh
bitbake-layers show-layers

Create a layer, giving its location, name and (optionally) priority. Priority decides which layer wins when two provide the same recipe:

bitbake-layers create-layer --priority 7 ../layers/meta-st/meta-my-custo-layer

That produces:

meta-my-custo-layer
├── conf
│   └── layer.conf
├── COPYING.MIT
├── README
└── recipes-example
    └── example
        └── example.bb

Then, on a new layer:

  • Update README.
  • Set the priority in conf/layer.conf if the generated one is not what you want.
  • Add your own recipes, appends and add-ons.

Register it in the build:

bitbake-layers add-layer ../layers/meta-st/meta-my-custo-layer/

Applying a layer to a fresh delivery​

To drop a version-controlled layer onto a clean Distribution Package:

# Under the Distribution Package tree
git clone YOUR_LAYER_URL ../layers/meta-st/meta-my-custo-layer

source ./layers/meta-st/scripts/envsetup.sh
bitbake-layers add-layer ../layers/meta-st/meta-my-custo-layer/

The reusable ST bbclasses a custom layer builds on — st-partitions-image, flashlayout-stm32mp and the flash-layout .tsv format — are documented in Yocto classes.