Added passing options to SUPER_INSTALL.
[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 PICKING A VERSION
15 =================
16
17 First, you need to decide which version of charm++ to use.  Your
18 choice is determined by three options:
19
20 1.)  The way a parallel program written in Charm++ will communicate:
21
22         "net-" Charm++ communicates using the regular TCP/IP stack
23 (UDP packets), which works everywhere but is fairly slow.  Use this
24 option for networks of workstations, clusters, or single-machine 
25 development and testing.
26
27         "mpi-" Charm++ communicates using MPI calls.  Use this for
28 machines with a good MPI implementation (such as the Origin 2000).
29
30         "exemplar", "ncube-2", "paragon-red", "sp3", and "t3e" Charm++
31 communicates using direct calls to the machine's communication primitives.
32
33         "sim-" and "uth-" are not actively maintained.  These are
34 single-processor versions: "uth-" simulates processors as user-level
35 threads; "sim-" switches between processors and counts communications.
36
37
38 2.)  Your operating system:
39
40         "linux"   Linux 
41         "win32"   MS Windows NT/98/2k (and MS Visual C++ compiler)
42         "cygwin"  MS Windows with Cygnus' Cygwin Unix layer
43         "irix"    SGI IRIX
44         "origin"  SGI Origin 2000 IRIX
45         "sol"     Solaris
46         "sun"     SunOS
47         "rs6k"    IBM R/S 6000 A/IX 
48         "sp"      IBM SP A/IX
49         "hp"      Hewlett-Packard HP-UX
50         "axp"     DEC Alpha DECUNIX
51         
52
53 3.)  Your compiler and other options.  Charm++ normally picks an
54 appropriate compiler for the system, but you may select another
55 compiler:
56
57         "-cc"      The OEM C/C++ compiler.  When given, this
58 will override the choice of the GNU C/C++ compiler.
59         "-kcc"     Kuck & Associates C++ compiler.
60         "-acc"     Uses HP's aCC instead of CC.
61
62 Some operating systems have other options, such as:
63         "-x86"     For Solaris, use PC hardware (instead of Sun).
64         "-axp"     For Linux, use Alpha hardware (instead of PC).
65         "-64"      For IRIX, use -64 instead of -32. 
66
67 You may also choose to enable direct SMP support with a "-smp"
68 version, which may result in more efficient communication in
69 a cluster-of-SMPs.  A "-smp" version will communicate using
70 shared memory within a machine; but message passing across machines.
71 "-smp" is currently only available with "net-" versions.
72 Because of locking, "-smp" may slightly impact non-SMP performance.
73
74
75 Your Charm++ version is made by concatenating all three options, e.g.:
76
77 "net-linux"     Charm++ for a network of Linux workstations, compiled
78                 using g++.
79 "net-linux-kcc" Charm++ for a network of Linux workstations, compiled
80                 using Kuck & Associates C++ compiler.
81 "net-linux-smp" Charm++ for a network of Linux SMP workstations,
82                 compiled using g++.
83 "net-sol-cc"    Charm++ for a network of Sun workstations, 
84                 compiled using Sun CC.
85 "mpi-origin"    Charm++ for SGI Origin 2000, compiled using SGI CC.
86
87
88
89 BUILDING THE SOURCE
90 ===================
91
92 If you have downloaded a binary version of Charm++, you can skip
93 this step-- Charm++ should already be compiled.  For win32 systems,
94 see README.win32; for net- version, see README.net
95
96 Once you have decided on a version, unpack Charm++, cd into charm,
97 and run
98
99      > ./SUPER_INSTALL _target_ _version_ _opts_
100
101 Where _target_ is one of
102         "charm++"  The basic Charm++ language.
103         "AMPI"     An implementation of MPI on top of Charm++
104         "FEM"      A Finite-Element framework on top of Charm++
105
106 And _opts_ are command line options passed to the charmc compile script.
107 Common compile time options such as -g, -O, -Ipath, -Lpath, -llib are 
108 accepted.
109
110 For example, on a Linux machine, you would run
111      > ./SUPER_INSTALL charm++ net-linux -O
112
113
114 This will construct a _version_ directory, link over all
115 the Charm++ source code into _version_/tmp, build the entire
116 Charm++ runtime system in _version_/tmp, and link sample programs 
117 into _version_/pgms.
118
119
120
121 BUILDING A PROGRAM
122 ==================
123
124 To make a sample program, cd into _version_/pgms/charm++/queens/.
125 This program solves the N-queens problem-- find how many ways there 
126 are to arrange N queens on an NxN chess board such that none may 
127 attack another.  
128
129 To build the program, type make.  You should get an
130 executable named "pgm".
131
132 To run the program on two processors, type
133      > ./charmrun pgm 12 100 +p2
134
135 This should run for a few seconds, and print out:
136 There are 14200 Solutions to 12 queens. Finish time=4.030000
137
138
139
140 FOR MORE INFORMATION
141 ====================
142
143 The Charm++ web page, with documentation, more programs,
144 and the latest version of Charm++, is at
145         http://charm.cs.uiuc.edu/
146
147 The Charm++ mailing list, for questions, comments, suggestions, 
148 improvements, or bug reports is
149         ppl@cs.uiuc.edu
150
151
152 AUTHORS
153 =======
154
155 Charm++ is written and maintained by the Parallel Programming
156 Lab, in the Computer Science department at the University of 
157 Illinois at Urbana-Champaign.  Our managing professor is
158 Dr. L.V. Kale; students have included (in rough time order)
159 Wennie Shu, Kevin Nomura, Wayne Fenton, Balkrishna Ramkumar,
160 Vikram Saletore, Amitabh B. Sinha, Manish Gupta, Attila Gursoy, 
161 Balkrishna Ramkumar, Amitabh B. Sinha, Nimish Shah, Sanjeev 
162 Krishnan, Parthasarathy Ramachandran, Jeff Wright, Michael Lang, 
163 Jackie Wang, Fang Hu, Michael Denardo, Joshua Yelon, Narain Jagathesan,
164 Zehra Sura, Krishnan Varadarajan, and Sameer Paranjpye.  Current developers
165 include Milind Bhandarkar, Robert Brunner, Terry Wilmarth, Gengbin Zheng, 
166 Jayant Desouza, Orion Lawlor, Karthik Mahesh, and Neelam Saboo.