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 make files 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

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]