Software

Installing OpenEmbedded on Gumstix Overo

1. Introduction

This article explains a basic installation process of OpenEmbedded on Gumstix Overo COM, and it also shows how to change the instsetting of OpenEmbedded, which will lead to customize your installing Linux packages.
OpenEmbedded is a framework that creates Linux distributions to targeted embedded systems. OpenEmbedded is a collection of command lines, which are called “bitbake” and are written in Python. To build an embedded Linux for a system, “bitbake” collects the required packages and builds them. OpenEmbedded installs cross-toolchain, kernel, applications for the root file system, and other requirements for embedded Linux.
This article is specific hardware, Gumstix Overo. However, this installation method can be applicable to other hardware. Try this information as a guidelines and/or reference. You may utilize the information listed here when you install OpenEmbedded on other hardware.

Basic information about OpenEmbedded and OpenEmbedded for Gumstix Overo

Many embedded devices use OpenEmbedded for installing specific embedded Linux OSes. One distribution is often branched out to support many devices and/or hardware. Then, each branch-outed Linux is specifically optimized for its targeted hardware or device. For example, Angstrom and Yocto Project are originated from the same Linux distribution. Now Angstrom is used for BeagleBoard as well as Linux Zaurus. Yocto project, which is supported by Linux Foundation, is specifically targeted at Intel devices. Since the origin of embedded Linux OSes for these device and project are the same, one new package can be built on a certain embedded Linux, the recipe, which let the new package build, can be acceptable to other embedded Linux OSes. To use OpenEmbedded, users can easily manage to set up the specific packages for certain embedded Linux OSes. For farther information, please visit website below.

Gumstix Overo employs a branch of OpenEmbedded, whose structure is slightly different from the mainline of OpenEmbedded.

To find solutions for the OpenEmbedded related issues on Gumstix Overo COM or other hardware, reading these websites, joining mailing list, and reading archives of the mailing lists are highly recommended, and you may find solutions there. However, since the volume of the archives is quite large, you may have a difficult time to find solution may look for. To avoid such things happening, please go through this article and get idea of the installation process.

2. Development Environment

The software, which is required for the installation of OpenEmbedded, is listed at the URL below.

Actually, at the end, the details of installation process is different, and it is highly depending on the distributions. Each Linux distribution does have different names on packages and own installation methods. If you like to know how to install the requirements of Linux distribution that you have selected, go to OpenEmbedded's website (URL is shown below), and look at required software for each distribution and its installation method. The installation method for Ubuntu is shown at the next section

The required software and files for the build system of OpenEmbedded are:

  • Python (Python 2.6.x and 2.7.x only; Python 3.x.x is not acceptable.)
  • Development file for Python (its package names is such as “python-dev” or “python-devel”)
  • Python PLY (Python Lex-Yacc)
  • python-progressbar (this is for the display of the progress of download or build process)
  • GNU Patch
  • GNU m4
  • GNU make
  • perl
  • diffstat

These sets of software are needed for downloading source code of the software shown above.

  • wget
  • curl
  • ftp
  • cvs
  • subversion
  • git
  • mercurial (this is not required for Overo COM)

To check whether the downloaded files are correct ones or not, test with these sets of software shown below.

  • md5sum
  • sha256sum

The sets of software shown below are required for extracting the downloaded archives.

  • tar
  • bzip2
  • gzip
  • unsip

To build the documents, which are included in the downloaded packages, apply the software shown below.

  • Jade
  • Docbook
  • sgmtools
  • docbook-utils
  • texinfo
  • texi2html

Other requirements are:

  • GNU sed
  • Bison
  • bc
  • glibc heades
  • pcre headers
  • SDL heades
  • mktemp
  • help2man
  • charpath

2.1 Preparation for building OpenEmbedded on Ubuntu

To build an image for Gumstix Overo COM, this article uses an Ubuntu as the working environment. This Ubuntu is version 10.04 and an LTS (Long Term Support).

Since Ubuntu is based upon Debin, this method can be applicable to and replicated on other Debian based Linux distributions. However, this method is specifically tested with Ubuntu 10.04 only. There is no guarantee to complete the preparation and building process successfully.

To use a package management command “aptitude”, install the applications, which are needed for building an image on this Ubuntu.

$ sudo -s
$ aptitude install sed wget cvs subversion git-core coreutils unzip \
  unziptexi2html texinfo docbook-utils gawk python-pysqlite2 diffstat \
  help2man make gcc build-essential g++ desktop-file-utils chrpath \
  aptitude install libxml2-utils xmlto python-psyco libapr1 

“/bin/sh” of Ubuntu has the symbolic link to “dash” shell commands. Since “bash” shell commands are considered as the standard for Linux commands, “dash” commands may cause errors during the building process. To avoid the errors form happening, the configuration of the symbolic link is changed, and it is directed to “bash” shell commands.

# dpkg-reconfigure dash

To execute this command, a dialog box appears, asking whether “/bin/sh” should be linked with “dash” or not? Please select “no” to connect “bash.” After answering “no,” “/bin/sh/ is linked to “bash.”

2.2 Download of OpenEmbedded and its configuration

In the previous section, the setting-up of working environment has been completed. The applications, which are used for building OpenEmbedded image, have been downloaded and installed on Ubuntu. Next, in this section, OpenEmbeddd is down loaded and configured.

To seek the information for downloading and configuration of OpenEmbedded, you may already visited the websites shown below. However, this section follows the method, which is listed on Gumstix's site. Never apply to the method of OpenEmbedded site. Please be careful.

The size of the source file for OpenEmbedded is about 250MB. At least 10GB of free space is required in Ubuntu. To build OpenEmbedded, this article assumes that a user works at log-in user's home directory.

Create a working directory and move to the created directory

$ mkdir -p ~/overo-oe
$ cd ~/overo-oe

To use “git”, the metadata of OpenEmbedded is obtained. Then, check out the branch for Overo COM.

$ git clone git://gitrious.org/gumstix-oe/mainline.git org.openembedded.dev
$ cd org.openembedded.dev
$ git checkout –track -b overo-2011.03 origin/overo-2011.03 

Obtain “bitbake” command independently. Do NOT use a “bitbake”, which is stored at the repository of Ubuntu.

$ cd ~/overo-oe
$ git clone git://git.openembedded.org/bitbake bitbake
$ cd bitbake
$ git checkout 1.12.0

Create the configuration file for OpenEmbedded and the profile for configuring the environment variables.

$ cd ~/overo-oe
$ cp -r org.openembedded.dev/contrib/gumstix/bild

Up this point, under the working directory “~/overo-oe/”, these files and directories should have been created so far. The directory tree is listed below. Please use it for checking.

~/overo-oe/
 |--bitbake/
 |   |-- AUTHORS
 |   |-- COPYING
 |   |-- ChangeLog
 |   |-- HEADER
 |   |-- MANIFEST.in
 |   |-- TODO
 |   |-- bin/
 |   |-- classes/
 |   |-- conf/
 |   |-- contrib/
 |   |-- doc/
 |   |-- lib
 |   `-- bild/
 |--build/
 |   |-- conf/
 |   |    |-- auto.conf/
 |   |    |-- local.conf/
 |   |    `-- site.conf/
 |   |-- extra/
 |   |    `-- site.conf/
 |   `-- profile
 `--org.openembedded.dev
     |-- COPYING.MIT
     |-- MAINTAINERS
     |-- README
     |-- bin/
     |-- classes/
     |-- conf/
     |-- contrib/
     |-- docs/
     |-- files/
     |-- lib/
     |-- recipes/
     |-- removal.txt/
     `-- site/
  • The bitbake directory is a collection of bitbake commands, which are written in Python.
  • Under the build directory, the files, which are related to the environment variables, are putted together. Under the directory of “org.openembedded.dev”, there are configuration files for building OpenEmbedded.

2.3 Configurations for the Build command

To execute the Build command, the information of environment variables, which are written in the documents located at the directory of “~/overo-oe/build/profile”, have to be completed. To set the configuration of these environment variables permanently, all information of these documents are copied to “.bashrc”. Then, to log in Ubuntu, the file is loaded, and the information is automatically set up. You do not need to configure the information again manually.

$ cp ~/.bashrc ~/bashrc.bak
$ cat ~/overp-oe/ 

If you like to configure the information as you execute the build command with “bitbake” only, run a command shown below before execute the build command.

$ source ~/overo-oe/profile

or

$ .~/overo-oe/profile

The language setting of some packages is required in English. Otherwise, the package will cause errors during the building process. As the language setting turns into English, the error messages will be written in English only.

$ export LANG = “en_US.UTF-8”

This change is only for a precautionary measure. The packages that you shave selected may or may not cause errors. There are no guarantee for the cause or prevention of errors.

3. Building the image for Overo

Now, the setting up for the building process has been completed. In this section, select a target and execute the build command of “bitbake” for building an image for Overo. There are several build targets for Overo, and its targets are shown below.

bitbake x-load                      MLO (bootstrap loader for OMAP3)
bitbake u-boot                      u-boot for Overo COM
bitbake virtual/kernel              kernel only
bitbake omap3-console-image         Console image only, no GUI
bitbake omap3-palmtop-image         Touch panel capable image and small size image
bitbake omap3-desktop-nand-image    a desk-top image, which can be stored in nand
bitbake omap3-desktop-image         a desk-top image, which is used for nfs or SD boot

Try to build a basic, “bitbake omap3-console-image”

$  bitbake omap3-console-image

As this build command is executed, “~/overo-oe/org.openembedded.dev/recipes/images/omap3-console-image.bb” is parsed, and the recipes, which are written in the document above, are initially executed. The recipes written in the document, trigger to execute other recipes, secondarily. At the end of this chain of secessions, “bitbake omap3-console-image” command executes totally 5168 tasks and builds the image. These 5168 tasks include the stages of fetch, unpack, patch, configure, and configure for each package.

The source code of each package is downloaded at the directory of “~/overo-oe/sources/”, and test verified its version with a file checksum. Then, each file is categorized by its targeted architecture and machine, and a file is brought to a specific directory located under “~/overo-oe/tmp/work/”. Then, the stored files are extracted and built in the specific directory. The list of these directories is shown below.

~/overo-oe/tmp/work/
       |--all-angstrom-linux-gnueabi
       |--armv7a-angstrom-linux-gnueabi
       |--i686-linux(or x86_64-linux)
       `--oevro-angstrom-linux-gnueabi
  • all-angstrom-linux-gnueabi a package of angstrom, which does not depend on architecture
  • armv7a-angstrom-linux-gnueabi a package of angstrom, which is targeted and specifically buildt for the armv7a architecture
  • i686-linux(or x86_64-linux) a package of angstrom, which consists of specific tools for the host OS. The tools work well on the host OS, which provides the working environment.
  • oevro-angstrom-linux-gnueabi a package of angstrom, which is specifically targeted at Overo COM.

Since the results of supporting Angstrom on armv7a are shared on OpenEmbedded, the three out of four files are succeeded after the name of angstrom.

Under the directory of “~/overo-oe/tmp/”, all build and packaging processes are completed.

tmp/ 
 |-- abi_version
 |-- cache/
 |-- deploy
 |-- distro_pr
 |-- legacy-staging.log
 |-- pkgdata/
 |-- pstage/
 |-- rootfs/
 |-- saved_tmpdir
 |-- stamps/
 |-- sysroots/
 |-- usr/
 `-- work/

As all tasks are completed, a built file is generated under the directory of “~/overo-oe/tmp/deploy/glibc/”

3.1 About a built file

~/overo-oe/tmp/deploy/glibc/
    |-- images/    an actual image, which is written into nand, microSD card.
    |-- ipk/       a set of ipk software packages, which constitutes the bootable image. The role of ipk strongly resembles the role of deb package.  
    `-- sources/   This provides kinks to source and/or recipes, which are categorized by the types of licenses such as GPLv2, MIT, and so on.

3.2 about image

The files, which are required for the bootable image, are stored at the directory of “image”. As command of “bitbake omap3-console-image” is completed, the directories shown below are created under the “images” directory

~/overo-oe/tmp/deploy/glibc/
     |-- images/       <- This one!
     |     `-- overo
     |-- ipk/            
     `-- sources/  
images/
 `-- overo
      |-- Angsrom-omap3-console-image-glibc-ipk-2011.03-overo-testlab/
      |-- Angsrom-omap3-console-image-glibc-ipk-2011.03-overo.rootfs.tar.bz2
      |-- Angsrom-omap3-console-image-glibc-ipk-2011.03-overo.rootfs .ubi/
      |-- Angsrom-omap3-console-image-glibc-ipk-2011.03-overo.ubifs.img
      |-- modules-3.0-r103-overo.tgz
      |-- omap3-console-image-overo.tar.bz2 ->  Angstrom-omap3-console-image-glibc-ipk-2011.03-overo.rootfs.tar.bz2
      |-- omap3-console-image-overo.ubi -> Angstrom-omap3-console-image-glibc-ipk-2011.03-overo.rootfs.ubi
      |-- u-boot-overo-2011.09+r76+gitr0f331e606c80166c1bfe5cac40dfc0616708f31b-r76.bin
      |-- u-boot-overo.bin -> u-boot-overo-2011.09+r76+ gitr0f331e606c80166c1bfe5cac40dfc0616708f31b-r76.bin
      |-- uImage-3.0-r103-overo.bin
      |-- uImage-overo.bin -> uImage-3.0-r103-overo.bin
      `-- ubinize.cfg

These images are u-Boot, Kernel image (uImage) that read by u-Boot, Kernel module, ubi image, which is bootable form nandFLASH, and tar.bz2 image, which is booted form microSD. To boot Overo COM, addition to these files, a MLO is also required.

4 Customizing a bootable image

Now you know how to build and to install the built image of OpenEmbedded. This section shows you how to customize the bootable image of OpenEmbedded. There are two different ways to modify the bootable image. One is to work with the “ipk” package. The other is to alter the recipes for creating the bootable image of OpenEmbedded.

4.1 about ipk

In the last part of the previous section, details of “images” directory are explained. Before start discussing how to customize a bootable image, briefly talk about the “ipk”directory.

~/overo-oe/tmp/deploy/glibc
     |-- images/ 
     |-- ipk/              <- This one!
     |     |-- all
     |     |-- armv7a
     |     |-- i686
     |     `-- overo 
     `-- sources/  

After executing “bitbake omap3-console-image”, the directories shown above is created. The third one from the top is the “ipk” directory. The “ipk” directory stores the “ipk” packages. The ipk packages mange images and applications. The function of the “ipk” packages is very similar to the deb packages of Debian distribution. To work with the “ipk” package, you can customize the image or install new applications into the host Linux OS.

4.2 Customized by ipk packages

To customize the bootable image, “ipk” packages are selected from one of subdirectories of “~/overo-oe/tmp/deploy/glibc/ipk/” where packages are classified by its targeted architecture. After selecting the packages, install them.

After the “bitbake” command is executed, the “ipk” packages are created at the directories shown below. These packages are categorized by the types of architectures.

ipk
 |-- all/        (The “ipk” packages for all architectures are output in this directory.)
 |-- armv7a/     (The “ipk” packages for armv7a architectures are output in this directory.)
 |-- i686/       (The “ipk” packages for i686 architectures are output in this directory.)
 `-- overo       (The “ipk” packages for overo architectures are output in this directory.)

To install the package (“example.ipk” in the example of commands), boot from the bootable image. and use the “opkg” command. To install the package via network, copy the “ipk” package into the and execute the “opkg” command.

$ opkg install example.ipk

Similar to Debian's the “apt” and “aptitude” commands, the “opkg” command allows downloading and installing “ipk” files, which has been already built and stored at an outside URL.

$ opkg update
$ opkg list | grep example
example.ipk
$ opkg install example.ipk

If you are looking for a package, which has not been included in the directory of the output packages, you should add the package manually, and execute the build command.

Obtain the list of all packages, which “bitbake” can handle the installation process.

$ bitbake -s > list text

If the package, which you are looking for, is in the list and has not been built yet, to follow the commands shown below, you should build and create the “ipk” package.

For example, if you are supposed to add “vim” into the build image, look at the list, first.

$ grep vim list.txt
devimage                 0:0.1-r4
devimage-image           0:1.0-r0
gvim                     0:7.2-r8.3
task-devimage            0:1.0-r7
vim                      0:7.2-r8.3
vim-tiny                 0:7.2-r8.3

As you find it in the list, then, build it.

$ bitbake vim

As the build process is successfully completed, its ipk package is created under the directory of “~/overo-oe/tmp/deploy/glibc/armv7a/vim_7.2-r8.3.6_armv7a.ipk”. As following the steps shown above, this “ipk” package is copied, and its installation is done by the “opkg” command

 $ opkg install #####.ipk                       (#### indicates the name of package)

If all the required dependences for a package are not installed appropriately, the warning appears in the “opkg” command. To avoid this happening, all its required dependences should be installed.

This is how to customize a bootable image by installing additional “ipk” packages. This process is not complicated. However, even though the outputs of the “list” command indicate that recipes for packages exist in the directory of “~/overo-oe/org.openembedded.dev.recipes/”, some packages may only build but not be installed, or only be installed but not run. Therefore, as you customize the bootable image, you have to carefully select the packages.

4.3 Customized by modifying the contents of recipes

So far, this article has explained how to customize the bootable image by selecting the “ipk” packages. This part of the article shows the customization of OpenEmbedded by modifying recipes before building its bootable image. For the example, the language setting of this bootable image is modified from English to Japanese before the bootable image is built.

As explained above, the build target for Overo COM initially does not include any local language other than Enlish. The example, whose language setting is modified, is omap3-desktop-nand-image. This built image is identical to the image that is intalled in nandFlash of Overo.

First, the language setting of “~/overo-oe/build/conf/local.conf” is examined. In the configuration file, which is located at the directory of “~overo-oe/org.openembedded.dev/conf/distro”, there is a line of “DISTRO = “angstrom-2008.1”, and this line indicates that the image for Overo is based upon the distribution of “angstrom-2008.1”.
The configuration of “angstrom-2008.1” is written in “angstrom-2008.1.conf”. In this file, the configuration of language is defined as “IMAGE_LINGUAS = '${@base_less_or _equal(“ROOT_FLASH_SIZE”, “16”, “”, “en-us”, d)}'. It determines the language setting as English. In the line, the setting is defined as “en-us”. “en-us” should be chaged to”ja-jp”.

Then, The is a file callled “local.conf.sample” at the dirctory of “~overo-oe/org.openembedded.dev/conf/”. This is a sample file of configuration, which can be applied to “~overo-oe/build/conf/local.conf”. In this file of “local.conf.sample”, there is a line of a language configuration:

ENABLE_BINARY_LOCALE_GENERATION = “0” 
GLIBC_GENERATE_LOCALES = “en_US.UTF-8 en_GB.UTF-8 de_DE.UTF-8” 

If the value of the former line is set as 1, the latter line generates a newly configured local language setting. To use these lines in the sample file as a sample, the new local configurations are added to the file located at “~overo-oe/build/conf/local.copnf”. The lines are:

ENABLE_BINARY_LOCALE_GENERATION = “1”
GLIBC_GENERATE_LOCALES = “en_US.UTF-8 ja_JP.UTF”-8”

Also, a recipe file is modified for a new local language setting. A recipe file, omap3-nand-desktop-image.bb belongs to “omap3-nand-desktop-image”, which is located inside the directory of “~overo-oe/org.openembedded.dev/recipes/images/. In the recipe file, the part of line is changed from

IMAGE_LINGUAS = “en-us”

to

IMAGE_LINGUAS = “ja-jp”

Moreover, “~overo-oe/build/conf/local.conf” is needed to be checked. In the “local.conf” file, there is a line that identifies the distribution of the image.

DISTRO = “angstrom-2008.1”

The line above indicates that the distribution of the image for Overo COM is angstrom-2008.1. The details of the built information for DISTRO is written in the configuration file located at “~/overo-oe/prg.openembedded.dev/conf/distro”.
In the “angstrom-2008.1.conf”, which determines the setting of angstrom-2008.1, there is a line that sets up the language setting.

IMAGE_LINGUAS = '${@base_less_or_equal(“ROOT_FLASH_SIZE”, “16”, “”, “en-us”, d)}'

This configuration forces the language setting in English (en-us), if the size of the internal nandFLASH on the targeted device is quite small. The size of nandFLASH on Overo has 256M, and this is more than enough to install the local language setting. For a precautionary measure, the language setting of this line is also altered. To prevents the language setting selects English somehow, the initial setting turns into Japanese.

IMAGE_LINGUAS = '${@base_less_or_equal(“ROOT_FLASH_SIZE”, “16”, “”, “ja-jp”, d)}'

After modifying these parts, execute the command “bitbale omap3-desktop-nand-image”. Then, “omap3-desktop-nand-image”, which contains Japanese local setting, is created. To check the created image contains the ja-jp local setting before booting the image on Overo COM, please aply the commands shown below.

$ cd ~overo-oe/tmp/deploy/glibc/images/overo/Angstrom-omap3-desktop-nand-image-glibc-ipk-2011.03-overo-testlab

$ grep ja-jp *
files-in-image.txt:-rw-rw-r-- 1 root root   1569  Nov  25  19:54  glibc-localedata-ja-jp.control
files-in-image.txt:-rw-rw-r-- 1 root root     30  Nov  28  20:34  glibc-localedata-ja-jp.list
files-in-image.txt:-rw-rw-r-- 1 root root   1556  Nov  25  19:19  locale-base-ja-jp.control
files-in-image.txt:-rw-rw-r-- 1 root root      0  Nov  28  20:34  locale-base-ja-jp.list
files-in-image.txt:-rwxr-xr-x 1 root root    456  Nov  25  19:19  locale-base-ja-jp.postinst
files-in-image.txt:-rwxr-xr-x 1 root root    402  Nov  25  19:19  locale-base-ja-jp.post rm
installed-package-sizes.txt:72        KiB   /armv7a/glibc-localedata-ja-jp_2.9-r37.4.6_armv7a.ipk
installed-package-sizes.txt:4          KiB   /armv7a/locale-base-ja-jp_2.9-r37.4.6_armv7a.ipk
installed-packages.txt;glibc-localedata-ja-jp_2,9-r37.4.6_armv7a.ipk
installed-packages.txt:locale-base-ja-jp_2.9-r37.4.6_armv7a.ipk

$ grep JP *
files-in-image.txt:-rw-r--r-- 1 root root     1115  Nov  27  04:17  lang-ja_jp.png
files-in-image.txt:-rw-r--r-- 1 root root     2221115  Nov  25  18:51  ja-JP

As the output lines indicate, the Japanese local setting is built with the image, and the “ipk” packages that handles Japanese language setting are installed in “omap3-desktop-nand-image”.

Revision History

  • 2012/2/29 The article is initially uploaded.
  • 2012/3/05 Overo is chaged to Overo COM.

Front page   Edit Freeze Diff Backup Upload Copy Rename Reload   New List of pages Search Recent changes   RSS of recent changes
Last-modified: 2012-03-05 (Mon) 10:04:21 (2083d)