Plugin setup

As an initial configuration of the plugin , you have to specify the path of the Jamaica home directory (e.g. /usr/local/jamaica). To do that, go to Window->Preferences and in the list select the item Jamaica Builder. Here you can specify the path. The input is only accepted, if it is a valid path.

Setting JamaicaVM as default JRE

During the plugin startup, the JamaicaVM automatically is added the the installed JREs. To set JamaicaVM to your default JRE, go to Window->Preferences-> and in the Preferences dialog expand the item Java and click on Installed JREs. On that page, check the box with the JamaicaVM.
You may check the JRE settings by clicking the Edit... button. The plugin expects the JamaicaVM default system library in the directory <JAMAICA>/classes with the archive name jamaica-classes.jar. If this library can not be found, an external JAR can be specified using the button Add external JAR....

Using the plugin

Visual elements added to the workbench

The plugin adds two new pulldown buttons to the toolbar. They are placed into the Run/Debug group. The plugin'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.
The next two sections explain how to use these two dialogs.
Note: The plugin 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 the New... button. A new configuration is created and is shown appears in the list. The plugin 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. 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 the Search...-Button 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'. If a Target Site Launch Configuration of the applications target has been set up, it is called directly after the build process.

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 'global' radio button, the according value of the global tab will be used.

Recognized variables

For any option which contains paths, two variables are recognized and expanded:
  1. ${jamaica.home} is replaced with the path of your JamaicaVM Home directory. This path needs to be set in the Jamaica Builder preferences page. See also chapter Plugin setup.
  2. ${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 plugin 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.

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 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: Otherwise, the application name generated by the JamaicaVM Builder (by default the name of your main class) is used. This option 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.

Tab Download

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:
FTP Download
The type FTP Download contains the following options: The plugin 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.

Tab Remote Execution

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:
Telnet
The type Telnet contains the following options: The plugin will open a Telnet connection to the specified host and port. Then, it does the following steps:
  1. After connecting to the host, the Telnet terminla type is set to "dumb".
  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 +x) to make it executable
  6. Sending the load command (with all used variables expanded)
  7. Wait for program termination
  8. Deleting the file according to the option Delete file on target after program termination
  9. Disconnecting form the host
Note: The plugin so far only supports Unix/Linux like Telnet terminals. Support for the other target terminals (like VxWorks) will follow.
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.

Generated files

The settings made in the Jamaica Builder preference page are stored in <WORKSPACE>/.metadata/.plugins/com.aicas.jamaica.eclipse/pref_store.ini. The launch configurations are stored in <WORKSPACE>/.metadata/.plugins/org.eclipse.debug.core/.launches/