Executing Remote Applications with Eclipse

TODO: {{#todo:Polish this and mark it as OE 4|Michael Gloff|oe 4,mg}}

Table 1: Conventions
connection_name	Refers to the name of the connection used to connect to the target board.
app_name	Refers to the target name of the application being developed.
target_board	Refers to the name of the device for which the application is being developed.

Remote development using Eclipse is enhanced with tools such as the Eclipse Run/Debug Configurations and SSH which enable the remote execution of the application on the remote board. The Eclipse Run/Debug Configurations provide a way to transparently run an application on the remote board by automatically uploading the binary, changing execute permissions, executing, and interacting with the application using an SSH Shell.

Setup

Before continuing, ensure that Eclipse is open to the C/C++ or Qt C++ perspective.

1. Open EMAC Eclipse
2. Click Window -> Open Perspective -> Other...
3. Select C/C++ or Qt C++ (if developing a Qt application)
4. Click OK

Create a Run Configuration

Launching an application from within Eclipse requires that a Run Configuration be created. This configuration provides Eclipse all the information it needs to be able to run a specific application. The application can be located either on the development machine or on the target machine provided a suitable connection is available. The following procedure assumes that the application being run is located on a remote target machine. This will be the case for all application development for EMAC products.

1. Create a new launch configuration
   1. In the Project Explorer View, right-click the project to be run
   2. Select Run As -> Run Configurations... to bring up the Run Configuration Dialog.
   3. In the Type List, right-click C/C++ Remote Application and select New... from the context menu. A new configuration will appear with the Name: equal to the name of the currently open project. This name can be changed by editing the Name: field.
2. For instructions relating to fields in the main tab, refer to Figure 1 below.
   

   Figure 1: Run / Debug Configuration Main Tab
   1. Choose a connection from the Connection: drop-down menu or click New... to create a new one.
   2. The default for the Project: field will be the currently-active project. If this is not set to the project that you wish to run, click Browse... to choose the correct one.
   3. Choose a C/C++ Application: value by manually typing the app_name with path hierarchy into the field, using the Search Project... dialog to search the current project, or manually browsing for the application using the Browse... button.
   4. Choose a Remote Absolute File Path for C/C++ Application: value. Note that this location must be writable on the target board. EMAC recommends using the /tmp directory for initial application testing, as this location is linked to a ramdisk and avoids unnecessary writes to the flash. Type the desired location in the provided text field, or select Browse... to search the remote filesystem for the target binary. Note that this step requires that the Connection: field is set to a valid connection and the development machine is connected to the target board.
3. For instructions relating to the Arguments tab, refer to Figure 2 below.
   

   Figure 2: Run / Debug Configuration Arguments Tab
   If app_name takes any command-line arguments, they must be entered on the arguments tab. To avoid having to come back to this screen each time the arguments change, it is possible to use special Eclipse variables to specify the arguments, as described below:
   1. Click Variables... to open the Select Variable dialog.
   2. Choose a variable either by searching for it using the search input field at the top of the dialog or scrolling manually through the available variables.
   3. Click Edit Variables... to create a new variable or edit a user-modifiable variable.
   4. Many of the default variables have values that change depending on the arguments given in the Select Variable dialog. Some, such as those whose values are expected to be locations in the filesystem, can be configured with an additional dialog. To do so, click Configure....

Running the Remote Application

Using the Eclipse Run Menu to run a remote application can be done from the RSE, C/C++, Qt C++, or Debug perspectives. To run the application using the configuration created in the instructions above, follow the steps below:

1. Open Eclipse to the RSE, C/C++, Qt C++, or Debug perspective.
2. Click Run -> Run Configuration....
3. Double-click the launcher configuration created in the instructions above.

The application will be uploaded to the target board and executed. All program output will be displayed in the Console view in Eclipse.

Next Steps

The remote application debugging process is very similar to the remote Run configuration. Continue with the Eclipse Remote Debugging guide.