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