Printer Friendly - GettingStartedSetup

Content:

Introduction
Considerations regarding the shell used
PATH
Environment variables
Other systems (like "module")
Testing

Introduction

We are aware that the setup procedures described here might not be what is actually going to be used in a specific lab, department or installation (e.g. a module system might be used). However you decide to make the software available to the user, the reference is always what the setup.sh (or setup.csh) are doing - namely settin some environmental variables and adding some directories to the users PATH.

Considerations regarding the shell used

There are two major types of shells available:

Bourne-compatible shells (most commonly used one is "bash")
C shell (popular is e.g. "tcsh")
We use the file-extension ".sh" for Bourne-compatible files and ".csh" for C-shell like files.

There are two types of shell-scripts we provide:

executables

will be accessible through the users PATH
should have the correct permissions ("rwxr-xr-x", i.e. 0755) so that they can be run directly via

            some_script.sh

setup files

should have the correct permissions ("rw-r–r–", i.e. 0644) so that they can not be run directly
should be 'sourced/dotted' in the shell-specific way:

            . /where/ever/some_setup.sh             # Bourne-compatible shells (bash, sh, ksh, dash, zsh)

            source /where/ever/some_setup.csh       # C shell (tcsh, csh)

yes, some Bourne-compatible shells allow the use of 'source' instead of the '.' (dot), but we think it is a god idea to stick with a way that is guaranteed to work in all Bourne-compatible shells as good practice.

PATH

Our different programs will add one or more directories to the users PATH. These are (relative to the installation directory $ROOT - only the 64-bit Linux example is given here):

Package	Directories
BUSTER	`$ROOT/scripts` `$ROOT/autoBUSTER/bin/linux64` `$ROOT/MakeTNT/bin`
autoPROC	`$ROOT/autoPROC/bin/linux64`
SHARP/autoSHARP	`$ROOT/scripts`

Environment variables

Some environment variables are required for each program to work correctly - both for licensing as awell as finding required additional programs, data files etc. These are (relative to the installation directory $ROOT:

Package	environment variable	value
BUSTER	`BDG_home`	`$ROOT`
	`MakeTNT_home`	`$ROOT`
autoPROC	`autoPROC_home`	`$ROOT`
SHARP/autoSHARP	`SHARP_home`	`$ROOT`

If running a multi-package installation (e.g. as part of the Global Phasing Consortium) all of these should be set - even if they point to the same location.

Other systems (like "module")

If a different system is being used instead of the default

 . /where/ever/some_setup.sh             # bash, sh, ksh, dash, zsh
   - or -
 source /where/ever/some_setup.csh       # tcsh, csh

the above settings need to be present to the user at the time of running our programs.

If some other system is in place (e.g. individual wrapper scripts for each command, aliases or something else), then it is the installers responsibility to ensure all programs, tools and commands are made available to the user and each functions as expected.

Testing

One way of testing would be to run

for Bourne-compatible shells:

        ( env | sort > env.1 ; . /where/ever/installed/setup.sh; env | sort > env.2 ; diff env.1 env.2 ; rm env.1 env.2 )

for C-shell shells:

        ( env | sort > env.1 ; source /where/ever/installed/setup.csh; env | sort > env.2 ; diff env.1 env.2 ; rm env.1 env.2 )

This should show the change in the users environment when using our default setup system (assuming a completed and working installation). To test if e.g. a module system works in the same way, one could then run something like

  ( env | sort > env.1 ; module load GPhL; env | sort > env.2 ; diff env.1 env.2 ; rm env.1 env.2 )

and compare the output with what the above command achieved.

If a customised local installation doesn't work as expected, it might be a good initial step to first see if a default installation using the setup.sh/setup.csh system works. If all fails, please contact us at one of

buster-develop @ globalphasing.com
  proc-develop @ globalphasing.com
 sharp-develop @ globalphasing.com

with as much detail about the operating system (and version), the environment (shell, type of user account) etc.