\section{Installing \converse{} and \charmpp{}}

The two programming systems are distributed as a single package ---
one always installs both.  They will all be installed in a single
directory which, for lack of a better term, we will call the ``charm''
directory.  It would be typical to choose {\tt /usr/local/charm} as
the location for the charm directory, although any location will do.
Our explanation of the installation process will assume that {\tt
/usr/local/charm} is to be the location of the charm directory,
if not, you must mentally translate.

Download the tar-file file appropriate to your machine.  For example,
if you are installing the version of \converse{}/\charmpp{} for networks of Sun
workstations running Solaris, download {\tt net-sol.tar.gz} from PPL's
website (preferred) {\tt http://charm.cs.uiuc.edu/} or using anonymous FTP:

\begin{alltt}
    % ftp a.cs.uiuc.edu
    Connected to a.cs.uiuc.edu.
    220 a.cs.uiuc.edu FTP server ready.
    Name: anonymous
    331 Guest login ok, send your complete e-mail address as password.
    Password: jyelon@cs.uiuc.edu
    230-
    230-    Welcome to the University of Illinois at Urbana-Champaign,
    230-                 Dept. of Computer Science FTP server.
    230-
    230 Guest login ok, access restrictions apply.
    ftp> cd pub/research-groups/CHARM/CHARM.5.0
    250 CWD command successful.
    ftp> binary
    200 Type set to I.
    ftp> get net-sol.tar.gz
    200 PORT command successful.
    150 Opening BINARY mode data connection for net-sol.tar.gz (648211 bytes).
    226 Transfer complete.
    local: net-sol.tar.gz remote: net-sol.tar.gz
    648211 bytes received in 38 seconds (17 Kbytes/s)
    ftp> quit
\end{alltt}

Now that you have downloaded it, you are ready to install it: uncompress it,
untar it, and move the directory thereby created to {\tt /usr/local/charm}:

\begin{alltt}
    % gunzip net-sol.tar.gz
    % tar xf net-sol.tar
    % mv net-sol/* /usr/local/charm
\end{alltt}

You are almost ready to go.  The last thing you need to do is put the
charm binaries in your path.  There are two acceptable ways to do
this.  The first is to simply reset your path:

\begin{alltt}
    % setenv PATH /usr/local/charm/bin:$PATH
\end{alltt}

The second is to install {\tt charmc} in a common directory available
to all users of your machine, such as {\tt /usr/local/bin}.  {\em DO
NOT} move or copy {\tt charmc}: If you do, it will cease to function correctly.
The only reliable way to
put {\tt charmc} in a common directory is to symbolically link it:

\begin{alltt}
    % ln -s /usr/local/charm/bin/charmc /usr/local/bin/charmc
\end{alltt}

The programming systems, \converse{} and \charmpp{}, are
probably ready to go.  However, there is one possible situation that
they may not be.  If your parallel machine has a separate ``host''
computer on which you do compilation, and if your ``host'' computer is
of a type different from the one we anticipated, then some of the
binaries may be compiled for the wrong kind of CPU.  To correct this
situation, you may need to rebuild the cpm, \charmpp{}, and sdag compilers.
We suggest that you get the source distribution from the above locations,
and compile them yourself. Instructions to compile from source
distributions are included as a {\tt README} file in the sources.

This should complete the installation process.  You are ready to test
\converse{} and \charmpp{}.  However, there are a few things to
attend to before you start using them on a regular basis.  These are
security issues and disk space consumption.

\subsection{Security Issues}

On most computers, \charmpp{} programs are simple binaries, and they pose
no more security issues than any other program would.  The exceptions
to this rule are the network versions {\tt net-*}.  
This section only applies to users
of the networked versions, all other users may skip it.

The network versions utilize many unix processes communicating with
each other via UDP.  No attempt is currently being made to filter out
unauthorized packets.  Therefore, it is theoretically possible to
mount a security attack by sending UDP packets to an executing
\converse{} or \charmpp{} program's sockets.

The second security issue associated with networked programs is
associated with the fact that we, the \charmpp{} developers, need evidence
that our tools are being used.  (Such evidence is useful in convincing
funding agencies to continue to support our work.)  To this end, we
have inserted code in the network {\tt charmrun} program (described
later) to notify us that our software is being used.
Implementationally speaking, the {\tt charmrun} program sends a
single {\tt UDP} packet to {\tt charm.cs.uiuc.edu}.  This data is put
to one use only: it is gathered into tables recording the internet
domains in which our software is being used, the number of individuals
at each internet domain, and the frequency with which it is used.

We recognize that some users may have objections to our notification
code.  Therefore, we have provided a second copy of the {\tt
charmrun} program with the notification code removed.  If you look
within the charm {\tt bin} directory, you will find these programs:

\begin{alltt}
    % cd /usr/local/charm/bin
    % ls charmrun*
    charmrun
    charmrun.notify
    charmrun.silent
\end{alltt}

The program {\tt charmrun.silent} has the notification code removed.  To
permanently deactivate notification, you may use the version without the
notification code:

\begin{alltt}
    % cd /usr/local/charm/bin
    % cp charmrun.silent charmrun
\end{alltt}

Although versions for some other machines contain
programs named {\tt charmrun.notify} and {\tt charmrun.silent}, they
never actually notify us.  The existence of the extra files is just to
make our compilation scripts more consistent across versions.  The
{\em only} versions that ever notify us are the network versions.

\subsection{Reducing disk usage}

This section describes how you may delete parts of the distribution to
save disk space.  

The charm directory contains a collection of example-programs and
test-programs.  These may be deleted with no other effects:

\begin{alltt}
    % rm -r /usr/local/charm/pgms
\end{alltt}

You may delete the programs {\tt charmrun-notify} and {\tt
charmrun-silent}, although please read the section on security first.

Finally, you may {\tt strip} all the binaries in {\tt
/usr/local/charm/bin}, if we have not already done so.

\subsection{Using more than one version of \charmpp{} on the same Machine}

It is common to wish to install more than one version of \charmpp{} on the
same machine.  For example, we often use the uniprocessor version for
debugging our programs (it supports {\tt gdb} in a simple way), and
then we switch to the networked version to run our programs in
parallel.

To do this, you will need more than one charm directory.  For example,
we use {\tt /usr/local/charm.uth} and {\tt /usr/local/charm.net}.
Simply install the versions independently, one at a time.  All charm
directories should be in the same parent directory.

Each version contains the {\tt charmc} script.  Which {\tt charmc} you
use to compile your programs determines which behavior the program
will exhibit.  For example, if you install a uniprocessor version in
{\tt /usr/local/charm.uth} and a networked version in {\tt
/usr/local/charm.net}, and if you compile using {\tt
/usr/local/charm.uth/bin/charmc}, then your programs will be
uniprocessor programs.

The exception to this rule is if you use the {\tt -machine} option of
{\tt charmc}.  {\tt -machine} causes charm to look for another
installed charm directory with the specified name.  For example, if
you installed {\tt /usr/local/charm.uth} and {\tt
/usr/local/charm.net} as described above, you could specify:

\begin{alltt}
    % /usr/local/charm.net/bin/charmc -machine charm.uth myprog.C
\end{alltt}

Even though you are running the {\tt charmc} script from the network
version, it will produce uniprocessor binaries, since you told it
explicitly to use that version.



