3. Usage

This chapter provides usage hints for OE. It mainly describes the building of opie-image and related items.

3.1 Update OE

To update the OE package directory enter the directory and run

To checkout your repository remove your org.openembedded.dev dir (or even better rename it) and do a

monotone --db=OE.db co --branch=org.openembedded.dev

as the update process pull;update may take days!
For a quicker way to do see here.

3.2 Bitbake

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 usefull beside building complete packages.

But first here is the help message of bitbake.

        sc@schomep4:~$ bitbake --help
        usage: bitbake [options] [package ...]
        
        Executes the specified task (default is 'build') for a given set of BitBake files.
        It expects that BBFILES is defined, which is a space seperated list of files to
        be executed.  BBFILES does support wildcards.
        Default BBFILES are the .bb files in the current directory.

        options:
        --version             show program's version number and exit
        -h, --help            show this help message and exit
        -bBUILDFILE, --buildfile=BUILDFILE
                        execute the task against this .bb file, rather than a
                        package from BBFILES.
        -k, --continue  continue as much as possible after an error. While the
                        target that failed, and those that depend on it, cannot
                        be remade, the other dependencies of these targets can
                        be processed all the same.
        -f, --force           force run of specified cmd, regardless of stamp status
        -i, --interactive     drop into the interactive mode.
        -cCMD, --cmd=CMD      Specify task to execute
        -rFILE, --read=FILE   read the specified file before bitbake.conf
        -v, --verbose         output more chit-chat to the terminal
        -D, --debug           Increase the debug level
        -n, --dry-run         don't execute, just go through the motions
        -p, --parse-only      quit after parsing the BB files (developers only)
        -d, --disable-psyco   disable using the psyco just-in-time compiler (not recommended)
        -s, --show-versions   show current and preferred versions of all packages
        -e, --environment     show the global or per-package environment (this is what used to be bbread)
        

Examples

A bitbake nano will parse all *.bb files defined in local.conf, build a hash and build everything, which nano depends on and last but not least nano itself.

A bitbake -c clean nano will clean the nano package.

A bitbake -b whereYourOEPackageDirIsbitbake/nano/nano_1.3.5.bb / will just build nano. All depends have already to be fullfilled for that. This does not execute the bb file parsing and spares time (e.g. during debugging).

A bitbake -b whereYourOEPackageDirIsbitbake/nano/nano_1.3.5.bb -f -c clean / will force a clean on the already builded nano package.

A bitbake -b whereYourOEPackageDirIsbitbake/nano/nano_1.3.5.bb -f -c fetch / will force a fetch on the already builded nano package. The package source is downloaded again independent of the cache status.

A bitbake -b whereYourOEPackageDirIsbitbake/nano/nano_1.3.5.bb -f -c build / will force a build on the nano package. This will execute all stages "before" compile like fetch, patch, configure ... and compile itself.

A bitbake -D -D -D nano will build the nano package and show you all files parsed.

A bitbake virtual/kernel -c clean; bitbake virtual/kernel builds a new kernel for the opie-image and afterwards the related image.

Possible CMD options

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.

Hint : If e.g. a stage "build" is used, all prepended stages are executed automatically.

Hint2 : An additional -f forces the command.

3.3 How the configuration works

This section describes the parsing order of .conf and .bb files during a build run. The order defines, where to add / overwrite options for the build process. A changed option may be overwritten / menipulated in a later stage of parsing.

An example is described in the following list.

• openembedded/conf/bitbake.conf
  This is where all parsing starts.
• YourBuildDir/conf/local.conf
  Here you can do you local configuration. Most interesting options are MACHINE and DISTRO. A TARGET_OS or TARGET_ARCH are normally defined somewhere deeper in the conf tree.
• openembedded/conf/machine/YourDefinedMachine.conf
  And all included machine_xxx.conf files. Here the HW-dependend options (kernel, etc ...) are defined.
• openembedded/conf/distro/YourDefinedDistro.conf
  And all included YourDefinedDistro_xxx.conf files (mostly none). Here the Distro dependend options are defined.
• All BBFILES defined .bb files
  This is the final run.

To get a first overview for the set parameters, bitbake prints out the following options before executing.

OE Build Configuration:
TARGET_ARCH   = "arm"
TARGET_OS     = "linux"
MACHINE       = "c7x0"
DISTRO        = "mftetest"
TARGET_FPU    = ""
        

Note, that is you have an "INVALID" option noted here, you will run into series problems during build process and you can interrupt the process.

3.4 Howto set / manipulate variables

Bitbake is able to handle the following assignments.

• =
  Sets a variable to the value given ( e.g. TARGET_OS = "linux" )
• ?=
  Sets a variable to the value given if not already set.
• :=
  Immediate variable expansion.
• +=
  Adds a part to an existing variable (append) ( e.g. PATH += "/usr/local/arm/2.95.3/bin" ) appends the given path to the existing path variable.
• =+
  Adds a part to an existing variable (prepend) ( e.g. PATH += "/usr/local/arm/2.95.3/bin" ) prepends the given path to the existing path variable.

3.5 Cleaning

Cleaning single packages is easy. A

bitbake -c clean packagename

for a self selected actual package or

bitbake -b ../openembedded/packages/packagename_x.y.z.bb -f -c clean

for a specified version of package does that for you.

As soon as you maybe want to use an older version of qte for rebuilding the opie-image, you have to clear manually. You have to guarantee, that all packages depending on qte are cleared from the build dirs.

For example a qte rebuild needs

• cd tmp/work
  • rm -rf *opie*
  • rm -rf libopie*
  • rm -rf libq*
  • rm -rf *qte*
• cd tmp/cache
  • rm -rf *opie*
  • rm -rf *libopie*
  • rm -rf *libq*
  • rm -rf *qte*
• cd tmp/stamps
  • rm -rf *opie*
  • rm -rf libopie*
  • rm -rf libq*
  • rm -rf *qte*

before rebuilding.

Note :If nothing helps, a rm -rf tmp helps always. But in this case all staging items (cross-compiler, ...) have to be rebuild, which takes a lot of time.

See also here.

3.6 Building your own meta package

Sometimes (or always) after a reflash, some liked packages are missing. If you use your tmp/deploy/ipk dir as repository, you can easily create a meta package, which builds all whished packages and creates a meta ipkg out of the result.

This section describes how to manage that.

Assumed you want to have rsync, bash, opie-zsafe added always, you can follow the steps described below to create a meta package.

• Create a dir meta in you private packages dir (if not done so).
• Create a file called xx-collections.inc and xxaddons.bb in there.
  • xxaddons.bb file has the following content.
    

    include sc-collections.inc
    DEPENDS = "${XX_ADDONS_SYSTEM} \
               ${XX_ADDONS_OPIE}
    LICENSE = GPL
    

  • xx-collections.inc file has the following content.
    

    XX_ADDONS_SYSTEM = "rsync bash"
    XX_ADDONS_OPIE = "opie-zsafe"
    

• Create a dir called xxadd containing a xxadd.bbfile with the following content.

  DESCRIPTION = "Sc's additional meta package."
  MAINTAINER = "Werner Schulte <w1@schulte-ac.de>"
  LICENSE = "GPL"
  ALLOW_EMPTY = 1
  PACKAGES = "${PN}"
  DEPENDS = "rsync bash opie-zsafe"
  RDEPENDS = "rsync bash opie-zsafe"
  

  The lines have the following meaning.
  • DESCRIPTION, MAINTAINER, LICENCE : as normal.
  • ALLOW_EMPTY = 1 : allows an empty package (with only depends).
  • PACKAGES = ${PN} : the packages name.
  • DEPENDS : A list of packages to be build when metapackage is build.
  • RDEPENDS : A list of packages to be installed at meta package install.
• Build package scadd (bitbake scadd).