Monday, February 02, 2009

Convenience for Maxine in Eclipse

Isn't it a bit sad that we've got this marvellous IDE, and yet we have to switch to the command line every now and then to kick off a Maxine build, or run a Java application in Maxine, or look at its and the VM's innards in the Inspector? Yes, it is. So I decided to exploit the capabilities of Eclipse and set up some neat one-click experience facilities to make life easier.

Building Maxine and the Image

The first task I want to make easier is building Maxine. Of course, the command lines one has to use are as simple as this:

~/workspace/maxine~maxine$ bin/max build
~/workspace/maxine~maxine$ bin/max image

But still, switching to the command line is the kind of media break at least I don't like too much. I want to have one task for each of the lines above, because sometimes one wants to build the VM sources without building the image at the same time.

The Eclipse feature to use is called external tools. There is a button right next to the run button in Eclipse (it looks like the one to the right) with a menu attached; click on the black triangle to invoke the menu, and then on External Tools Configurations.... In the dialogue that appears, double-click on the Program item; this will start the creation of a new external tool configuration invoking some application external to Eclipse. (We don't care about Ant tasks.)

The settings that should be applied look like in the two images below. It is quite obvious that these settings just provide a convenient wrapper around the max script, with the path to the script and its working directory and environment settings given, and also with the command line argument (build) being passed to the script. It's that simple.

In the Main tab, I have used the workspace_loc Eclipse variable to avoid having to enter the full path to the max script. Being able to give its location relative to the Eclipse workspace is much more convenient and makes the configuration reusable. The same holds for the working directory setting, which is simply the workspace directory.

The settings in the Environment tab are important because they give the max script the environment variables it requires to be run. I set JAVA_HOME to /usr/jdk/latest, and JUNIT4_CP to ${eclipse_home}/plugins/org.junit4_4.3.1/junit.jar, which is the JUnit distribution that comes with Eclipse. Note that I have once more used an Eclipse variable, eclipse_home, which points to the root of the Eclipse installation.

After having entered all the information, clicking the Apply button will save the settings. Clicking Run will save them and run the script immediately, building the Maxine sources as requested. Note how the script's output appears in the Eclipse console window.

With the wrapper for building Maxine in place, it is very straightforward to create another one for building the image. In the external tools dialogue, just right-click on the Build Maxine entry, and select the Duplicate option from the context menu. This will create a clone of the configuration we just created, and make it available for editing. The only settings that have to be changed are the name (obviously) and the command line argument (set it to image). Once that's done, click on Apply to save, or on Run to see how it works.

Running ''Hello World''

Creating a wrapper for running the Hello World application that comes with Maxine is just as simple. Try yourself, and recall that the command line argument to be passed to max is helloworld.

Interlude: Another Java Application

Of course, it is not enough to be able to (albeit conveniently) execute the simple things from within Eclipse. I want to be able to run any given Java application in Maxine, and, what's more, I want to be able to run Java applications in the Inspector. For the rest of this tutorial, we'll need some Java application that does not come with the Maxine distribution, so we can see how Eclipse facilitates integrating tools spanning several workspace projects.

The application we'll use is deliberately simple; actually, it's just another Hello World, but one that resides outside the Maxine workspace directories and projects. Here's the source code:

public class MyHW {
public static void main(String[] args) {
System.out.println("Hello, world!");

This is all we need; just create a Java project MyHW in Eclipse, and a corresponding class containing the code above. I won't go into the details of this here.

Just one note: in Eclipse, Java projects have the default property that their source code and binary directories are separate. I haven't changed this default for the MyHW project, so all details given below are chosen to work with this, and no guarantees for other configurations are given.

Running MyHW on Maxine

In terms of the command line, the max invocation for running MyHW is as follows (note the directory I'm in):

~/workspace/MyHW$ ../maxine~maxine/bin/max vm -cp bin MyHW

In detail, this invokes the max script with the vm parameter indicating that the VM should be run, passing the VM an extension to the class path (the standard option -cp is used for this, and the class path is the bin directory of the MyHW Eclipse project), and the application to be run.

To set up a generic configuration for running Java applications on Maxine from within Eclipse, the class path and application in question need to be passed as variable parameters. The rest is rather simple.

Here's the dedicated behaviour: we want to be able to select a Java file in Eclipse's package explorer, then go to the Run External Tool menu and select a tool called Run Application on Maxine. This should trigger execution of the selected application on Maxine.

Let's start with one of our previously created external tool configurations. For instance, let's duplicate the Build Image configuration and rename it to Run Application on Maxine. The trivial thing is to replace the image parameter with vm.

The working directory should be the project directory of the Java application we're about to execute, so that setting should be ${project_loc}. The project_loc Eclipse variable contains, for any selected resource, the root folder of the project it belongs to.

After the vm parameter, we need to pass the class path and Java application name. The class path is the project location with bin/ appended (Eclipse default). The Java application is the name of the resource without the file name suffix. Here is how the full list of arguments to the max script looks:

vm -cp ${project_loc}/bin ${java_type_name}

The interesting bit about this setting is the java_type_name variable: it will, for a selected Java resource, contain that resource's fully qualified Java type. So, just what we need to pass the VM on the command line.

To summarise, the complete settings for the Run Application on Maxine configuration are given in the image below.

Running MyHW in the Inspector

Guess what, setting up a configuration for the Inspector is trivial now. Really, all you have to do is clone the run configuration we created above, and replace the vm command line argument with inspect. Bingo.

Concluding Remark

You may have noticed that running and inspecting Java applications with Maxine is not quite as convenient as usually seen in Eclipse, namely via the Run as... and Debug as... options in a Java file's context menu. While this would certainly be appreciable, it seems to require setting up Maxine as a full-fledged Java runtime environment, which I haven't (yet) figured out how to achieve. Maybe this will happen some time in the future.

For now, I'm happy with the convenience wrappers for the max script. They also relieve me of keeping track with configuration changes in Maxine command lines and things that need to be passed on the command line to get the Inspector up and running, and so forth: just having everything tucked away in the max script is very convenient. Setting up things directly would imply dealing with the gory details.

No comments:

Post a Comment