How To Add A Custom App To A Yocto Build

This page is a walk-through to show you how to add your own code/app to a custom Linux build that uses Yocto.

Making A Basic Hello, World App (Binary)

Firstly, we need a basic application that we can then add to a Yocto build. Let’s create a simple application that prints Hello, World to stdout and then exits.

We need to create the following files:

• HelloWorld.c

• HelloWorld.h

• LICENSE

• configure.ac

• Makefile.am

These will be added to a git repository and pushed to GitHub (no folder structure, all these files will be added to the root repository directory).

Let’s create a HelloWorld.c:

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>

#include "HelloWorld.h"

int main(int argc, char *argv[]) {
    printf("Hello, World...\n");
    return 0;
}

And a matching HelloWorld.h:

#ifndef HELLO_WORLD_H
#define HELLO_WORLD_H

/* Some cross-platform definitions generated by autotools */
#if HAVE_CONFIG_H
#  include <config.h>
#endif /* HAVE_CONFIG_H */

#endif /* HELLO_WORLD_H */

We also need a LICENSE file. Yocto is quite particular about licenses, to ensure that users can specify exactly what licensing restrictions are present in a particular build (e.g. make sure this build ONLY contains open-source code). Create a LICENSE file, we will use the MIT license for this one:

The MIT License (MIT)

Copyright (c) 2014 Dynamic Devices

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

We need a configure.ac file:

#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.

#AC_PREREQ(2.60)
AC_INIT(YoctoHelloWorldApp, 1.0, [e-mail])
AC_CONFIG_SRCDIR([HelloWorld.c])
AC_CONFIG_HEADER([config.h])
AM_INIT_AUTOMAKE(YoctoHelloWorldApp, main)

# Checks for programs.
AC_PROG_CC
AC_PROG_INSTALL
AC_PROG_MAKE_SET

# Checks for libraries.
AM_PROG_LIBTOOL

# Set shared libraries
AC_DISABLE_STATIC
AC_ENABLE_SHARED

# Checks for header files.

# Checks for typedefs, structures, and compiler characteristics.

# Checks for library functions.

#AC_CONFIG_MACRO_DIR([m4])
AC_CONFIG_FILES([Makefile])
AC_OUTPUT

Finally, make a Makefile.am:

AUTOMAKE_OPTIONS = foreign

CFLAGS = -Wall -pedantic
include_HEADERS = HelloWorld.h

bin_PROGRAMS = helloworld
helloworld_SOURCES = HelloWorld.c

Notice in the Makefile.am file that we add helloworld to the bin_PROGRAMS variable. This makes Yocto create a binary executable of your example “Hello, World” application and places it in /usr/bin, making it executable from the command-line. We will use this feature to test it in QEMU once we have built the image below.

Commit all these files into a git repository. If you want the Yocto layer to download the files automatically, this repository needs to be placed on a server, so I used GitHub.

During development, you may not want to have to commit everytime you wish to build your code. See the bottom of this page on how achieve this.

The code for this example app is located at https://github.com/gbmhunter/YoctoHelloWorldApp.

Make A Layer To Hold The App

The application needs to be added to a Yocto layer before it can be included in a build. It can either be added to an existing layer, or added to a new one. We will create a new layer to keep the development environment “clean”. All layers are contained with a meta-<layer name> folder.

We will create a layer called meta-example. Create a new directory called meta-example in the main Yocto directory (called poky in our case).

~/poky$ mkdir meta-example

Now cd into this new directory and create a new folder called conf.

~/poky$ cd meta-example
~/poky/meta-example$ mkdir conf=

The config folder holds configuration data about the layer. cd into this directory and create a new file called layer.conf:

~/poky/meta-example$ cd conf
~/poky/meta-example/conf$ touch layer.conf

Add the standard config code to layer.conf as shown below. This layer.conf file tells Yocto where the BitBake files are located in this package. We won’t go into any more detail about this file, as this is beyond the scope of this tutorial.

# We have a conf and classes directory, add to BBPATH 
BBPATH := "${BBPATH}:${LAYERDIR}" 
# We have a packages directory, add to BBFILES 
BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \ 
            ${LAYERDIR}/recipes-*/*/*.bbappend" 
BBFILE_COLLECTIONS += "example" 
BBFILE_PATTERN_example := "^${LAYERDIR}/" 
BBFILE_PRIORITY_example := "5"

We have finished with the conf folder. We now need to create a recipe for this layer of ours. cd into the parent directory, and create a new directory called recipes-example.

~/poky/meta-example/conf$ cd ..
~/poky/meta-example$ mkdir recipes-example