Building and Customizing EMAC OE

TODO: {{#todo:Broken Links and info boxes; recommends Debian 5.0; Poor transition from background info into howto steps; tries too hard to be distro neutral; only provides dependency info for Debian; we should mirror bitbake and update the links, so the links won't break; still shows using svn for OE|Michael Gloff|oe 4,mg,Review}}

An EMAC [OpenEmbedded] Linux build is the end product of several different build systems. These consist of three core components: BitBake, OpenEmbedded, and EMAC . Each one of these tools is built one upon the other: BitBake → OpenEmbedded → EMAC OpenEmbedded. You will need to download each component separately.

Please familiarize yourself with [OpenEmbedded's Wiki] before continuing.

System Preparation

You need to be running a GNU/Linux operating system to use OpenEmbedded. OpenEmbedded requires a large number of development tools to work correctly with your Linux distribution. However due to the large number of distributions available, please see the OpenEmbedded Wiki page OEandYourDistro for the instruction on the installation of the development packages which are required.

After installing all of the necessary packages to your distribution you will need to set up the location of EMAC OE. By default EMAC OE expects to be installed in /opt/oe.

As the superuser (root or as sudo):

1. Create a group called oe and add the development users to the group.
2. Make a directory in /opt called oe.
3. Change the permissions of /opt/oe to 6775.
4. Add a umask of 0002 to each account.

developer@ldc:~$ add-group oe developer
developer@ldc:~$ mkdir /opt/oe
developer@ldc:~$ chmod 6775 /opt/oe
developer@ldc:~$ oe /opt/oe

umask can be run by the user on the command line or added to the user's startup script. These are typically .<shell_name>rc or .profile in the user's home directory. Failure to do so will result in files without write access to group members.

developer@ldc:~$ umask 0002

umask without any argument will show the current environment umask.

After adding the development users to the oe group and modifying the umask, log out of the development system and log back in before continuing.

Installing Dependencies

developer@ldc:~$ sudo apt-get install sed wget cvs subversion git-core \
		 coreutils unzip texi2html texinfo libsdl1.2-dev docbook-utils \
		 gawk python-pysqlite2 diffstat help2man make gcc build-essential g++ \
		 libxml2-utils xmlto python-psyco \
		 docbook \
		 ccache bash \
		 ncurses-dev fakeroot \
		 qemu kvm

Installing BitBake

This information is from [OpenEmbedded's Getting Started page].

EMAC OE Linux 4.0 is based on the stable-2009 branch of [OpenEmbedded]. For stable-2009 use BitBake versions between 1.8.12 and 1.8.18. As a user in the oe group, download and extract BitBake:

developer@ldc:~$ cd /opt/oe
developer@ldc:~$ wget http://download.berlios.de/bitbake/bitbake-1.8.18.tar.gz
developer@ldc:~$ tar xzvf bitbake-1.8.18.tar.gz
developer@ldc:~$ ln -s bitbake-1.8.18/bin/bitbake bitbake

Installing OpenEmbedded

Checkout the stable-2009 branch of the OpenEmbedded git repository:

developer@ldc:~$ cd /opt/oe
developer@ldc:~$ git clone git://git.openembedded.org/openembedded /opt/oe/openembedded
developer@ldc:~$ cd openembedded
developer@ldc:~$ git checkout -b stable/2009 origin/stable/2009
developer@ldc:~$ git pull
developer@ldc:~$ git status

If everything went correctly, git status should reply as follows:

# On branch stable/2009
nothing to commit (working directory clean)

Installing EMAC OpenEmbedded

1. Checkout the public build tree of EMAC OE from EMAC's Subversion repository:

   developer@ldc:~$ cd /opt/oe
   developer@ldc:~$ svn checkout https://svn.emacinc.com/public/EMAC-OE-2009.03-STABLE/trunk /opt/oe/emac-oe_stable-2009
   

2. Download the additional source package from the EMAC FTP server:

   developer@ldc:~$ cd /opt/oe
   developer@ldc:~$ wget ftp://ftp.emacinc.com/Controllers/Development_Kits/EMAC_Open_Tools/Linux/emac-oe_stable-2009_sources.tar.bz2
   developer@ldc:~$ tar xjvf emac-oe_stable-2009_sources.tar.bz2
   

Making the Build

Set the Machine Type

OpenEmbedded uses configuration files to determine the features, recipe versions, architecture, and setup of the build. The local.conf file specifies the machine and distribution configuration to use as well as other settings. EMAC provides default configuration files for all of our supported target machines. The oe-set-machine.sh script is provided to automatically create a symbolic link from local.conf to the configuration file set up for the selected machine. This must be done to configure EMAC OE prior to starting a build.

developer@ldc:~$ cd /opt/oe/emac-oe_stable-2009
developer@ldc:~$ ./oe-set-machine.sh

Type in the selection for the desired target machine and press enter.

Generate a Base Build

The oe-run.sh script is a wrapper script for bitbake which sets all of the environment variables internally on each run. This isolates EMAC OE's bitbake version from other bitbake versions on the system. If directory locations were used that differ from the set up instructions on this page, the variables in oe-run.sh will need to be modified accordingly.

This step will take several hours depending on the time it takes to download and compile the sources. All of the sources will be downloaded and compiled in the order they are called by the build recipes. The default configurations provided by EMAC specify that recipes should be built in parallel when possible, so bitbake will generally be performing multiple fetch / compile operations at any point during the build.

The default headless image for EMAC machines is named emac-image. This recipe is located in recipes/images/emac-image.bb in the EMAC OE tree. This should be the first image built for any target to verify the setup.

Run the emac-image image recipe.

developer@ldc:~$ ./oe-run.sh emac-image

Bitbake performs a sanity check on the system each time that it is run. If any misconfigurations are detected, the user will be notified of the issue and a suggested fix. Depending on the system, there may be several issues to correct on the first run. For example, a common issue is the value of /proc/sys/vm/mmap_min_addr, as illustrated below:

ERROR:  Openembedded's config sanity checker detected a potential misconfiguration.
        Either fix the cause of this error or at your own risk disable the checker (see sanity.conf).
        Following is the list of potential problems / advisories:
 
        /proc/sys/vm/mmap_min_addr is not 0. This will cause problems with qemu so please fix the value (as root).
 
To fix this in later reboots, set vm.mmap_min_addr = 0 in /etc/sysctl.conf.

EMAC recommends fixing this issue as suggested, but the user should be aware of the possible security implications.

On the first build, bitbake will create a cache of the recipes in the build system, which will take a few minutes. After this is complete, bitbake attempts to run all of the recipes required for the image to be built. This is done in multiple threads utilizing the dependencies between recipes to determine which packages are built first. The first task is to “fetch” the software required to build each recipe. This may take a while depending on the network connection speed. After the source is downloaded the first time, any further builds will use the existing local source copy rather than downloading the source again.

Occasionally, project maintainers or mirrors will move or obsolete a source download such that the location specified in the recipe SRC_URI is no longer valid. If this happens, bitbake will print an error and stop the build. For example, the following error occurred when the zlib version 1.2.3 recipe was run:

Connecting to www.zlib.net|69.73.181.135|:80... connected.
HTTP request sent, awaiting response... 404 Not Found
2011-06-26 10:55:33 ERROR 404: Not Found.

NOTE: Task failed: Fetch failed: http://www.zlib.net/zlib-1.2.3.tar.bz2
ERROR: TaskFailed event exception, aborting
ERROR: Build of /opt/oe-test/openembedded/recipes/zlib/zlib-native_1.2.3.bb do_fetch failed
ERROR: Task 633 (/opt/oe-test/openembedded/recipes/zlib/zlib-native_1.2.3.bb, do_fetch) failed
NOTE: Waiting for 1 active tasks to finish
NOTE: 1: /opt/oe-test/openembedded/recipes/gettext/gettext-native_0.17.bb, do_populate_staging (27565)
NOTE: Tasks Summary: Attempted 160 tasks of which 159 didn't need to be rerun and 1 failed.
ERROR: '/opt/oe-test/openembedded/recipes/zlib/zlib-native_1.2.3.bb' failed

Although EMAC attempts to keep up with source availability issues, they still occur due to constant development in the open source community. If you encounter an error like this, please contact EMAC technical support with the error message.

All build files will be generated in the tmp directory. If a tmp directory does not exist it will be created. Image files will be located in tmp/deploy/images after the build has successfully completed.

The default graphical image for EMAC OE is called emac-ppc-image (“ppc” refers to “Panel PC”) and expands on the emac-image recipe to add a GUI using X11 and the Matchbox Desktop environment. If the target machine has support for a graphical interface, this image can be built using the same process as with the emac-image above:

developer@ldc:~$ ./oe-run.sh emac-ppc-image

Install the Build Image

After building the image, it can be loaded to the board for testing. This process differs between target systems based on the architecture, bootloader, and media type. Some general information is provided in this section.

x86 Image Install

This example is for x86 based single board computers only using a CompactFlash SSD. For other boards contact EMAC Technical Support. See Loading Linux Images to a Compact Flash_Disk

ARM Image Install

EMAC ARM systems utilize U-Boot for the bootloader. While the procedure differs between each board, images are loaded from a TFTP server on the local network and programmed to flash through U-Boot. EMAC maintains documentation on how to load and program images for each of these bootloaders; please refer to these guides for specific instructions.

Loading Images with U-Boot

Loading Images with RedBoot