Skip to content

Sample: Headless application

This sample shows how to customize Welma to run a non-graphical application at start-up. It can be used to experiment with Welma and as a starting point for your own application and distribution.

It is provided as a dedicated meta-layer (meta-demo-headless), which is the recommended way to use Welma and Yocto.

Running the demo

Clone meta-demo-headless

If you followed the Quick start guide, the meta-demo-headless layer folder should already be present in your Yocto directory. If not, refer back to the quick start, or add it to your manifest-*.txt file and run welma-manifest/setup-download.

welma-manifest/${WELMA_REF}/manifest-${MACHINE}.txt
meta-demo-headless    git@gitlab.com:${WELMA_GIT_NAMESPACE}/meta-demo-headless ...

Add the meta-layer

We now need to make this layer accessible to Yocto. For this, you can either directly use the template provided (recommended) or edit your layer configuration (bblayers.conf) manually.

Option 1: Run the setup tool

Load the configuration from the templates available in the meta-layers.

Warning

This will override your local configuration and changes you made to your local configuration files.

source meta-welma/setup/setup-build-env \
    meta-welma-*/conf/templates/$MACHINE \
    meta-demo-headless/conf/templates/default

Option 2: Edit your bblayers.conf file

Manually edit your bblayers.conf file and add the layer:

build/conf/bblayers.conf
BBLAYERS =+ "<path-to-yocto-dir>/meta-demo-headless"

Check the meta-layer is found

Bitbake should now be able to find the recipes to build the image if you run the following command:

bitbake-layers show-recipes "demo-image-*"

Example output:

=== Matching recipes: ===
demo-image-headless:
  meta-demo-headless   1.0
demo-image-headless-dbg:
  meta-demo-headless   1.0
demo-image-headless-dev:
  meta-demo-headless   1.0
demo-image-headless-tst:
  meta-demo-headless   1.0

Build and run

Now that the image is accessible, simply build the image and deploy for your target:

bitbake demo-image-headless-dev

After deploying it on your device or emulator and logging on the system, you will be able to see the application running and logging cpu usage periodically:

journalctl --follow

Mar 08 22:06:02 qemuarm-welma demo-headless-app[798]: demo-headless-app:cpu-info:cpu  2893 4 9018 133243 40 0 21 0 0 0
Mar 08 22:06:03 qemuarm-welma demo-headless-app[798]: demo-headless-app:cpu-info:cpu  2896 4 9020 133638 40 0 21 0 0 0
Mar 08 22:06:04 qemuarm-welma demo-headless-app[798]: demo-headless-app:cpu-info:cpu  2896 4 9020 134038 40 0 21 0 0 0
Mar 08 22:06:05 qemuarm-welma demo-headless-app[798]: demo-headless-app:cpu-info:cpu  2896 4 9020 134438 40 0 21 0 0 0

That's it 🎉! You can now experiment with your own application, dive into the implementation below, or look at the Next steps.

meta-demo-headless layer content

This section explains the content of this meta-layer and how it is configured.

  • DISTRO and MACHINE are defined in conf/templates/${MACHINE}/local.conf.sample.

  • The bitbake layers are defined in conf/templates/${MACHINE}/bblayers.conf.sample

  • The production image inherits welma-image and adds our demo headless application:

    recipes-welma/images/demo-image-headless.bb
    SUMMARY = "A small image just to demonstrate Welma"

inherit welma-image

IMAGE_INSTALL += "demo-headless-app"

  • The development image adds developer tools inherited from Welma's development image:

    recipes-welma/images/demo-image-headless-dev.bb
    require demo-image-headless.bb
inherit welma-image-devel

# Use pre-generated keys to avoid a time-consuming (15s) key generation on first SSH connection
IMAGE_INSTALL += "ssh-pregen-hostkeys"

  • recipes-welma/images/license-digest.bbappend configures the software license digest / SBOM to be generated for our demo-image-headless image

  • recipes-welma/images/all.bbappend defines the recipes to be built by bitbake all.

  • The headless application and its systemd service are provided by the demo-headless-app recipe: 

    recipes-welma/demo-headless-app/demo-headless-app_1.0.0.bb
recipes-welma/demo-headless-app/files/demo-headless-app.pam
recipes-welma/demo-headless-app/files/demo-headless-app.service

Next steps

Congratulations! You can now start a headless application automatically at boot. You can continue by: