Creating recipes in Arago

Introduction

As it is described in the Arago project's main page (Arago Project[1]) "Arago Project is an overlay for OpenEmbedded/Angstrom, which targets TI platforms OMAP3 (EVM and BeagleBoard) and DaVinci (6446, 355, 6467...) and provides a verified, tested and supported subset of packages, built with a free and open toolchain".

Arago is thought to provide a SDK, which needs first to set up the build environment (See Setting Up Build Environment[2]). Arago is based on three repositories:

arago.git : which contains the Arago specific package build recipes
arago-oe-dev.git : snapshot of the OpenEmbedded development branch
arago-bitbake.git : an Arago version of the bitbake build tool.

Based on these repositories, you can build filesystem images, containing all the necessary packages to run over a specific platform. But you may want to add new packages into the filesystem. Therefore, this document is focused to present the main components needed to develop a recipe, and it assumes that you have already set up a development environment as described.

Brief review of Arago directory layout

After setting up your build environment, your directory structure should look like this:

   workspace
   |-arago
   |-arago-bitbake
   |-arago-oe-dev
   |-arago-custom
   |-arago-tmp
   `-dowloads

arago: The 'arago' directory contains configuration data for the build system.This directory also contains overrides to the standard OpenEmbedded recipes. This is where all of the different TI platforms and packages customizations reside. Bitbake will give preference to recipes that it finds here over recipes contained in arago-oe-dev.

NOTE: You should never edit files in this directory. You should place your overrides in arago-custom.

arago-oe-dev: This directory contains a snapshot of the OpenEmbedded development branch. It contains the "recipes" to build many hundreds of software packages.

NOTE:As well as 'arago' directory you should never edit files in this directory, just place your overrides in arago-custom.

arago-bitbake: This directory contains the bitbake tool and its associated configuration files.

arago-custom: You should place your custom recipes here and also any overrides to recipes contained in 'arago' or 'arago-oe-dev' directories. Bitbake gives highest preference to the recipes in this directory, making it possible for you to override any functionality without having to touch directories under Arago control.

arago-tmp:This is where the build system keeps its working files and also where it places the output of the build. There's a lot going on here, so let's look at the top layer of the directory structure under arago-tmp:
- cache: This is where bitbake caches information it obtains from parsing all available .bb files. You will not need to look in this directory.
- stamps: This directory contains zero length files that are used to track each phase of the build as it is completed. You will normally not need to look in this directory.
- cross: This directory contains the cross development tools for generating code for TI procesors.
- staging: Header files, libraries, and other items needed by the build system are stored in this directory.
- rootfs: After an image recipe build, this directory will contain the complete root file system for the image. This directory is suitable for nfs mounting.
- deploy: This directory contains the final output of the build process: a set of images and ipkg files.
- work:This appropriately named directory is where the real work gets done. A subdirectory is created for each package that is built.There will typically be several subdirectories in each package working directory, let's look at the main ones:
  - <packagename-dir>:This is where the downloaded source code is expanded and patched. It will typically contain the source code for the package as well as any associated makefiles and documentation.
  - packages: This is where the build system places the files which will be packaged into ipkg files.The contents of each of these subdirectories is a root based tree of files exactly as they are to be installed in the target system.
  - tmp: This directory contains the scripts used to build the package and also the log files generated during the build process for the package. This is an extremely valuable debugging resource when you need to see exactly what the build system is doing.
  - image: There is normally no reason to look in this directory. It will contain the directory structure for the package installation, but without the actual files.

  tmp
  |-cache
  |-stamps
  |-cross
  |-staging
  |-work
  |-rootfs
  `-deploy

Arago build tool: BitBake

Recipe Contents

Since Arago is an overlay for OpenEmbedded, it is based upon a tool called BitBake, just as OpenEmbedded does. As well as 'make' tool uses 'Makefiles', BitBake is a tool that uses 'RECIPES' for executing tasks and managing metadata.

Besides descriptive information about the package, a recipe also includes:

The recipe's version
Dependent packages
Source code location
Patches if necessary
Instruction of how to configure and build the package files
Installation location on the target machine

Writting a recipe

Basic Variables

Recipes usually use names of the form: packagename_versionnumber.bb We are going to use as example, sample-recipe_1.0.0.bb, its code is presented below:

  DESCRIPTION = "Sample program"
  PR = "r0"
  DEPENDS = ""
  
  SRC_URI = " \
  file://sample.c \
  "
  S = "${WORKDIR}"
  
  do_compile () {
  ${CC} ${CFLAGS} ${LDFLAGS} -o sample sample.c
  }
  
  do_install () {
  install -d ${D}${bindir}/
  install -m 0755 ${S}/sample ${D}${bindir}/
  }
  
  FILES_${PN} = "${bindir}/sample"

To understand what is described above, use the following table that summaries the main variables often used in the recipes:

Variable	Description
PN	The package name. Determined from the recipe filename - everything up until the first underscore is considered to be the package name. For the sample-recipe_1.0.0.bb recipe the PN variable would be set to "sample-recipe".
PV	The package version. Determined from the recipe filename - everything between the first underscore and the final .bb is considered to be the package version. For the sample-recipe_1.0.0.bb recipe the PV variable would be set to "1.0.0".
P	The package name and versions separated by a hyphen. For the sample-recipe_1.0.0.bb recipe the P variable would be set to "sample-recipe-1.0.0".
PR	The package release. This should be explicitly set in the recipe, if not set it defaults to "r0".
WORKDIR	The working directory is where the source code is extracted, where files (other than patches) are copied, and where the logs and installation files are created. WORKDIR is initialized to PN-PV-PR, so for example recipe sample-recipe_1.0.0.bb, the value of WORKDIR would be set to "sample-recipe_1.0.0-r0" (assuming that the recipe set PR to "r0")
S	This is the unpacked source directory. Bitbake expects to find the extracted source for a package in a directory called packagename-version in the WORKDIR directory. This is the directory which it will change to before patching, compiling and installing the package. For example, let's assume we have a package recipe called sample-recipe_1.0.0.bb and we are extracting the source from the sample-1.0.0.tar.gz file. Bitbake expects the source to end up in a directory called sample-1.0.0 within the WORKDIR. If the source does not end up in this directory, then bitbake needs to be told this by explicitly setting S.
D	This is the destination directory. It specifies where your package should be installed. The packaging system takes the contents of this directory and packages it for installation on the target. The directory structure beneath D should reflect where the package files are to end up in the target system. For example, if a package file is intended to end up in /usr/bin on the target system, the recipe should install the files into ${D}/usr/bin. It is considered poor practice to directly specify /usr/bin. The build system provides a set of variables that you should use instead (see table in Appendix). So for the example above, the proper installation directory specification would be ${D}${bindir}
DESCRIPTION	Specifies the text that will be displayed by the package management system to describe what the package is.
MANTAINER	The name of the mantainer and usually an e-mail address
LICENSE	The package license name
DEPENDS	If there were dependencies on any other packages to build or run, we would list them here.
SRC_URI	Tell the build system where to find source code for the package
FILES_${PN}	Describes the list of files to be installed
RDEPENDS	A list of recommended packages to be installed

Local sources and remote sources

The example recipe code above specified the name of the source file "sample.c" with a file:// prefix, this is the way you must do it, if the source code is located in the local file system. If there were multiple source files, you would list them all here.

  SRC_URI = " \
  file://sample.c \
  "

Now we'll look at the case where the source code is fetched from a remote machine.

Our recipe only requires a few minor change:

  SRC_URI = " \
  http//www.mysite.com/downloads/sample-${PV}.tgz 
  "

The first change simply replaces the list of source and/or makefiles with a URL for the tarball.

A second change is possible because the build system sets the S variable to ${WORKDIR}${P} by default. If the tarball is constructed in the standard fashion, we are able to delete the line in our recipe that used to explicity set S for the location of our source files.

Applying patches

Our recipe is going to require a one line change:

  SRC_URI = " \
  http//www.mysite.com/downloads/sample-${PV}.tgz\
  file://examplepatch.patch;patch=1 \
  "

Adding md5sum information

Some files when downloaded need to be checked using its md5sum.

  SRC_URI = "http//downloads.sourceforge.net/media_files.tar.gz;name=mediafiles"
  SRC_URI[mediafiles.md5sum] = "ffc705fc5581c584d88bd88a8b9caedf"

Possible command options

Bitbake normally acts on all metafiles defined in local.conf. It resolves all dependencies and builds, what is needed. To be able to do this, it first scans all directories given by the BBFILES entry in local.conf and build a hash out of that. This costs some time (and memory). Behind that, bitbake understands several commands useful beside building complete packages.

First here is an extract of the 'help' message of bitbake.

mrodriguez@optimus:~/devdirs/vaddio$ bitbake --help
.
.
.

Options:
 --version             show program's version number and exit
 -h, --help            show this help message and exit
  .
 .
 .
                       shell.
 -c CMD, --cmd=CMD     Specify task to execute. Note that this only executes
                       the specified task for the providee and the packages
                       it depends on, i.e. 'compile' does not implicitly call
                       stage for the dependencies (IOW: use only if you know
                       what you are doing). Depending on the base.bbclass a
                       listtasks tasks is defined and will show available
                       tasks

The following list gives an overview over the bitbake commands:

clean: cleans the package (tmp/work). Does not touch deploy dir (this has to be done manually).
fetch: fetches the package source from the source tree.
patch: eventually patches the sources with the patches provided in the package.
configure: configures the package. Knows several configure methods like autoconf/automake, qmake.
compile: compiles the package.
build: builds the package.
install: install the package.
package: packages the package.

In the sample-recipe code, there are specific instructions for the commands: compile and install. Whether is a Makefile, those might not be necessary.

do_compile () {
${CC} ${CFLAGS} ${LDFLAGS} -o sample sample.c
}

do_install () {
install -d ${D}${bindir}/
install -m 0755 ${S}/sample ${D}${bindir}/
}

Building and installing a package

Building the pakage

To build a 'sample' package, simply type the following at a console prompt. Unlike make, you don't need to cd into the package directory to do this. BitBake knows where to look for recipes and it will automatically find and build the sample-recipe package.

   $ bitbake sample-recipe

After the build completes, you will find the resulting package in the <workspace>/arago-tmp/deploy/ipk/armv5te directory with the name sample-recipe_1.0.0-r0_armv5te.ipk.

Installing our package manually

Installation is a two step process. First, from your build machine command line, copy the ipkg file to your rootfs using the scp utility:

   $ scp <workspace>/arago-tmp/deploy/ipk/armv5te/sample-recipe_1.0.0-r0_armv5te.ipk root@192.168.1.4:/home/root

The above assumes that the IP address of your target is 192.168.1.4, you will need to change this to reflect the actual IP adress.

To install the package, from the command line prompt on your target console type:

   $ cd /home/root
   $ ipkg install sample-recipe_1.0.0-r0_armv5te.ipk

And finally, execute it:

   $ sample-recipe
   'Executing sample: HelloWorld'
   $

Appendix

Variable name	Definition	Typical value
prefix	/usr	/usr
base_prefix	(empty)	(empty)
exec_prefix	${base_prefix}	(empty)
base_bindir	${base_prefix}/bin	/bin
base_sbindir	${base_prefix}/sbin	/sbin
base_libdir	${base_prefix}/lib	/lib
datadir	${prefix}/share	/usr/share
sysconfdir	/etc	/etc
localstatedir	/var	/var
infodir	${datadir}/info	/usr/share/info
mandir	${datadir}/man	/usr/share/man
docdir	${datadir}/doc	/usr/share/doc
servicedir	/srv	/srv
bindir	${exec_prefix}/bin	/usr/bin
sbindir	${exec_prefix}/sbin	/usr/sbin
libexecdir	${exec_prefix}/libexec	/usr/libexec
libdir	${exec_prefix}/lib	/usr/lib
includedir	${exec_prefix}/include	/usr/include

References

OpenEmbedded Main Page [3]
OpenEmbedded User Manual [4]
Bitbake User Manual [5]
Arago Main Page [6]
Build system for Verdex Pro series overview [7]

❯