Applications HOWTO

This document describes how to use the infrastructure of the software distribution to build and include applications and libraries in the firmware image. The methods described in this document are the preferred ones when developing software using the software distribution.

Requirements

An installed version of the software distribution is required, for install directions read the software distribution install howto.

To understand the design of the software distribution read the software distribution design guide.

The compiling for cris howto document is recommended as it will help you to understand how the compiler works.

Readers advice

This document is written with 2.10 and 2.20 versions of the software distribution in mind. However, most of the concepts discussed should apply for earlier versions as well.

Text within angle brackets ”<>” should be read as a placeholder for something else, for example, linux-<kernel version> could be linux-2.6.19.

Examples in this document assume that you have installed the Developer Board/Device Server SDK in the /<home directory>/axis/devboard directory. The expression ”~/axis/devboard” will be used throughout this document.

Include a simple program

We start with how to include a very simple program in the software distribution. The program used in this section is the “Hello World!” program known from the compiling_for_cris_howto guide.

Configure the environment

First we need to configure the environment. If you haven't installed the software distribution yet do so now, instructions can be found in the software_distribution_install_howto.

Enter the software distribution root directory

cd ~/axis/devboard

Then source the init_env file to set up environment variables that you will need.

source init_env

or

. init_env

By sourcing the init_env file environment variables such as the path to the compiler and the software distribution root directory will be configured in the current shell. The software distribution requires that these environment variables are set correctly and therefore it is recommended that always source the init_env file when working with the software distribution.

The program

As we are going to work with the very simple “Hello World!” application create a directory named hello in the apps directory.

mkdir apps/hello

Copy the source code below and save it to a file named hello.c in the hello directory that we created:

#include <stdio.h>
int main(int argc, char *argv[]) {
  printf("Hello World!\n");
  return 0;
}

Create a Makefile

The build system in the software distribution is based on several Makefiles1) that makes up a set of rules. These rules control things such as which compiler and which standard C library to use and much more. To make use of these rules we will write a Makefile for our application. It may seem like an awful lot of work for a compiling one c-file, but this is just to make things easier later on. For example we will not have to worry about all the things described in the compiling_for_cris_howto as the build system will take care of this for us.

A typical Makefile used in the software distribution for a simple program such as our “Hello World!” program could look something like this:

AXIS_USABLE_LIBS = GLIBC UCLIBC
include $(AXIS_TOP_DIR)/tools/build/rules/common.mak

PROGS     = hello
INSTDIR   = $(prefix)/bin/
INSTMODE  = 0755
INSTOWNER = root
INSTGROUP = root

OBJS      = hello.o

all: $(PROGS)

$(PROGS): $(OBJS)
        $(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@

install: $(PROGS)
        $(INSTALL) -d $(INSTDIR)
        $(INSTALL) -m $(INSTMODE) -o $(INSTOWNER) -g $(INSTGROUP) $(PROGS) $(INSTDIR)

clean:
        rm -f $(PROGS) *.o core

Note: make requires tabs indents, spaces will not work.

Tips: Normally you could save time by copying a Makefile from another application or library. For example have a look at apps/init/Makefile and compare it to the Makefile above.

The Makefile above could be considered pretty standard except the first two lines. The first line in the Makefile above set a variable that will be examined by the rules that are included in the second line. The AXIS_USABLE_LIBS variable simply tell the build system which standard C library this application can be compiled for. Generally, both these lines should be included first in any Makefile for an application or a library.

For more information on the make program and Makefiles have a look in the GNU Make Manual.

The rules of the build system

When the make program executes the Makefile above the build system rules (remember, the second line?) will perform several things. The explanation below is not complete but will give you an idea of what happens.

Pretty much the first thing that will happen is that a file named .target-makefrag in the same directory as the Makefile is read. The purpose of the .target-makefrag file is to specify for the build system which target system the application should be build for. Available “targets” and their effect can be seen in the table below.

Target nameDescription
cris-axis-linux-gnuBuild the application for crisv10 (ETRAX 100LX) with the glibc standard C library.
cris-axis-linux-gnuuclibcBuild the application for crisv10 (ETRAX 100LX) with the uClibc standard C library.
crisv32-axis-linux-gnuBuild the application for crisv32 (ETRAX FS) with the glibc standard C library.
crisv32-axis-linux-gnuuclibcBuild the application for crisv32 (ETRAX FS) with the uClibc standard C library.
hostBuild the application for the host system.

Depending on which target the .target-makefrag file specifies the build system rules will set variables such as CC, LD, INSTALL, CFLAGS, LDFLAGS, LDLIBS differently. As seen some of these are used in the Makefile above. For example the CC variable specifies the compiler and compiler flags such as -mlinux and -march as discussed in the compiling_for_cris_howto.

Build the application

Now when we have created the Makefile we are ready to build the application and test if the Makefile and build system work together as expected.

As you may have noticed the Makefile above include AXIS_TOP_DIR variable. So if you didn't follow the instructions above it is recommended that you source the init_env file now or make will fail as this environment variable is needed.

As mentioned the build system will look for a .target_makefrag file in the ~/axis/devboard/apps/hello directory. Normally this file is created automatically by the build system for all source packages included in the software distribution. But we have not instructed the build system about our “hello” application yet and consequently we will have to create this file. More about the inclusion of the application in the build system later on. To create the .target_makefrag file type make <target> in the same directory as the application. This will run a rule found in the build system that will place a .target_makefrag file with the correct target syntax in the directory.

To build the hello executable for the CRISv10 architecture (ETRAX 100LX) and glibc use the following commands:

cd ~/axis/devboard/apps/hello
make cris-axis-linux-gnu
make

The output should look something like this:

gcc-cris -isystem /home/karljope/axis/devboard/target/cris-axis-linux-gnu/include
         -mlinux -mno-mul-bug-workaround -Wall -Wshadow -O2 -g -c -o hello.o hello.c
gcc-cris -isystem /home/karljope/axis/devboard/target/cris-axis-linux-gnu/include
         -mlinux -mno-mul-bug-workaround
         -L/home/karljope/axis/devboard/target/cris-axis-linux-gnu/lib
         -Wl,-rpath-link,/home/karljope/axis/devboard/target/cris-axis-linux-gnu/lib
         hello.o -o hello

Or something like this for the CRISv32 architecture (ETRAX FS) and uClibc:

gcc_cris -mlinux -march=v32 
         -muclibc=/home/karljope/axis/devboard/target/crisv32-axis-linux-gnuuclibc
         -Wall -Wshadow -O2 -g -c -o hello.o hello.c
gcc_cris -mlinux -march=v32
         -muclibc=/home/karljope/axis/devboard/target/crisv32-axis-linux-gnuuclibc
         hello.o -o hello

To remove any existing .o-file and executable you could use the clean target. In that case type:

make clean
make

If no errors occur an executable named hello should be available in the apps/hello directory.

Create an image with the "hello" application

Now that we have successfully compiled the “Hello World!” application it is time to build an firmware image and upload it to the target system. This can be done in two different ways. Either you just install the executable manually into the target directory in ~/axis/devboard/target/, which will be used as the root directory of the compressed ROM file system image. Or you could edit one of the files in the software distribution to tell the build system that your application should be included in the ROM file system automatically when running make in root directory of the software distribution.

The manual method

Choose this method if you would like to install the executable manually. In this example it is assumed that the target system is already built once before. Assure that the build type for your application is the same as the build type of the target system, if not change the build type of your application as described above.

To add the “Hello World!” application, use the install target in the Makefile by typing:

cd ~/axis/devboard/apps/hello
make install

The hello executable will then be installed in ~/axis/devboard/target/<target type>/bin all according to the Makefile we created earlier.

Then you need to build the new firmware images, type:

cd ~/axis/devboard
make images

This will create the images that you have to flash your developer board with. Consult the flash_howto for instructions.

Note: Running make in the software distribution top-level directory creates a new target directory. This results in that manually installed applications are not included in the firmware images. As a consequence running make install must be performed for each manually added application after every time a top-level make have been performed.

The automatic method

Chose this method if you wish to create your firmware images by running make in the software distribution top-level. First, let us see how the build system works.

The top-level Makefile (~/axis/devboard/Makefile) has a variable (SUBDIRS) containing a list of applications, libraries, packages, scripts, and the Linux kernel. This variable simply lists all the source code directories in the software distribution that should be installed and included in the firmware image when running make. Adding the directory apps/hello in this SUBDIRS list is enough to make make work as desired. However, the top-level Makefile is generated. Hence, it is not recommended to edit the Makefile as it very likely will be re-generated. Instead we can add the “Hello World!” application to the SUBDIRS list by editing the configuration files used by the build system. The configure script in the software distribution root directory make use of several files to create the top-level Makefile. In this example we will edit (or create) the ~/axis/devboard/configure-files/post file which is one of these files.

NB: If you use the 2.00 release of the software distribution the support for the ~/axis/devboard/configure-files/post file is not included, instead add the content described below to the ~/axis/devboard/configure-files/devboard/devboard file.

The ~/axis/devboard/configure-files/post file is not distributed with the software distribution, so do not panic if you can not find it. Fire up your favorite text editor and add the following line to the ~/axis/devboard/configure-files/post file:

sub apps/hello

Lines like this inform the build system which source packages to fetch and unpack into the software distribution directory tree. More important to us is the knowledge that the sub command adds the file path (apps/hello) to the SUBDIRS variable. In the normal case sub will try to fetch the package from the software distribution repository but if the package already exists in the directory tree the only thing that will happen is that the package gets added to the SUBDIRS list. Read more about the sub function and other functions in the functions_guide.

After adding/modifying the configure-files/post file you should run the configure script.

./configure

To build the “Hello World!” application and the firmware images for the target system run:

cd ~/axis/devboard
make

If everything goes well the new firmware images should have been created when the make program finish. The next part step is to flash upgrade the developer board with the newly created firmware images. Consult the flash_howto for instructions.

Test the application on the target system

When the target system is upgraded with the firmware images created earlier login with telnet, ssh, or via the serial terminal and try the “Hello World!” application.

When logged in type:

hello

The output should be Hello World!

Notes

The top-level Makefile

You can find out more about the make targets by running make help in the ~/axis/devboard directory.

C++ development

You can also develop for the ETRAX 100LX using the C++ programming language and g++-cris. However you can not use uClibc in its current state.

1) A Makefile is, simply put, a file with a collection of rules for the make program.
 
axis/apps_howto.txt · Last modified: 2009/02/03 15:41 by jesper
 
All text is available under the terms of the GNU Free Documentation License (see Copyrights for details).