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