added empty macro when CMK_OPTIMIZE defined.
[charm.git] / README
1                            Charm++ CVS Version
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 latest charm++ 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@charm.cs.uiuc.edu:/cvsroot login
24
25       when CVS password is prompted, just press 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
36 PICKING A VERSION
37 =================
38
39 First, you need to decide which version of charm++ to use. The "build" 
40 script in charm source directory takes several command line options to
41 compile Charm++. The command line syntax is:
42
43 build <target> <version> [options ...] [--basedir=dir] [--libdir=dir] [--incdir=dir] [charmc-options ...]
44
45 REQUIRED:
46 ---------
47 <target> specifies the parts of Charm++ to compile.  The most often used 
48   <target> is "charm++", which will compile the key Charm++ executables and 
49   runtime libraries.  Other common targets are "AMPI" and "FEM".
50 <versions> defines the CPU, OS and Communication layer of the machines.  See 
51   "How to choose a <version>" below for details.
52
53 OPTIONAL:
54 ---------
55 <options> defines more detailed information of the compilations, including 
56   compilers, features to support, etc.  See "How to choose <option>"
57   below.
58 [--libdir=dir] specify additional lib paths for building Charm++.
59 [--incdir=dir] specify additional include paths for building Charm++.
60 [--basedir=dir] a shortcut to specify additional include and lib paths for 
61                building Charm++, the include path is dir/include and lib path 
62                is dir/lib.
63
64
65 Running build script, a directory of the name of combination of version and 
66 options like "<version>-<option1>-<option2>-..." will be created and 
67 the build script will compile Charm++ under this directory.
68
69 For example, on an ordinary Linux PC:
70
71    ./build charm++ net-linux
72
73 will build charm++ in the directory: net-linux/.  The communication
74 defaults to UDP packets and the compiler to gcc.
75
76 For a more complex example, on a Scyld workstation with the Intel C++ 
77 compiler, where you want the communication to happen over TCP sockets:
78
79    ./build charm++ net-linux scyld icc tcp
80
81 will build charm++ in the directory: net-linux-scyld-tcp-icc/.
82
83 You can specify multiple options, however you can use at most one compiler 
84 option. The sequence of the options are not important given in build script, 
85 only one directory name will be generated, following the rules:
86 1. compiler option will be at the end;
87 2. other options are sorted alphabetically.
88
89 **** How to choose a <version> ****
90
91 Here is the table for choosing correct version. The default setting of compiler
92 in Charm version is gcc/g++. However, one can use <options> to specify other 
93 compilers. See the detailed explanation of the <options> below.
94 (Note: this isn't a complete list.  Run ./build for a complete listing)
95
96 Charm version          OS        Communication    Default Compiler  
97 -------------       ---------    --------------   --------------------
98 net-linux            PC Linux       UDP/Myrinet   GNU compiler
99 net-sol              Solaris        UDP           GNU compiler
100 net-win32            Win32          UDP           MS Visual C++
101 net-cygwin           Win32/cygwin   UDP           GNU compiler
102 mpi-sp               IBM A/IX       MPI           A/IX xlC Compiler 
103 mpi-origin           Origin2000     MPI           SGI C++ compiler
104
105 net-ppc-darwin       MacOS X        UDP           GNU C++ compiler
106 net-linux-ia64       IA64 Linux     UDP/Myrinet   GNU compiler
107 net-irix             IRIX           UDP           GNU compiler
108 net-axp              Alpha          UDP           GNU compiler
109 net-hp               HP-UX          UDP           GNU compiler
110 mpi-linux            PC Linux       MPI           GNU compiler
111 mpi-linux-ia64       IA64 Linux     MPI           GNU compiler
112 mpi-axp              Alpha          MPI           GNU compiler
113 mpi-linux-axp        Alpha Linux    MPI           GNU compiler
114 origin2000           Origin2000  shared-mem       SGI C++ compiler
115 t3e                  Cray T3E    shared-mem       Cray C++ compiler
116
117
118 To choose <version>, your choice is determined by three options:
119
120 1.)  The way a parallel program written in Charm++ will communicate:
121
122         "net-" Charm++ communicates using the regular TCP/IP stack
123 (UDP packets), which works everywhere but is fairly slow.  Use this
124 option for networks of workstations, clusters, or single-machine 
125 development and testing.
126
127         "mpi-" Charm++ communicates using MPI calls.  Use this for
128 machines with a good MPI implementation (such as the Origin 2000).
129
130         "exemplar", "ncube-2", "paragon-red", "sp3", and "t3e" Charm++
131 communicates using direct calls to the machine's communication primitives.
132
133         "sim-" and "uth-" are not actively maintained.  These are
134 single-processor versions: "uth-" simulates processors as user-level
135 threads; "sim-" switches between processors and counts communications.
136
137
138 2.)  Your operating system:
139
140         "linux"   Linux 
141         "win32"   MS Windows with MS Visual C++ compiler
142         "cygwin"  MS Windows with Cygnus' Cygwin Unix layer
143         "irix"    SGI IRIX
144         "origin"  SGI Origin 2000 IRIX
145         "sol"     Solaris
146         "sun"     SunOS
147         "rs6k"    IBM R/S 6000 A/IX 
148         "sp"      IBM SP A/IX
149         "hp"      Hewlett-Packard HP-UX
150         "axp"     DEC Alpha DECUNIX
151         
152
153 3.)  Some operating systems have other options, such as:
154         "-x86"     For Solaris, use PC hardware (instead of Sun).
155         "-axp"     For Linux, use Alpha hardware (instead of PC).
156         "-ia64"    Use Itanium(tm) instructions (instead of x86)
157
158 Your Charm++ version is made by concatenating the options, e.g.:
159
160 "net-linux"     Charm++ for a network of Linux workstations, compiled
161                 using g++.
162 "mpi-origin"    Charm++ for SGI Origin 2000, compiled using SGI CC.
163
164
165 **** How to choose <options> ****
166
167 <version> above defines the most important OS, CPU and Communication of 
168 your machine, and most of time, it use the GNU gcc as default compiler. 
169 To use different compiler or demand additional special feature support, you 
170 need to choose <options> from the following list:
171
172 * gcc3  - GNU GCC/G++ version 3
173 * acc  - HP aC++ compiler
174 * cc  - For Sun WorkShop C++ compilers;
175 * cc64 - For 64 bits Sun WorkShop C++ compilers;
176 * cxx - DIGITAL C++ compiler;
177 * kcc - KAI C++ compiler;
178 * pgcc - Portland Group's C++ compiler;
179 * icc - Intel C/C++ compiler for Linux IA32
180 * ecc - Intel C/C++ compiler for Linux IA64
181 * mpcc - SUN Solaris C++ compiler for MPI.
182
183 * scyld - support Beowulf Scyld;
184 * gm - support MyriCom's Myrinet GM library;
185 * vmi - support NCSA's VMI library;
186
187 * tcp - for net- version, default communication is via UDP. Using option
188         tcp will switch to TCP. TCP version of CHarm++ is usually slower
189         than UDP, but it is more reliable.
190 * smp - Enable direct SMP support.  An "smp" version communicates using
191         shared memory within a machine; but normal message passing across 
192         machines. Because of locking, "smp" may slightly impact non-SMP 
193         performance. Try your application to decide if enabling smp mode 
194         improves performance.
195
196 * bluegene - compile Charm++ as running on Blue Gene emulator.
197 * help - show supported options for a version. For example, for net-linux, 
198          running:
199          > ./build charm++ net-linux help
200          will give:
201          supported options: gcc3 gm icc kcc pgcc scyld smp bluegene tcp
202
203
204 BUILDING THE SOURCE
205 ===================
206
207 If you have downloaded a binary version of Charm++, you can skip
208 this step-- Charm++ should already be compiled.  For win32 systems,
209 see README.win32; for Cygwin version, see README.cygwin; for net- version, 
210 see README.net.
211
212 Once you have decided on a version, unpack Charm++, cd into charm,
213 and run
214
215      > ./build <target> <version> <opts>
216
217 <target> is one of
218         "charm++"  The basic Charm++ language.
219         "AMPI"     An implementation of MPI on top of Charm++
220         "FEM"      A Finite-Element framework on top of Charm++
221
222 <version> is described above
223
224 <opts> are build-time options (such as the compiler or "smp"), 
225 or command line options passed to the charmc compile script.
226 Common compile time options such as -g, -O, -Ipath, -Lpath, -llib are 
227 accepted.
228
229 For example, on a Linux machine, you would run
230      > ./build charm++ net-linux -O
231
232 This will construct a net-linux directory, link over all
233 the Charm++ source code into net-linux/tmp, build the entire
234 Charm++ runtime system in net-linux/tmp, and link sample programs 
235 into net-linux/pgms.
236
237 Several #define's control the compilation of Charm++.  Some of these
238 #define's can be found in src/<version>/conv-mach.h.  #define's can
239 also be specified on the command line, using the -D option.  For
240 example,
241     > ./build charm++ net-linux -O -DCMK_OPTIMIZE=1
242
243 CMK_OPTIMIZE: Turn on optimizations in Charm++/Converse. This disables most of
244 the run-time checking performed by Converse and Charm++ runtime. This option
245 should be used only after the program has been debugged. Also, this option
246 disables Converse/Charm++ tracing mechanisms such as projections and summary.
247
248
249 BUILDING A PROGRAM
250 ==================
251
252 To make a sample program, cd into pgms/charm++/queens/.
253 This program solves the N-queens problem-- find how many ways there 
254 are to arrange N queens on an NxN chess board such that none may 
255 attack another.
256
257 To build the program, type make.  You should get an
258 executable named "pgm".
259
260
261 RUNNING A PROGRAM
262 ==================
263
264 Following the previous example, to run the program on two processors, type
265
266      > ./charmrun ./pgm 12 100 +p2
267
268 This should run for a few seconds, and print out:
269 There are 14200 Solutions to 12 queens. Finish time=4.030000
270
271 Charmrun is used to provide a uniform interface to run charm programs.
272 On some platforms, charmrun is just a shell script which calls the 
273 platform-specific start program, such as mpirun on mpi versions.
274
275 For net- version, charmrun is an executable which invokes rsh or ssh to start 
276 node programs on remote machines. You should set up a ~/.nodelist that 
277 enumerates all the machines you want to run jobs on, otherwise it will
278 create a default ~/.nodelist for you that contains only localhost. Here is a 
279 typical .nodelist file:
280
281 group main ++shell /bin/ssh
282 host <machinename>
283
284 The default remote shell program is rsh, but you can define different remote 
285 shell you like to start remote processes in the ++shell option. You should 
286 also make sure that you can rsh or ssh to these machines without password 
287 authentication. Just type following command to verify:
288      > rsh <machinename> date
289 If this gives you current date immediately, your running environment with this 
290 node has been setup correctly.
291
292 Now, for test running purpose, net- version charmrun comes with an easy-to-use 
293 "++local" options. No remote shell invocation is needed in this case. It starts
294 node programs right on your local machine. This could be useful if you just 
295 want to run program on only one machine, for example, your laptop. This
296 can save you all the hassle of setting up rsh/ssh or charmd daemons.
297 To use this option, just type:
298      
299      > ./charmrun ++local ./pgm 12 100 +p2
300
301 However, for best performance, you should launch one node program per processor.
302
303 For more detailed information, please check the "INSTALLATION MANUAL" and "RUN MANUAL" 
304 under doc/install.
305
306
307 FOR MORE INFORMATION
308 ====================
309
310 The Charm++ web page, with documentation, more programs,
311 and the latest version of Charm++, is at
312         http://charm.cs.uiuc.edu/
313
314 The Charm++ mailing list, for questions, comments, suggestions, 
315 improvements, or bug reports is
316         ppl@cs.uiuc.edu
317
318
319 AUTHORS
320 =======
321
322 Charm++ was created and is maintained by the Parallel Programming Lab, 
323 in the Computer Science department at the University of Illinois at
324 Urbana-Champaign.  Our managing professor is Dr. L.V. Kale; students
325 have included (in rough time order) Wennie Shu, Kevin Nomura, Wayne
326 Fenton, Balkrishna Ramkumar, Vikram Saletore, Amitabh B. Sinha, Manish
327 Gupta, Attila Gursoy, Balkrishna Ramkumar, Amitabh B. Sinha, Nimish
328 Shah, Sanjeev Krishnan, Jayant DeSouza, Parthasarathy Ramachandran,
329 Jeff Wright, Michael Lang, Jackie Wang, Fang Hu, Michael Denardo,
330 Joshua Yelon, Narain Jagathesan, Zehra Sura, Krishnan Varadarajan, and
331 Sameer Paranjpye.  Current developers include Milind Bhandarkar,
332 Robert Brunner, Terry Wilmarth, Gengbin Zheng, Jayant Desouza, Orion
333 Lawlor, Karthik Mahesh, and Neelam Saboo.
334
335
336
337