Contributing to Jaspersoft Studio and building from sources

Overview

The purpose of this page is to show how to contribute to Jaspersoft Studio project and configure a fully functional working environment in order to do it.

Prepare your working environment - part 1: IDE setup.

The first thing to do before checking out the code from repository is to setup your Eclipse installation in order to an IDE configuration with all the required plug-ins to start developing.

Currently Jaspersoft Studio RCP version is based on Eclipse 3.8.2. Therefore the suggested IDE is this one.
However we will provide here information also on how to develop using the latest Eclipse version: Juno SR2 4.3.1.

First step is to download a valid Eclipse version:

After the first launch, you can use the Eclipse feature, available since Indigo, that enables the user to import/export software configuration.
We already prepared a dedicated p2f file that allows you to do this, for both 3.8.2 and 4.3.1 version.
Once downloaded, you can launch the wizard File > Import > Install > "Install Software Items from File" and select the file. (Note: check "Contact all update sites during install to find required software" and uncheck "Install latest version of selected software.".

You will see a similar wizard page:

The main features that will be installed may be different from Eclipse versions. So it's better to stick to the ones proposed in the correct p2f file. We usually keep them updated at the following location

Prepare your working environment - part 2: get the sources.

Now it's time to download the source code from the repositories. 
The current public repositories containing the Jaspersoft Studio source code are located here:

You can get the sources from SVN using your method of choice. You can use TortoiseSVN or any other standalone client you prefer. Otherwise you can do it directly by using an Eclipse dedicated plug-in either Subclipse or Subversive.

NOTE: For the sake of simplicity we prepared two Team Project Set (*.psf) files for Subclipse: one for 3.8.2 and another one for 4.3.1.

In this way you can easily import the needed projects using the wizard available at File > Import > Team > "Team Project Set".

Prepare your working environment - part 3: launch configuration creation.

After sources building, you have all you need to start coding and modifying/fixing Jaspersoft Studio.  To see how your modification affect the application you can create a launch configuration to run/debug and test everything is fine.

To create a launch configuration just open the dialog Run > "Run configurations". Now you can enter the name for your configuration. You can leave the selected default information, or just in case change some default memory settings from the Arguments tab.

Packaging Jaspersoft Studio: create the distributions.

NOTE: As we already stated, the actual product is built on top of the Eclipse 3.8 platform. So this information is valid only if you are using the Eclipse 3.8 version.

In previous sections we saw how to configure a fully working environment in order to extend Jaspersoft Studio. We focused on the "plug-in version" of Jaspersoft Studio.

However, you may already know that Jaspersoft Studio is made available as standalone RCP product for different platforms.
At the moment we produce packages for the following operating system configurations:

  • Linux 32/64bit (tar.gz package)
  • MacOSX 64bit (dmg installer)
  • Windows 32/64bit (exe installer)

Previously we used Eclipse PDE-build to create the product versions. However recently we introduced Tycho in order to build Jaspersoft Studio using Maven.
This allowed us to have a more clean and simple infrastructure to maintain.

It's not purpose of this tutorial give you an introduction to either Maven or Tycho, however it's enough for the user to know that every feature and plug-in contains in its root folder a dedicated pom.xml file. Plus we created a master project that is directly or indirectly referenced by all the other ones.

This project is the aggregator one, also located on the Jaspersoft Studio repository trunk.

In order to build the product you will need to produce a local repository starting from the current target platform used for the RCP version (right now 3.8.2).
After downloading and unpacking the zip file, you can use a similar command from console in order to create the local repository to a location of your choice.

./eclipse  -debug -consolelog -nosplash -verbose \
-application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher \
-metadataRepository file:/Users/mrabbi/dev/jaspersoftstudio/localrepo/jss382target \
-artifactRepository file:/Users/mrabbi/
dev/jaspersoftstudio/localrepo/jss382target \
-source /Users/mrabbi/
dev/jaspersoftstudio/targetPlatforms/jss_382 -compress -append -publishArtifacts

If you give a look at the aggregator/pom.xml you will notice the usage of a ${targetplatform.repo} property. Therefore be sure that in your Maven settings.xml file this corresponds to the previously created local repository.

You can now proceed with the creation of the product versions of Jaspersoft Studio using the command 

mvn clean package

from command line inside the aggregator project folder. After the procedure has completed you should see a similar screen:

Last step missing is the packaging of the RCP distributions. For this purpose the aggregator/ant-scripts/packageDistributions.xml should be invoked. 

Please be sure to have the NSIS (Nullsoft Scriptable Install System) installed in your system if you want to create the Windows installers. It is available for all the most common platforms including Windows, Linux and Mac: refer to the project home page.

Moreover, in order to create the Mac installer, you need to add a file inside aggregator/ant-scripts/ called authenticationInfo.properties containing the following properties:

 dmg.sshhost=my_mac_machine dmg.sshuser=myuser dmg.sshpass=mypassword dmg.sshroot=/home/myuser

This information is used to access via ssh a Mac machine to create the DMG disk image for Mac OS X.

After that you can do right click on the packageDistributions.xml file and press the Run As > Ant Build menu item.

After the task has concluded you will have the following kind of packages inside the aggregator/product/dist folder:

  • .exe installers for both Windows 32-bit and 64-bit
  • .tgz packages for both Linux 32-bit and 64-bit
  • .deb packages for both Linux 32-bit and 64-bit
  • .dmg package for Mac OS X 64-bit

Extra: creating a launch configuration to test the product.

Previously we saw how to create a launch configuration for testing modification/extensions to plug-ins. However it can be useful, also to test how it will look like our RCP product. This of course requires to have an Eclipse 3.8 environment.

The quickest way is to open the jaspersoftstudio.product file located inside the com.jaspersoft.studio.rcp plug-in. Then you will simply need to click on the "Run" or "Debug" icons in order to launch the product. This will automatically add also a new entry among yours "Run/Debug configurations".

You can edit this newly created configuration adding your additional plugins, by modifying the items selected inside the "Plug-ins" section of your Launch Configuration.

Extra: using the dedicated target platforms.

In order to make the developer's life more easy we prepared different target platforms that can be imported into an existing Eclipse installation and allows the user to start coding and testing more quickly. These zipped target platforms are downloadable from the dedicated Sourceforge page

The developer can import them via Preferences > Plug-in Development > Target Platform section. 

Having them all, allows to verify if all the code produced actually compiles on 3.6 / 3.7 / 3.8 / 4. 2/ 4.3.1, that right now are the Eclipse versions supported.
Besides it allows to test that the plug-in version of JSS works fine on every Eclipse version currently supported.

Feedback
randomness