Hints on installing the OTDT

Starting with version 1.2.0 the procedures for installing the OTDT have been unified to fit into the conventions of the new provisioning system "p2". As a result it is now possible to install the OTDT on top of any of the provided Eclipse packages. Starting with Eclipse 3.5 this combination works well enough to perform various p2 operations like uninstalling (reverting) etc.

1. Step-by-step installation

Using the update UI of p2, this is how you install the OTDT:
Steps to perform
  1. Open the update UI using Help > Install New Software...
  2. Click Add... and enter this URL:
    Location:http://www.objectteams.org/distrib/otdt-updates-1.4
  3. After waiting for meta data to be fetched in the background you should see a site named "Object Teams Updates" containing the category "OTDT 1.4.x based on Eclipse 3.6".
  4. Select desired features:
    1. The impatient may simply select the category (top level) and click Install to get all that's available from our site.
    2. If you want to know better what's in it, have a look at this table of features and select features accordingly.
  5. Click Next and follow the wizard.
  6. When a dialog asks for permission to restart the Eclipse SDK, answer Yes.
  7. The subsequent launch of Eclipse should show the following indications of a successful installation:
    • The splash screen contains the OTDT icon.
    • The Build ID on the splash screen (and elsewhere) has a suffix ".OT_1.4.0Mx"
    • The startup message is "Loading Object Teams Workbench with OT/Equinox enabled"
    • Once the workbench is up and running you may check the install:
      • open the Help > About Eclipse SDK dialog and check that the appropriate features appear (two features for a normal install).
      • click the Eclipse icon, select "Eclipse RCP" and inspect the Plug-in Details then search for the org.eclipse.ui.workbench plug-in: it should show its version as something like:
        3.6.0.I20091028-1300
        **** OT-adapted by:
        * org.objectteams.otequinox.branding
        * org.objectteams.jdt.ui.adaptor
        This shows that the two specified plug-ins are successfully connected to the org.eclipse.ui.workbench plug-in.

  While parts of the OTDT come as regular features/plug-ins, two things are special about this installation:

The following table explains the effects of installing the OTDT in more detail:

Background information
If you'd like to know what's happening, here is the list of files being installed / modified and their respective purposes:
Replacing plug-in:
plugins/org.eclipse.jdt.core_3.6.0.v_OTDT_r140_YYYYYYYYYYYY.jar
This plug-in is branched from the original jdt core in order to seamlessly support OT/J.
Except for a small number of unconditional OT/J keywords (see otjld §A.0), this branch is fully compatible with the jdt core of the host Eclipse installation.
Plug-ins implementing the OT/Equinox infrastructure:
plugins/org.objectteams.otequinox_1.4.X.jar
The plug-in providing the extension point org.objectteams.otequinox.aspectBindings where all aspect plug-ins register. This plug-in manages the dependencies between aspect plug-ins and the base plug-ins which they adapt.
plugins/org.objectteams.equinox.hook_1.4.X.jar
A fragment for the Equinox framework. It installs the byte code transformers which perform the load-time byte-code weaving for connecting aspect plug-ins with their base classes.
This fragment must be physically located in the same directory where also the org.eclipse.osgi bundle resides. For this reason installing OT/Equinox requires write permissions to the installation's plugins directory. → Cf. Eclipse bug 257178
plugins/org.objectteams.otequinox.runtime_1.4.X.jar
Another fragment for the Equinox framework. It hosts the actual byte-code weaver and additional library classes required to run Object Teams programs.
plugins/org.objectteams.equinox.branding_1.4.X.jar
This tiny aspect plug-in adapts the "Plug-in Details" dialog of Eclipse in order to display which installed plug-ins are currently adapted by an aspect plug-in.
(Almost) regular plug-ins:
plugins/org.objectteams.xxx_1.4.X
These plugins implement the various parts of the OTDT. While some of these are plain plug-ins, a growing number of plug-ins is implemented in OT/J in order to apply our adaptations in a very modular way. Those plug-ins are the reason why the OTDT requires OT/Equinox to actually be installed.
Configuration files:
configuration/config.ini
During installation of OT/Equinox some declarations are automatically added to this file in order to announce the above fragments and to hook into the Equinox framework.
eclipse.ini
During installation of the OTDT some JVM arguments are automatically added to this file in order to avoid a known deadlock occurring with the Sun JVM (see Issue 122).

2. Adding the OTDT on top of a shared installation

The Eclipse command line argument -configuration allows you to operate different Eclipse configurations sharing the same base installation. If you carefully perform the following steps, also the OTDT can be installed without affecting other configurations based on the same shared installation.
Steps to perform
  1. Create a new configuration folder, e.g.,
    $ mkdir otdt_configuration
  2. Copy the default configuration as a sub folder into that folder, e.g.,
    $ cp -r eclipse/configuration otdt_configuration/
  3. Launch eclipse with at least the -configuration argument pointing to the nested configuration folder, e.g.,
    $ ./eclipse/eclipse -configuration otdt_configuration/configuration -data ${HOME}/otdt_workspace
  4. From here proceed following the "Step-by-step installation" above.
    • Only in step 7 the splash screen will not contain the OT logo. This is due to the fact, that this installation strategy cannot write to eclipse.ini.
    • In addition to the splash screen the OTDT normally adds some VM arguments to this file. So when using the -configuration switch you might want to pass some VM arguments from the command line, but note that passing VM arguments from the command line overrides any entry in eclipse.ini so you have to specify the full list of VM arguments, e.g.,
      $ ./eclipse/eclipse -configuration dir -data dir -vmargs -XX:+UnlockDiagnosticVMOptions -XX:+UnsyncloadClass -Dosgi.support.class.certificate=false -Xms40m -Xmx768m

      (You probably want to create a shell/batch script for this command line ;-))

Explanation of VM arguments:

-XX:+UnlockDiagnosticVMOptions -XX:+UnsyncloadClass
These VM arguments work around an issue in the Sun JVM that can lead to deadlocks. These should not be used on MacOS.
-Dosgi.support.class.certificate=false
This helps to avoid another cause for deadlocks during class loading (platform independent).
-Xms40m -Xmx768m
Recommended memory settings.

With the ability to share an installation comes the option to use an installation to which the current user does not have writing permissions.

3. Installing and using the command line compiler

The command line compiler can be downloaded as a single jar file called ecotj-1.4.X.jar.

The compiler can be run by the following command:
java -jar ecotj-1.4.X.jar arguments
Use -help as the argument to see the list of options.

Running OT/J programs outside Eclipse is only slightly more complicated. Please see these howtos if you want to compile and/or run OT/J programs from the command line using ant.