View source for Eclipse on Gumstix for new users

This guide provides step-by-step instructions for using the Eclipse Integrated Development Environment (IDE) to develop applications for the Gumstix COMs.

We'll walk through these tasks:
:* setting up Eclipse
:* connection to your Gumstix system
:* creating a simple "Hello, World!" Python program
:* running a web server
:* installing new packages on your Gumstix
:* creating a small graphical Java application
:* remote debugging of your Java application
:* natively-compiling C/C++ code on your Gumstix
:* remote debugging C/C++ using the GDB server interface

We will also explain how to set up a cross-compilation toolchain so you can develop C/C++ applications on your development computer and upload them to your Gumstix.

Remember, Gumstix COMs are fully-fledged, albeit tiny, Linux systems so there are many tools we don't cover here.  For example, [http://wiki.openembedded.net/index.php/OpenEmbedded_Tools_for_Eclipse_(OTE) this document] explains how to use the powerful OpenEmbedded build system within Eclipse.

Required Tools:
:* any Windows, Apple or Linux computer with a USB port
:* recent version of the Java Runtime Environment (available [http://java.sun.com/javase/downloads/index.jsp here])
:* a Gumstix COM running [http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Downloading-pre-built-images/111.html up-to-date software]
:* any expansion board of the Gumstix Overo series, such as Chestnut or Tobi, that has both a USB console port and a 10/100 
:* Ethernet jack
:* a 5V power supply
:* an ethernet cable and internet connection
:* a mini-A to Standard-A USB cable
:* a [http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Creating-a-bootable-microSD-card/111.html bootable microSD card] (only needed for native C/C++ compilation)

Key Idea:
[[File:GumstixEclipse1.jpg|thumb|right|upright=5]]

==Download Eclipse==
[http://www.eclipse.org/downloads/ Download] the Eclipse IDE for Java Developers for your Operating System: www.eclipse.org

[[Image: GumstixEclipse2.jpg | thumb | left]]

:* it is ''not'' necessary to install the Eclipse software; just double-click on the application once it has finished downloading
:* when prompted, choose a workspace folder in which you want to store your projects and your configuration information
:* then click through to the Eclipse workbench itself

==Install Plugins==
For developers, a great variety of additional features can be added to Eclipse from various repositories of plug-ins known as ''Update Sites''.
To install a new plugin in Eclipse, first select the ''Update Site''.
:* navigate to '''Help->Install New Software...'''
:* select the Update Site for your version of Eclipse from the "Work with"dropdown menu

[[File:GumstixEclipse3.jpg]]

:Note: If you are not sure which version of Eclipse you have, you can check by reopening Eclipse, it will be displayed on the loading screen.

----
Hint:
If the update site is not available, you can add it by clicking the 'Add...' button on the right. For the Galileo release, you can use the URL http://dowload.eclipse.org/releases/galileo
----

As we are working with a remote system, we'll install the Remote System Explorer plugin.
:* search for the ''Remote System Explorer End-User Runtime'' plugin
:* select it for installation

[[File:GumstixEclipse4.jpg]]

Still in Eclipse,
:* select "Next".... twice
:* select the radio button to "ACCEPT" the terms of the license agreement
:* choose "Yes" to restart Eclipse for the changes to take effect

Once Eclipse has restarted, let's add two other useful plugins that allow connection to the console port of our Gumstix without needing a terminal emulator program such as kermit or TeraTerm.
From within Eclipse,
:* navigate to '''Help->Install New Software'''
:* search on "Target" to find the ''Target Manager Terminal''

[[File:GumstixEclipse5.jpg]]

:* select the ''Target Manager Terminal''
:* click "Next"
:* click "Finish" to complete installation
:* choose "Yes" to restart Eclipse for the changes to take effect

We'll also need to add a new update site by doing these steps in Eclipse:
:* navigate to '''Help->Install New Software...'''
:* click the "Add..." button
:* type ''http://rxtx.qbang.org/eclipse'' into the ''Location'' field and create a name

[[File:GumstixEclipse6.jpg]]

:* Click the "OK" button
Go into the sub-directory as shown below to select the ''RXTX End-User Runtime'' plugin that this site provides.

[[File:GumstixEclipse7.jpg]]

:* click "Next" twice
:* select the radio button to "ACCEPT" the terms of the license agreement
:* click "OK" at the security warning window
:* click "Finish" to complete installation
:* choose the "Yes" button to restart Eclipse for the changes to take effect

==Connect Your Gumstix==
Now it is time to connect your Gumstix---let's get started by establishing a console connection.
:* mount your Gumstix COM down on to your expansion board
:* plug the mini-A USB plug into the port marked CONSOLE and end of the cable into a standard USB port on your computer
----
Hint:
Your computer should detect your Gumstix system when you first connect the USB cable, even though the power is not yet turned on. On Macintosh and Windows systems, a pop-up window should appear instructing you to download a new driver (do so) or notifying you that a USBserial device has been detected. If not, you can download drivers from [http://www.ftdichip.com/FTDrivers.htm this site]. Choose the "VCP" driver.
Once you have downloaded this driver, make sure to unplug and then replug the USB cable running from your computer to your Gumstix expansion board so the Gumstix will be recognized by your computer.
----
:* connect your Gumstix to the internet using an ethernet cable
    NOTE: You still have NOT plugged the power cable in to the 
    Gumstix expansion board! This diagram shows the locations
    of the USB 'CONSOLE' port and the 'POWER' input port on a 
    Summit board on which an Overo COM has been mounted.

[[File:GumstixEclipse8.jpg]]

:* if you are booting from a microSD card, insert this card now until you hear it click in place.
Before applying power to the board, let's open up a connection to the console port.
In Eclipse,
:* navigate to '''Window->Show View->Other->Terminal->Terminal'''
:* click on the 'N' connection icon in the window that appears

[[File:GumstixEclipse9.jpg]]

:* make the connection using the following settings:
    Connection Type: Serial
    Port: <port to which your Gumstix is connected>
    Baud Rate: 115200
    Data Bits: 8
    Stop Bits: 1
    Parity: none
    Flow Control: none
    Timeout: 5

----
Hint:
The port to which your Gumstix is connected will have a different name depending on your Host operating system.
:* On Windows, it should be ''USB-COM''
:* On Macintosh, it should be ''/dev/tty.usbserial-xxxxxxxx'' where ''xxxxxxxx'' is an arbitrary string of characters
:* On Linux, it should be ''/dev/ttyUSBx'' where ''x'' is a number.
----

[[File:GumstixEclipse10.jpg]]

----
Hint:
If this does not work, or you wish to gain Console access via a Unix Shell instead, visit the tutorial on [[Gaining Console Connection via Terminal]]
----

*Now, it's time to apply power to the Gumstix expansion board so plug the 5V wall adapter into the power input jack on the Gumstix.

You should see text appear in this window; for now, just let the Gumstix boot. When prompted, you can log in to the root account. The default credentials are:

'''Overo'''

username: root

password: <leave blank>


'''VerdexPro'''

username: root

password: gumstix

==Create a Web Site==
Each Gumstix comes with a built-in package manager called opkg. A package manager is a useful tool for installing software; you can install everything from media players to GPS mapping tools to the Firefox web browser. In this example, you'll use opkg tool to install a new application for your Gumstix: the Apache web server.

To make your own Gumstix web site, type the following in the terminal window:
    opkg update 			<Enter>
    opkg install apache2		<Enter>
Before you start using Apache, which is now running, you'll need to find the IP address (internet address) of your Gumstix COM. To do this, type the following command into the terminal window:
    ifconfig | grep 'inet addr' 	<Enter>
You should see something like this appear on your screen.
    inet addr: 10.0.1.73 Bcast: 192.168.0.255 Mask: 255.255.255.0
The IP address of your Gumstix is the first address shown: ''10.0.1.73'' in this case.
Now,
:* open up a web browser on your host computer
:* type that IP address of your Gumstix into the address bar
You should see something like this which is the default web site for Apache running on your Gumstix.

[[File:GumstixEclipse11.jpg]]

To make your web site say something more interesting, do the follow in your terminal window:
:* type: ''nano /usr/share/apache2/htdocs/index.html''
:* replace the words at the top of the screen "It Works" with the words "Gumstix Rocks!"
:* press 'Ctrl+O' <Enter>
:* press 'Ctrl+X' to save and exit
:* refresh your web browser

==Write a Java Application==
So far, you haven't actually used Eclipse other than as a console interface for your Gumstix. It is time to harness the power of Eclipse to write a small graphical Java application.
In Eclipse.
:* Navigate to '''File-> New-> Java Project''',
:* Name the project ''gumstix-java''
:* Select "Finish"
Once the project is created,
:* Select '''File->New->Class'''
:* Name your class ''Hello''
:* click "FINISH"

Add the following code to your class:

    import javax.swing.JFrame;
    import javax.swing.JLabel;
    public class Hello {
    	public static void main(String [] args) {
    		JFrame frame = new JFrame("hello");
    		final JLabel label = new JLabel("hello from Gumstix");
    		frame.getContentPane().add(label);
    		frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
    		frame.pack();
    		frame.setVisible(true);
    	}
    }

You should get something that looks like this:

[[File:GumstixEclipse12.jpg]]

Press the green run button to test drive our application on our host machine.

----
Hint:
Eclipse has many auto-completion features. Simply typing /:*<Enter> before a class creates a standard documentation block. Likewise, pressing <Ctrl>+<Space> provides context specific auto-completion options. Many other hints for speedy development are explained in the tutorials [http://www.eclipse.org/resources/?category=Getting%20Started here].
----

==Upload Code==
In Step 5 we discovered the IP address of our Gumstix. With this, we can connect to our Gumstix using the SSH protocol which allows us to rapidly transfer files. For this step, navigate to '''Window->Open Perspective->Other->Remote System Explorer''' and click on the connection icon in the ''Remote Systems'' panel on the left. Select ''SSH without shells'' as the connection type and press Next. Put the internet address you found in Step 5 into the field marked ''Host Name'' and hit finish. To test that everything is working correctly, right-click on the terminal item list under your new connection and select ''Launch Terminal''. A console interface exactly like the USB console interface we set up in Step 3 should pop up.


----
Hint:
A 'Perspective' is an arrangement of windows and widgets, that is a specific view of the Eclipse workspace, designed for a particular task. If you wish to focus on any particular widget, double click the tab in Eclipse; return to the previous view by double-clicking again.
----


By installing the VNC viewer plugin, we can get a graphical interface to our Gumstix system. Do this by adding the ''Tools for mobile linux runtime'' plugin ('''Help->Install New Software''') from the main update site. To use, select the VNC viewer widget from '''Window->Show View->Other->VNC Category->VNC''' and click on the ''New Connection'' icon in the VNC Viewer panel. Again, the ''Host'' is the internet address of your Gumstix board.

[[File:GumstixEclipse13.jpg]]

Finally, we need to upload our java code before we can run it. Switch back to the Java Perspective ('''Window->Open Perspective->Java''') and right-click on our Java file and selecting Export. Choose the option to export file to a remote file system and choose to upload your ''Hello.class'' file.

[[File:GumstixEclipse14.jpg]]

You will need to ''Browse'' to find your Gumstix board; you should upload this code to your home directory on the Gumstix.

==Debug a Java Application==
We can debug our java application remotely from Eclipse. To do this, we need a Java Virtual Machine capable of doing debugging. This time, the package we need isn't available in our package sources however we can fetch the package directly from a web site and install it using the same opkg package management tool.
    wget http://bugcommunity.com/downloads/files/phonemeadvanced- personal-debug_mr2-r1_armv6.ipk 	<Enter>
    opkg install -force-depends phoneme-advanced-personaldebug_mr2-r1_armv6.ipk <Enter>
Let's also update our Java libraries so we have access to the standard graphical libraries.
    opkg install classpath-gtk	<Enter>
Next, let's start our Java code in debugging mode on the Overo:
    java-cdc -Xdebug -Xrunjwdp:transport=dHt_socket,server=y,suspend=y,address=1234 Hello	<Enter>
Finally, let's connect to our debugging session by navigating in Eclipse to '''Run->Debug Configurations''' and double-clicking on Remote Java Application to create a new configuration. Fill in the form as shown below using the internet address found in the previous step.

==Install a native C/C++ SDK==
When we discussed Python and Java we noted that both are interpreted languages--- neither needs to be compiled. C and C++ code requires compilation which can be done natively---on the Gumstix itself---or on a development machine using a cross-compiler. To do native compilation, you need to install a compiler as well as any required libraries. You'll need to be booting from a microSD card as this installation takes approximately 75MB of space.
    $ echo 'src/gz angstrom-base http://www.angstromdistribution.org/feeds/unstable/ipk/glibc/armv7a/base'  > /etc/opkg/angstrom-base.conf
    $ opkg update
    $ opkg install task-native-sdk
Firstly, we are adding a new package repository to our package manager and updating our list of available packages before actually installing the complete package needed to do native development.

Let's create either of the following files in Eclipse, upload the code and then compile on the Gumstix using our newly installed compiler.

===C++: HelloWorld.cpp===
    #include <iostream>
    using namespace std;
    int main () {
    	cout << "Gumstix runs on C++" << endl;
    	return 0;
    }

Save the file and issue the following commands to compile and run HelloWorld.cpp
    g++ -o hello hello.cpp	<enter>
    Gumstix runs on C++   	<enter>

===C: HelloWorld.c===
    #include <stdio.h>
    int main () {
    	printf("Gumstix runs on C\n");
    	return 0;
    }

Save the file and issue the following commands to compile and run HelloWorld.c
    gcc -o hello hello.c
    Gumstix runs on C

<TODO: More exciting examples using on-board LEDs.>

==Using GDB as a remote debugger in C/C++==
These instructions will teach you how to download, install, and use the GDB debugger remotely on your Overo COM.

<pre>NOTE:	
remote system - a device that is being operated remotely (via SSH, USB Serial, etc). This means that it is a device that you are operating from a different system 
(ie: if you are accessing the Overo COM via connection with your PC, then the Overo COM is a remote system).
For the purpose of this guide, the Overo COM will be the remote system.

local host - the device that is being used to work on (ie: If you are working on your PC, that is the local host. If you then connect to another computer via VNC, 
that is a remote system, and you laptop is still the localhost).
For the purpose of this guide, your Personal Computer will be the local host.</pre>

Before starting, it is important to note there are many different ways to run a remote debugger. The most fundamental choice when debugging remotely is whether you want to:
:*Run the debugger on the remote system or
:*Run the debugger on the local host with a cross debugger on the remote system

This guide will teach you how to download, install, and run the debugger on the remote system (choice A). If you wish to learn more about the cross debugger option, use Google. Also the wikipedia article on cross compilers (which operate in a very similar fashion) is very good, albeit a bit complicated. None of this is necessary in understanding the contents of this guide. 

For the purposes of this guide, we will be using the GDB: the GNU project debugger. As stated on their website:

<pre>GDB, the GNU Project debugger, allows you to see what is going on `inside' another program while it executes -- or what another program was doing at the moment it 
crashed.

GDB can do four main kinds of things (plus other things in support of these) to help you catch bugs in the act:
- Start your program, specifying anything that might affect its behavior.
- Make your program stop on specified conditions.
- Examine what has happened, when your program has stopped.
- Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another.</pre>

While the reasons for using a debugger instead of trying to debug with the ‘brute force’ method of adding print statements throughout the entire program are enumerable, there are a few that stand out:
# The ability to ‘step’ through a program
#* The GDB debugger allows you to ‘step’ through a program. This means that instead of just executing the program and then leaving you with a final error message, it will execute one line at a time until the program crashes. This allows the user to see exactly where, and why, the program crashed. 
# The ability to set breakpoints
#* The GDB debugger allows you to set breakpoints in the program. These are points where the CPU will stop executing the code and allow the user to decide whether to continue. This allows the user to explore what is ‘going on’ at certain points in the execution, something that otherwise is not possible. 
# The ability to look at the Backtrace
#* This will show you where, and exactly why, your program crashed. Although SEGFAULT isn’t very useful, the backtrace will tell you what caused the SEGFAULT. Everything from what line, what variable, and even the address that variable was at.

===Installing the GDB===
Once the Overo COM has been connected to the local host, you should have access to the following command line:
<pre>root@overo:~#	</pre>
Although you are working on your local host, this command line is for the remote system. It is the same as if you opened up Terminal (for Mac, Linux) or XTerm (for Windows). You now have access and control of the remote system.

Now there are some packages that must be downloaded and installed onto the Overo so that it can run the GDB environment. To do this issue the following command:
<pre>opkg update	 	<enter>
opkg install gdb 	<enter></pre>
This should spew out a bunch of text such as:
<pre>Downloading http://www.angstrom...</pre>
Just let it run and once its done, you’ll have the GNU GDB debugger installed on your Overo COM.

===Creating a C/C++ Program to Debug===
Now, your Overo COM has a debugger installed and ready to use. However, this does not mean you are ready to go. There are two more things required before it is possible to use a GDB debugger.
:* A C/C++ program
:* A SDK to run the program on
To see how to install a SDK and write/run a simple program in C/C++, see [[#Install a native C/C++ SDK]]. 

Once you have a program ready, you first must create an executable file. Lets use for example the C++ program HelloWorld.cpp. To create the executable file HelloWorld, issue the following command:
<pre>g++ -o HelloWorld HelloWorld.cpp 	<enter></pre>
Now, to run the program:
<pre>./HelloWorld				<enter></pre>
To do the same thing with a C program (HelloWorld.c), issue the command
<pre>gcc -o HelloWorld HelloWorld.c		<enter></pre>
<pre>./HelloWorld				<enter></pre>

What this command does is uses the GNU compiler (either g++ or gcc) and creates an executable object (HelloWorld) out of the C or C++ program file (either HelloWorld.cpp or HelloWorld.c). You may name the executable whatever you like, but it is considered best practice to name it the same thing as the program file.

===Debugging the Program===
Now that you have GDB installed and a C/C++ program ready to go, its time to debug. To open to GDB environment, run the following command
<pre>gdb						<enter></pre>
Some text should spit out, and the following command line should appear
<pre>(gdb)</pre>
Now that the debugger is running, it is time to tell the debugger what program we want to debug. To do this, first we need to declare our HelloWorld file as an executable file. For this run the following command	
<pre>(gdb) exec-file HelloWorld		<enter></pre>
Now that we have an executable file ready to be debugged, its time to run the program
<pre>(gdb) run HelloWorld			<enter></pre>
The debugger will now run your program. If the program has no syntax or logic errors, the program should run and end with the line:
Program exited normally.
If there are errors, or the program crashed, it is possible to extract the exact details of that crash  by issuing the back trace command.
<pre>(gdb) bt			<enter></pre>
Once you are done you can quit by issuing the command:
<pre>(gdb) quit			<enter></pre>

A complete list of commands in GDB:
www.yolinux.com/TUTORIALS/GDB-Commands.html

====GDB Debugger Tutorial====
For a complete GDB Debugger tutorial (very good tutorial, comes with sample code they walk you through and extra errors for you to debug yourself!):
http://www.cs.cmu.edu/~gilpin/tutorial/

Now you have a debugger up and running! Play around with it by putting errors into your program on purpose to see the powers of having a remote debugger!

==Use a C/C++ cross-compiler==
In order to do C/C++ development on our host machine, we need to add in a plugin to Eclipse. Also, we need to download an appropriate cross-compilation toolchain. For now, I recommend the lovely instructions from

http://www.designarm.com/quickstart-guide/linux-software/eclipse.html &

http://www.bugcommunity.com/wiki/index.php/BUG_Kernel_Development_with_Eclipse

==Further Reading==
===Internal===
[[Gaining Console Connection via Terminal]]<br>
[[HelloWorld | HelloWorld in Python, C and C++]]<br>
[[Remote Debugging with GDB]] <br>
[[HelloWorld in Java]]

===External===
:* Tutorials built into Eclipse
:* Bitbake commander
:* OpenEmebedded|Poky docs + Bitbake docs
:* Eclipse Plugin Tutorial




















[[Category:How_to_-_eclipse]]