root/branches/mcstas-1.x/INSTALL

/*******************************************************************************
*
* McStas, neutron ray-tracing package
*         Copyright 1997-2002, All rights reserved
*         Risoe National Laboratory, Roskilde, Denmark
*         Institut Laue Langevin, Grenoble, France
*
* Documentation: INSTALL
*
* %Identification
* Written by: KN
* Date: 1997
* Origin: Risoe
* Release: all McStas
* Version: $Revision: 1.17 $
*
* This file is part of McStas.
* It details the installation procedure
*
*******************************************************************************/

NOTE: This document is obsolete - please refer to the documents in

install_docs/tex/install.*
install_docs/html/install.html

McStas uses autoconf to detect the system configuration and create the
proper Makefiles needed for compilation. On Unix-like systems, you
should be able to compile and install McStas using the following steps:

1. Unpack the sources to somewhere convenient and change to the source
   directory:

  gunzip -c mcstas-<release>.tar.gz | tar xf -
  cd mcstas-<release>/

2. Configure and compile McStas:

  ./configure
  make

3. Install McStas:

  make install

You should now be able to use McStas. For some examples to try, see the
examples/ directory.

The installation of McStas in step 3 by default installs in the
/usr/local/ directory, which on most systems requires superuser (root)
privileges. To install in another directory, use the --prefix= option to
configure in step 2. For example,

  ./configure --prefix=/home/joe

will install the McStas programs in /home/joe/bin/ and the library files
needed by McStas in /home/joe/lib/mcstas/.

In case ./configure makes an incorrect guess, some environment variables
can be set to override the defaults:

 - The CC environment variable may be set to the name of the C compiler
   to use (this must be an ANSI C compiler). This will also be used for
   the automatic compilation of McStas simulations in mcgui and mcrun.
 - CFLAGS may be set to any options needed by the compiler (eg. for
   optimization or ANSI C conformance). Also used by mcgui/mcrun.
 - PERL may be set to the path of the Perl interpreter to use.

To use these options, set the variables before running ./configure. Eg.

    setenv PERL /pub/bin/perl5
    ./configure

It may be necessary to remove configure's cache of old choices first:

    rm -f config.cache

If you experience any problems, or have some questions or ideas
concerning McStas, please contact kristian.nielsen@risoe.dk.


Installing on non-Unix systems
==============================

Windows:

McStas has been successfully compiled on Windows using Microsoft
Visual C++ in 32-bit mode. Define the preprocessor macro 'WIN32' when
compiling to get McStas to use the Windows file system
semantics. Search the archive of the mailing list
(http://neutron.risoe.dk/neutron-mc/) for details. As far as we know,
the front-end programs have not been used on Windows at this point.

At Ris, we do not use McStas in Windows, so we cannot provide direct
support for this operating system. Try asking on the mailing list if you
need help. If you experience a specific problem with using McStas on
Windows, send a description of the problem to the mailing list so that
we can fix it in the next version.

If you want to volunteer to provide Windows binaries to other users,
please contact kristian.nielsen@risoe.dk.

Macintosh:

McStas has been successfully compiled on the Macintosh using Code
Warrior. Define the preprocessor macro 'MAC' when compiling to get
McStas to use the Macintosh file system semantics. It is reportedly
necessary to increase the default size of memory allocated to programs
by the compiler to make the simulations work. It may also be necessary
to edit the default file paths in the file port.h, since environment
variables are (as far as we know) not available on the Macintosh.

At Ris, we do not use McStas on the Macintosh, so we cannot provide
direct support for this system. Try asking on the mailing list if you
need help. If you experience a specific problem with using McStas on the
Macintosh, send a description of the problem to the mailing list so that
we can fix it in the next version.


Troubleshooting
===============

[Also see the FAQ at http://neutron.risoe.dk/mcstas/FAQ.html for
up-to-date help on common problems in McStas.]

You should try to make sure that the directory containing the McStas
binaries (mcstas, gscan, mcdisplay, etc.) is contained in the PATH
environment variable. The default directory is /usr/local/bin, which is
usually, but not always, included in PATH. Alternatively, you can
reference the McStas programs using the full path name, ie.

  /usr/local/bin/mcstas my.instr
  perl /usr/local/bin/mcrun -N10 -n1e5 mysim -f output ARG=42
  perl /usr/local/bin/mcdisplay --multi mysim ARG=42

This may also be necessary for the front-end programs if the install
procedure could not determine the location of the perl interpreter on
your system.

If McStas is installed properly, it should be able to find the files it
needs automatically. If not, you should set the MCSTAS environment
variable to the directory containing the runtime files "mcstas-r.c" and
"mcstas-r.h" and the standard components (*.comp). Use one of

  MCSTAS=/usr/local/lib/mcstas; export MCSTAS     # sh, bash
  setenv MCSTAS /usr/local/lib/mcstas             # csh, tcsh

The PGPLOT library, which is used by the mcdisplay frontend, needs the
PGPLOT_DIR environment variable to be set to the directory containing
PGPLOT, eg.

  PGPLOT_DIR=/usr/lib/pgplot; export PGPLOT_DIR   # sh, bash
  setenv PGPLOT_DIR /usr/lib/pgplot               # csh, tcsh

See the PGPLOT documentation for details.