GNU Classpath, Cacao or JamVM and Mauve developer setup howto
Copyright (C) 2005, 2006 Raïf S. Naffah. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
This is a simple step-by-step list, for Fedora Core 4, Ubuntu and Debian sid users, to setup an environment for hacking GNU Classpath with Native Eclipse (which we shall refer to in the rest of this note as just Eclipse) and testing it with Cacao or JamVM and Mauve.
Note: The eclipse classpath build process from cvs assumes that Cairo is installed. Be sure to get it if you haven't already.
- GNU Classpath, Cacao or JamVM and Mauve developer setup howto
- Installing Eclipse
- Check out GNU Classpath with Eclipse
- Check out and build a VM
- Check out, and configure, Mauve
- Run the Mauve tests
- Bugs and feature requests
Fedora Core 4, Ubuntu breezy and Debian sid come with Eclipse based on a fully Free Software stack by default now. For Fedora Core type yum install eclipse-pde-devel, for Ubuntu aptitude install eclipse-sdk and for Debian aptitude install eclipse eclipse-cdt to install it. Note: Make sure you also install the CDT eclipse-cdt it is needed for some of the automagic building stuff.
Now a simple eclipse should start up the native Eclipse environment.
Installing the ChangeLog and Bugzilla plugin
The Changelog and Bugzilla plugins make hacking on GNU Classpath a lot more fun. But they are not required (so feel free to skip this step).
On Fedora Core you can type yum install eclipse-changelog eclipse-bugzilla and restart eclipse.
For other distributions you will have to go to the Help -> Software Updates -> Find and Install... menu and choose the Search for new features option. Click Next and then in the next dialog click New Remote Site.... For the Bugzilla plugin use the URL http://people.redhat.com/jpound/update. Then click New Remote Site... again. And for the Changelog Plugin use the URL http://people.redhat.com/pmuldoon/update. Now click Finish. It will search for a while and then you can select the checkboxes for the bugzilla and changelog plugin. Select them both and click Next or Finish.
NOTE: If eclipse seems to freeze at this point with an information dialog where you cannot even hit Cancel there might be a Restart Eclipse Now? dialog behind the progress dialog.
WARNING: Don't try installing the Bugzilla plugin on Debian (eclipse 3.1.1-6) it will seem to install nicely and restart eclipse at first but then on a later startup of eclipse it will complain about Bundle "org.eclipse.compare" version "3.1.1" has already been installed from: update@plugins/org.eclipse.compare_3.1.1.jar and org.eclipse.core.runtime.CoreException: java.lang.ClassNotFoundException: org.eclipse.ui.internal.ide.IDEApplication. If this happens then the fix is to rm -rf ~/.eclipse (this will remove all your settings!).
Installing the CDT plugin
NOTE: You only need to do this if the CDT isn't available yet for your distribution. On Debian (unstable) you can simple do aptitude install eclipse-cdt. On Fedora you can simply do a yum install eclipse-cdt.
Follow the instructions above for installing plugins, but use the following URL in a Site Bookmark in the update manager: http://download.eclipse.org/tools/cdt/releases/eclipse3.1
Downloading and installing this plugin might take a very long time. And you might see several warnings from the garbage collector:
GC Warning: Repeated allocation of very large block (appr. size 5509120): May lead to memory leak and poor performance.
This issue has been solved in gcj 4.1/GNU Classpath 0.19. This was bug#24086
Check out GNU Classpath with Eclipse
HINT: Because of the eclipse bug #111957 mentioned below you might want to first make sure that the meny item Project -> Build automatically is unchecked. That way no uncessary compilation happens while we are checking out a new classpath project.
If this is the first time you use Eclipse (you are in the welcome screen) click on the Workspace icon.
Select File > New > Other... or just press Ctrl-N.
Select Checkout Projects from CVS and click Next.
Select Create a new repository location (this dialog only comes up if you already have some preconfigured locations, otherwise just skip to the next step) and click Next.
In the next dialog, enter the required information as provided on the GNU Classpath CVS information page, located at http://savannah.gnu.org/cvs/?group=classpath. At the time of writing this note, that information consisted of the following, as shown in the next illustration:
TIP: Paste the repository description :pserver:email@example.com:/sources/classpath into the Host field of this dialog, and Eclipse will parse it for you and fill in all the other fields.
Leave the rest of the fields to their default values and click Next.
Select Use specified module name and enter classpath in the input field. Press Finish.
You can press Finish above and ignore any of the Next configuration screens since the defaults (check out as project in the workspace, with the name classpath for CVS HEAD) are fine. If you want to name the project differently, import it into another project workspace or work on a GNU Classpath CVS branch (for example the generics-branch) then want to check out the Next screens.
After pressing Finish above the CVS checkout console will get activated and you should start seeing the log messages scrolling in that window. After a few seconds (or minutes depending on the grunt of your box), a new package named classpath should appear in the Eclipse Project Explorer view.
The GNU Classpath module contains customized Eclipse Builders that will launch, among other things, the autogen.sh script, the configure script and build the contents of the native subdirectory in the project, installing the binaries into the install subdirectory in the project. The autogen.sh script requires automake 1.9 to be installed.
However, these builders don't reliably run when the project is first checked out. This seems to be an Eclipse bug, namely https://bugs.eclipse.org/bugs/show_bug.cgi?id=111957. The workound for this is to choose Project->Clean..., select the classpath project, and OK.
Eclipse will now start building all of GNU Classpath this will take a little while. When it is finished you can check under the Problems tab that everything went fine (there should be no errors, only a few warnings).
HINT: If you unchecked the automatic build option above to work around the eclipse bug #111957 then you can now reenable it by making sure Project -> Build automatically is checked.
Check out and build a VM
You can choose your runtime. Either use Cacao or JamVM.
This is a straightforward operation using the information provided on the Cacao SVN page at http://www.cacaojvm.org/. The repository string, for easy pasting, is currently
As Cacao is using SVN and eclipse does not ship SVN support, you have to install an SVN client in eclipse. A famous one is Subclipse. Installation instructions of Subclipse can be found here.
For JamVM you would replace all references to cacao with jamvm below and use the following CVS string
Note: The reason we recommend Cacao or JamVM here is that these are the simplest VMs to set up to work with Classpath in an Eclipse workspace -- all the needed Eclipse build configuration files are checked in, and it will readily use the classpath built in the same workspace.
Check out cacao into a new Eclipse project named "cacao", following the same steps as when you checked out classpath.
Select Checkout Projects from SVN and click Next.
Select Create a new repository location and click Next.
Fill in the fields by pasting svn://c1.complang.tuwien.ac.at:/ahome/cacao/svn/cacao in the Url field and click Next.
Select the folder trunk and click Next.
Type the project name cacao and click Finish.
Select Checkout Projects from CVS and click Next.
Select Create a new repository location and click Next.
Fill in the fields by pasting :pserver:firstname.lastname@example.org:/ahome/cacao/cacaocvs in the host field and click Next.
Type the module name cacao. You don't need any specialized options so you can just press Finish.
You will then have to apply the Clean... trick again to make Cacao build.
Note that after building Cacao you will see a few errors in the Problems view. These are not really errors but are, instead, minor bugs in the Eclipse CDT. In particular we seem to hit https://bugs.eclipse.org/bugs/show_bug.cgi?id=120184 and https://bugs.eclipse.org/bugs/show_bug.cgi?id=120797
Once it is all checked out and built, you have a working VM! Changes to classpath will be available for use by your cacao build as soon as Eclipse is finished compiling them -- and ordinarily this is instantaneous. You can try your new VM from the shell:
$ cd ~/workspace $ ./classpath/install/bin/cacao -help Usage: cacao [-options] classname [arguments] (to run a class file) cacao [-options] -jar jarfile [arguments] (to run a standalone jar file) ...
Note that this cacao is built from the just checkout sources and uses the GNU Classpath classes from the classpath workspace. If you turn on Project -> Build automatically then any change you make in the classpath workspace will automatically be available to this cacao runtime.
Check out, and configure, Mauve
This is a similar operation to checking out GNU Classpath, with the obvious difference that the repository and the module name will be Mauve's rather than GNU Classpath's. The needed information is provided on the Mauve CVS page at http://sources.redhat.com/mauve/cvs.html. The CVS location you want to use is :pserver:email@example.com:/cvs/mauve, and the module is mauve. Clean and rebuild the project as above.
Run the Mauve tests
With Anthony Balkissoon's new Harness, and the newly added Mauve Harness.launch runner (to the Mauve project), it is easy to run one test, or all tests in a folder (and all enclosed folders)! But first, you need to have the fakejdk installed.
Installing the "fakejdk"
From Tom Tromey's mail http://lists.gnu.org/archive/html/classpath/2005-12/msg00134.html: "...check out the fakejdk project from :pserver:firstname.lastname@example.org:/cvs/rhug, module fakejdk. This ought to auto-build, but if not, apply the usual Clean hack.) This just makes a little project consisting of symlinks -- it is a huge hack."
In Eclipse, select Window -> Preferences.... When the dialog window appears, unfold the Java group and select Installed JREs.
Click Add and name the new JRE classpath. Click the Browse... button and select the folder where you checked out the fakejdk project.
Unselect the Use default system libraries checkbox.
Note: In Eclipse 3.2 there is no more the Use default system libraries checkbox. Instead, to run the Mauve tests with Classpath you need to click on "Run->Run..", select Mauve Harness or MauveTestlet then switch to the Environment tab and select the Replace native environment with specified environment checkbox.
Note: On some configuration, with cacao, you might have to also add vm.zip from cacao installation directory, prior to the rt.jar archive. You only need to add vm.zip if any attempt to run cacao ends early with a weird error such as "java.lang.NoClassDefFoundError: java/lang/System".
Select Source attachment (none) and click the Edit... button
Click the External Folder... button and browse to the install/share/classpath folder in your GNU Classpath workspace folder. Click OK.
You should now see a new JRE named classpath appear in the list of available JRES which Eclipse can use.
Running one or more tests
Either select one file, or a folder from the Eclipse [Package Explorer] panel in the [Java] View, then select [Mauve Harness] under the Run button as shown below.
if you selected a file, and that file was an instance of Testlet, or if you selected a folder and that folder contains one or more Testlets, either directly or within other contained folders, you should start seeing the output of those tests in the [Console] View.
You can also start the test(s), after selecting a file or a folder, when you select the [Mauve Harness] from the [Run -> Run...] menu item, and press the [Run] button.
Tweaking the Mauve Harness runner
From time to time, you may need to tweak the pre-configured parameters of the Mauve Harness runner. To do that, display the [Create, manage, and run configurations] dialog by selecting the [Run -> Run...] menu item, and then selecting [Mauve Harness] under [Java Application] in the left pane. A screen similar to the following will be displayed:
Select the [Arguments] tab as shown above and edit the values of the arguments to suit your needs. The description of the options possible for passing to the Harness class are described in detail in the README file in the (Mauve) project.
Running Mauve from the command line
Consult the README file in the Mauve project for information, and examples, of how to do that.
Bugs and feature requests
The following are a couple of suggestions for how to make the whole experience better.
There should be a simple guide on how to setup a new Hello World project that automagically uses the classpath and cacao runtime workspaces. (The best way to do this is to make a "fake JDK" project, so that we can tell Eclipse that a project in the workspace is actually a JDK install. That way it is simple to point projects at the Classpath in the workspace. -tom)
The running all of mauve automagically through batch_runner should be made possible from inside Eclipse without the need to hard code paths in the script itself.
How do you get normal emacs keybindings? (Window->Preferences->Keys->Scheme -tom)
Can you add simple scripts to actions?
Indentation seems completely wrong. Is there a way to setup normal GNU style code style for all files/projects? (You can probably import the style from Classpath and use it globally. For our projects we should set them all up with this style, though.)
You can checkout the wonka module from Mauve CVS and it comes with a runner for the VisualTester. But this depends on jamvm. Changing it to use cacao seems to not work. Does anybody have a working example?
Same for the Free Swing Demo in classpath. There is a runner for it, but that doesn't seem to work. And the eclipse built cacao seems unable to get past the first dialog (might be because it isn't using a proper glibj.zip but a "flat" classpatch class lib.
Have to try out gjdoc. It has eclipse builders. Does it work? (yes -tom)
The search function does not really work in eclipse-CDT (Search->C/C++ search), see bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=108951 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=348393