[Overview]

HCSS Software Installation for Developers

The new builds install themselves with a small installer. This installer is a command-line tool that installs any given project for any available track and build.

Quick Start

  1. download Download and unzip the latest installer
  2. Ensure you have an appropriate Java version installed.
  3. In a terminal, run for example:
    hcss.installer hcss 8.0 225
    The same way you can install a different project than project hcss. For a complete overview of available projects tracks and builds, have a look at the Overview.
    If you are wondering about installation options, please read the section Installing Projects below. The following command gives you a quick summary:
    hcss.installer --help
  4. Launch hipe by executing:
    hcss-8.0.225/bin/hipe
    The rest of the story you can find below and in the other help pages accessible on the build page.

Contents

Features

Some of its features are:

It is still rough on the edges, and by no means it replaces the singing and dancing installer for User Releases. It simply provides the means to have a simple light-weight installer for developers:

Also note, that documentation is built infrequently and only the online documentation is considered (no PDF documents) for several reasons.

Requirements

Download

download Download the latest installer.

To use the new builds, you need to download and install the HCSS installer once. It is important that you download and unzip the installer in a writable location. Otherwise it can not refresh itself whenever a new version of the installer itself becomes available.

A writable location on your hard-disk, both for the installer as well as the builds that you will be downloading through the installer. Something of 2GB of free disk space should do the trick;

Java Requirements

The java command on your console needs to point to a Oracle/SUN JVM compatible Java 7 (try: java -version). Every build is created against a specific Java patch version; you can find that information in the build page of the project you wish to install.
See e.g. the Requires section in hcss-8.0.225 build page.

The developer installer informally supports platforms such as Microsoft Windows (x86, x86_64), Linux variants (x86, x86_64), MacOS X (x86_64), Oracle/Sun Solaris (sparc, sparcv9). Formally supported operating systems are listed here.

Please note that MacOS X user will get a fully installed system, but anything to do with Versant enhanced classes will not work at run-time. This is not a limitation of the installer, but a result of the fact that Versant does not provide Versant specific native libraries on MacOS X. Users should not worry that they are missing out on something; Versant is only used as part of internal operations.

Linux, Solaris and MacOS X users

Unpack the ZIP file in a convenient and writable location (e.g. ${HOME}/bin).

Windows users

Unpack the ZIP file in a convenient and writable location (e.g. %HOMEPATH%/builds).
Open a console. On Windows this can be achieved by clicking on the Start button and typing in the Start Search field: CMD.EXE and pressing ENTER.

Installing Projects

To get an impression of available projects builds for the various tracks, please have a look at the build page.
This section explains how to download and install these builds.

Default Installation

Now you've got the installer on your platform, you can download any project as follows:

Unix users (assuming the installer is in your PATH):

hcss.installer hcss 8.0 225

Windows (assuming the installer is in your PATH):

hcss.installer.bat hcss 8.0 225

This will install the above project in your current directory under hcss-8.0.225.

Installation Options

A list of all available options you will get with:

hcss.installer --help

Example: A developer may also want to have the sources of both the main tree as well as the parallel test tree available in Eclipse as well as the precompiled binaries of the test tree:

hcss.installer --test=yes --src=yes hcss 8.0 225

Example: If you want the sources unpacked in the installation tree:

hcss.installer --src=yes --unpack=yes hcss 8.0 225

Using an installed project

Running HCSS applications

Once installed, you simply run HIPE by executing the command:

./hcss-8.0.225/bin/hipe

You can also simply browse to the bin folder and double-click on hipe.

It should work out of the box; that is no CLASSPATH, PATH or the like. In fact you may want to revisit your environment, to see whether these are not pointing to an old installation!

Importing libraries into Eclipse

In the project folder you will find a file called installed.userlibraries. You can import that file into Eclipse as a User Library:

Now you have access to all JAR files as well as their native libraries. If you have selected the --developer option during installation, you will have the test binaries as well as the associated source code attached to those binaries.

Uninstalling Projects

Installed projects can be simply uninstalled by removing the directory.

Cluster Installation

You can provide a cluster wide installation by ensuring both installation directories as well as the repository cache are accessible by e.g. a shared mount point in your cluster. Things to take into account are:

The example below assumes that all software versions are installed in /share/hcss and that the commands are given in bash.

Installer

To keep everything together, it is convenient to unpack the installer in the same cluster area:

$ installerdir=/share/hcss/installer
$ mkdir -p $installerdir
$ cd $installerdir
$ unzip hcss.installer.zip

OS and Architecture

An HCSS software installation is Operating System and Hardware Architecture specific.
It is recommended to reflect this information in the directory structure you provide to your users:

# osarch=/share/hcss/linux-x86
# osarch=/share/hcss/sunos-sparc
# osarch=/share/hcss/sunos-sparcv9
# osarch=/share/hcss/windows-x86
# osarch=/share/hcss/windows-x86_64
$ osarch=/share/hcss/linux-x86_64
$ mkdir -p $osarch

Cached repository

The repository can be shared across the various combinations of OS/Arch specific installations though:

$ cache=/share/hcss/repository
$ mkdir -p $cache

Software installation

Assuming your path is pointing to the appropriate Java 6 Update 13 at a minimum (and valid to yourOS/Arch), you can now proceed installing the software:

$ cd $osarch
$ $installerdir/hcss.installer --doc=yes --src=yes --cache=$cache hcss 1.2 1750

Running the installer without arguments gives you the full list of options.

Software configuration

The installation comes with a default configuration <hcss>/installed.properties. You should overwrite this file to provide your users with the default properties which are specific to your site.
This can be done in one go for all installations as follows:

# assuming that the site properties file is called:
$ properties=/share/hcss/site.properties
$ for n in $osarch/*/installed.properties ; do rm $n && ln -s $properties $n ; done

Where did my ... go?

Downloads

All downloads end up in a cache directory. This is usually called .hcss.d/repository and lives in your home directory.
If you do not like that, you can always explictly set it with the --cache=alternative-dir option.

Be careful: Deleting the cache directory will make all installed projects invalid! You will have to delete those projects and re-install the ones that you wanted to keep in the first place.

Reference Platform

The reference platform is kind of 'gone'. The installer will download all the necessities for your specific operating system (Mac OsX, Windows, Linux, Solaris) and architecture (32/64bit, sparc, intel) only.

class path

You do not need a class path environment variable anymore. The applications are automatically constructing the class-path on the fly, by reading the installed.userlibraries file.
However, if you do set that environment variable, the application will respect it and read it prior to the installed.userlibraries file

native library path

You do not need a LD_LIBRARY_PATH (or windows equivalent) environment variable anymore. The applications are automatically finding appropriate native libraries on the fly, by reading the installed.userlibraries.
However, if you do set that environment variable, the application will respect it and read it prior to the installed.userlibraries file

VERSANT_ROOT

In most cases (you are a pure client of the Versant service), the installation is making sure that this Versant specific environment variable is set-up properly.

Due to the way the internals of Versant work, we found some specific situations where you still have to set this environment variable yourself:

Either way, if you have set this environment variable yourself, the HCSS applications will notify this by a message:

WARNING: Environment variable [VERSANT_ROOT] already set by you to
[/path/to/versant/server/root].
Trust you know what you are doing!

PATH

Applications can work out of the box, so there is no need to hard-code the locations of the binaries. You are free to do so anyway, of course.

lib directory

The installed project does not contain a lib directory, but if you read the installed.userlibraries file, you will understand where the actual JAR files are residing.

The installer is keeping notion of what you already have downloaded (to avoid massive daily downloads as we are currently experiencing with the so-called old-style and new-style builds); this is done in the so-called repository on your local system.
Therefore JAR files can be shared across different versions of e.g. DP-HIFI and thus it is not needed to copy them over to the specific installation directory.

The repository can be found under $HOME/.hcss.d/repository in UNIX systems and under %HOMEPATH%/.hcss.d/repository in Windows.

How to

Use property files

By default any application within the installation is can be controlled with the following (in order of preference) property files:

  1. <HOME>/.hcss/application.props
  2. <HOME>/.hcss/user.props
  3. <HCSS_PROPS> (used by the actual application, but not by the launcher!)
  4. /etc/hcss/installed.properties
  5. <INSTALLATION>/installed.properties

Note that the HCSS_PROPS is an environment variable holding one or more property files separated by the Operating System dependent path-separator. It is primarily intended for developers and or customised/exotic installations to pass on (temporary) properties. It can not be used to pass the java virtual machine options that are explained below.

Also note that the system can differentiate between options specific to one application only. That is, given the name (title) of the application, you can set-up a property file specific to that application.

Increase memory

The installation preset memory requirements an application (as found in <INSTALLATION>/installed.properties):

   java.vm.memory.min=64m   # minimum memory reserved for heap space
   java.vm.memory.max=512m  # maximum memory reserved for heap space
   java.vm.memory.perm.min=32m  # minimum memory reserved for permanent data
                                # (class definitions, ...)
   java.vm.memory.perm.max=128m # maximum memory reserved for permanent data

You can change/override these defaults in any of the property files, bearing in mind the order of preference of those property files as explained before.

Other Java options

Though our reference platform dictates SUN Java SE, we recognise that people may want to use other Java Virtual Machines. However Java options are not standarised. Therefore we also provide the means to specify any other options with the property java.vm.options. It can take any additional number of java options seperated by spaces, e.g.:

   java.vm.options = -XX:PermSize=512m -Xincgc

You can change/override these defaults in any of the property files, bearing in mind the order of preference of those property files as explained before.


Last update of this page: 2012-04-24 13:00 CEST