make a table for most versions with easy format, not cover all versions though.
[charm.git] / README
1                               Charm++ 5.4 (Release 1)
2
3        Copyright (C) 1989-2000 Regents of the University of Illinois
4
5 INTRODUCTION
6 ============
7
8 Charm++ is a message-passing parallel language and runtime system.
9 It is implemented as a set of libraries for C++, is efficient,
10 and is portable to a wide variety of parallel machines.
11 Source code is provided, and non-commercial use is free.
12
13
14 GETTING THE LATEST CHARM SOURCE
15 ===============================
16
17 You can use our anonymous cvs server to checkout the charm++ latest source code.
18 (It may not be the latest stable version though) 
19 What you need to do is as following:
20
21 1. login the cvs server:
22
23       cvs -d :pserver:checkout@thrift.cs.uiuc.edu:/expand6/cvsroot login
24
25       when CVS passwd is prompted, just type <Enter>.
26 2. checkout charm:
27
28       cvs co -P charm
29
30       You should get latest charm source tree.
31 3. logout the cvs server:
32
33       cvs logout
34
35 PICKING A VERSION
36 =================
37
38 First, you need to decide which version of charm++ to use. 
39 Here is a table for choosing correct version, for the detailed explanation
40 of the options see the comments following the table.
41 (Note: this table doesn't necessarily include all the current supported version,
42 run ./build in charm top directory to check the latest versions.)
43
44 Charm version          OS        Communication     Compiler  
45 -------------       ---------    --------------   --------------------
46 net-linux            PC Linux       UDP           GNU compiler
47 net-linux-kcc        PC Linux       UDP           KAI C++ compiler
48 net-linux-pgcc       PC Linux       UDP           Portland Group's C++ compiler
49 net-linux-scyld      PC Linux     Scyld/UDP       GNU compiler
50 net-linux-smp        PC Linux SMP workstations    GNU compiler
51 mpi-linux            PC Linux       MPI           GNU compiler
52 mpi-axp-cc           Alpha          MPI           DIGITAL C++ compiler  
53 mpi-linux-axp        Alpha Linux    MPI           GNU compiler
54 mpi-linux-axp-cxx    Alpha Linux    MPI           DIGITAL C++ compiler
55 net-axp-cc           Alpha          UDP           DIGITAL C++ compiler
56 net-cygwin           Win32/cygwin   UDP           GNU compiler
57 net-win32            Win32          UDP           MS Visual C++
58 net-sol-cc           Solaris        UDP           Sun WorkShop C++ Compiler
59 net-sol              Solaris        UDP           GNU compiler
60 net-irix             IRIX           UDP           SGI C++ compiler
61 net-irix-64          IRIX           UDP           SGI 64bits C++ compiler
62 origin2000           Origin2000  shared-mem       SGI C++ compiler     
63 mpi-origin           Origin2000     MPI           C++ compiler
64 net-hp               HP-UX          UDP           GNU compiler
65 net-hp-cc            HP-UX          UDP           HP-UX C++ compiler
66 net-hp-acc           HP-UX          UDP           HP-UX aC++ compiler
67 mpi-sp               AIX            MPI           AIX xlC Compiler 
68 t3e                  Cray T3E    shared-mem       Cray C++ compiler
69
70
71 Your choice is determined by three options:
72
73 1.)  The way a parallel program written in Charm++ will communicate:
74
75         "net-" Charm++ communicates using the regular TCP/IP stack
76 (UDP packets), which works everywhere but is fairly slow.  Use this
77 option for networks of workstations, clusters, or single-machine 
78 development and testing.
79
80         "mpi-" Charm++ communicates using MPI calls.  Use this for
81 machines with a good MPI implementation (such as the Origin 2000).
82
83         "exemplar", "ncube-2", "paragon-red", "sp3", and "t3e" Charm++
84 communicates using direct calls to the machine's communication primitives.
85
86         "sim-" and "uth-" are not actively maintained.  These are
87 single-processor versions: "uth-" simulates processors as user-level
88 threads; "sim-" switches between processors and counts communications.
89
90
91 2.)  Your operating system:
92
93         "linux"   Linux 
94         "win32"   MS Windows NT/98/2k (and MS Visual C++ compiler)
95         "cygwin"  MS Windows 98/NT/2k with Cygnus' Cygwin Unix layer
96         "irix"    SGI IRIX
97         "origin"  SGI Origin 2000 IRIX
98         "sol"     Solaris
99         "sun"     SunOS
100         "rs6k"    IBM R/S 6000 A/IX 
101         "sp"      IBM SP A/IX
102         "hp"      Hewlett-Packard HP-UX
103         "axp"     DEC Alpha DECUNIX
104         
105
106 3.)  Your compiler and other options.  Charm++ normally picks an
107 appropriate compiler for the system, but you may select another
108 compiler:
109
110         "-cc"      The OEM C/C++ compiler.  When given, this
111 will override the choice of the GNU C/C++ compiler.
112         "-kcc"     Kuck & Associates C++ compiler.
113         "-acc"     Uses HP's aCC instead of CC.
114         "-pgcc"    Portland Group's ANSI and K&R C compiler.
115
116 Some operating systems have other options, such as:
117         "-x86"     For Solaris, use PC hardware (instead of Sun).
118         "-axp"     For Linux, use Alpha hardware (instead of PC).
119         "-64"      For IRIX, use -64 instead of -32. 
120         "-scyld"   For Beowulf Cluster with Scyld.
121         "-vmi"     For NCSA's Virtual Machine Interface.
122
123 You may also choose to enable direct SMP support with a "-smp"
124 version, which may result in more efficient communication in
125 a cluster-of-SMPs.  A "-smp" version will communicate using
126 shared memory within a machine; but message passing across machines.
127 "-smp" is currently only available with "net-" versions.
128 Because of locking, "-smp" may slightly impact non-SMP performance.
129
130
131 Your Charm++ version is made by concatenating all three options, e.g.:
132
133 "net-linux"     Charm++ for a network of Linux workstations, compiled
134                 using g++.
135 "net-linux-kcc" Charm++ for a network of Linux workstations, compiled
136                 using Kuck & Associates C++ compiler.
137 "net-linux-smp" Charm++ for a network of Linux SMP workstations,
138                 compiled using g++.
139 "net-sol-cc"    Charm++ for a network of Sun workstations, 
140                 compiled using Sun CC.
141 "mpi-origin"    Charm++ for SGI Origin 2000, compiled using SGI CC.
142
143
144
145 BUILDING THE SOURCE
146 ===================
147
148 If you have downloaded a binary version of Charm++, you can skip
149 this step-- Charm++ should already be compiled.  For win32 systems,
150 see README.win32; for Cygwin version, see README.cygwin; for net- version, 
151 see README.net.
152
153 Once you have decided on a version, unpack Charm++, cd into charm,
154 and run
155
156      > ./build _target_ _version_ _opts_
157
158 Where _target_ is one of
159         "charm++"  The basic Charm++ language.
160         "AMPI"     An implementation of MPI on top of Charm++
161         "FEM"      A Finite-Element framework on top of Charm++
162
163 And _opts_ are command line options passed to the charmc compile script.
164 Common compile time options such as -g, -O, -Ipath, -Lpath, -llib are 
165 accepted.
166
167 For example, on a Linux machine, you would run
168      > ./build charm++ net-linux -O
169
170
171 This will construct a _version_ directory, link over all
172 the Charm++ source code into _version_/tmp, build the entire
173 Charm++ runtime system in _version_/tmp, and link sample programs 
174 into _version_/pgms.
175
176 Several #define's control the compilation of Charm++.  Some of these
177 #define's can be found in src/_version_/conv-mach.h.  #define's can
178 also be specified on the command line, using the -D option.  For
179 example,
180     > ./build charm++ net-linux -O -DCMK_OPTIMIZE=1
181
182 CMK_OPTIMIZE: Turn on optimizations in Charm++/Converse. This disbles most of
183 the run-time checking performed by Converse and Charm++ runtime. This option
184 should be used only after the program has been debugged. Also, this option
185 disables Converse/Charm++ tracing mechanisms such as projections and summary.
186
187 CMK_THREADS_USE_ISOMALLOC: Ths option specifies that the user-level threads in
188 Converse/Charm++ be migratable using a method called isomalloc. The
189 isomalloc-based threads make sure that the thread's stack spans a unique range
190 of virtual addresses across all the processors. Thus, references to stack
191 remain valid even when a thread migrates to different processor.
192
193 CMK_THREADS_USE_COPY_STACK: This option specifies that the user-level threads
194 in Converse/Charm++ be migratable by using a method where the used portion of a
195 thread's stack is copied in and out of a main stack on context-switch. Since
196 the main (process) stack spans the same range of virtual addresses in all
197 processes in a homogeneous cluster, references to stack remain valid across al
198 te processors even after a thread migrates.
199
200 CMK_THREADS_USE_PTHREADS: This is an alternate implementation of
201 Converse/Charm++ user-level threads that use Posix threads. They have higher
202 (about 10 times) context-switching costs over the default implementation of
203 threads in Converse. However, they are more portable. In particular, they avoid
204 some of the known problems in the way current linuxthreads implementation
205 interacts with the default user-level threads in Converse. Also, memory
206 debugging tols such as purify are incompatible with Converse's default
207 user-level threads. The implementation based on posix threads can be used for
208 memory debugging with purify.
209
210 CMK_TRUECRASH: The net-* version of Converse trap a number of signals such as
211 SIGSEGV and SIGBUS to gracefully handle premature termination of Converse
212 programs. The downside to this is that these signals do not produce core dumps
213 for post-mortem debugging. Setting CMK_TRUECRASH to 1 while building
214 Converse/Charm++ on these machines allows core dumps to be produced on abnormal
215 terminations.
216
217 BUILDING A PROGRAM
218 ==================
219
220 To make a sample program, cd into _version_/pgms/charm++/queens/.
221 This program solves the N-queens problem-- find how many ways there 
222 are to arrange N queens on an NxN chess board such that none may 
223 attack another.  
224
225 To build the program, type make.  You should get an
226 executable named "pgm".
227
228
229 RUNNING A PROGRAM
230 ==================
231
232 Following the previous example, to run the program on two processors, type
233
234      > ./charmrun ./pgm 12 100 +p2
235
236 This should run for a few seconds, and print out:
237 There are 14200 Solutions to 12 queens. Finish time=4.030000
238
239 Charmrun is now available on all platforms. Depending on what platform you are 
240 running charm program, charmrun could be just a shell script which is a wrapper
241  for mpirun, for example, in mpi- version. The idea of charmrun is trying to 
242 provide a uniform parameters across all platforms.
243
244 For net- version, charmrun is an executable which invokes rsh or ssh to start 
245 node programs on remote machines. Remember that you should set up a ~/.nodelist that enumerates all the machines you want to run jobs on, otherwise it will
246 create a default ~/.nodelist for you that contains only localhost. Here is a 
247 typical .nodelist file:
248
249 group main ++shell /bin/ssh
250 host machinename
251
252 The default remote shell program is rsh, but you can define differnt remote 
253 shell you like to start remote processes in the ++shell option. You should 
254 also make sure that you can rsh or ssh to these machines without passwd 
255 authentication. Just type following command to verify:
256      > rsh(ssh) machinename date
257 If this gives you current date immediately, your running environment with this 
258 node has been setup correctly.
259
260 Now, for test running purpose, net- version charmrun comes with an easy-to-use 
261 "++local" options. No remote shell invocation is needed in this case. It starts
262  node programs right on your local machine. This could be useful if you just 
263 want to run program on only one machine, for example, your laptop. This
264 can save you all the hassle of setting up rsh/ssh or charmd daemons.
265 To use this option, just type:
266      
267      > ./charmrun ++local ./pgm 12 100 +p2
268
269 However, for best performance, you should launch one node program per processor.
270
271 For more detailed information, please check the "INSTALLATION MANUAL" and "RUN MANUAL" under doc/install.
272
273 FOR MORE INFORMATION
274 ====================
275
276 The Charm++ web page, with documentation, more programs,
277 and the latest version of Charm++, is at
278         http://charm.cs.uiuc.edu/
279
280 The Charm++ mailing list, for questions, comments, suggestions, 
281 improvements, or bug reports is
282         ppl@cs.uiuc.edu
283
284
285 AUTHORS
286 =======
287
288 Charm++ is written and maintained by the Parallel Programming Lab, in
289 the Computer Science department at the University of Illinois at
290 Urbana-Champaign.  Our managing professor is Dr. L.V. Kale; students
291 have included (in rough time order) Wennie Shu, Kevin Nomura, Wayne
292 Fenton, Balkrishna Ramkumar, Vikram Saletore, Amitabh B. Sinha, Manish
293 Gupta, Attila Gursoy, Balkrishna Ramkumar, Amitabh B. Sinha, Nimish
294 Shah, Sanjeev Krishnan, Jayant DeSouza, Parthasarathy Ramachandran,
295 Jeff Wright, Michael Lang, Jackie Wang, Fang Hu, Michael Denardo,
296 Joshua Yelon, Narain Jagathesan, Zehra Sura, Krishnan Varadarajan, and
297 Sameer Paranjpye.  Current developers include Milind Bhandarkar,
298 Robert Brunner, Terry Wilmarth, Gengbin Zheng, Jayant Desouza, Orion
299 Lawlor, Karthik Mahesh, and Neelam Saboo.
300