\charmpp{} can be installed either from the source code or using a precompiled
binary package. Building from the source code provides more flexibility, since one 
can choose the options as desired. However, a precompiled binary may be slightly
easier to get running.
 
\section{Downloading \charmpp{}}

\charmpp{} can be downloaded using one of the following methods:

\begin{itemize}
\item From \charmpp{} website -- The current stable version (source code and
binaries) can be downloaded from our website at {\em http://charm.cs.illinois.edu/software}.
\item From source archive -- The latest development version of \charmpp{} can be downloaded
from our source archive using {\em git clone http://charm.cs.illinois.edu/gerrit/charm}.
\end{itemize}

If you download the source code from the website, you will have to unpack it 
using a tool capable of extracting gzip'd tar files, such as tar (on Unix) 
or WinZIP (under Windows).  \charmpp{} will be extracted to a directory 
called ``charm''. 

\section{Installation}

A typical prototype command for building \charmpp{} from the source code is:
\vspace{5pt}\\
{\bf ./build $<$TARGET$>$ $<$TARGET ARCHITECTURE$>$ [OPTIONS]} where,

\begin{description}
\item [TARGET] is the framework one wants to build such as {\em charm++} or {\em
AMPI}.
\item [TARGET ARCHITECTURE] is the machine architecture one wants to build for
such as {\em net-linux-x86\_64}, {\em bluegenep} etc.
\item [OPTIONS] are additional options to the build process, e.g. {\em smp} is
used to build a shared memory version, {\em -j8} is given to build in parallel
etc.
\end {description}

In Table~\ref{tab:buildlist}, a list of build commands is provided for some of the commonly 
used systems. Note that, in general, options such as {\em smp},
\verb|--with-production|, compiler specifiers etc can be used with all targets.
It is advisable to build with \verb|--with-production| to obtain the best
performance.  If one desires to perform trace collection (for Projections),
\verb|--enable-tracing --enable-tracing-commthread| should also be passed to the
build command.

Details on all the available alternatives for each of the above mentioned
parameters can be found by invoking \verb|./build --help|. One can also go through the
build process in an interactive manner. Run \verb|./build|, and it will be followed by
a few queries to select appropiate choices for the build one wants to perform.


\begin{table}[ht]
\begin{tabular}{|p{6cm}|p{9cm}|}
\hline
Net with 32 bit Linux & \verb|./build charm++ net-linux --with-production -j8|
\\\hline
Multicore 64 bit Linux & \verb|./build charm++ multicore-linux64 --with-production -j8|
\\\hline
Net with 64 bit Linux & \verb|./build charm++ net-linux-x86_64 --with-production -j8|
\\\hline
Net with 64 bit Linux (intel compilers) & \verb|./build charm++ net-linux-x86_64 icc --with-production -j8|
\\\hline
Net with 64 bit Linux (shared memory) & \verb|./build charm++ net-linux-x86_64 smp --with-production -j8|
\\\hline
Net with 64 bit Linux (checkpoint restart based fault tolerance) & \verb|./build charm++ net-linux-x86_64 syncft --with-production -j8|
\\\hline
MPI with 64 bit Linux & \verb|./build charm++ mpi-linux-x86_64 --with-production -j8|
\\\hline
MPI with 64 bit Linux (shared memory) & \verb|./build charm++ mpi-linux-x86_64 smp --with-production -j8|
\\\hline
MPI with 64 bit Linux (mpicxx wrappers) & \verb|./build charm++ mpi-linux-x86_64 mpicxx --with-production -j8|
\\\hline
IBVERBS with 64 bit Linux & \verb|./build charm++ net-linux-x86_64 ibverbs --with-production -j8|
\\\hline
Net with 32 bit Windows & \verb|./build charm++ net-win32 --with-production -j8|
\\\hline
Net with 64 bit Windows & \verb|./build charm++ net-win64 --with-production -j8|
\\\hline
MPI with 64 bit Windows & \verb|./build charm++ mpi-win64 --with-production -j8|
\\\hline
Net with 64 bit Mac & \verb|./build charm++ net-darwin-x86_64 --with-production -j8|
\\\hline
Blue Gene/L & \verb|./build charm++ bluegenel xlc --with-production -j8|
\\\hline
Blue Gene/P & \verb|./build charm++ bluegenep xlc --with-production -j8|
\\\hline
Blue Gene/Q & \verb|./build charm++ pami-bluegeneq xlc --with-production -j8|
\\\hline
Blue Gene/Q & \verb|./build charm++ pamilrts-bluegeneq xlc --with-production -j8|
\\\hline
Cray XT3 & \verb|./build charm++ mpi-crayxt3 --with-production -j8|
\\\hline
Cray XT5 & \verb|./build charm++ mpi-crayxt --with-production -j8|
\\\hline
Cray XE6 & \verb|./build charm++ gemini_gni-crayxe --with-production -j8|
\\\hline
\end{tabular}
\caption{Build command for some common cases}
\label{tab:buildlist}
\end{table}

As mentioned earlier, one can also build \charmpp{} using the precompiled binary
in a manner similar to what is used for installing any common software.


The main directories in a \charmpp{} installation are:

\begin{description}
\item[\kw{charm/bin}]
Executables, such as charmc and charmrun,
used by \charmpp{}.

\item[\kw{charm/doc}]
Documentation for \charmpp{}, such as this
document.  Distributed as LaTeX source code; HTML and PDF versions
can be built or downloaded from our web site.

\item[\kw{charm/include}]
The \charmpp{} C++ and Fortran user include files (.h).

\item[\kw{charm/lib}]
The libraries (.a) that comprise \charmpp{}.

\item[\kw{charm/examples}]
Example \charmpp{} programs.

\item[\kw{charm/src}]
Source code for \charmpp{} itself.

\item[\kw{charm/tmp}]
Directory where \charmpp{} is built.

%\item[\kw{charm/tools}]
%Visualization tools for \charmpp{} programs.

\item[\kw{charm/tests}]
Test \charmpp{} programs used by autobuild.

\end{description}

\section{Security Issues}

On most computers, \charmpp{} programs are simple binaries, and they pose
no more security issues than any other program would.  The only exception
is the network version {\tt net-*}, which has the following issues. 

The network versions utilize many unix processes communicating with
each other via UDP.  Only a simple attempt is currently 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.
This notification is a single {\tt UDP} packet sent by {\tt charmrun}
to {\tt charm.cs.illinois.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 {\tt bin} directory, you will find these programs:

\begin{alltt}
    \$ cd 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 charm/bin
    \$ cp charmrun.silent charmrun
\end{alltt}

The only versions of \charmpp{} that ever notify us are 
the network versions.


\section{Reducing disk usage}

The charm directory contains a collection of example-programs and
test-programs.  These may be deleted with no other effects. You may 
also {\tt strip} all the binaries in {\tt charm/bin}.





