added cvs server usage and charmrun information in README.
[charm.git] / README
1                               Charm++ 5.5
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
142
143 BUILDING A PROGRAM
144 ==================
145
146 To make a sample program, cd into _version_/pgms/charm++/queens/.
147 This program solves the N-queens problem-- find how many ways there 
148 are to arrange N queens on an NxN chess board such that none may 
149 attack another.  
150
151 To build the program, type make.  You should get an
152 executable named "pgm".
153
154
155 RUNNING A PROGRAM
156 ==================
157
158 Following the previous example, to run the program on two processors, type
159
160      > ./charmrun ./pgm 12 100 +p2
161
162 This should run for a few seconds, and print out:
163 There are 14200 Solutions to 12 queens. Finish time=4.030000
164
165 Charmrun is now available on all platforms. Depending on what platform you are 
166 running charm program, charmrun could be just a shell script which is a wrapper
167  for mpirun, for example, in mpi- version. The idea of charmrun is trying to 
168 provide a uniform parameters across all platforms.
169
170 For net- version, charmrun is an executable which invokes rsh or ssh to start 
171 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
172 create a default ~/.nodelist for you that contains only localhost. Here is a 
173 typical .nodelist file:
174
175 group main ++shell /bin/ssh
176 host machinename
177
178 The default remote shell program is rsh, but you can define differnt remote 
179 shell you like to start remote processes in the ++shell option. You should 
180 also make sure that you can rsh or ssh to these machines without passwd 
181 authentication. Just type following command to verify:
182      > rsh(ssh) machinename date
183 If this gives you current date immediately, your running environment with this 
184 node has been setup correctly.
185
186 Now, for test running purpose, net- version charmrun comes with an easy-to-use 
187 "++local" options. No remote shell invocation is needed in this case. It starts
188  node programs right on your local machine. This could be useful if you just 
189 want to run program on only one machine, for example, your laptop. This
190 can save you all the hassle of setting up rsh/ssh or charmd daemons.
191 To use this option, just type:
192      
193      > ./charmrun ++local ./pgm 12 100 +p2
194
195 However, for best performance, you should launch one node program per processor.
196
197 For more detailed information, please check the "INSTALLATION MANUAL" and "RUN MANUAL" under doc/install.
198
199 FOR MORE INFORMATION
200 ====================
201
202 The Charm++ web page, with documentation, more programs,
203 and the latest version of Charm++, is at
204         http://charm.cs.uiuc.edu/
205
206 The Charm++ mailing list, for questions, comments, suggestions, 
207 improvements, or bug reports is
208         ppl@cs.uiuc.edu
209
210
211 AUTHORS
212 =======
213
214 Charm++ is written and maintained by the Parallel Programming
215 Lab, in the Computer Science department at the University of 
216 Illinois at Urbana-Champaign.  Our managing professor is
217 Dr. L.V. Kale; students have included (in rough time order)
218 Wennie Shu, Kevin Nomura, Wayne Fenton, Balkrishna Ramkumar,
219 Vikram Saletore, Amitabh B. Sinha, Manish Gupta, Attila Gursoy, 
220 Balkrishna Ramkumar, Amitabh B. Sinha, Nimish Shah, Sanjeev 
221 Krishnan, Parthasarathy Ramachandran, Jeff Wright, Michael Lang, 
222 Jackie Wang, Fang Hu, Michael Denardo, Joshua Yelon, Narain Jagathesan,
223 Zehra Sura, Krishnan Varadarajan, and Sameer Paranjpye.  Current developers
224 include Milind Bhandarkar, Robert Brunner, Terry Wilmarth, Gengbin Zheng, 
225 Jayant Desouza, Orion Lawlor, Karthik Mahesh, and Neelam Saboo.