Revision as of 13:35, 27 October 2014

This page describes how to setup the Trace Compass development environment.

Note that this should only be required if you want to make modifications to the code or contribute patches. If you only want to run the plugin as a user, you would probably be better served by the stable or nightly builds, available on this page.

Get the Eclipse SDK

Under eclipse.org downloads, select the Eclipse IDE for Eclipse Committers archive. You can start with any Eclipse pre-package, but make sure you have the Eclipse Plug-in Development Environment feature installed.

Uncompress and start Eclipse. Example for Linux:

$ tar xzvf eclipse-standard-luna-SR1-linux-gtk-x86_64.tar.gzz
$ cd eclipse
$ ./eclipse

The first time you run it, it will ask for a workspace directory. You can use the default location.

You will then be greeted by the welcome screen, which you can dismiss by clicking the Workbench arrow in the upper-right corner.

Get the source code for org.eclipse.tracecompass

First, make sure you have a Git client installed (either the git command-line tool, or the EGit plugin, also available in Eclipse's "Install New Software").

Then, simply clone the following repository somewhere on your hard drive:

• git://git.eclipse.org/gitroot/tracecompass/org.eclipse.tracecompass.git

Import the Trace Compass projects into the workspace

• Select "File -> Import..."
• Select "General -> Existing Projects into Workspace"
• Next to "Select root directory" click "Browse..."
• Navigate to the directory where you git clone'd the project earlier.
• It should now list the available plugins. Make sure they are all checked and click "Finish".
• The plugins should now be added to your workspace, and visible in the Package Explorer view on the left.

You will probably get a bunch of build errors at this point. DON'T PANIC! This is because Trace Compass needs additional dependencies that might not be present in your current Eclipse installation. We will install those in the following section.

Set the Target Platform

Eclipse offers the ability to set target platforms, which will download a specific environment to run your plugins, without having to "pollute" your Eclipse install. Trace Compass ships target definition files, which is the recommended way of installing its dependencies.

To set the target platform for the Trace Compass plugins:

• Expand the "org.eclipse.tracecompass.target" project.
• Double-click the .target file that corresponds to your Eclipse version (tracecompass-e4.4.target, at the time of this writing).
• In the view that just opened, click Set as Target Platform on the top right.

Eclipse will now download the required dependencies, which may take some time the first time.

If you wish to switch target platforms in the future, you can come back to this plugin, or you can go to "Window -> Preferences -> Plug-in Development -> Target Platform". From that page, you can switch between any of the known targets, or your base Eclipse runtime.

Build the documentation (optional)

If you imported the *.help plugins (which contain the user and developer guides), you might notice warnings in these plugins because of missing files. It is because the documentation plugins need to be built using a separate component. If you do not care for the documentation, you can ignore those warnings, or even remove those plugins from your workspace.

On the other hand, if you want to build or work on the documentation (which you should do if you add user-visible features!), here is how to build it.

First you need to install the Mylyn-Wikitext Eclipse plugin:

• Go to "Help -> Install New Software..."
• Select "-- All Available Sites--"
• In the list of available plugins, select "Collaboration -> Mylyn Wikitext", and click Next/Finish to install it.
• Restart Eclipse

You can now build the documentation plugins:

• Click on one of the *.help projects
• In the top menu, click "Project -> Build Project"
• After it is built, the warning should disappear, and the HTML files should be present in its doc/ subdirectory.

Note that this builder does not run automatically ; Ant is not very smart at figuring out which files were changed, so it would end up constantly rebuilding the doc plugins for nothing. For this reason, if you modify the source (.mediawiki) files, you will have to rebuild the HTML manually, using the same method.

Run (or Debug) the plugins

To run (or debug) the code, start a nested Eclipse with the plugins loaded:

• Right-click the "org.eclipse.tracecompass.tmf.core" plugin
• Select "Run As -> Eclipse Application" (or "Debug As -> Eclipse Application" to run in debug mode).

The next time you can just select "Eclipse Application" from the Run (or Debug) icon in the toolbar.