wiki:Building_SHR

Introduction

Older version of this page Building_SHR_old.

Background

The SHR distribution is put together using the  OpenEmbedded software framework.

Although it may seem initially daunting for new users, it is actually a very simple and effective way of creating a custom Linux distro. An easy way to understand OpenEmbedded is to consider that a Linux distribution is generally constructed from lots of different software packages, where specific versions must be downloaded and compiled, and the resulting binaries written to the relevant places in a Linux file system.

OpenEmbedded allows us to automate this process through the use of plain text configuration files and a powerful Python script called BitBake which can parse each file and perform the necessary actions. The file contents are known as metadata, and this is where we are able to specify details such as where the source code for a package can be obtained, and which version should be compiled. BitBake is also able to apply patches and take care of cross compiling as well as create opkg software archives for each package and write complete filesystem images.

SHR specifics

in order to build SHR we need to download all the metadata files which have been created by the SHR developers for their software along with the files from OpenEmbedded for the rest of the distro and then we need to run the BitBake program to read these files, obtain the sources and compile them into binaries.

In addition to this, many SHR users and developers prefer to do the whole thing inside a chroot jail which contains specific build tools, in order to provide a standard environment regardless of the underlying host. In this case we also need to download and configure all the files and directories which will be inside the jail. Most of this can be taken care of by a universal Makefile which is maintained by the SHR team, and this makes the whole process very simple.

Setting up the build environment

The first step in building SHR is to set up the build system by downloading all the necesarry OpenEmbedded and SHR files and tools using one of the following methods:

Chroot method (recommended)

In order to download and configure all the necesarry files and packages to begin building SHR, it is recommended that the chroot method is used. Instructions on how to do this using the SHR Makefile can be found at:  http://shr-project.org/trac/wiki/Building_SHR_with_chroot

Manual method (advanced users only)

The instructions for setting up the build system without a chroot can be found at:  http://shr-project.org/trac/wiki/Building_SHR_without_chroot

Optional build parameters

After completing one of the above steps you should be ready to begin building software. However, as SHR images contain a lot of packages, it may take a while to compile, depending on the speed of your build host and you may wish to make some minor changes in order to speed up the build process. If you wish to do this you should open the file shr-core/conf/local.conf with a text editor (Vim and Emacs are available inside the chroot, otherwise you can exit the chroot and use your favourite editor).

If you have multi core system you can enable this feature:

PARALLEL_MAKE = "-j 4"
BB_NUMBER_THREADS = "4"

With this option you can specify that only certain locales are built.

GLIBC_GENERATE_LOCALES = "en_US.UTF-8 en_GB.UTF-8 cs_CZ.UTF-8"

The following option should be set to match the one above.

IMAGE_LINGUAS = "en-us en-gb cs-cz"

In order to speed up the whole build you can disable locale generation altogether, using this option. However, it is not possible to build an image without the en_US.UTF-8 locale, so this is only useflu for building single packages.

ENABLE_BINARY_LOCALE_GENERATION = "0"

Building an image

The SHR Makefile and "setup-env" set the environment up to build for the OM-GTA02 device by default, so if you wish to compile SHR for the FreeRunner you can use the following command:

bitbake -k shr-image

*Note the use of the "-k" parameter which instructs BitBake to continue after errors.

The completed images are saved in shr-core/tmp-eglibc/deploy/images, and individual packages in shr-core/tmp-eglibc/deploy/ipk.

To compile for other devices such as the Neo 1973 you can prefix MACHINE before the BitBake command like this:

MACHINE=om-gta01 bitbake -k shr-image

The list of target device names is as follows:

Device Name
Nokia N900nokia900
Openmoko Neo 1973om-gta01
Openmoko FreeRunnerom-gta02
Golden Delicious GTA04om-gta04
HTC Dreamhtcdream
Palm Prepalmpre

If you wish to change the default target device, you can edit it in the file called "setup-local" which can be found inside the shr-core directory. Once changed you can simply run ". ./setup-env" to set your new target.

Building SHR packages

If you want to build everything that is available in the shr feeds run the following:

bitbake -k task-shr-feed

In order to build individual packages (e.g. shr-settings), simply call BitBake with the name of the package as follows:

bitbake shr-settings

Further information

Track and browse remote metadata on the web

old SHR (based on OE-classic) activity:

SHR-CORE danny (used in shr-2012.07) activity:

SHR-CORE dylan (used in shr-2013.07) activity:

SHR-CORE shr (used in shr-next) activity:

Development

If you are interested in developing SHR application, you should now switch over to Getting started developing SHR

Also, if you are interested in developing for FSO, the framework used by SHR, you should now switch over to Developing for FSO with shr-chroot

Troubleshooting

If you run in to trouble building SHR you may want to check the troubleshooting page at: SHR_Build_Troubleshooting