Building TRex manually

Table of Contents

1. Checking-out the required project files
2. Building TRex
3. Starting TRex
4. Alternatives to starting TRex via Run...

First, check on the Features and Requirements page that you meet all the requirements you need to run and build TRex.

Note: Since 2007/09/07, the sources in SVN trunk cannot be checked out anymore with Eclipse 3.2. You definitely need Eclipse 3.3 (Europa) to build TRex from the sources in SVN trunk!

Checking-out the required project files

To build TRex manually within Eclipse from the sources, you need to check-out the sources from our SVN repository:

If you have installed an SVN plug-in for Eclipse, your SVN plug-in will offer an SVN Repository Exploring perspective, where have to create a new repository location for the TRex SVN repository. To achieve this, do right click in the SVN Repositories view and select New. In the New Repository Location dialog, enter http://www.trex.informatik.uni-goettingen.de/svn/trex/ as root URL. (It may be possible that you are asked to enter a password, because some directories of the TRex SVN repository contain non-public files. In this case, simply click Cancel in the password dialogue to get access to the public files only.)

After that, you have to navigate to the trunk directory in the SVN Repository Exploring perspective. Individually check-out the directories listed below from the TRex SVN repository by right clicking on the directory and selecting Check out from the context menu of the (each directory needs to be checked out as an Eclipse project on its own; do not check out trunk as a single project):

• com.yourkit.profiler.controller
• de.ugoe.cs.swe.trex
• de.ugoe.cs.swe.trex.antlr
• de.ugoe.cs.swe.trex.core
• de.ugoe.cs.swe.trex.refactoring.core
• de.ugoe.cs.swe.trex.refactoring.ui
• de.ugoe.cs.swe.trex.ui
• de.ugoe.cs.swe.trex.ui.help
• (If you like to perform some JUnit tests later, you may also check-out de.ugoe.cs.swe.trex.tests. Further directories may exist: however, these usually contain experimental plug-ins; hence, only developers or brave users should check them out.)

For a detailed description of the directories, refer to the Up-to-date documentation of the TRex plug-in structure

Building TRex

Now, you have to build TRex:

• Change into the PDE perspective (Window->Open Perspective->Other.... In the subsequent dialog, select Plug-In Development->OK as shown below).

• Now, the Package Explorer view should look like shown below. (Version number given behind each project directory may vary. Furthermore, the help plug-in and the YourKit profiler plug-in have been added since this screenshot was taken. It is OK that some projects contain errors as indicated by the red error markers; we will tell you in a later step how to solve this...) Each project is a plug-in, i.e. for a better modularisation, TRex consists of several plug-ins.

• Make sure that you have Java 5 language level enabled (in Window->Preferences.... Navigate via Java->Compiler to the Compiler Compliance Level settings, select 5.0 or higher and click OK).

• If you have enabled Build Automatically in the main menu Project section and our branched version of the ANTLR plugin for Eclipse is installed, TRex is now automatically built.
  • It may be possible that some red error marker are still displayed after the first automatic build. In this case, select all TRex projects in the Package Explorer and select from the main menu Project->Clean...->OK. This triggers a further automatical build which usually succeeds.
  • If you have disabled Build Automatically, you have to apply Build Project for all of the above TRex projects.
  • If you have not installed our branched version of the ANTLR plugin for Eclipse, but only the plain one from sourceforge, you have to compile the ANTLR *.g grammar files manually.

Starting TRex

Now, you are ready to start a second incarnation of Eclipse which runs the TRex plug-ins:

• Select the project de.ugoe.cs.swe.trex.ui in the Package Explorer.
• Select Run... from the main menu Run item or select the Run As item from the context menu of the Package Explorer:

• In the subsequent dialog, select Eclipse Application and click on the New button. (This icon may be hard to find: it is located on the left hand side in the upper part of the dialog. The more prominent identical icon on the right hand side is just to illustrate the provided instructions.)

• A new configuration is created. If you like, you can give it a new Name or change the Location of the Workspace Data (usually, you do not have to change the workspace location, but can use the one automatically suggested by Eclipse. By default, each configuration has an own workspace to seperate the different incarnations of Eclipse).

• Change to the Plug-ins tab and select Choose plug-ins and fragments to launch from the list. Take care that in the Workspace Plug-ins section, the TRex plug-ins you like to start (i.e. the ones you have checked out above) are selected. Take care that in the Target Platform section, the org.antlr.* plug-ins are deselected (otherwise, you might get a conflict with de.ugoe.cs.swe.trex.antlr).

• You may want to press Validate Plug-in Set to check that everything is fine (as shown below, you may get warnings that some fragments or plug-ins will be disabled; this is OK, since these are intended for other operating systems).

• To be able to edit large TTCN-3 test suites, you may want to add -Xmx512m to the VM arguments section of the Arguments tab.

• To support debugging, you may also want to add -consoleLog into the Program arguments section of the Arguments tab. Furthermore, in the Tracing tab you may enable tracing for the TRex plug-ins as shown below (to avoid beeing flooded with tracing information, deselect symbolresolver and all other plug-ins in particular the org.eclipse ones). When starting TRex you will then see debug output in the Console view of the hosting PDE Eclipse incarnation. It is always good to place both incarnations in a way that you can always see the Console view of the hosting PDE Eclipse incarnation, because then you will notice immediately any exceptions occuring in TRex.

• Finally, press Apply.
• Now, you are to press Run to start the second incarnation of Eclipse which runs the TRex plug-ins.

Alternatives to starting TRex via Run...

• If you like to start TRex with full product branding enabled, open the file trex.product from the de.ugoe.cs.swe.trex.ui plug-in in the Product Configuration Editor. As shown below, click in the Overview tab on Launch the product (Eclipse 3.2) or Launch the Eclipse Application (Eclipse 3.3) respectively. (This automatically selects the minimal set of required plug-ins.) If you are using a runtime JRE prior to 1.6, see the note below.

Note: If you are using a runtime JRE prior to version 1.6, you will get an exception when trying to launch. To circumvent this, you will need to do a few extra steps in order to get things working. First, follow the above instruction as you would normally do: By clicking on Launch a product, Eclipse automatically generates a new run configuration with the name trex.product. Choose Open Run Dialog... from the Run menu and select this configuration from the left pane. After this step, in the list box below of the the Workspace hierarchy, select all required TRex plug-ins for manually build. Next, click on Add required plug-ins. Locate and deselect the plug-ins named org.eclipse.jdt.compiler.apt and org.eclipse.jdt.compiler.tool. Finally, click on Validate Plug-ins. You should now get a notification that no problems were found. You can now confirm the changes by clicking on Apply.

• In order to avoid restarting the second incarnation of Eclipse after each change to the TRex sources, you may use Debug instead of Run/Launch to utilize the hot code replace functionality of Eclipse. (This only works for changes to Java source files, not for changes to XML configuration files. Furthermore, it works only for changing existing method bodies, but not for adding new methods or changing the signature of an existing method.)