        Virtual Instrumentation (VITESS)
	for pulsed and continuous sources


Helmholtz-Zentrum Berlin für Materialien und Energie GmbH
        former Hahn-Meitner-Institut Berlin

Modules:
	Klaus Lieutenant   (klaus.lieutenant@helmholtz-berlin.de)
        Andreas Houben
	Géza Zsigmond      (geza.zsigmond@psi.ch)
	Sergey Manoshin
        Daniil Nekrassov   (daniil.nekrassov@helmholtz-berlin.de)
	Dietmar Wechsler
	Friedrich Streffer

GUI Software:
	Michael Fromme     (fromme@helmholtz-berlin.de)


README

This program has been developed on Unix and Windows, and runs fine on both operating systems.
As a special variant of Unix, it has been ported to run with Mac OS X (Darwin).

Since version 2.11 VITESS uses gnuplot as a default plot program if present.
We assume gnuplot to be installed with a Linux distribution, and provide some
instructions for Mac users how to install gnuplot and other tools needed
by VITESS modules, see darwin_gnuplot.txt.

Installation under Unix
-----------------------
The VITESS software comes to you as a gzipped tar file.
When your browser asks for a file name to store the tar file, it might suggest
	vitess_download
We assume you change that to a name with .tar.gz ending like vitess.tar.gz if necessary.

You may compare the CRC32, MD5 or SHA1 checksums of the downloaded vitess.tar.gz with those given at

https://www.helmholtz-berlin.de/vitess

Linux
-----
The file vitess.tar.gz may be uncompressed in whatever
<vitess parent directory> you want, like
$HOME for a personal installation in $HOME/vitess, _no root privileges_ needed!
Assumed the tar ball is ~/Downloads/vitess.tar.gz, you might do
cd
tar zxvf ~/Downloads/vitess.tar.gz

If you want to install system wide, /usr/opt may be a good idea for root.

We assume you have installed Tcl/Tk, and libgd using libz, libpng, and libttf (libfreetype)
from your distribution. Compiled binaries are for SuSE 10.2 (32 bit) and 11.3 (64 bit).

Darwin
------
When downloading, Safari puts the tar ball to ~/Downloads/vitess.tar.gz
and a double click on that file will produce the ~/Downloads/vitess/ directory.
Move it to a place more appropriate, if you like.

The binaries will work on Darwin 10.6 (snow leopard) and 10.7 (lion) Mac, if you install gnuplot,
because VITESS and gnuplot share some tool libraries like libgd.

You will need administrator privileges to install gnuplot, but it will be
a short time to do, if you follow the instructions in darwin_gnuplot.txt
on a Darwin 10.6 (snow leopard) or 10.7 (lion) Mac.

All Unix systems, compilation from sources
------------------------------------------
We assume Tcl/Tk software with a version 8.2 or higher is installed separately.
VITESS version 2.11 has been tested with Tcl/Tk 8.5 .
If you miss information, try
http://www.tcl.tk/

The Tcl/Tk code should work with little or no modification for all Unix derivates.
You need not compile a special wish for your system.

VITESS used BLTwish extensions to Tcl/TK for plots of monitor modules.
Tcl/TK Versions >= 8.5 are not compatible with BLT, but VITESS works fine
with these versions where gnuplot is installed, or simpler plot widgets replace
BLT widgets automatically,

C sources have been compiled for Windows, Linux, Darwin, and elder versions for
Solaris and Tru64, too.

VITESS relies on the pseudorandom number generators from the GNU Scientific Library.
We provide these in the rng sub directory, see rng/README.txt.
Another prerequisite for some modules is the g2 library provided, 
see g2-0.72/Readme.vitess on how to compile this library.

The Perl script  mmake.pl  in the SRC directory may be used to generate a
GNU Makefile adopted to the local Unix, like configure does for other software.
As some modules need GD graphics routines, which rely on auxiliary libraries,
mmake.pl looks for these and gives hints if they are missing on your system. 
  (As an extra this script generates a nmake file vitess.mak
  suitable for Microsoft Studio compilers.)
Just call
cd SRC
mmake.pl -h
to see what options are possible, and
make
make install
to compile and then move the binaries to the MODULES directory.


VITESS start script
-------------------
try
<vitess parent directory>/vitess/Vitess

You may change the first 3 lines
#!/bin/sh
# the next line restarts using wish \
exec /usr/bin/wish "$0" "$@"

to use another wish than /usr/bin/wish if necessary.
  (VITESS versions up to 2.8 had
  #!/usr/local/bin/bltwish
  as first line to use the bltwish, which would be valid on elder Linux systems.)

Alternatively you may adopt the script callVitess provided in the tar ball.

Missing shared libraries?
-------------------------
Some modules like bender or visual need more shared libraries, see above.
To see what is missing you might use the ldd command with Linux or otool -L with Darwin.


Difference to the Windows version
---------------------------------
The Windows version comes alongside with standard Tcl/Tk software and gnuplot,
which have to be installed separately with Unix.

The MODULES directory contains binary executable files for modules, you
need the right ones for your operating system.

For the module guide (from guide.c) we find

guide.exe		 Windows 32 bit
guide_Linux		 Linux i386
guide_Linux_x86_64       Linux x86 64 bit architecture
guide_Darwin             Darwin 32 bit
guide_Darwin_x86_64      Darwin 64 bit

and in the past
guide_SunOS		 Solaris sparc
guide_OSF		 Tru64 alpha

Installing Vitess for a multi user enviroment under Linux
---------------------------------------------------------

If you plan to install Vitess as root to a system directory like /opt
for all users, you may face the problem that they are not allowed to write files
in that directory.
They need to use a copied own directory with vitess files for that purpose.

It's easy to provide this. Let us assume root unzipped the latest version
to /opt/vitess3.4, she or he may provide a call script like 
/usr/local/bin/vitess3.4 for users in the default PATH.

Do as root then
/opt/vitess3.4/TOOLS/make_callscript.pl /usr/local/bin/vitess3.4

If users invoke Vitess via
vitess3.4
the first time, an own directory ~/vitess3.4 will be created, where all
sub directories will be symbolic links to the installed Vitess version,
except ~/vitess3.4/FILES which is a true recursive copy. Snapshots,
modified parameter files and .gui files will be individual then.
