Creating recipes in Arago

From RidgeRun Developer Connection

Jump to:navigation, search

Contents

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:

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
NOTE: You should never edit files in this directory. You should place your overrides in arago-custom.

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



  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:

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:


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 and other interesting links

Navigation
Toolbox