Working with the Plug-in

Workbench Integration

Creating a Builder configuration and then launching the Builder with that configuration is very similar to launching a Java application, applet or external tool. Therefore the plug-in follows the Eclipse Launch Framework used to launch any kind of application. This framework consists of user interfaces (toolbar button and dialog) and an API for plug-in development to manage and launch such configurations. In order to define how to download and execute an application on the target system, a type of configuration needs to be created too. And because these tasks need to be performed by another application, the launch framework is used here as well. General settings in Eclipse are done in so called "Preference Pages". JamaicaVM Plug-in specific settings, e.g. directory of the Jamaica installation, can be set in this a page.

Visual elements added to the workbench

The plug-in adds two new pulldown buttons to the toolbar. They are placed into the Run/Debug group. The plug-in's UI are launch configuration dialogs (LCD). In Eclipse, this type of dialog is used to manage configurations that will launch Java applications, applets or external tools. The left button (with the JamaicaVM logo) launches configurations of the JamaicaVM Builder. The second button launches configurations to download and execute applications that where built with the JamaicaVM Builder.

Eclipse IDE Workbench with the JamaicaVM Plug-in toolbar buttons

The next two sections explain how to use these two dialogs.

Note: The plug-in works in conjunction with Java projects. To follow these instructions, it is best to set up a sample Java project with a Hello World application.

Builder Launch Configuration Dialog

Open the dialog by clicking on the button's arrow and selecting Jamaica Builder.... A history of the recent launches will automatically be added to the menu of this pulldown button. On the left side of the LCD, a list with available configurations is displayed. At beginning, this list is empty since no new configuration was created. Select the configuration type JamaicaVM Builder and click on New.... A new configuration is created and is shown appears in the list. The plug-in set values for the input fields Project and Main Class. They only are set if a Java element was selected when opening this dialog. Java elements can be an open file in the editor, a selected Java file or package in the Package Explorer view of the Java Perspective. In the dialog area, a set of tabs are shown.

JamaicaVM Builder Launch Configuration Dialog

Two levels of tab folders structure the options. In the outer level, there is one tab for the global options and one for each available target. This is your host platform and your target(s) (e.g. linux-gnu-i686 and vxworks-i686). Each of these outer tab folders contain an inner folder with several tab items containing the JamaicaVM Builder options. To organize these options, they have been grouped in those tabs. For new configurations, default values for the host and targets are taken from the JamaicaVM configuration file <JAMAICA>/etc/jamaica.conf. If not already done, the first thing in every new configuration is to define the main class of the application. Go the the tab global->General. Click on Search... to get a list of all classes with main types in your current workspace. To constrain the search, you first can select your project using the Browse... button. Given the main type of your application, two global Builder options automatically are prefilled with values. The option -classpath gets the values of your Java build path (set in the project properties) and the path of your project output location. The option -destination is set to <PROJECT_PATH>/<MAIN_CLASS>. The combo box with your targets defines for which platform the JamaicaVM Builder is generating code. The name of the target is appended to the configuration name. Changing your target selection will rename your configuration.

Provide further Builder options as needed. If a value is not correct or can not be verified, an error message shows up. The dialog allows to run the Builder even with errors, but most probably the Jamaica Builder will at last exit with the problem. To start the Jamaica Builder, click Run. In the console view of Eclipse, the output of the Builder is shown. The Builder runs in the background which allows you to keep on working. In order to cancel the build process, click on the red terminate button in the console view. If the Builder has finished, the console shows the task as 'terminated'.

Global and target specific options

A number of options (e.g. -classpath) can be specified globally and target specific whereas the target specific options have higher priority. For instance, if you specify a classpath in the tab global and in the tab of your currently selected target, the value of the target tab will be used. By selecting the radio button global, the according value of the global tab will be used.

Recognized variables

For any option which contains paths, two variables are recognized and expanded:

  • ${jamaica.home} is replaced with the path of your JamaicaVM Home directory. This path needs to be set in the JamaicaVM Builder Preferences Page.

  • ${jamaica.project} is replaced with the absolute path of your project location.

Target Site Configuration

Launching a target site configuration will perform the tasks of downloading and executing applications. Open this dialog by clicking on the pulldown button JamaicaVM Target Site. On plug-in startup, a default configuration is added for each available target. The dialog contains three tabs: one for general settings of a target, one to define how to download the application and one to define how to execute the application on the target. This dialog 'knows' which application has been last built for a specific target. Launching the configuration for that target will download and execute the binray that was last built for this target. This dialog should contain only one configuration for each target.

JamaicaVM Target Site Launch Configuration Dialog

Target host

This target, which also is the default for JamaicaVM Builder Configurations, will execute your application on localhost. The combo box with all targets is set to Execute application on localhost. This disables all options in the tab Download. In the tab Remote Execution, the host is set to 'localhost' and the only enabled option is Arguments. If your application expects program arguments, specify them here. Enclose an argument containing spaces in ".

Other Targets

For targets other than 'host', a download type and a remote execution type must be selected. By default the download type is set to FTP and the remote execution type to Telnet. The Main tab contains the following general options:

  • Target: Defines the target of the configuration.

  • Remote Directory: Defines in which directory on the target to download and execute the application.

  • Always use this program name: When downloading the application, this name is used on the target site.

This option Always use this program name is useful, when the target has little ROM available and you want to execute different applications on it. The old application will be overwritten and deleting the file manually is not necessary. If this option is not set, the application name generated by the JamaicaVM Builder (by default the name of your main class) is used.

Download Tab

The tab consists of a section with general settings and three possible types of downloads. The first is simply to skip the task of downloading the application. The second one is to use the File Transfer Protocol (FTP) and the third one is to use a command or script file defined by the user. The section General Settings contains the following options:

  • Host: Host name of your target. This can be the DNS name or an IP address. Do not include ftp://

  • Username: FTP login username

  • Password: FTP login password

  • Smart Download: This will only download the application if the JamaicaVM Builder has been run and rebuilt the application for this target. If not, the download task is skipped and only the remote execution type is launched.

FTP Download

The type FTP Download contains the following options:

  • Port: FTP port number (default: 21)

  • Verbose mode: Show verbose output when opening the FTP connection and downloading the file.

The plug-in will open a FTP connection to the specified host and port. Then, it does the following steps:

  1. Login with the given username and password

  2. Set the connection mode to passive

  3. Set the transfer mode to binary

  4. Change to the remote directory (specified in the tab Main.

  5. Put the file on the host. The file name on the target will either be the name specified in the Main tab by the field Always use this program name or the file name generated by the JamaicaVM Builder.

  6. Disconnecting form the host

User defined download

This type allows the user to specify his own commands or script file that perform the downloading. Give the absolute path of a script file and provide arguments as needed. The variables according to the list will be expanded by their values.

Remote Execution Tab

The tab consists of a section with general settings and three possible types of remote execution. The first is simply to skip the task of executing the application. The second is to open a Telnet session to the target host and start the application. The third type is to use a command or script provided by the user. The section General Settings contains the following options:

  1. Host: Host name of your target. This can be the DNS name or an IP address.

  2. Username: Telnet login username

  3. Password: Telnet login password (can be empty)

  4. Arguments: In case your application takes program arguments, they need to be specified here. Enclose an argument containing spaces in ".

Telnet

The type Telnet contains the following options:

  • Port: Telnet port number (default: 23)

  • Load Command: This setting defines how to actually start the application on the target. By default this is ./<PROGRAM_NAME>

  • Verbose mode: Show more detailed output when opening the Telnet session and executing the application.

  • Delete file on target after program termination: After program termination and before closing the Telnet connection, the file with your application is deleted on the target.

  • Interactive Telnet Session: This will open a Telnet terminal in the Console View of Eclipse. Change to that view and enter your telnet commands

  • Auto login: Using Interactive Telnet, this option will automatically login with the given username and password.

The plug-in will open a Telnet connection to the specified host and port. Then, it does the following steps:

  1. Connecting to the host.

  2. Send username and wait for password prompt if any password is given

  3. Send password

  4. Change to the remote directory (specified in the tab Main by the field Always use this program name or the file name generated by the JamaicaVM Builder.

  5. Change the file attribute of the downloaded file (chmod 755) to make it executable

  6. Sending the load command (with all used variables expanded)

  7. Wait for program termination

  8. If option Delete file on target after program termination was selected, delete the file on the target.

  9. Disconnecting form the host

Expect

Expect is a program that «talks» to other interactive programs according to a script. Following the script, Expect knows what can be expected from a program and what the correct response should be. An interpreted language provides branching and high-level control structures to direct the dialogue. In addition, the user can take control and interact directly when desired, afterward returning control to the script. Clicking on the button will open a dialog which allows to edit the command script. For more information on Expect, see http://expect.nist.gov/.

User defined remote execution

This type allows the user to specify his own commands or script file that perform the execution of the application on the target. Give the absolute path of a script file and provide arguments as needed. The variables according to the list will be expanded by their values.

JamaicaVM

Eclipse allows to define multiple Java Runtime Environments(JREs). The first time Eclipse is started with the JamaicaVM Plug-in, the JamaicaVM is added to the list of installed JREs. Open Windows->Preferences->Java->Installed JREs. In that list, you should see an entry with JamaicaVM. Click Edit... to check all paths and settings. Note that JamaicaVM is of JRE type JamaicaVM and not StandardVM.