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