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.

BitBake

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

Recipes usually uses 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 hello hello.c
  }
  
  do_install () {
  install -d ${D}${bindir}/
  install -m 0755 ${S}/hello ${D}${bindir}/
  }
  
  FILES_${PN} = "${bindir}/hello"

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.bb".
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 strace_4.5.14.bb, the value of WORKDIR would be set to "strace_4.5.14-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 strace_4.5.14.bb and we are extracting the source from the strace-4.5.14.tar.gz file. Bitbake expects the source to end up in a directory called strace-4.5.14 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 below). 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

Fetching sources from a repository and applying patches

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:

  DESCRIPTION = "hello world sample program"
  PR = "r0"
  DEPENDS = ""
  SRC_URI = " \
  http://www.mysite.com/downloads/helloworld-${PV}.tgz \
  "
  
  do_install () {
  install -d ${D}${bindir}/
  install -m 0755 ${S}/hello ${D}${bindir}/
  }
  FILES_${PN} = "${bindir}/hello"

The first change simply replaces the list of source and make files with a URL for the tarball.

The second change is possible because the build system sets the S variable to ${WORKDIR}${P} by default. Since we've constructed our tarball 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.

References and other interesting links

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