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