View source for Trace Compass/Development Environment Setup

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 [https://projects.eclipse.org/projects/tools.tracecompass/downloads this page].

= Get the Eclipse SDK =

Under [https://www.eclipse.org/downloads/packages/ eclipse.org download packages], 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-committers-2023-03-R-linux-gtk-x86_64.tar.gz 
 $ 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.

= Setup Java 17 =

Trace Compass uses source compatibility to Java 11. However, to run the Trace Compass RCP and to develop it, Java 17 is required. Here is how to install Java 17 on recent Ubuntu:

 $ sudo apt-get install openjdk-17-jdk

For old versions of Ubuntu, install from the [https://launchpad.net/~openjdk-r/+archive/ubuntu/ppa OpenJDK PPA].

Next, the JRE must be added in Eclipse. 

* Select "Window -> Preferences".
* Navigate to "Java -> Installed JREs".
* Click "Add..." and enter the path to Java 17 home directory (ex: /usr/lib/jvm/java-17-openjdk-amd64).
* Check the Java 11 entry to use it by default for new projects and run configurations.

Note: if you migrate your environment to Java 17, existing debug and run configurations will continue to use the previous JRE. To use the new JRE, open the run configuration pannel "Run -> Run configurations..." and from the tab "Main", select the appropriate JRE under "Java Runtime Environment -> Execution environment".

= Setup Maven =
To be able run a Maven build from command-line, Maven version v3.8.x or later needs to be installed. Follow the [https://maven.apache.org/install.html installation guide] for that.

= Setup Maven Plug-ins =
When developing for the Trace Compass incubator project, make sure to install the m2e plug-ins to your Eclipse IDE. You can omit these steps if not developing incubator features. This is a recent addition to m2e and requires an Eclipse IDE 2021-06 or later.

To install M2E, select menu "Help -> Install New Software...". An "Install" dialog will open. Select the release update site from the "Work with" drop-down menu. For example, if your IDE is based on Eclipse 2023-03 the select "2023-03 - http://download.eclipse.org/releases/2023-03". Then select "M2E- Integration for Eclipse" and "M2E - PDE Integration" and select "Next" Button and the "Finish". Restart Eclipse when asked for it.

= 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 [http://www.eclipse.org/egit/ Eclipse Git Team Provider] plugin, also available in Eclipse's "Install New Software").

Then, simply clone the following repository somewhere on your hard drive:
* https://git.eclipse.org/c/tracecompass/org.eclipse.tracecompass.git

 git clone https://git.eclipse.org/r/tracecompass/org.eclipse.tracecompass.git

If adding tests that require an actual trace, then it should be added to the following trace repository first:

* https://git.eclipse.org/c/tracecompass/tracecompass-test-traces.git/

 git clone https://git.eclipse.org/r/tracecompass/tracecompass-test-traces.git

Extra functionalities are developed in the Trace Compass Incubator sub-project. If interested in any of those feature, the following repository can be cloned

* https://git.eclipse.org/c/tracecompass.incubator/org.eclipse.tracecompass.incubator.git/

 git clone https://git.eclipse.org/r/tracecompass.incubator/org.eclipse.tracecompass.incubator.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 the Eclipse version (tracecompass-e4.20.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.

= Define an API baseline =

== Using the Eclipse IDE ==

''Starting with Eclipse 4.5.0, it is no longer necessary to download and maintain a separate Eclipse installation for the API baseline. You can simply use a target definition file, as explained below.''

Since Trace Compass is out of incubation with its 1.0 release, all API changes have to be tracked and marked with the proper @since annotations. The Eclipse API tool can compare the contents of the current workspace with the last stable version, defined in a target definition file.

To set up the API baseline, follow these steps:

* Select "Window -> Preferences". In the window that opens, select "Plug-in Development -> API Baselines" on the left pane.
* Click on "Add Baseline..."
* Choose "A target platform" and click Next.
* In the next page check the box next to the target which contains "baseline" in its name, like "tracecompass-baseline-7.0". Use the version of Trace Compass that you're are developing against, which is usually the latest release.
* Click "Refresh" to download the contents of the target.
* Specify a name for this baseline in the top area, like "Trace Compass 7.0" for example.
* Click "Finish", then "OK" in the previous dialog.

It should offer you do to a full rebuild. You can click "Yes" at this point.

Once that is done, your workspace will be rebuilt and the API changes will now be tracked. Any new method or class will have to be annotated with "@since n", where n is the major.minor version number found in the plugin's MANIFEST.MF file.

= 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 using maven build from the command-line from the Trace Compass root directory:
* mvn clean install -DskipTests=true
* 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.

= Run test suite with Maven =

Before submitting to Gerrit, it may be useful to validate changes for possible regression. Running the GUI tests opens windows that will interfere with the main desktop session. On Linux, the windows can be redirected to a virtual display.

== Setup virtual display on Ubuntu ==
* Install Xephyr and Metacity: sudo apt-get install xserver-xephyr metacity
* Start the virtual display: Xephyr :2 -screen 1024x768 &
* Setup environment: export DISPLAY=:2
* Start the Metacity window manager: metacity --replace &
* Execute the tests: mvn clean install

== Static code verification ==

In the testing phase, it is suggested to use [http://www.vogella.com/tutorials/Findbugs/article.html FindBugs] to check the code for common errors. Coding conventions are checked with Checkstyle. Bad practices are verified by (PMD).

Conversely, one can use [http://docs.sonarqube.org/display/SONAR/Installing+SonarQube+in+Eclipse sonar for eclipse] to check all the issues in one place.

You can also consult the static analysis results at [https://scan.coverity.com/projects/tracecompass Coverity] and [https://dev.eclipse.org/sonar/dashboard/index/org.eclipse.tracecompass:org.eclipse.tracecompass Eclipse SonarQube server].

= Using the Eclipse Installer (Oomph) =

(experimental)

You can use the Eclipse Installer to setup the Eclipse installation and everything required to get started with Trace Compass development. It downloads Eclipse, sets the API baseline, clones the Trace Compass git repository and imports the projects for you.

# Download the Eclipse Oomph installer, available at https://wiki.eclipse.org/Eclipse_Oomph_Installer
# Extract and start the installer.
# After the initial preference questions, at the package selection, click the menu button in the top-right corner and select Advanced Mode.
# If you are behind a proxy, at this point you might want to double check your network settings by clicking in the "Network Proxy Settings" at the bottom.
# Under Eclipse.org, Select Eclipse IDE for Eclipse Committers. Click Next.
# Under Eclipse Projects, double-click on Trace Compass. Click Next.
# Enter installation folder name, workspace name, etc. Click Next, Finish.

After the Eclipse workbench is installed and launched, wait for the "Executing startup tasks" job to be completed, then you should have a complete Eclipse environment to work on Trace Compass.