Getting started with HIPE development

This tutorial will teach you the following:

  1. How to obtain the source code of HIPE.
  2. How to use the Eclipse development environment to modify a component of HIPE.
  3. How to put back the modified component into HIPE to see the result of your changes.

Getting HIPE source code

You can get HIPE source code in two ways:

  • If you are installing a user release, select the Advanced installation and make sure that the option Would you like to have the source code installer? is checked (see figure below).
  • If you are downloading a developer build from the Continuous Integration System, run the installer with the option --src=yes or --developer (--developer implies --src=yes).

FIXME insert figure.

You can find the source code in the same repository that contains HIPE binary files. It resides by default in the .hcss.d directory within your home directory.

In this tutorial you will make a tiny (but highly visible) change in the ia_gui_apps module. Go to this directory:


This directory contains one or more further subdirectories, each representing a version number of the module. For example:

1.153.4  1.193.4  1.220  1.221

If you install or update HIPE often you will likely have several entries. How do you find out which one corresponds to a certain HIPE version? Go to your HIPE installation directory and open the installed.userlibraries file. Search for ia_gui_apps and you will find an entry similar to the following:

<archive path="/home/drizzo/.hcss.d/repository/modules/hcss/ia_gui_apps/1.220/ia_gui_apps_1.220.jar"/>

This tells you that the right directory is 1.220. Among the files in this directory, is the one containing the source.

Installing and configuring Eclipse

Now that you have the source, you need to set up the tools to modify it. We strongly recommend you use the Eclipse development environment. Besides being free and multi-platform, it has the crucial advantage of some Herschel-specific plugins that will make your life much easier.

To download Eclipse, go to and choose Eclipse IDE for Java Developers from the download page. This tutorial was written using Eclipse 3.5 (Galileo).

After installing Eclipse, install the HCSS Project plugin by following these steps:

  1. In Eclipse, choose Help --> Install New Software.
  2. In the Install window, click Add. The Add Site dialogue opens. Write in the Location field and any name you like in the Name field. Click OK.
  3. Check the Uncategorized entry that has appeared in the Install window, and click Next. Follow the instructions on screen to complete the installation.

Creating an Eclipse project

First you have to unpack the source code. Create a directory to contain it, named for example ia_gui_apps, and a main subdirectory. In Linux thsi would be the command to issue:

mkdir -p ia_gui_apps/main

Unpack the zip file containing the ia_gui_apps source in the main directory.

Start Eclipse and choose File --> New --> Java Project. The New Java Project dialogue appears. Write any name you like in the Project name field. In the Contents pane, select Create project from existing source. Then click Browse and select the ia_gui_apps directory that contains the sources. Click Finish.

The project is created, and immediately gives an avalanche of errors, visible as little red icons in the Package Explorer view. This is normal, because Eclipse cannot yet find the auxiliary components it needs to build the project.

Choose Project --> Properties. The properties dialogue appears. Go to the Java Build Path section and select the Libraries tab. Click Add library. The Add Library dialogue appears. Select HCSS Project Container from the list (this is the plugin you installed earlier) and click Next. You can now configure the plugin by setting the following fields:

  • Project: projects are listed in the Developer Tracks pages of the Continuous Integration system, and have names such as hcss.dp.core. If you are developing for the core system only (no instrument-specific software) write hcss.dp.core. If you are developing for an instrument, write one of hcss.dp.hihi, hcss.dp.pacs and hcss.dp.spire. Since ia_gui_apps is part of the core system, you can write hcss.dp.core for this tutorial.
  • Track: corresponds to the major version of HIPE you are developing for. Write 3.0, 4.0 or whatever version of HIPE you have installed. You can check by choosing Help --> About in HIPE. If you see for example 4.0.375 you have to write 4.0 in this field.
  • Build: you can choose to download a specific build or click Fetch latest to get the most recent one for the major version you have selected. For this tutorial, to achieve maximum compatibility, write the build number corresponding to the HIPE version you have installed (375 in the example above).
  • Build Updates: in this page you can choose how often Eclipse will look for and install updated builds. The default is not to look for updates.

Click Finish once you are done. Eclipse downloads the necessary files and builds the project. All the red error icons should disappear.

Modifying the source

You will not change any Java or Jython code in this tutorial, but just an HTML file. The point of the tutorial is to show how to incorporate your changes back into HIPE.

In the Package Explorer view of Eclipse, open the node herschel.ia.gui.apps.views.welcome.contents. Right click on welcome.html and choose Open With --> Text Editor from the context menu. This is the page that is displayed in the Welcome view of HIPE.

Change the following line to anything you like:

<h1>Welcome to Herschel Interactive Processing Environment!</h1>

Just a suggestion:

<h1>Welcome to Sputnik Interactive Processing Environment!</h1>

Save the file.

Creating a JAR file

JAR (Java ARchive) files are the building blocks HIPE is made of. You now have to create a JAR file with your modified ia_gui_apps module.

Right click on the project name and choose Export from the context menu. The Export dialogue appears. Select Java --> JAR file and click Next. The JAR Export dialogue appears.

Write a name in the JAR file field, for example ia_gui_apps_new.jar. You can leave all the other settings unchanged. Click Finish. Your JAR file is created in the directory where Eclipse project are stored (workspace is the default name).

Including the changes into HIPE

Now you need to tell HIPE to look for your JAR file. You do this by editing the installed.userlibraries file in your HIPE installation directory. Open the file in your favourite editor and insert the following line as the first <archive path line, just below the <library name line:

<archive path="/home/username/workspace/ia_gui_apps_new.jar"/>

You should of course put the correct path and name of your JAR file. Save the file and start HIPE. You should see your change.


You can follow the same pattern to change any HIPE component. In the next tutorial you will learn how to write a simple Task and include it in HIPE.

-- DavideRizzo - 30 Apr 2010

Edit | Attach | Watch | Print version | History: r14 | r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r2 - 2010-04-30 - DavideRizzo
This site is powered by the TWiki collaboration platform Powered by Perl