Difference between revisions of "Creating a New EMAC OE SDK Project"

From wiki.emacinc.com
Jump to: navigation, search
m (Marked for review.)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{todo|Review (11.26.13-20:35->MD+)|Mike Dean|project=oe 4,oe 5,md,Review,ky}}
+
{{todo|SEOKWREV (11.26.13-20:35->MD+);(11.27.13-15:20-KY+);(12.5.13-18:20-MG+);(03.04.14-16:20->BS-);(03.20.14-15:45->BS+);(04.14.14-14:40->BS+)|Mike Dean|project=oe 4,oe 5,md,SEOKWREV,ky,mg,bs}}
 +
 
 +
{{#seo:
 +
|title=Creating a New EMAC OE SDK Project
 +
|titlemode=append
 +
|keywords=Create EMAC SDK Project,Set Up EMACK Project
 +
|description=EMAC OE SDK is a complete development kit for creating C/C++ applications for EMAC products.
 +
}}
  
 
{{EMAC OE SDK Conventions}}
 
{{EMAC OE SDK Conventions}}
Line 11: Line 18:
 
===Set Up the Project===
 
===Set Up the Project===
  
−
The first step in creating an EMAC OE project is creating a project directory in <code>/path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects</code>.
+
The first step is to create a project directory in <code>/path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects</code> directory.
  
−
<syntaxhighlight lang="bash">
+
<syntaxhighlight lang="console">
 
developer@ldc:~$ mkdir /path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/example
 
developer@ldc:~$ mkdir /path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/example
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Creating the project in this directory is necessary in order for the <code>global.properties</code> include and the path variables in global.properties to be correct. If it is created in any other directory, then the make targets will fail without modifications on the Makefile that go beyond the scope of this guide.
+
 
 +
{{mbox | type=information | style = margin-bottom: 1em; | text = This directory is recommended to allow the user to easily leverage the use of the SDK. See the section below for [[Creating_a_New_EMAC_OE_SDK_Project#Alternate Project Locations | alternate project locations]].}}
  
 
===Write the C Code===
 
===Write the C Code===
  
−
This guide uses the C code from Listing 1 as an example. It is simple enough that the basic familiarity with C expected of those viewing this guide precludes the need for explanation. As a general step in application development using the EMAC OE SDK, the C files in this step should be saved in the project's top-level directory. In this case, <code>example.c</code> should be saved as <code>/path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/example/example.c</code>.
+
The C code for this example is listed below. Copy the code into a blank document and save as <code>example.c</code> in the project directory created above.
  
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
Line 49: Line 57:
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
'''Listing 1. example.c'''
  
 
===Modify the Makefile===
 
===Modify the Makefile===
 +
 +
Makefiles are used to tell the compiler what actions to perform. Makefiles are useful so that the developer does not have to remember a long list of compile options and source files that need to be compiled.
  
 
====Create the New Makefile====
 
====Create the New Makefile====
  
−
Now that the C file has been written, it is time to copy a suitable Makefile from one of the example projects. The following command will accomplish this:  
+
The EMAC OE SDK provides a very basic Makefile that can be used for new projects and extended as needed. Navigate to the hello project in the SDK projects and copy the Makefile file to the current project directory. Or from the command line type:
  
−
<syntaxhighlight lang="bash">
+
<syntaxhighlight lang="console">
 
developer@ldc:~$ cd /path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/example/
 
developer@ldc:~$ cd /path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/example/
 
developer@ldc:~$ cp ../hello/Makefile ./
 
developer@ldc:~$ cp ../hello/Makefile ./
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
====Tell the Makefile What Files to Compile====
 
  
−
The project is almost ready to be compiled. However, there are a few lines in the Makefile which must be modified before this can happen. First, the <code>CFILES</code> and <code>TARGET</code> variables in the Makefile must be modified to suit this project:  
+
====Configure What Source Files to Compile====
 +
 
 +
Open the Makefile in a text editor and modify the <code>CFILES</code> and <code>TARGET</code> variables as follows:  
  
 
* <code>CFILES=example.c</code> instead of <code>CFILES=hello.c</code>
 
* <code>CFILES=example.c</code> instead of <code>CFILES=hello.c</code>
 
* <code>TARGET=example</code> instead of <code>TARGET=hello</code>
 
* <code>TARGET=example</code> instead of <code>TARGET=hello</code>
  
−
This tells the Makefile that the source file used is <code>example.c</code>. This variable can be assigned a space-delimited list of C files. In the example there is only one file so this is not a concern.  
+
This tells the Makefile that the source file used is <code>example.c</code> and the resulting executable will be called <code>example</code>. The CFILES variable can be assigned a space-delimited list of C files for larger projects.
  
−
====Tell the Makefile What Libraries to Link====
+
====Configure Libraries to Link====
 +
 
 +
In order to use the trigonometric functions present in the source file, the math library must be included. To include the math library in the compilation process, add it to the LIBFLAGS variable on the line below CFILES.
  
−
The last change that must be made to this Makefile is that we need to modify <code>LIBFLAGS</code> to reflect the use of the math library for the trigonometric functions in the C file. The math library is <code>libm.so</code>; therefore, we use <code>-lm</code> to indicate to the linker to link <code>libm</code> to the binary. If the library for readline were needed, instead, this would be specified with <code>-lreadline</code> to link <code>libreadline.so</code> Add the following line to the Makefile:
 
 
* <code>LIBFLAGS+=-lm</code>
 
* <code>LIBFLAGS+=-lm</code>
  
−
Where in the Makefile this line is added does not matter, though it makes sense to group it with the other variable declarations.  
+
The math library is <code>libm.so</code>. Other libraries may need to be included in custom projects that make use of advanced functions.
 +
 
 +
{{mbox | type = notice | text = More detailed information on working with libraries and the linker under Linux can be found at [http://www.yolinux.com/TUTORIALS/LibraryArchives-StaticAndDynamic.html YoLinux - Static, Shared Dynamic and Loadable Linux Libraries]}}
  
−
{{mbox | type = notice | text = Much more detailed information on working with libraries and the linker under Linux can be found at [http://www.yolinux.com/TUTORIALS/LibraryArchives-StaticAndDynamic.html YoLinux - Static, Shared Dynamic and Loadable Linux Libraries]}}
 
  
 
Listing 2 shows the complete modified makefile for the <code>example.c</code> project.
 
Listing 2 shows the complete modified makefile for the <code>example.c</code> project.
Line 119: Line 133:
 
===Cross-Compile with the EMAC OE SDK===
 
===Cross-Compile with the EMAC OE SDK===
  
−
Now it is time to use GNU make to compile the example source code into an application that can be run on the target machine. Makefile-based development with the EMAC OE SDK is a powerful tool which enables the customer to compile code for the target EMAC product on the Linux development machine. Once a project has been set up as described above, development can begin using the GNU make targets as described below.
+
Using the Makefile created above, the GNU make utility will be used to compile the example source code into an application that can be run on the target machine.  
−
 
+
Change into the example project directory then execute the make targets as shown in Listing 3. For a description of each make target, read the bullet items below.
−
First, set the current directory to the one containing the Makefile, then execute the make targets as shown in Listing 3. For a description of each make target, read the bullet items below.
 
  
 
<syntaxhighlight lang="console">
 
<syntaxhighlight lang="console">
Line 150: Line 163:
 
'''Listing 3. Example Make Target Invocation'''
 
'''Listing 3. Example Make Target Invocation'''
  
−
* <code>make clean</code> removes all object, dependency, and executable files generated by previous invocations of make. It literally “cleans” the directory as shown in Listing 1, Target 1.
+
 
−
* <code>make all</code> resolves dependencies for the source code necessary to cross-compile the target file. The <code>gcc</code> and <code>g++</code> binaries used are specified in <code>global.properties</code> as relative paths to the <code>/path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/example/</code> directory. This is why the source files must be kept in their own directory within <code>/path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects</code>. Listing 1, Target 2 demonstrates a successful <code>make all</code> invocation.
+
* <code>make clean</code> removes all object, dependency, and executable files generated by previous invocations of make.
 +
* <code>make all</code> resolves dependencies for the source code necessary to cross-compile the target file and creates the target program provided there are no errors in the source code. The <code>gcc</code> and <code>g++</code> compilers used are specified in <code>global.properties</code>.
 +
* <code>make upload</code> uses ftp to transfer the executable file to the target device. The username and password used to connect to the target device are stored in <code>global.properties</code>
  
 
===Optional global.properties Modifications===
 
===Optional global.properties Modifications===
Line 157: Line 172:
 
In order to debug applications effectively, the <code>-g</code> debug flag must be specified when running the compiler. This is set up to occur automatically by its inclusion in the <code>global.properties CFLAGS</code> variable.
 
In order to debug applications effectively, the <code>-g</code> debug flag must be specified when running the compiler. This is set up to occur automatically by its inclusion in the <code>global.properties CFLAGS</code> variable.
  
−
For release builds, however, this can be harmful to the application's performance since keeping the debug symbols in the executable bloats its size. In a typical general-purpose computer this may not be noticeable, but for embedded systems there are typically memory and disk limitations. For production or release versions of an application EMAC recommends modifying the <code>global.properties CFLAGS</code> variable to replace <code>-g</code> with <code>-g0</code> which tells the compiler not to include debug information in the executable.
+
For release builds, however, this can be harmful to the application's performance. In a typical general-purpose computer this may not be noticeable, but for embedded systems there are typically memory and disk limitations. For production or release versions of an application it is recommended to replace <code>-g</code> with <code>-g0</code> which tells the compiler not to include debug information in the executable.
  
−
Using the <code>file</code> command:
+
To get information about a particular file, use the <code>file</code> command:
  
 
<syntaxhighlight lang="console">
 
<syntaxhighlight lang="console">
Line 165: Line 180:
 
myexecutable: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.14, not stripped
 
myexecutable: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.14, not stripped
 
</syntaxhighlight>
 
</syntaxhighlight>
−
Will tell you if debugging information is available within the executable. If you see, <code>not stripped</code>, that means debugging symbols are in the binary. If you wish to remove them without using a release target build, you can use the <code>strip</code> command:
+
 
−
<syntaxhighlight lang="bash">
+
The stripped/not stripped field of the output tells weather the executable contains debugging symbols. Debugging symbols can be removed from an executable without recompiling using the <code>strip</code> command:
 +
 
 +
<syntaxhighlight lang="console">
 
developer@ldc:~$ strip myexecutable
 
developer@ldc:~$ strip myexecutable
 
</syntaxhighlight>
 
</syntaxhighlight>
−
If you see no output after running that command, you may assume the command succeeded (this is default behavior upon successful completion of an operation for most Unix and Linux tools). In order to make sure it succeeded, you can run the file command on it again:  
+
 
 +
To verify that the executable was stripped, run <code>file</code> again:
 +
 
 
<syntaxhighlight lang="console">
 
<syntaxhighlight lang="console">
 
developer@ldc:~$ file myexecutable
 
developer@ldc:~$ file myexecutable
Line 175: Line 194:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
The output above shows, stripped, which tells us the <code>strip</code> command succeeded in removing debugging symbols from the binary.
+
 
 +
==Alternate Project Locations==
 +
If the project is created outside of the /path/to/sdk/projects directory, the paths present in the Makefile and the path to the SDK in the global.properties files will need to be modified as below.
 +
 
 +
<cl>
 +
 
 +
1. Copy the correct ''global.properties'' file from the ''SDK/projects'' directory to the current project directory
 +
 
 +
<syntaxhighlight lang="bash">
 +
developer@ldc:~$ cp -L /path/to/sdk/projects/global.properties /path/to/project/hello
 +
</syntaxhighlight>
 +
 
 +
* Modify the ''include'' line at the top of the make file to refer to the new ''global.properties'' file
 +
<syntaxhighlight lang="console">
 +
include global.properties
 +
</syntaxhighlight>
 +
 
 +
* Change the value of <code>SDKBASE</code> in ''global.properties'' to point to the location of the SDK installation.
 +
 
 +
</cl>
  
 
==Next Steps==
 
==Next Steps==
  
−
Once the target binary has been compiled, the project is ready to be debugged.  
+
Once the target binary has been compiled, the project is ready to be executed and debugged.  
  
−
{{mbox | type = notice | text = Useful tools related to this article:
+
[[Remote_Debugging_EMAC_OE_SDK_Projects_with_gdbserver | Remote Debugging with gdbserver ]]
−
* <code>make</code> - Automates builds
 
−
* <code>ld</code> - The linker
 
−
* <code>ldd</code> - Displays shared library dependencies for a binary executable.
 
−
* <code>strip</code> - Removes debugging symbols from a binary executable.
 
−
* <code>gdb</code> - The GNU Debugger. Often used indirectly through the Eclipse IDE interface.
 
−
* <code>file</code> - Command which displays information about a file passed to it as an argument. Useful for determining whether debugging information has been stripped from a binary executable, among other things.
 
−
}}
 
  
−
[[Category:EMAC OE SDK]]
+
<!--[[Category:EMAC OE SDK]]-->

Latest revision as of 13:41, 14 April 2014

TODO: {{#todo:SEOKWREV (11.26.13-20:35->MD+);(11.27.13-15:20-KY+);(12.5.13-18:20-MG+);(03.04.14-16:20->BS-);(03.20.14-15:45->BS+);(04.14.14-14:40->BS+)|Mike Dean|oe 4,oe 5,md,SEOKWREV,ky,mg,bs}}

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 a complete development kit for creating C/C++ applications for EMAC products. The SDK can be used to compile code anywhere in the development system. This procedure explains the process of creating and building a new project within the SDK.

New Project Procedure

This guide assumes that the EMAC OE SDK has been installed and configured. It also assumes a basic familiarity with the C programming language and that a basic text editor is available. The example code calculates the perimeter of a right triangle given the length of its longest edge and the angle between that edge and one of the other edges.

Set Up the Project

The first step is to create a project directory in /path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects directory. 

developer@ldc:~$ mkdir /path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/example


This directory is recommended to allow the user to easily leverage the use of the SDK. See the section below for alternate project locations.

Write the C Code

The C code for this example is listed below. Copy the code into a blank document and save as example.c in the project directory created above. 

#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
 
#define HYP 10.0
#define DEG 30.0
 
 
int main(void)
{
	float opp, adj;
 
	opp = HYP * sin(DEG);
	adj = HYP * cos(DEG);
 
	printf("Hypotenuse: \t%3.2f\n", HYP);
	printf("Angle: \t\t%3.2f\n", DEG);
	printf("Opposite Side: \t%3.2f\n", opp);
	printf("Adjacent Side: \t%3.2f\n", adj);
	printf("%3.2f + %3.2f + %3.2f = %3.2f \n", HYP, opp, adj, (HYP + opp + adj));
 
	exit(EXIT_SUCCESS);
}

Listing 1. example.c

Modify the Makefile

Makefiles are used to tell the compiler what actions to perform. Makefiles are useful so that the developer does not have to remember a long list of compile options and source files that need to be compiled.

Create the New Makefile

The EMAC OE SDK provides a very basic Makefile that can be used for new projects and extended as needed. Navigate to the hello project in the SDK projects and copy the Makefile file to the current project directory. Or from the command line type: 

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


Configure What Source Files to Compile

Open the Makefile in a text editor and modify the CFILES and TARGET variables as follows:

  • CFILES=example.c instead of CFILES=hello.c
  • TARGET=example instead of TARGET=hello

This tells the Makefile that the source file used is example.c and the resulting executable will be called example. The CFILES variable can be assigned a space-delimited list of C files for larger projects.

Configure Libraries to Link

In order to use the trigonometric functions present in the source file, the math library must be included. To include the math library in the compilation process, add it to the LIBFLAGS variable on the line below CFILES.

  • LIBFLAGS+=-lm

The math library is libm.so. Other libraries may need to be included in custom projects that make use of advanced functions.

More detailed information on working with libraries and the linker under Linux can be found at YoLinux - Static, Shared Dynamic and Loadable Linux Libraries


Listing 2 shows the complete modified makefile for the example.c project. 

include ../global.properties
 
TARGET=example
CFILES=example.c
 
LIBFLAGS+=-lm
 
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 2. Modified Example Makefile


Cross-Compile with the EMAC OE SDK

Using the Makefile created above, the GNU make utility will be used to compile the example source code into an application that can be run on the target machine. Change into the example project directory then execute the make targets as shown in Listing 3. For a description of each make target, read the bullet items below. 

developer@ldc:~$ cd /path/to/sdk/EMAC-OE-arm-linux-gnueabi-SDK_XX.YY/projects/example/
#### Target 1 ####
developer@ldc:~$ make clean 
rm -f *.o *.gdb example example.d

#### Target 2 ####
developer@ldc:~$ make all 
../../gcc-4.2.4-arm-linux-gnueabi/bin/arm-linux-gnueabi-gcc  -Wall -MMD -g -march=armv5te -mtune=arm926ej-s -o example.o -c example.c\
../../gcc-4.2.4-arm-linux-gnueabi/bin/arm-linux-gnueabi-gcc  example.o  -lm  -o example

#### Target 3 ####
developer@ldc:~$ make upload 
wput --reupload --dont-continue sentence ftp://root:emac_inc@10.0.2.41/../../tmp/example
--16:52:48-- `app_name'
    => ftp://root:xxxxx@10.0.2.41:21/../../tmp/example
Connecting to 10.0.2.41:21... connected!
Logging in as root ... Logged in!
Length: 13,774
 
16:52:48 (example) - `350.6K/s' [13774]
 
FINISHED --16:52:48--
Transfered 13,774 bytes in 1 file at 107.3K/s

Listing 3. Example Make Target Invocation


  • make clean removes all object, dependency, and executable files generated by previous invocations of make.
  • make all resolves dependencies for the source code necessary to cross-compile the target file and creates the target program provided there are no errors in the source code. The gcc and g++ compilers used are specified in global.properties.
  • make upload uses ftp to transfer the executable file to the target device. The username and password used to connect to the target device are stored in global.properties

Optional global.properties Modifications

In order to debug applications effectively, the -g debug flag must be specified when running the compiler. This is set up to occur automatically by its inclusion in the global.properties CFLAGS variable.

For release builds, however, this can be harmful to the application's performance. In a typical general-purpose computer this may not be noticeable, but for embedded systems there are typically memory and disk limitations. For production or release versions of an application it is recommended to replace -g with -g0 which tells the compiler not to include debug information in the executable.

To get information about a particular file, use the file command: 

developer@ldc:~$ file myexecutable
myexecutable: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.14, not stripped

The stripped/not stripped field of the output tells weather the executable contains debugging symbols. Debugging symbols can be removed from an executable without recompiling using the strip command: 

developer@ldc:~$ strip myexecutable

To verify that the executable was stripped, run file again: 

developer@ldc:~$ file myexecutable
myexecutable: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.14, stripped


Alternate Project Locations

If the project is created outside of the /path/to/sdk/projects directory, the paths present in the Makefile and the path to the SDK in the global.properties files will need to be modified as below.


  1. Copy the correct global.properties file from the SDK/projects directory to the current project directory 

    developer@ldc:~$ cp -L /path/to/sdk/projects/global.properties /path/to/project/hello

  2. Modify the include line at the top of the make file to refer to the new global.properties file 

    include global.properties

  3. Change the value of SDKBASE in global.properties to point to the location of the SDK installation.


Next Steps

Once the target binary has been compiled, the project is ready to be executed and debugged.

Remote Debugging with gdbserver


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