sit/README.md

# Software Installation Tool (SIT)

## About
SIT is a simple software installation tool inspired by Gentoo's emerge script.
It eases the installation process and helps to prevent errors during the
installation. Further sit helps with documenting software installations
by generating log files from the installation process, which are installed
along the software package itself.

## Getting started

### Basic usage

In its current version sit can only install a package using a package class file
including the necessary information.

The package tree resides per default in the directory `$SIT_PATH/packages`. For
convenience it should look like follows:
```shell
  $SIT_PATH/packages/CATEGORY/PACKAGE/PACKAGE-VERSION
```

The global configuration file of SIT is `$SIT_PATH/etc/sit.conf`.  It includes
a variety of default values:
* PREFIX_BASE
* SRC_POOL
* SCLASS_DIR
* DEFAULT_PLATFORM
* DEFAULT_COMPILER

A user specific configuration file `$HOME/.sit`" can be used to overwrite the
settings in the global configuration file.

The installation process is currently controled with the following environment
variables:
* COMPILER
* COMPILER_VERSION
* MPI
* MPI_VERSION
* PLATFORM
* HOSTNAME

Sit detects currently the build platform using the `SITE_PLATFORM_NAME` variable.
If sit cannot determine the PLATFORM it uses the default platform specified
in `sit.conf`.
For each platform configuration files are stored unter
```shell
$SIT_PATH/etc/platform-configs/$PLATFORM/*
```

At the moment only compiler configurations are supported.

To install a package simply call sit with the necessary information provided by
these variables:
```shell
[VARIABLE_DECLARATIONS] sit PACKAGE
```
e.g.
```shell
PREFIX_BASE=/opt COMPILER=gnu COMPILER_VERSION=4.5 sit mpi/openmpi-1.5.1
```
or for a package to be installed with a specific compiler and mpi version
```shell
PREFIX_BASE=/opt COMPILER=gnu COMPILER_VERSION=8.3.0 MPI=openmpi MPI_VERSION=4.0.1 ./sit performance/extrae/extrae-3.6.1
```

### Package files

Package files should include all the necessary information for the installation
proces. The syntax of the package class files is inspired by gentoo's ebuild files.


A sit package file must contain at least the following variables
```
A   archive (source tarball)
P   package (name of extracted source folder)
URL
INSTALLER
```

Optional varialbes to control the build process are
```
CONFIGURE_OPTS  options which will be passed to configure
CMAKE_OPTS      options which will be passed to cmake
MAKEOPTS        options which will be passed to make (see sit.conf)
```

During the installation the following directory paths are used
```
WORKDIR         working directory to which e.g. sources will be unpacked
SRCDIR          source directory
BUILDDIR        directory in which the package will be build ($WORKDIR/build)
LOGDIR          directory storing the temporary logfiles ($WORKDIR)
```

For fine tuning of the installation process the user can overwrite the following
functions. If not other mentioned they are executed in $BUILDDIR
```
src_unpack      extract $SRC_POOL/${A} into $WORKDIR
src_prepare     prepare extracted sources
src_configure   configure
src_build       make
src_pretest     tests to be performed before installation
src_install     make install
src_posttest    tests to be done after installation
```

The following helper functions can be used
```
unpack      recognize and extract a compressed tar file
```