Developing Pal-J components using Eclipse

Contents

Introduction
Checking out the PalCom SVN tree
Importing the Pal-J developer projects
Importing the tutorial example project
Compiling the example project for the JVM
Running the example on the JVM
Setting paths for command-line work
Compiling for the Pal-VM
Running on the Pal-VM
Building and running new Pal-J components

Introduction

This tutorial describes the steps needed for building and running a Pal-J application using the Eclipse IDE. Inside Eclipse, the application is automatically compiled for the JVM, and you can test-run it on the JVM. When an application compiles and runs in Eclipse, it can be compiled and run on the Pal-VM from the command-line, with unmodified source code. Working with Pal-J this way, you can take advantage of the Eclipse Java development facilities, such as the debugger and Content Assist.

Only a small subset of the Java standard class libraries are available in Pal-J and there are also a few limitations to the language itself:

Checking out the PalCom SVN tree

The Pal-J Eclipse projects are available in the PalCom SVN repository. See palcom/doc/setup/PalCom-SVN.txt for general information about the PalCom SVN. This section describes the steps needed for checking out the projects using the Eclipse SVN client.

First, check out the PalCom SVN tree in one workspace:

When the check-out has finished, you can switch to the Java perspective, and see that there is a project "palcom" in the Package Explorer view.

Importing the Pal-J developer projects

For working with the Pal-J Eclipse projects, we need to switch to another workspace, and import the individual projects from the checked-out tree:

The Pal-J development projects have now been imported into the workspace. Wait for the build of the projects to finish.

After the build, there will be errors in a number of projects. One manual step is required to remove them. Open up the dev-lib project, right-click on build.xml and choose Run As->Ant Build... (three dots). On the Refresh tab, select Refresh resources upon completion and choose The entire workspace. On the JRE tab, enter "-Xmx500m" in the VM arguments box. Click Run.

Wait for the projects to build again. Now, all errors should disappear.

The projects j-libs, mal-layer, routing-layer, function-layer, process, and xml contain libraries used by Pal-J programs. In the project pal-jbase, there are JVM implementations of Pal-VM's so called base classes. The reason for having this as a separate Eclipse project is that it needs a different classpath. The component named ist.palcom.base in the project pal-jbase and the java.* components in j-libs/src are tightly coupled to the Pal-J compiler and language interoperability between Java and SmallTalk.

Importing the tutorial example project

There is a small Pal-J project made for this tutorial, that uses threads from the ist.palcom.palcomthreads component. We will import that project into the workspace.

The example project will be copied into the workspace. It compiles automatically for the JVM. When copied into the workspace, the project still has some SVN meta information left. We want to remove that, so our test project is not connected to the PalCom SVN.

You can see that the project is disconnected when the small orange icon has disappeared from pal-j-example in the Package Explorer.

Compiling the example project for the JVM

The code for the example project is in Example.java, in the component named "example" under pal-j-example/src. As mentioned above, it will be compiled automatically. As a test, modify one of the System.out.println calls in Example.java so it prints something else, and save the file. Eclipse will re-compile it automatically.

Running the example on the JVM

In order to run the example, right-click on Example.java and choose Run As->Java Application. The program will print three lines to the console.

Setting paths for command-line work

The same example component can also be built for the Pal-VM. This is done from the command-line. For compiling with the Pal-J compiler, and running programs on the Pal-VM, you need to add two directories to your PATH environment variable:

If you use Bash, you can do this as follows: 

$ export PATH=$PATH:home-dir/palcom-checkout/palcom/bin
$ export PATH=$PATH:home-dir/palcom-checkout/palcom/developer/dev-bin

These directories need to be on the PATH whenever you work with PalCom command-line tools, so it is a good idea to update your startup scripts to do this automatically.

Compiling for the Pal-VM

There is a Makefile in the pal-j-example/src directory, that can be used for compiling the program: 

$ cd home-dir/palcom-workspace/pal-j-example/src
$ make example.prc

The component file example.prc will be generated in the src directory. You can see the file in Eclipse if you right-click on the pal-j-example project and choose Refresh (Eclipse needs to refresh its view of the file system when such changes happen outside Eclipse).

Running on the Pal-VM

For running the example, type the following from the command-line, still standing in the src directory: 

$ pal-vm -cp . example.prc

The Pal-J program will print the same three lines to the console as before.

Building and running new Pal-J components

The easiest way to start when making a new Pal-J component is to copy the example project to a new project and make changes from there. The new project will have its Eclipse classpath set correctly, and the Makefile can be modified to compile new components as they are added.

A Pal-J project defines one or more PalCom components. A Java package corresponds to a component in Pal-VM. Neither packages nor the corresponding components are hierarchical. E.g, the ist.palcom.palcomthreads and ist.palcom.palcomthreads.test packages define two components and should therefore contain one Component specification each (files named Component).

Dependencies between components and the files to be included in a particular component are specified in the Component specification file (placed in the same directory as the Java files for the component):

For the components to be built correctly for the Pal-VM, you also need to modify the Makefile. List the PRC file names of all components in the project on the right-hand-side of the assignment to the components variable, separated by space. For each component, add two rules corresponding to the rules for example.pra and example.prc (PRA files are intermediate files output by the Pal-J compiler). When adding a component named my.test.comp, you would extend the Makefile like this (where Comp.java is replaced by the Java files in the component): 

components := example.prc my.test.comp.prc

...

my.test.comp.pra: my/test/comp/Comp.java my/test/comp/Component
	pal$(dev)-j -classpath "$(lib)$(sep)." -c my/test/comp/Component

my.test.comp.prc: my.test.comp.pra
	pal$(dev)-asm my.test.comp.pra

You may also want to modify the rule for the target all, so the right component is executed. When executing a component, the Pal-VM starts the first Java main method it finds in the component. It is best to have only one main method in each component.

Following these steps, it is possible to develop Pal-J components in Eclipse, running them both on the Pal-VM and the JVM. For the latter, the Eclipse debugger can also be used, with breakpoints, etc.