1. TL;DR Kepler install HowTo

# set IMAS_HOME variable, load IMAS libs to compile KCA later, and load Java and Ant dependency:
module load IMAS
# specify tagged versions for kepler-patches and kepler-core-actors:
make all TAG_KP=p3 TAG_KCA=2.1.5
# confirm all is well, then
make install TAG_KP=p3 TAG_KCA=2.1.5

More information below. Or raise an issue on https://jira.iter.org!

Kepler User Mini Howto

 Once Kepler is installed (e.g. make install IMAS_HOME=~/imas, see below), then a user should load the Kepler module to get started:

module use $IMAS_HOME/etc/modulefiles # if not already in use
module load Kepler/2.5master-develop # unless TAG_KP TAG_KCA were set at
# install time (see below)

The user can then create his/her first local Kepler installation, using kepler_install. It will be installed below $KEPLER_DIR (which defaults to KEPLER_DIR_DEFAULT set in site-config). For example:

# export KEPLER_DIR=$HOME/.local/Kepler # optional override
kepler_install my_first_kepler # creates lightweight installation

Now, read the instruction at the end of the above command, which indicate how to switch to the newly installed environment:

kepler_load my_first_kepler # which is short-hand for:
# module unload Kepler ; module load $KEPLER_DIR/modulefiles/Kepler/my_first_kepler

The latter command can also be used directly (i.e. not after loading Kepler or Keplertools first), for example in a new environment. It will load the version of Keplertools that was used to make this local installation:

module load $KEPLER_DIR/modulefiles/Kepler/my_first_kepler

This will setup the symlinks and variables like KEPLER and KEPLER_DOT to the appropriate values. (The module name can be changed by setting KEPLER_DIR_NAME variable in site-config.)

Also available are:

kepler_avail # list all local Kepler environments (given a $KEPLER_DIR)
kepler_load OtherVersion # switch environment to another local Kepler
module unload Kepler # unset the Kepler environment

Please note that module avail Kepler will NOT show local installations. This is because $MODULEPATH does not contain $KEPLER_DIR/modulefiles. To list local Kepler installations, run kepler_avail or extend the MODULEPATH.

1.1. Kepler Installation Mini Howto

Type make to get the default make help output which gets you started.

1.1.1. make help

Will give some info of installation paths etc.

1.1.2. make all

Short hand for make update version, check the version and dependencies.

1.1.3. make install

Short hand for make update version install_. Will actually checkout and install all you need: Kepler+patches+actors + Keplertools + modulefile.

1.1.4. Version selection

There are quite a few capitalized variables that the user can override from the shell. Please read the header of Makefile for detailed information.

1.1.5. Examples

Typical commands:

make update # To fetch latest changes, checkout the default (branch HEAD).
make version # To inspect (latest) version information.
make all # Same as the two above, `make update version`.
make install # Same as `make all`, plus actually install it.

Then you'd probably want to install a certain tagged version, for example Kepler 2.5 with patches p2 and kepler-core-actors 2.1.3.

make all TAG_KP=p2 TAG_KCA=2.1.3 # Optional step to inspect before...
make install TAG_KP=p2 TAG_KCA=2.1.3

Suppose you want a specific tagged version, but it's not the HEAD of the default branch, then instruct to that version, it's the same:

make install TAG_KP=p1 TAG_KCA=2.1.2 # update, checkout, check and install

For testing, you may want a different install dir: just override IMAS_HOME. Note that the following example omits the TAG_* variables. That means the default is installed: Kepler/2.5master-develop. The name reflects the branch names, i.e. master of patches and develop of KCA.

make install IMAS_HOME=~/imas

Suppose you want a specific non-tagged commit, then you need to provide some more information to fine-tune the version selection and installation name. Here is an example to install a Kepler with a custom patches commit and a tagged kepler-core-actors. It would install as version 2.5label-2.1.3:

make all VER_KP=label COMMIT_KP=d3fe25a TAG_KCA=2.1.3 # optional inspect
make install VER_KP=label COMMIT_KP=d3fe25a TAG_KCA=2.1.3

If you know what you are doing and you want to avoid the (slightly time-consuming) version checking, you can use

export MATCH_VER_KB='*' # override the default version test pattern.
make all # Test checkout and show this would install.