\label{s:install}

\section{Getting McStas}
\label{s:obtain}
The \htmladdnormallink{McStas}{http://www.mcstas.org} package is
available in various distribution packages, from the project
website at
\htmladdnormallink{http://www.mcstas.org/download}{http://www.mcstas.org/download}.
\begin{itemize}
\item{\texttt{McStas-2.0-i686-Win32.exe}\\Windows self-extracting executable
    including essential support tools. - Refer to section
    \ref{s:win32_install}. }
\item{\texttt{McStas-2.0.dmg}\\Mac OS X disk image for PPC and Intel machines. Please follow
    the instructions in the README file in the disk image. }
\item{\texttt{mcstas-2.0-i386.deb}\\Binary Debian GNU/Linux packages for 32 bit Intel/AMD processors, currently built on Debian stable.
   Tested to work on Ubuntu and Debian systems.
 - Refer to section \ref{ss:deb_install}}
\item{\texttt{mcstas-2.0-amd64.deb}\\Binary Debian GNU/Linux packages for 64 bit Intel/AMD processors, currently built on Debian stable.
   Tested to work on Ubuntu and Debian systems.
 - Refer to section \ref{ss:deb_install}}
\item{\texttt{mcstas-2.0-i686-unknown-Linux.tar.gz}\\Binary package
  for Linux systems, currently built on Debian stable.
  Should work on most Linux setups.
 - Refer to section \ref{s:unix_install}}
\item{\texttt{mcstas-2.0-src.tar.gz}\\Source code package for
    building \htmladdnormallink{McStas}{http://www.mcstas.org} on
    (at least) Linux and Windows XP. This package should compile on
    most Unix platforms with an \texttt{ANSI-c} compiler. - Refer to section \ref{s:unix_install}}
\end{itemize}

\section{Licensing}
The conditions on the use of McStas can be read in the files
\verb+LICENSE+ and \verb+LICENSE.LIB+ in the distribution. Essentially,
McStas may be used and modified freely, and copies of the McStas source code
may be distributed to others.
New or modified component and instrument files may be shared by
the user community, and the core team will be happy to include user contributions in the package.

\section{Installation on windows}
\label{s:win32_install}
As of release 1.10 of McStas, the preferred way to install on
Microsoft Windows is using a self-extracting \texttt{.exe} file.

\noindent The archive includes all software needed to run McStas, including perl, a
c-compiler, PDL, PGPLOT, a vrml viewer.

\noindent Installation of all the provided support tools is needed to get a fully
functional McStas. (The option not to install the tools is included for people who want to
upgrade from a working, previous installation of McStas.)

\noindent The safe and fully tested configuration/installation is to install all
tools, leaving all installation defaults untouched. Specifically you
may experience problems if you install to non-standard locations.

\noindent Simply follow the guidance given by the installer, pressing 'next' all
the way.

\noindent To use grid and cluster computing, you will need an SSH client. McStas is configured to
use PuTTY.

\noindent We also recommend to install Gnuplot, Matlab or 
iFit (free Matlab replacement) from \\\htmladdnormallink{http://ifit.mccode.com/}{http://ifit.mccode.com/}, 
FreeWRL from \\\htmladdnormallink{http://freewrl.sourceforge.net/}{http://freewrl.sourceforge.net/}
or InstantPlayer from \\\htmladdnormallink{http://www.instantreality.org/}{http://www.instantreality.org/} 
or OctagePlayer from \\\htmladdnormallink{http://www.octaga.com/download\_octaga.html}{http://www.octaga.com/download_octaga.html}, 
and HDFView from \\\htmladdnormallink{http://www.hdfgroup.org/hdf-java-html/hdfview/}{http://www.hdfgroup.org/hdf-java-html/hdfview/}, 
prior to installing McStas.

\noindent For MPI (parallelisation) on Windows, we advice you to install MPICH2 from \htmladdnormallink{Argonne National Laboratory}{http://www-unix.mcs.anl.gov/mpi/mpich/} including development libraries before installing McStas. Also, your \verb+mpiexec.exe+ must be on the \verb+PATH+. You may have to customize the \verb+mpicc.bat+ script from the McStas distribution with the proper C compiler and MPI library path.

\noindent If you experience any problems, or have some questions or ideas
concerning McStas, please contact
\htmladdnormallink{pkwi@fysik.dtu.dk}{mailto:pkwi@fysik.dtu.dk}
or the McStas mailing list at \htmladdnormallink{mcstas-users@mcstas.org}{mailto:mcstas-users@mcstas.org}.


\section{Installation on Unix systems}
\label{s:unix_install}
Our current reference Unix class platform is
\htmladdnormallink{Ubuntu Linux}{http://www.ubuntu.com}, which is
based on \htmladdnormallink{Debian
  GNU/Linux}{http://www.debian.org}. Some testing is done on other
Unix variants, including \htmladdnormallink{Fedora
  Core}{http://fedora.redhat.com},
\htmladdnormallink{SuSE}{http://www.novell.com/products/suselinux/}
and \htmladdnormallink{FreeBSD}{http://www.freebsd.org}.
\ \\\ \\
 WARNING: The 'dash' shell which is used as /bin/sh on some Linux system (Including Ubuntu 8.04) makes the 'Cancel' and 'Update'
  buttons fail in mcgui. Possible solutions are:
\begin{itemize}
 \item If your system is a Debian or Ubuntu, please run the command
   \verb+dpkg-reconfigure dash+ and say 'no' to install dash as /bin/sh  (See section \ref{ss:deb_install})
 \item If your /bin/sh is dash, please install bash and manually change the /bin/sh link to point at bash.
\end{itemize}

\subsection{Debian class systems}
\label{ss:deb_install}
As of release 2.0, we provide a Debian binary package (32 bit package for Intel/AMD). We have tested that the
package works properly on Ubuntu and Debian systems. To install it, please
perform the following tasks:
\begin{enumerate}
\item{As root, issue the command \\\verb+apt-get install perl perl-tk gcc libc6-dev pdl bash+}
\item{Optionally, as root, issue the commands
\\\verb+apt-get install openssh-client openssh-server+
\\\verb+apt-get install mpi-default-bin mpi-default-dev+
to benefit from MPI and SSH grid parallelization}
\item{As root, issue the command \\\verb+dpkg-reconfigure dash+\\and
    say 'no' to install dash as /bin/sh.}
\item{Optionally, install FreeWRL from \verb+http://freewrl.sourceforge.net/download.html+, 
InstantPlayer from \\\htmladdnormallink{http://www.instantreality.org/}{http://www.instantreality.org/} 
or WhiteDune with \\\verb+apt-get install whitedune+.}
\item{To view OFF/PLY geometry files you may use Geomview or Meshlab, that can be installed with \\\verb+apt-get install geomview meshlab+.}
\item{If you have access to Matlab(R) or alternatively the free iFit replacement from \\\htmladdnormallink{http://ifit.mccode.com/}{http://ifit.mccode.com/}, install it prior to McStas, so that the configuration can detect it.}
\item{Download the packages from \verb+http://www.mcstas.org/download+}
\item{Double click the packages files (starting from the 'mcstas' one) or alternatively, as root, issue the command \\\verb+dpkg -i mcstas-2.x-amd64.deb+ (or \\\verb+dpkg -i mcstas-2.x-i386.deb+ on 32 bit systems). This later step may be replaced by a manual build from the Mctas tarball (see below)}
\item{Alternatively, as root, issue the commands \verb+sudo apt-add-repository 'deb http://packages.mccode.org/debian stable main ; apt-get update ; apt-get install mcstas-suite'+ :
\end{enumerate}
Updating your operating system to a new release \emph{may} in some cases require you to re-install McStas following the procedure above. 

\subsection{Other Linux/Unix systems}
To get a fully functional McStas installation on Unix systems, a few support
applications are required. Essentially, you will need a C compiler,
Perl and Perl-Tk, as well as a plotter such as Matlab, Gnuplot or
PGPLOT. In the installer package, we supply a method to install PGPLOT
and related perl modules - see step \ref{pg_install} below.

\noindent On Debian and Ubuntu systems, the
needed packages to install are \texttt{perl-tk, pdl, gcc,
  libc6-dev} \\(On Ubuntu you need to enable the 'universe' package
distribution in the file \\\verb+/etc/apt/sources.list+.)

\noindent We also recommend to install octaga VRML/X3D viewer such as
FreeWRL from \\\htmladdnormallink{http://freewrl.sourceforge.net/}{http://freewrl.sourceforge.net/} or 
InstantPlayer from \\\htmladdnormallink{http://www.instantreality.org/}{http://www.instantreality.org/}.

\noindent Additionally, MPICH, OpenMP (gcc-4.2 or icc or pgcc), openssh, Octave/Gnuplot, HDF and NeXus libraries may be installed, to enhance McStas clustering method and data formats.

\subsection{Configuration and installation}
McStas uses autoconf to detect the system configuration and creates the
proper Makefiles needed for compilation. On Unix-like systems, you
should be able to compile and/or install McStas using the following steps:
\begin{enumerate}
\item{Unpack the sources to somewhere convenient and change to the
    source directory:\\
  \texttt{gunzip -c <package>.tar.gz | tar xf -}\\
  \texttt{cd mcstas-2.0/}}
\item{Configure McStas:\\
  \texttt{./configure} or \texttt{./configure --with-nexus --with-cc=gcc-4.2}}
\item{Build McStas (only in case of the \verb+mcstas-2.0-src.tar.gz+ package):\\
  \texttt{make}}
\item{Install McStas (as superuser):\\
  \texttt{make install}
\item{Optionally build/install PGPLOT (as superuser - build
    dependencies are pdl, g77, libx11-dev, xserver-xorg-dev, libxt-dev
    on Ubuntu):\\
    \texttt{make install-pgplot \&\& ./configure}
    \label{pg_install}}

\label{makeinst}}
\end{enumerate}



\noindent The installation of McStas in step \ref{makeinst} by default installs in the
\texttt{/usr/local/} directory, which on most systems requires superuser (root)
privileges.

\subsection{Specifying non-standard options}
To install in a different location than \texttt{/usr/local}, use the --prefix= option to
configure in step 2. For example,\\

  ./configure --prefix=/home/joe\\

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

\noindent On 64-bits systems, you may have to use: ./configure --with-pic before installing PGPLOT with: make install-pgplot

\noindent To enable NeXus format in mcformat, you need the NeXus and HDF libraries, and have to use: ./configure --with-nexus

\noindent To specify a non standard C compiler (e.g. gcc-4.2 or icc that support OpenMP), you may use e.g.: ./configure --with-cc=gcc-4.2

\noindent To enable a non standard C compiler to be used with MPI, you may have to edit your mpicc shell script to set e.g.: CC="icc", or redefine the 'cc' to point to your prefered compiler, e.g.: ln -s /usr/bin/gcc-4.2 /usr/bin/cc

In case ./configure makes an incorrect guess, some environment variables
can be set to override the defaults:
\begin{itemize}
\item{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.}
\item{CFLAGS may be set to any options needed by the compiler (eg. for
   optimization or ANSI C conformance). Also used by mcgui/mcrun.}
\item{PERL may be set to the path of the Perl interpreter to use.}
\end{itemize}
\noindent To use these options, set the variables before running ./configure. Eg.\\

    setenv PERL /pub/bin/perl5

    ./configure\\

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


    rm -f config.cache\\


\noindent If you experience any problems, or have some questions or ideas
concerning McStas, please contact
\htmladdnormallink{peter.willendup@risoe.dk}{mailto:peter.willendup@risoe.dk}
or the McStas mailing list at \htmladdnormallink{mcstas-users@mcstas.org}{mailto:peter.willendup@risoe.dk}.

\section{Finishing and Testing the McStas distribution}
\label{s:testing}

Once installed, you may check and tune the guessed configuration stored within file
\begin{itemize}
\item{\verb+MCSTAS\tools\perl\mccode_config.perl+ on Windows systems}
\item{\verb+MCSTAS/tools/perl/mccode_config.perl+ on Unix/Linux systems}
\end{itemize}
where \verb+MCSTAS+ is the location for the McStas library.

You may, on Linux systems, ask for a reconfiguration (e.g. after installing MPI, Matlab, ...) with the commands, e.g:
\begin{verbatim}
cd MCSTAS/tools/perl/
sudo ./mcstas_reconfigure
\end{verbatim}
On Windows systems, the reconfiguration is performed with the \verb+mcconfig.pl+ command.

The \verb+examples+ directory of the distribution contains a set of instrument examples. These are used for the McStas self test procedure, which is executed with
\begin{verbatim}
    mcrun --test # mcrun.pl on Windows
\end{verbatim}
This test takes a few minutes to complete, and ends with a short report on the installation itself, the simulation accuracy and the plotter check.

You should now be able to use McStas. For some examples to try, see the
examples/ directory. Start 'mcgui' (mcgui.pl on Windows), and select one of the examples in the 'Neutron Sites' menu.
