# CRUSH Rebuild Guide for Developers

Author: Attila Kovacs <attila[AT]sigmyne.com>

Last updated: 6 January 2018


-------------------------------------------------------------------------

#### Table of Contents

1. __Introduction__

2. __Prerequisites__

3. __Rebuild Instructions__


-------------------------------------------------------------------------





## 1. Introduction

This is a simple guide meant for developers, who wish to modify and/or
rebuild CRUSH from the source code. 

As of version 2.40, the CRUSH source code -- including the `crushtools` and 
the `jnum` sub-packages, all configuration files, instrument data, shell 
wrappers, and documentation -- is distributed as a separate tarball or ZIP 
archive. You can find the source distributions at

    http://www.sigmyne.com/crush

under the _Download_ tab.




## 2. Prerequisites

### Java JDK

 You need a Java Developers Kit (JDK), 1.8.0 or later, containing the `javac`
 compiler. If you do not have javac on your system, grab a JDK e.g. from 
   
    java.oracle.com



### Apache ANT build system
  
 The CRUSH source package includes build files to use with the Apache Ant
 build system. If you don't already have Ant on your machine, you'll
 probably want to install it. You can find it at:

    ant.apache.org



### Dependencies

 CRUSH requires the excellent nom.tam.fits libraries both for (re)building
 and for running. Since the FITS libraries are an external dependence, they
 are not bundled with the source code of CRUSH. Grab a recent release
 (>= 1.15.0) from:

    https://github.com/nom-tam-fits/nom-tam-fits/releases

 Alternatively, the FITS libraries are also readily provided for Debian-based
 Linux distros (e.g. Ubuntu), altough these may not be the latest. You can
 install these via:

    > sudo apt-get install libfits-java




## 3. Rebuild Instructions

### 3.1. Unpack the source tarball
   
 Unpack the source tarball, e.g.

    > tar xzf crush-src-<version>.tar.gz

 (Subsitute the appropariate CRUSH version for `<version>`, e.g. `2.41-1`) 

 Now, go inside the freshly unpacked directory:

    > cd crush-src-<version>


### 3.2. Add build dependecies 

 Place `fits.jar` (the nom.tam.fits library) inside `deps/`. You may skip this 
 step on Linux if it is readily available as `/usr/share/java/fits.jar`. 


### 3.3. Compile

    > ant

 Note, that you might get an error about `JAVA_HOME` not being correctly set. 
 If necesssary, set `JAVA_HOME` to the main Java SDK folder (the one that has 
 `bin/` inside it containing `javac`) before running ant.

 This step will recompile the source code in `src/` and place binary jars
 into `dist/crush/lib`.

 The `crush` sub-directory inside the `dist` folder contains your own
 ready-to-go version of CRUSH.


### 3.4. Add runtime dependecies

 On Linux, if you have `fits.jar` and `commons-compress.jar` in 
 `/usr/share/java`, you can skip this step.

 Otherwise, copy/symlink `fits.jar` (the same one you used for compiling) into 
 `dist/crush/lib`.

 Optionally, for wider FITS compression support, copy/symlink 
 `commons-compress.jar` (Apache compression libraries) into `dist/crush/lib/`. 
 (Or, on Linux, you can simply install the `apache-commons-compress` package.)


### 3.5. Test

 Go into the `dist/crush` directory, e.g.:

    > cd dist/crush

 and run `crush` with your freshly minted JARs:

    > ./crush


### 3.6. Clean up 

 From the top of the unpacked source folder, run:

    > ant clean

 to remove the contents of the `build/` directory, which are no longer
 necessary after the binary JARs were created.


-----------------------------------------------------------------------------
Copyright (C)2018 -- Attila Kovacs