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:
- ${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.
- ${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:
- 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.
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:
- 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 plugin will open a FTP connection to the specified host and port. Then, it does the following steps:
- Login with the given username and password
- Set the connection mode to passive
- Set the transfer mode to binary
- Change to the remote directory (specified in the tab Main.
- 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.
- 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:
- Host: Host name of your target. This can be the DNS name or an IP address.
- Username: Telnet login username
- Password: Telnet login password (can be empty)
- 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 './'
- Verbose mode: Show more details 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 plugin will open a Telnet connection to the specified host and port. Then, it does the following steps:
- After connecting to the host, the Telnet terminla type is set to "dumb".
- Send username and wait for password prompt if any password is given
- Send password
- 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.
- Change the file attribute of the downloaded file (chmod +x) to make it executable
- Sending the load command (with all used variables expanded)
- Wait for program termination
- Deleting the file according to the option Delete file on target after program termination
- 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/