2 - How to install SquashTM project into Eclipse

Workstation prerequisites

You need to have installed on your computer :

• • a JDK 1.6

  • maven 3

You should also dedicate memory space to maven builds by setting the MAVEN_OPTS system variable to -Xmx512m -XX:MaxPermSize=128m

A "tail" software such as Bare Tail is useful

Installing Mercurial

You will need a Mercurial client. We use the TortoiseHg rather than the MercurialEclipse plug-in.

You may also want a three-way merge tool, such as Diffuse and configure Mercurial to use it. If you use TortioseHg, it can be done in the Workbench settings.

Installing Eclipse

Download and install Eclipse for Java EE developpers, version 4.2 (Juno)

Plug-ins

Install these plug-ins through Marketplace or up to date sites such as :

• • m2e (Maven integration)

  • Groovy

  • Groovy - m2e integration : make sure this plug-in, which is available with Groovy-eclipse, is installed

  • Eclipse ResourceBundle Editor, available through the third party update site : http://dev.nightlabs.org/updatesites/development/

  • m2e connector for wro4j (updatesite)

You may also want to install :

• • SpringIDE to edit Spring xml files

  • Bndtools, which has a useful editor for .bnd files. We personally do not use its other features.

Configuration

In the eclipse.ini, on the top of the file, you need to add

-vm

<path to the jdk>/bin/javaw.exe

Use the Groovy 2.0 compiler : Window > Preferences > Groovy

Importing a project into workspace

Cloning the repository

Using Mercurial CLI (or TortoiseHg), clone the Squash TM repository in your eclipse workspace, then run a full maven build :

> cd myeclipseworkspace

> hg clone https://bitbucket.org/nx/squashtest-tm

> cd squashtest-tm

> mvn clean install -DskipTests

> cd provision

> mvn clean install -DskipTests

Importing the project modules into Eclipse

Start Eclipse, File > Import > Maven > Existing Maven Projects. For a start, you can import :

• • The root module

  • core/core.web

  • core/core.service

  • tm/tm.web

  • tm/tm.service

M2e may prompt you for installing connectors. In that case, proceed with the installation.

When the modules are imported, check that they are not of AspectJ nature, which might appear on core.service and tm.service modules : right-click each modules. If you see an AspectJ sub-menu, then open it and select [Remove AspectJ nature]

Finally, in each module, check the .settings folder using either Eclipse's Navigator view, or an explorer. Look for files named org.eclipse.pde.*.prefs and delete them. Then restart Eclipse. These files are automatically generated by m2e and might pop up again if you update a modules maven configuration. They configure Eclipse's OSGi runtime platform in a way which prevents Squash TM to start.

Configuring OSGi runtime

Technically speaking, the application that Eclipse will actually start is Equinox, an OSGI container in which Squash will execute. Squash requires two main things :

• • the java dependencies,

  • an access to some ressources of its environment (e.g. config files)

And we will here configure Equinox in order to provide those requirements.

The module provision fetches the dependencies, replace placeholders in the configuration files, create the database and gather everything in one place. You can build it as usual with mvn install.

Once the module provision is built, you can configure Equinox. Go to window>preference>plug-in development>target platform, and create a new entry named Squash (or whichever name you want). You need to start with an empty definition. On the location tab, click on [Add] and select the directory squashtest-tm/provision/target/eclipse-provision/bundles : those are all the dependencies Squash will need at runtime. Then, on the Argument tab you can add the following elements :

• • Program Arguments :

-os ${target.os} -ws ${target.ws} -arch ${target.arch} -nl ${target.nl} -consoleLog -console

• • VM arguments :

-Declipse.ignoreApp=true

-Dosgi.noShutdown=true

-Dorg.osgi.framework.system.packages.extra=com.sun.org.apache.xalan.internal.res,com.sun.org.apache.xml.internal.utils,

com.sun.org.apache.xpath.internal,com.sun.org.apache.xpath.internal.jaxp,com.sun.org.apache.xpath.internal.objects,com.sun.javadoc,

com.sun.tools.javadoc,javax.xml.namespace

-Dbundles.configuration.location="${workspace_loc}/squashtest-tm/provision/target/config"

-Dorg.osgi.service.http.port=9090

-Dorg.osgi.service.http.port.secure=9443

Once you have configured your platform, click on [Confirm]. Finally, tick the checkbox before your new platform definition to make it default.

Creating the run configuration

The run configuration instruct Eclipse how to run Squash via Equinox. Go to run>run configuration>OSGI framework and then hit [new]. The new run configuration will display all the bundles (jars) loaded for this run configuration. The main panel shows two sections : 'Workspace' and 'Platform'. The bundles listed in the 'Platform' section are inherited from the OSGI runtime you configured during the previous step. The bundles listed in the 'Workspace' section are the projects you imported in Eclipse : core.service, core.web, tm.service and tm.web (Note : if you cannot see your bundles in that list, read below).

Tick/untick the boxes to activate/deactivate the bundles you need. In particular, check that no bundle was activated twice - none of them should be ticked in both the 'Workspace' and 'Platform' section at the same time.

It is also better to set the start level of a few strategic bundles :

• • org.apache.felix.configadmin : 2

  • org.springframework.osgi.core : 2

  • org.springframework.context : 3

  • org.springframework.osgi.web.extender : 5

  • the rest : 4

The button 'Validate' shows which bundles cannot be solved, and which packages are missing for a complete classpath resolution. Normally at this point, only the bundle com.springsource.javax.servlet.jsp.jstl should be listed as unsolved : indeed, the missing one will be loaded using the VM arguments, not from the activated bundles.

If you made it until here, then your development environment is complete and ready to run : hitting [run] will start Squash. The logs will be created in <eclipse install directory>/logs/.

Troubleshooting : Eclipse build vs m2e build

The file META-INF/manifest.mf is especially critical. The maven build of each project (ie core.service, tm.service etc) is configured to create it properly, and then copy the META-INF directory at the root of their project. Eclipse actually expects to read the manifests at this location, and when no valid manifest is available, it will not add your project to the run configuration.

Problems may arise with older versions of Eclipse. With Eclipse 3.6 for instance, Eclipse and Maven compete against each other for the generation of the manifest. Most of the time, though, Eclipse wins and puts the wrong manifest in the META-INF. If this is too annoying for you, a definitive solution is to open all your .project and empty the <buildSpec/> tags. The drawback is, of course, that you loose part of the support of Eclipse and you will have to manually compile your projects.