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 have 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, since we will use a target platform it is possible to use also the latest available Eclipse version.

First step is to download a valid Eclipse version from the main website or from the archive one.

Second step once Eclipse is started is to configure the Target Platform we will use for development. You can get it here from the dedicated Sourceforge project page. Right now as we said the zip file (i.e: jss382TargetPlatform.zip) is packaged based upon the Eclipse 3.8.2. In the next future when transitioning to Eclipse 4 we will probably have a different one.

Unpack the downloaded zip file to a specific location and proceed to create a new target platform from the dedicated Preference page.

Choose from the wizard "Nothing: Start with an empty target definition". Proceed adding the previously extracted folder. 

Be sure to select the just created target definition and to apply changes before closing the Preferences dialog.

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. Anonymous credentials are anonsvn / anonsvn. You can use TortoiseSVN or any other standalone client you prefer. Anyhow we strongly advice to install a dedicated Eclipse plug-in either Subclipse or Subversive.

NOTE: For the sake of simplicity we prepared two Team Project Set (*.psf) files for Subclipse available here. One can be used to just test the plug-in version of Jaspersoft Studio, the other one can be used to create a "custom" RCP product. In this way you can easily import the needed projects using the wizard available at File > Import > Team > "Team Project Set". Alternatively you can simply checkout all the projects on the two repository trunks.

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.

Example VM Arguments extracted from the Jaspersoft Studio product file.

-Xms128m
-Xmx1024m
-XX:PermSize=128M
-XX:MaxPermSize=256M
-XX:+CMSClassUnloadingEnabled
-XX:+UseConcMarkSweepGC
-Dfile.encoding=UTF-8
-Djava.net.preferIPv4Stack=true

Building Jaspersoft Studio using Tycho.

In order to build your own version of Jaspersoft Studio you need to be sure to have a properly installed and configured Maven instance.
The build process is performed via Tycho, an Eclipse project that allows to build plugins, features and products using Maven. This is a much more smooth and simple way to build compared to the old PDE-build mechanism.

A bunch of additional information should be put in the .m2/settings.xml configuration file.
These are the mandatory properties you should have inside your default profile, or the one you are planning to use for building Studio.

<!-- SAMPLE PROPERTIES -->
<!-- Local Repository with the target platform for building -->
<targetplatform.repo>/tmp/developmentTests/jss382TargetRepo</targetplatform.repo>
<!-- Location for JRE packages-->
<jre.packages.location>/tmp/developmentTests/jre-packages</jre.packages.location>

The first property targetplatform.repo references the location of the P2 target repository used by Maven Tycho to build.
The second property jre.packages.location references the location of the JRE packages (.zip files) that will be automatically bundled in the final product.

These files can be found at the same location where is the target platform previously downloaded. Simply extract the target repository and copy the JRE zip packages to a dedicated folder.

Once everything is set up, you should access via console/terminal to the aggregator project location.
Just enter the command mvn clean package in order to trigger the build of products. After some minutes you should see a similar result.

This means that the build completed successfully. After that you should be able to locate .zip packages of the products inside the project folder com.jaspersoft.studio.rcp.product/target/products/. These are ready-to-use installations for the different platforms.

If you want also to produce also the dedicated installers, you should proceed with the next section.

Packaging Jaspersoft Studio: how to create the installers.

As you may already know 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 and deb packages)
  • MacOSX 64bit (dmg installer)
  • Windows 32/64bit (exe installer)

In order to package the RCP distributions we need to invoke the aggregator/ant-scripts/packageDistributions.xml ANT script.

Before proceeding see this checklist:

  • be sure to have Apache ANT installed. You should also enrich its lib folder with the additional jars:
    • ant-contrib: you can take the ant-contrib-1.0b3.jar file
    • jsch: you can take the jsch-0.1.51.jar file
  • 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. With the latest Mac OS X versions you should probably install it via homebrew. Macports appears to have existing issues.
    NSIS also requires some additional plugins in order to work fine:

Please note that for 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=/tmp/jss-build

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

Last step is to open the console/terminal at the following folder location aggregator/ant-scripts/ and run the command ant -f packageDistributions.xml.

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: updating the target platform and target repository.

At some point it could be necessary to add more plugins in the dependencies of the existing ones in the workspace. This means that we need to enlarge the currnet target platform used to develop and run our Jaspersoft Studio custom installation. This can be done through the dedicated Preference page and dialog.

However once modified we should re-create the P2 target repository from it. First step is to export the target defintion we are currently using via the proper wizard dialog File > Export > Plug-in Development > Target definition. Once done, we should enter a similar command in console:

./eclipse -debug -consolelog -nosplash -verbose \
-application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher \
-metadataRepository file:/tmp/customTargetRepository \
-artifactRepository file:
/tmp/customTargetRepository \
-source /tmp/customTargetPlatform -compress -append -publishArtifacts

At the end we can replace the target repository with the fresh new one.

Feedback
randomness