Using EMAC OE SDK Example Projects

From wiki.emacinc.com
Revision as of 22:40, 1 October 2013 by Mdean (talk | contribs)
Jump to: navigation, search
TODO: {{#todo:Make sure there is an OE 4 and OE 5 version; OE 5 will use CMake|Michael Gloff|oe 4,oe 5,mg}}
Table 1: Conventions
/download/directory/ The directory to which the SDK archive will be downloaded.
/path/to/sdk/ The directory to which the SDK will be extracted.
EMAC-OE-arm-linux-gnueabi-SDK_XX.YY.rZZ.tar.bz2
EMAC-OE-arm-linux-gnueabi-SDK_XX.YY 		XX - the SDK major version
YY - the SDK minor version
ZZ - the SDK current revision
target_program The program executable created to run on the target device. 
developer@ldc:~$
Prompt and commands to be run on a development machine that will run compliation tasks. 
root@emac-oe:~#
Prompt and commands to be run on a target machine.

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. NOTE: 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 two example files, a C file and a Makefile. They are 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 FTP capability to the build process.

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 who are looking to learn the EMAC SDK. 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. 

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

all is a make target. This command is the equivalent to the commonly seen, Build All command found in most IDE's. The build system will only compile files which have been modified since the last build.

Alternatively, you can simply run: 

developer@ldc:~$ make

When make is run by itself, it chooses its default make target. In this example, all is the default make target. In any normal project, the default make target will be the one which builds the project. This allows a programmer to simply run make most of the time they are doing development work.

The Makefile based build system fully supports incremental builds. Should you desire a full rebuild, two steps will need to be followed instead of one: 

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

The make clean command will delete any object files (these have the .o extension in the gcc on Linux build system), 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 how gcc approaches the incremental 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 variables stored in the global.properties file, which is included in the Makefile using the include keyword. 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. Run the program as shown in Listing 1 using the remote connection. 

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. Note that this assumes that you are logged in as the system root user.
/tmp/hello runs the program without any arguments.
NOTE: If you wish to run a program located in your current directory, you must run it as ./hello. Without the ./ prefix, the program will not be run by the shell. The shell will only look for a program in the default search PATH, unless the program's name is prefixed with a specific path. The ./ prefix is a relative path. The . represents the current directory, just as .. represents the previous directory. The / following the . indicates to the shell to look inside the current directory. In POSIX systems, such as Linux, filenames can have a . as their first character, which is why the / is needed. Incidentally, a . as the first character of the filename indicates that the file is hidden. Use the ls -a command to see such files.

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. Here is a brief description of this Makefile to help you get started.
  • The include command tells make to pull in the file specified in a way similar to the C/C++ #include preprocessor directive.
  • The TARGET= directive tells make the name and location it should use for any executable binaries or shared object binaries (shared objects are similar to Windows .dlls) 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, because CC is so defined in the global.properties file included by this Makefile. 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. This is similar to the way many scripting languages work, and hopefully will feel pretty natural to any developer working with Makefiles for the first time.
NOTE: This is a simple, basic Makefile which can be extended as needed to support many projects. Should your build requirements become complex, more sophistication may be required. A build system builder may be the tool you need. If this becomes necessary, options you may wish to consider include:
  • Buy a good book on make and learn the system thoroughly.
  • Adopt a build system builder tool. CMake has proven to be popular for many large projects, and is simpler to use than autotools. Buying a book on the build system builder tool chosen may prove wise.
  • The build system builder in Eclipse may be able to handle the complexity of your requirements. This is probably the simplest option.
NOTE: Build system builder refers to a tool which generates a set of scripts and/or Makefiles which are then used to build a project.

Next Steps

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

Retrieved from "https://wiki.emacinc.com/index.php?title=Using_EMAC_OE_SDK_Example_Projects&oldid=679"