Building and Customizing EMAC OE
An EMAC [OpenEmbedded] Linux build is the end product of several different build systems. These consist of three core components: [BitBake], [OpenEmbedded], and EMAC [OpenEmbedded]. 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.
|EMAC, Inc. provides this page for informational use for its customers and will not be held liable for any mistakes or omissions on this page which may cause your computer operating system to fail. Use at your own risk.|
You need to be running a GNU/Linux operating system to use OpenEmbedded. If you do not currently have a Linux distribution, EMAC recommends installing a [Debian] 5.0 or higher distribution (except for the unstable branch).
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
|The “oe” provider is not currently registered as a LANANA provider and this name should not conflict with other commercial *nix providers.|
As the superuser (root or as sudo):
- Create a group called
oeand add the development users to the group.
- Make a directory in
- Change the permissions of
- Add a umask of
0002to each account.
In Debian Lenny, you can do the following:
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
.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 (Debian)
This information is from [OEandYourDistro].
developer@ldc:~$ sudo aptitude update developer@ldc:~$ sudo aptitude -y 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
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
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
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
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
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, as described on the Debian wiki: 
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 takes a long time. 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|22.214.171.124|: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.
|This will require superuser access as sudo or root and is VERY DANGEROUS TO USE on a running development system. Although checks have been added to prevent user errors, misusing this script can DESTROY the root file system partition. Make sure to have a system backup before proceeding.|
You will a USB CompactFlash card reader to complete this step.
tmp/deploy/images find the file named
emac-image-x86.tar.gz. This is a symbolic link to the most recently generated build image. There is a problem with the GRUB bootloader in stable-2009 which prevents it from working properly on x86 systems. In order to get a working image you will need to use a supplied bootloader install script in
/opt/oe/emac-oe_stable-2009/contrib/put-image. Read the README.txt for the script usage.
Everything on the CompactFlash will be deleted in the process.
A simple example below:
developer@ldc:~$ sudo put-image --target=/dev/sdc --boot=/dev/sda --append="irqpoll" emac-image-x86.tar.gz
ARM Image Install
EMAC ARM systems utilize U-Boot or RedBoot 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 or RedBoot. EMAC maintains documentation on how to load and program images for each of these bootloaders; please refer to these guides for specific instructions.