Using EMAC OE SDK Example Projects

TODO: {{#todo:Polish(11.26.13-22:36->MG+)|Michael Gloff|oe 4,mg,ky,Review}}

The EMAC OE SDK is distributed with a set of example projects intended to demonstrate how to use the EMAC OE toolchain and libraries. This guide demonstrates the process of compiling one of the example projects and running it on the target machine. It is assumed that the procedure in the EMAC OE SDK Configuration Guide has been followed prior to reading this page.

This guide consists of a simple hello.c source file and a Makefile build file located within Listing 2 and Listing 3, respectively.

Tools

• GNU make. Manages project dependencies.
• EMAC OE SDK. [See the EMAC OE SDK Install Page].
• wput, Provides file transfer (FTP) capability.

EMAC SDK Example: Compile the "hello" Project

This procedure provides an overview of how to compile and run C applications for EMAC products. It assumes familiarity with the C programming language and is intended to be used by experienced programmers. The “hello” example project source can be found in the projects/ subdirectory of the EMAC OE SDK root directory. The full path to the source is as follows:

/path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/hello/

Cross-compile the program using GNU Make. From the terminal prompt type:

developer@ldc:~$ cd /path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/hello/
developer@ldc:~$ make all

The file Makefile specifies what Make targets are available and what actions should be performed for each target. all is a make target that directs Make to compile all source files for the project. This command is the equivalent to the Build All command found in most IDE's. The build system will only compile files which have been modified since the last build.

The Makefile based build system fully supports incremental builds. If a full rebuild is required, issue the following two commands.

developer@ldc:~$ make clean
developer@ldc:~$ make

The make clean command will delete any object files (with the .o extension), debugger information files (with the .gdb extension), executable binaries (generally, no extension) and any other files which are generated during the build process. Once this cleaning step is complete, the build system will attempt to rebuild everything.

For a more in-depth explanation on the gcc build process, see the GNU "make" Manual.

EMAC SDK Example: Uploading and Running the "hello" Project"

Uploading the Program to the Target Machine

developer@ldc:~$ make upload

upload is another make target. This command will send your freshly compiled binary to the target machine.

This Make target uses the development system's wput program to send the binary to the target machine through FTP. This is accomplished using the TARGET_IP, LOGIN, and PASSWORD variables stored in the global.properties file. The global.properties file also contains variables which Make passes to the compiler to ensure that the executable produced is compatible with the target CPU architecture.

Running the Program on the Target Machine

Connect remotely to the target machine using SSH and run the program as shown below.

developer@ldc:~$ ssh root@TARGET_IP
...
root@emac-oe:~# chmod u+x /tmp/hello
root@emac-oe:~# /tmp/hello

Listing 1. Running the Remote Application

• chmod u+x sets the root user's permissions to allow execution of the binary.
• /tmp/hello runs the program without any arguments.

If the file compiles without trouble but has runtime bugs, you can remotely debug the application using gdbserver. Read the EMAC OE SDK Remote Debugging Guide to learn more.

Example C File

This C file can be used by programmers as an example to ensure their build configuration for EMAC products is functioning correctly.

/**
 * @file hello.c
 *
 * Simple Hello World application for EMAC OE.
 *
 * @author EMAC, Inc. <support@emacinc.com>
 */
/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
 
#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    printf("Hello EMAC OE!\n");
    exit(EXIT_SUCCESS);
}

Listing 2. "Hello World" example project

Example Makefile

Listing 3 shows the default Makefile used for the hello example project. This is a necessary component of the EMAC SDK which directs GNU Make in resolving source code dependencies before calling the cross-compiler to create a binary for the target platform. It also provides a convenient upload target which utilizes the development system's wput command to send the compiled binary to the target system.

include ../global.properties
 
TARGET=hello
CFILES=hello.c
 
 
OBJS=$(CFILES:.c=.o)
DEPS=$(OBJS:.o=.d)
 
all: $(TARGET)
 
$(TARGET): $(OBJS) Makefile
  $(CC) $(VERBOSE) $(OBJS) $(OFLAGS) $(LIBFLAGS) $(SLIBS) -o $@
 
%.o: %.c
  $(CC) $(VERBOSE) $(CFLAGS) -o $@ -c $<
 
clean:
  $(RM) *.o *.gdb $(TARGET) $(DEPS)
 
upload: all
  $(WPUT) $(TARGET) ftp://$(LOGIN):$(PASSWORD)@$(TARGET_IP)/../../tmp/$(TARGET)
 
 
-include $(DEPS)

Listing 3. Example EMAC OE SDK Makefile

NOTE: Using the documentation for GNU make will be required to gain a solid understanding of the build system. Following is a brief description of this Makefile.

• The include command tells make to also look at the file specified for variable definitions.
• The TARGET= directive tells make the name and location it should use for any executable binaries or shared object binaries it produces.
• The CFILES= directive tells make the names of the C source files it needs to build.
• The OBJS= and DEPS= directives tell make how to produce file names for the object and dependency files it generates. This file specifies a method for these which will work for most projects, and is unlikely to need modification.
• all: specifies the make target named “all.” clean: and upload:, similarly, specify the make targets for targets of these names, respectively. New make targets can be given names this way. make will perform all the steps listed after the target name until it encounters another target name.
• The CC variable refers to the gcc command defined in the global.properties file. The $(CC) syntax tells make to read the value of the variable, CC, and replace $(CC) with the value of CC prior to attempting to execute the command.

Next Steps

After compiling and running an example project, the next step is to create a new project from scratch. The EMAC OE SDK New Project Guide details this process from start to finish.