Starlink / starjava

Java applications initially developed for the Starlink Project but now developed independently
Other
85 stars 23 forks source link
astronomy java
        Quick Start for the Starlink JAVA build system
        ==============================================

Prerequisites

First make sure you have a 1.8.x (a.k.a. Java 8) or later JDK available. Downloads are available from:

http://www.oracle.com/downloads

At present all development is performed with version 1.8.x as the target platform. Note we cannot distribute the SDK for licensing reasons.

You will also need to have JAI installed as part of the SDK. JAI is the "Java Advanced Imaging API" which is currently part of SUNs "Desktop Java". The version of JAI being used can be determined from the README-jai.txt file in the Starlink JRE package (see the /star/java/jre directory).

Now define STAR_JAVA to point at the "java" command of this:

setenv STAR_JAVA /some/where/jdk1.x.x/bin/java

Alternatively install the SDK into /star/java.

You do not need to have a Starlink classic system installed, before you can build the Java tools. Several of the Java applications use JNIHDS and JNIAST, which rely on native libraries to do their work. However the repository contains precompiled binaries of these libraries, for several platforms (see, for example, jniast/src/lib), and these are maintained by the appropriate developers. If you are not on one of these platforms, you will have to be more creative (perhaps talk to the stardev mailing list). SPLAT also uses its own JNI code, for efficiency, but if there is no classic system available, it should simply fail quietly, and proceed to access NDFs using the native code of the JNIHDS library.

Build ANT

Since it's been necessary to add some extension tasks to ANT you need to use the local release. To do this look in the "ant" directory and follow the instructions in the "README.Starlink" file.

If you already have a STARJAVA installation you may be able to use the ANT script found in the /star/starjava/bin directory, but if ANT reports that it is finding unexpected elements in the build files you will need to rebuild ANT. Other oddities when rebuilding ANT may be because you are picking up elements from an existing installation. To avoid this clear out the old version completely, or install into a different directory.

Start using the new ANT

If you have built and installed ANT you now need to add the "java/bin" directory that you should have created to your PATH (this the directory that is now equivalent to "/star/bin" and would eventually be "/star/starjava/bin" if released as part of the current system). You need the new "ant" command to get our extensions and to use JUnit.

If ANT is not finding the local extensions, it may be reading the ANT_HOME environment variable indicating another installation. In this case the ANT_HOME environment variable should be unset.

Perform the build

Just type:

% ant build

in the top-level "source" directory, and wait a while. This recurses into each of the package subdirectories and performs "ant build" on each package. If it reports that you cannot compile the Java files, make sure that the SDK is on your PATH (a javac command is required).

If you have a classic Starlink installation that is not installed in /star, you will need to re-define the ANT property "stardev". If we assume the new root is "/star-local", then the simplest way to do this is just to use -Dstardev=/star-local on the command-line:

% ant -Dstardev=/star-local

Alternatively, if you expect to do this a lot, define the value in the file $HOME/.stardev.properties, in which you should put the single line:

stardev=/star-local

Other ANT properties can be added on additional lines. In particular, you might want to set star.dir, which is the location where the Java applications will be installed; it defaults to the parent of this directory, but you may wish to redefine it to something like /star-local/java

Install everything

% ant install

Test the installation

If this all worked you should now be able to type:

% ../bin/treeview

To use the applications FROG, SPLAT, SoG, TOPCAT and TREEVIEW you need to run the various scripts found in the sub-directories of ../bin (if you have STARJAVA already installed check the environment variables and aliases and re-define these as appropriate).

Relationship with the Starlink Software Collection

If you have the Starlink Software Collection installed on your machine then STARJAVA should usually be installed into the "starjava" directory of that. That will have the effect of setting up the STARJAVA commands as part of the normal initialisations (that is the STARJAVA bin directory will be placed on the PATH, and various aliases will be established for the commands located in sub-directories, when you source the "etc/login" and "etc/cshrc" scripts).

To install STARJAVA elsewhere and still make use of the standard initialisations you will need to build and install the Starlink "init" package (which can also be downloaded from github, although normally you would do this as part of a complete build of the Starlink from source) and make it using a command like:

make STARJAVADIR=/my/starjava

where naturally "/my/starjava" is your STARJAVA installation directory.

Source Code

The starjava source code repository can be viewed at

https://github.com/Starlink/starjava

and checked out of its Git repository by doing

git clone git://github.com/Starlink/starjava.git

Peter W. Draper 13-APR-2016 (p.w.draper@durham.ac.uk)