properly compile ckcache.ci when int16 is supported.
[charm.git] / README
diff --git a/README b/README
index 0941a46bb4a50875c59fb917b328c814ad3c5cf4..d601d08a6657f77447eb950d0012eaccca277b19 100644 (file)
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
-                              Charm++ 5.5
+                           Charm++
 
-       Copyright (C) 1989-2000 Regents of the University of Illinois
+       Copyright (C) 1989-2012 Regents of the University of Illinois
 
 INTRODUCTION
 ============
@@ -14,29 +14,98 @@ Source code is provided, and non-commercial use is free.
 GETTING THE LATEST CHARM SOURCE
 ===============================
 
-You can use our anonymous cvs server to checkout the charm++ latest source code.
-(It may not be the latest stable version though) 
-What you need to do is as following:
+You can use anonymous Git access to obtain the latest Charm++ source
+code, as follows:
 
-1. login the cvs server:
+    git clone git://charm.cs.illinois.edu/charm.git
 
-      cvs -d :pserver:checkout@thrift.cs.uiuc.edu:/expand6/cvsroot login
-
-      when CVS passwd is prompted, just type <Enter>.
-2. checkout charm:
-
-      cvs co -P charm
-
-      You should get latest charm source tree.
-3. logout the cvs server:
-
-      cvs logout
 
 PICKING A VERSION
 =================
 
-First, you need to decide which version of charm++ to use.  Your
-choice is determined by three options:
+First, you need to decide which version of charm++ to use. The "build" 
+script in charm source directory takes several command line options to
+compile Charm++. The command line syntax is:
+
+build <target> <version> [options ...]
+                         [--basedir=dir] [--libdir=dir] [--incdir=dir]
+                         [charmc-options ...]
+
+For detailed help messages, pass -h or --help to the build script, i.e.
+./build --help
+
+REQUIRED:
+---------
+<target> specifies the parts of Charm++ to compile.  The most often used 
+  <target> is "charm++", which will compile the key Charm++ executables and 
+  runtime libraries.  Other common targets are "AMPI" and "FEM".
+<versions> defines the CPU, OS and Communication layer of the machines.  See 
+  "How to choose a <version>" below for details.
+
+OPTIONAL:
+---------
+<options> defines more detailed information of the compilations, including 
+  compilers, features to support, etc.  See "How to choose <option>"
+  below.
+[--libdir=dir] specify additional lib paths for building Charm++.
+[--incdir=dir] specify additional include paths for building Charm++.
+[--basedir=dir] a shortcut to specify additional include and lib paths for 
+               building Charm++, the include path is dir/include and lib path 
+               is dir/lib.
+
+
+Running build script, a directory of the name of combination of version and 
+options like "<version>-<option1>-<option2>-..." will be created and 
+the build script will compile Charm++ under this directory.
+
+For example, on an ordinary Linux PC:
+
+   ./build charm++ net-linux-x86_64
+
+will build charm++ in the directory: net-linux-x86_64/. The communication
+defaults to UDP packets and the compiler to gcc.
+
+For a more complex example, on a Scyld workstation with the Intel C++ 
+compiler, where you want the communication to happen over TCP sockets:
+
+   ./build charm++ net-linux scyld icc tcp
+
+will build charm++ in the directory: net-linux-scyld-tcp-icc/.
+
+You can specify multiple options, however you can use at most one compiler 
+option. The sequence of the options are not important given in build script, 
+only one directory name will be generated, following the rules:
+1. compiler option will be at the end;
+2. other options are sorted alphabetically.
+
+**** How to choose a <version> ****
+
+Here is the table for choosing correct version. The default setting of compiler
+in Charm version is gcc/g++. However, one can use <options> to specify other 
+compilers. See the detailed explanation of the <options> below.
+(Note: this isn't a complete list.  Run ./build for a complete listing)
+
+Charm version          OS        Communication    Default Compiler  
+-------------       ---------    --------------   --------------------
+net-linux            PC Linux       UDP/Myrinet   GNU compiler
+net-sol              Solaris        UDP           GNU compiler
+net-win32            Win32          UDP           MS Visual C++
+net-cygwin           Win32/cygwin   UDP           GNU compiler
+mpi-sp               IBM A/IX       MPI           A/IX xlC Compiler 
+mpi-origin           Origin2000     MPI           SGI C++ compiler
+net-ppc-darwin       MacOS X        UDP           GNU C++ compiler
+net-linux-ia64       IA64 Linux     UDP/Myrinet   GNU compiler
+net-linux-amd64      Opteron Linux  UDP           GNU compiler
+net-irix             IRIX          UDP           GNU compiler
+net-axp              Alpha          UDP           GNU compiler
+net-hp               HP-UX          UDP           GNU compiler
+mpi-linux            PC Linux       MPI           GNU compiler
+mpi-ppc-darwin       MacOS X        MPI           GNU C++ compiler
+mpi-linux-ia64       IA64 Linux     MPI           GNU compiler
+mpi-linux-x86_64     Opteron Linux  MPI           GNU compiler
+
+
+To choose <version>, your choice is determined by three options:
 
 1.)  The way a parallel program written in Charm++ will communicate:
 
@@ -48,9 +117,12 @@ development and testing.
        "mpi-" Charm++ communicates using MPI calls.  Use this for
 machines with a good MPI implementation (such as the Origin 2000).
 
-       "exemplar", "ncube-2", "paragon-red", "sp3", and "t3e" Charm++
+       "gemini_gni-", "bluegene[lp]-", "pami-bluegeneq-" Charm++
 communicates using direct calls to the machine's communication primitives.
 
+       "multicore-" Charm++ communicates using shared memory within a
+       single node
+
        "sim-" and "uth-" are not actively maintained.  These are
 single-processor versions: "uth-" simulates processors as user-level
 threads; "sim-" switches between processors and counts communications.
@@ -58,95 +130,149 @@ threads; "sim-" switches between processors and counts communications.
 
 2.)  Your operating system:
 
-       "linux"   Linux 
-       "win32"   MS Windows NT/98/2k (and MS Visual C++ compiler)
-       "cygwin"  MS Windows 98/NT/2k with Cygnus' Cygwin Unix layer
-       "irix"    SGI IRIX
-       "origin"  SGI Origin 2000 IRIX
-       "sol"     Solaris
-       "sun"     SunOS
-       "rs6k"    IBM R/S 6000 A/IX 
-       "sp"      IBM SP A/IX
-       "hp"      Hewlett-Packard HP-UX
-       "axp"     DEC Alpha DECUNIX
-       
-
-3.)  Your compiler and other options.  Charm++ normally picks an
-appropriate compiler for the system, but you may select another
-compiler:
-
-       "-cc"      The OEM C/C++ compiler.  When given, this
-will override the choice of the GNU C/C++ compiler.
-       "-kcc"     Kuck & Associates C++ compiler.
-       "-acc"     Uses HP's aCC instead of CC.
-
-Some operating systems have other options, such as:
-       "-x86"     For Solaris, use PC hardware (instead of Sun).
-       "-axp"     For Linux, use Alpha hardware (instead of PC).
-       "-64"      For IRIX, use -64 instead of -32. 
-
-You may also choose to enable direct SMP support with a "-smp"
-version, which may result in more efficient communication in
-a cluster-of-SMPs.  A "-smp" version will communicate using
-shared memory within a machine; but message passing across machines.
-"-smp" is currently only available with "net-" versions.
-Because of locking, "-smp" may slightly impact non-SMP performance.
-
-
-Your Charm++ version is made by concatenating all three options, e.g.:
-
-"net-linux"     Charm++ for a network of Linux workstations, compiled
-                using g++.
-"net-linux-kcc" Charm++ for a network of Linux workstations, compiled
-                using Kuck & Associates C++ compiler.
-"net-linux-smp" Charm++ for a network of Linux SMP workstations,
-                compiled using g++.
-"net-sol-cc"    Charm++ for a network of Sun workstations, 
-                compiled using Sun CC.
-"mpi-origin"    Charm++ for SGI Origin 2000, compiled using SGI CC.
-
+       "linux"       Linux
+       "win{32,64}"  MS Windows with MS Visual C++ compiler (32/64-bit, resp.)
+       "cygwin"      MS Windows with Cygnus' Cygwin Unix layer
+       "darwin"      Apple Mac OS X
+       "sol"         Solaris
+       "aix"         IBM A/IX
+       "sp"          IBM SP A/IX
+
+
+3.)  Some operating systems have other architecture options, such as:
+
+       "-x86"     For Solaris and Mac OS X, target x86 hardware (instead of
+                  SPARC or PPC).
+       "-ppc"     POWER/PowerPC
+       "-mips64"  MIPS, such as for SiCortex systems
+        "-ia64"    Use Itanium(tm) IA-64 instructions (instead of x86).
+        "-x86_64"  Use AMD64/EM64T 64-bit x86 instructions (instead of 32 bit).
+       "-cell"    Sony/Toshiba/IBM Cell PPE (e.g. Playstation 3,
+                  Mercury blades, Roadrunner)
+
+Your Charm++ version is made by concatenating the options, e.g.:
+
+"net-linux-x86_64"   Charm++ for a network of 64-bit Linux workstations,
+                     compiled using g++.
+
+"mpi-crayxt"         Charm++ for Cray XT4/5 systems using the system's compiler.
+
+
+**** How to choose <options> ****
+
+<version> above defines the most important OS, CPU and Communication of 
+your machine, and most of time, it use the GNU gcc as default compiler. 
+To use different compiler or demand additional special feature support, you 
+need to choose <options> from the following list:
+
+* gcc3  - GNU GCC/G++ version 3
+* acc  - HP aC++ compiler
+* cc  - For Sun WorkShop C++ compilers;
+* cc64 - For 64 bits Sun WorkShop C++ or IBM xlC compilers;
+* cxx - DIGITAL C++ compiler;
+* kcc - KAI C++ compiler;
+* pgcc - Portland Group's C++ compiler;
+* icc - Intel C/C++ compiler for Linux IA32
+* ecc - Intel C/C++ compiler for Linux IA64
+* mpcc - SUN Solaris C++ compiler for MPI.
+
+* scyld - support Beowulf Scyld based on bproc;
+* clustermatic - for Clustermatic Beowulf cluster based on bproc;
+* gm - support MyriCom's Myrinet GM library;
+* vmi - support NCSA's VMI library;
+
+* tcp - for net- version, default communication is via UDP. Using option
+        tcp will switch to TCP. TCP version of CHarm++ is usually slower
+        than UDP, but it is more reliable.
+* smp - Enable direct SMP support.  An "smp" version communicates using
+        shared memory within a machine; but normal message passing across 
+        machines. Because of locking, "smp" may slightly impact non-SMP 
+        performance. Try your application to decide if enabling smp mode 
+        improves performance.
+
+* bigsim - compile Charm++ as running on the BigSim emulator.
+* help - show supported options for a version. For example, for net-linux, 
+         running:
+         > ./build charm++ net-linux help
+         will give:
+         supported options: gcc3 gm icc kcc pgcc scyld smp bluegene tcp
 
 
 BUILDING THE SOURCE
 ===================
 
 If you have downloaded a binary version of Charm++, you can skip
-this step-- Charm++ should already be compiled.  For win32 systems,
-see README.win32; for Cygwin version, see README.cygwin; for net- version, 
+this step-- Charm++ should already be compiled.  For win32/win64 systems,
+see README.win; for Cygwin version, see README.cygwin; for net- version, 
 see README.net.
 
 Once you have decided on a version, unpack Charm++, cd into charm,
 and run
 
-     > ./build _target_ _version_ _opts_
+     > ./build <target> <version> <opts>
 
-Where _target_ is one of
+<target> is one of
        "charm++"  The basic Charm++ language.
        "AMPI"     An implementation of MPI on top of Charm++
        "FEM"      A Finite-Element framework on top of Charm++
+       "Tau"      TAU's performance profiling/tracing
 
-And _opts_ are command line options passed to the charmc compile script.
+<version> is described above
+
+<opts> are build-time options (such as the compiler or "smp"), 
+or command line options passed to the charmc compile script.
 Common compile time options such as -g, -O, -Ipath, -Lpath, -llib are 
 accepted.
 
 For example, on a Linux machine, you would run
-     > ./build charm++ net-linux -O
-
-
-This will construct a _version_ directory, link over all
-the Charm++ source code into _version_/tmp, build the entire
-Charm++ runtime system in _version_/tmp, and link sample programs 
-into _version_/pgms.
-
-
+     > ./build charm++ net-linux-x86_64 -O
+
+This will construct a net-linux-x86_64 directory, link over all
+the Charm++ source code into net-linux-x86_64/tmp, build the entire
+Charm++ runtime system in net-linux-x86_64/tmp, and link example programs
+into net-linux-x86_64/examples.
+
+Several #define's control the compilation of Charm++.  Some of these
+#define's can be found in src/<version>/conv-mach.h.  #define's can
+also be specified on the command line, using the -D option.  For
+example,
+    > ./build charm++ net-linux -O -DCMK_OPTIMIZE=1
+
+Production optimizations: Pass the configure option --with-production
+to ./build to turn on optimizations in Charm++/Converse. This disables
+most of the run-time checking performed by Converse and Charm++
+runtime. This option should be used only after the program has been
+debugged. Also, this option disables Converse/Charm++ tracing
+mechanisms such as projections and summary.
+
+When Charm++ is built successfully, the diretory structure under the
+target directory will look like:
+
+net-linux-x86_64/
+   |
+   ---  bin/                   # all executables
+   |
+   ---  doc/                   # documentations
+   |
+   ---  include/               # header files
+   |
+   ---  lib/                   # libraries
+   |
+   ---  lib_so/                        # dynamic libraries
+   |
+   ---  examples/              # all example programs
+   |
+   ---  tests/                 # all test programs
+   |
+   ---  tmp/                   # Charm++ build directory
 
 BUILDING A PROGRAM
 ==================
 
-To make a sample program, cd into _version_/pgms/charm++/queens/.
+To make a sample program, cd into pgms/charm++/queens/.
 This program solves the N-queens problem-- find how many ways there 
 are to arrange N queens on an NxN chess board such that none may 
-attack another.  
+attack another.
 
 To build the program, type make.  You should get an
 executable named "pgm".
@@ -157,35 +283,35 @@ RUNNING A PROGRAM
 
 Following the previous example, to run the program on two processors, type
 
-     > ./charmrun ./pgm 12 100 +p2
+     > ./charmrun ./pgm 12 6 +p2
 
 This should run for a few seconds, and print out:
 There are 14200 Solutions to 12 queens. Finish time=4.030000
 
-Charmrun is now available on all platforms. Depending on what platform you are 
-running charm program, charmrun could be just a shell script which is a wrapper
- for mpirun, for example, in mpi- version. The idea of charmrun is trying to 
-provide a uniform parameters across all platforms.
+Charmrun is used to provide a uniform interface to run charm programs.
+On some platforms, charmrun is just a shell script which calls the 
+platform-specific start program, such as mpirun on mpi versions.
 
 For net- version, charmrun is an executable which invokes rsh or ssh to start 
-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
+node programs on remote machines. You should set up a ~/.nodelist that 
+enumerates all the machines you want to run jobs on, otherwise it will
 create a default ~/.nodelist for you that contains only localhost. Here is a 
 typical .nodelist file:
 
 group main ++shell /bin/ssh
-host machinename
+host <machinename>
 
-The default remote shell program is rsh, but you can define differnt remote 
+The default remote shell program is rsh, but you can define different remote 
 shell you like to start remote processes in the ++shell option. You should 
-also make sure that you can rsh or ssh to these machines without passwd 
+also make sure that you can rsh or ssh to these machines without passwor
 authentication. Just type following command to verify:
-     > rsh(ssh) machinename date
+     > rsh <machinename> date
 If this gives you current date immediately, your running environment with this 
 node has been setup correctly.
 
 Now, for test running purpose, net- version charmrun comes with an easy-to-use 
 "++local" options. No remote shell invocation is needed in this case. It starts
- node programs right on your local machine. This could be useful if you just 
+node programs right on your local machine. This could be useful if you just 
 want to run program on only one machine, for example, your laptop. This
 can save you all the hassle of setting up rsh/ssh or charmd daemons.
 To use this option, just type:
@@ -194,32 +320,62 @@ To use this option, just type:
 
 However, for best performance, you should launch one node program per processor.
 
-For more detailed information, please check the "INSTALLATION MANUAL" and "RUN MANUAL" under doc/install.
+For more detailed information, please check the "INSTALLATION MANUAL" and "RUN MANUAL" 
+under doc/install.
+
+
+Build Charm++ in Dynamic libraries
+=============================
+
+In order to compile Charm++ into dynamic libraries, one need to specify
+"-build-shared" option as one of the Charm compiler script "charmc" 
+at link time. For example, to compile Charm++ under net-linux/tmp, run
+
+make charm++ OPTS='-O -build-shared'
+
+Charm++'s dynamic libraries are compiled into lib_so/ directory. 
+Typically, they are with ".so" suffix.
+
+Note, "-build-shared" option is automatically turned on when building 
+Charm++ using "build" script. So you don't need to pass "-build-shared" 
+option to "build".
+
+One can compile a Charm++ applicaiton linking against Charm++ dynamic 
+libraries, run charmc with "-charm-shared" as one of the link options.
+For example:
+
+charmc -o pgm pgm.o -charm-shared
+
+You can then run the program as usual.
+Note, linking against Charm++ dynamic libraries produces much smaller size
+binaries and takes much less linking time.
 
 FOR MORE INFORMATION
 ====================
 
 The Charm++ web page, with documentation, more programs,
 and the latest version of Charm++, is at
-       http://charm.cs.uiuc.edu/
+       http://charm.cs.illinois.edu/
 
 The Charm++ mailing list, for questions, comments, suggestions, 
 improvements, or bug reports is
-       ppl@cs.uiuc.edu
+       charm@cs.illinois.edu
 
 
 AUTHORS
 =======
 
-Charm++ is written and maintained by the Parallel Programming
-Lab, in the Computer Science department at the University of 
-Illinois at Urbana-Champaign.  Our managing professor is
-Dr. L.V. Kale; students have included (in rough time order)
-Wennie Shu, Kevin Nomura, Wayne Fenton, Balkrishna Ramkumar,
-Vikram Saletore, Amitabh B. Sinha, Manish Gupta, Attila Gursoy, 
-Balkrishna Ramkumar, Amitabh B. Sinha, Nimish Shah, Sanjeev 
-Krishnan, Parthasarathy Ramachandran, Jeff Wright, Michael Lang, 
-Jackie Wang, Fang Hu, Michael Denardo, Joshua Yelon, Narain Jagathesan,
-Zehra Sura, Krishnan Varadarajan, and Sameer Paranjpye.  Current developers
-include Milind Bhandarkar, Robert Brunner, Terry Wilmarth, Gengbin Zheng, 
-Jayant Desouza, Orion Lawlor, Karthik Mahesh, and Neelam Saboo.
+Charm++ was created and is maintained by the Parallel Programming Lab, 
+in the Computer Science department at the University of Illinois at
+Urbana-Champaign.  Our managing professor is Dr. L.V. Kale; students
+have included (in rough time order) Wennie Shu, Kevin Nomura, Wayne
+Fenton, Balkrishna Ramkumar, Vikram Saletore, Amitabh B. Sinha, Manish
+Gupta, Attila Gursoy, Balkrishna Ramkumar, Amitabh B. Sinha, Nimish
+Shah, Sanjeev Krishnan, Jayant DeSouza, Parthasarathy Ramachandran,
+Jeff Wright, Michael Lang, Jackie Wang, Fang Hu, Michael Denardo,
+Joshua Yelon, Narain Jagathesan, Zehra Sura, Krishnan Varadarajan, 
+Sameer Paranjpye, Milind Bhandarkar, Robert Brunner and Jayant Desouza. 
+Current developers include Terry Wilmarth, Gengbin Zheng, Orion Lawlor, 
+Karthik Mahesh, and Neelam Saboo.
+
+