Docs: refer to illinois.edu, not uiuc.edu
[charm.git] / doc / charm++ / install.tex
1 \charmpp{} can be installed either from the source code or using a precompiled
2 binary package. Building from the source code provides more flexibility, since one 
3 can choose the options as desired. However, a precompiled binary may be slightly
4 easier to get running.
5  
6 \section{Downloading \charmpp{}}
7
8 \charmpp{} can be downloaded using one of the following methods:
9
10 \begin{itemize}
11 \item From \charmpp{} website -- The current stable version (source code and
12 binaries) can be downloaded from our website at {\em http://charm.cs.illinois.edu/software}.
13 \item From source archive -- The latest development version of \charmpp{} can be downloaded
14 from our source archive using {\em git clone git://charm.cs.illinois.edu/charm.git}.
15 \end{itemize}
16
17 If you download the source code from the website, you will have to unpack it 
18 using a tool capable of extracting gzip'd tar files, such as tar (on Unix) 
19 or WinZIP (under Windows).  \charmpp{} will be extracted to a directory 
20 called ``charm''. 
21
22 \section{Installation}
23
24 A typical prototype command for building \charmpp{} from the source code is:
25 \vspace{5pt}\\
26 {\bf ./build $<$TARGET$>$ $<$TARGET ARCHITECTURE$>$ [OPTIONS]} where,
27
28 \begin{description}
29 \item [TARGET] is the framework one wants to build such as {\em charm++} or {\em
30 AMPI}.
31 \item [TARGET ARCHITECTURE] is the machine architecture one wants to build for
32 such as {\em net-linux-x86\_64}, {\em bluegenep} etc.
33 \item [OPTIONS] are additional options to the build process, e.g. {\em smp} is
34 used to build a shared memory version, {\em -j8} is given to build in parallel
35 etc.
36 \end {description}
37
38 In Table~\ref{tab:buildlist}, a list of build commands is provided for some of the commonly 
39 used systems. Note that, in general, options such as {\em smp}, {\em
40 --with-production}, compiler specifiers etc can be used with all targets. It is
41 advisable to build with {\em --with-production} to obtain the best performance.
42 If one desires to perform trace collection (for Projections), {\em
43 --enable-tracing --enable-tracing-commthread} should also be passed to the build command.
44
45 Details on all the available alternatives for each of the above mentioned
46 parameters can be found by invoking {\em ./build --help}. One can also go through the 
47 build process in an interactive manner. Run {\em ./build}, and it will be followed by 
48 a few queries to select appropiate choices for the build one wants to perform.
49
50
51 \begin{table}[ht]
52 \begin{tabular}{|p{6cm}|p{9cm}|}
53 \hline
54 Net with 32 bit Linux & ./build charm++ net-linux --with-production -j8
55 \\\hline
56 Multicore 64 bit Linux & ./build charm++ multicore-linux64 --with-production -j8
57 \\\hline
58 Net with 64 bit Linux & ./build charm++ net-linux-x86\_64 --with-production -j8
59 \\\hline
60 Net with 64 bit Linux (intel compilers) & ./build charm++ net-linux-x86\_64 icc --with-production -j8
61 \\\hline
62 Net with 64 bit Linux (shared memory) & ./build charm++ net-linux-x86\_64 smp --with-production -j8
63 \\\hline
64 Net with 64 bit Linux (checkpoint restart based fault tolerance) & ./build charm++ net-linux-x86\_64 syncft --with-production -j8
65 \\\hline
66 MPI with 64 bit Linux & ./build charm++ mpi-linux-x86\_64 --with-production -j8
67 \\\hline
68 MPI with 64 bit Linux (shared memory) & ./build charm++ mpi-linux-x86\_64 smp --with-production -j8
69 \\\hline
70 MPI with 64 bit Linux (mpicxx wrappers) & ./build charm++ mpi-linux-x86\_64 mpicxx --with-production -j8
71 \\\hline
72 IBVERBS with 64 bit Linux & ./build charm++ net-linux-x86\_64 ibverbs --with-production -j8
73 \\\hline
74 Net with 32 bit Windows & ./build charm++ net-win32 --with-production -j8
75 \\\hline
76 Net with 64 bit Windows & ./build charm++ net-win64 --with-production -j8
77 \\\hline
78 MPI with 64 bit Windows & ./build charm++ mpi-win64 --with-production -j8
79 \\\hline
80 Net with 64 bit Mac & ./build charm++ net-darwin-x86\_64 --with-production -j8
81 \\\hline
82 Blue Gene/L & ./build charm++ bluegenel xlc --with-production -j8
83 \\\hline
84 Blue Gene/P & ./build charm++ bluegenep xlc --with-production -j8
85 \\\hline
86 Blue Gene/Q & ./build charm++ pami-bluegeneq xlc --with-production -j8
87 \\\hline
88 Cray XT3 & ./build charm++ mpi-crayxt3 --with-production -j8
89 \\\hline
90 Cray XT5 & ./build charm++ mpi-crayxt --with-production -j8
91 \\\hline
92 Cray XE6 & ./build charm++ gemini\_gni-crayxe --with-production -j8
93 \\\hline
94 \end{tabular}
95 \caption{Build command for some common cases}
96 \label{tab:buildlist}
97 \end{table}
98
99 As mentioned earlier, one can also build \charmpp{} using the precompiled binary
100 in a manner similar to what is used for installing any common software.
101
102
103 The main directories in a \charmpp{} installation are:
104
105 \begin{description}
106 \item[\kw{charm/bin}]
107 Executables, such as charmc and charmrun,
108 used by \charmpp{}.
109
110 \item[\kw{charm/doc}]
111 Documentation for \charmpp{}, such as this
112 document.  Distributed as LaTeX source code; HTML and PDF versions
113 can be built or downloaded from our web site.
114
115 \item[\kw{charm/include}]
116 The \charmpp{} C++ and Fortran user include files (.h).
117
118 \item[\kw{charm/lib}]
119 The libraries (.a) that comprise \charmpp{}.
120
121 \item[\kw{charm/pgms}]
122 Example \charmpp{} programs.
123
124 \item[\kw{charm/src}]
125 Source code for \charmpp{} itself.
126
127 \item[\kw{charm/tmp}]
128 Directory where \charmpp{} is built.
129
130 \item[\kw{charm/tools}]
131 Visualization tools for \charmpp{} programs.
132
133 \item[\kw{charm/tests}]
134 Test \charmpp{} programs used by autobuild.
135
136 \end{description}
137
138 \section{Security Issues}
139
140 On most computers, \charmpp{} programs are simple binaries, and they pose
141 no more security issues than any other program would.  The only exception
142 is the network version {\tt net-*}, which has the following issues. 
143
144 The network versions utilize many unix processes communicating with
145 each other via UDP.  Only a simple attempt is currently made to filter out
146 unauthorized packets.  Therefore, it is theoretically possible to
147 mount a security attack by sending UDP packets to an executing
148 \converse{} or \charmpp{} program's sockets.
149
150 The second security issue associated with networked programs is
151 associated with the fact that we, the \charmpp{} developers, need evidence
152 that our tools are being used.  (Such evidence is useful in convincing
153 funding agencies to continue to support our work.)  To this end, we
154 have inserted code in the network {\tt charmrun} program (described
155 later) to notify us that our software is being used.
156 This notification is a single {\tt UDP} packet sent by {\tt charmrun}
157 to {\tt charm.cs.illinois.edu}.  This data is put
158 to one use only: it is gathered into tables recording the internet
159 domains in which our software is being used, the number of individuals
160 at each internet domain, and the frequency with which it is used.
161
162 We recognize that some users may have objections to our notification
163 code.  Therefore, we have provided a second copy of the {\tt
164 charmrun} program with the notification code removed.  If you look
165 within the {\tt bin} directory, you will find these programs:
166
167 \begin{alltt}
168     \$ cd charm/bin
169     \$ ls charmrun*
170     charmrun
171     charmrun-notify
172     charmrun-silent
173 \end{alltt}
174
175 The program {\tt charmrun.silent} has the notification code removed.  To
176 permanently deactivate notification, you may use the version without the
177 notification code:
178
179 \begin{alltt}
180     \$ cd charm/bin
181     \$ cp charmrun.silent charmrun
182 \end{alltt}
183
184 The only versions of \charmpp{} that ever notify us are 
185 the network versions.
186
187
188 \section{Reducing disk usage}
189
190 The charm directory contains a collection of example-programs and
191 test-programs.  These may be deleted with no other effects. You may 
192 also {\tt strip} all the binaries in {\tt charm/bin}.
193
194
195
196
197