Incorporated proofreading comments from 11-16 afternoon
authorRobert Brunner <rbrunner@uiuc.edu>
Fri, 17 Nov 1995 17:19:37 +0000 (17:19 +0000)
committerRobert Brunner <rbrunner@uiuc.edu>
Fri, 17 Nov 1995 17:19:37 +0000 (17:19 +0000)
doc/install/compile.tex
doc/install/install.tex
doc/install/run.tex

index d64bf024beff14a5cdc6bfa2a56e940d8d798112..c4035851f8eb35d4fbb8cd8017b3001e6728d870 100644 (file)
 % REVISION HISTORY:
 %
 % $Log$
-% Revision 1.4  1995-11-16 23:58:29  brunner
+% Revision 1.5  1995-11-17 17:19:37  brunner
+% Incorporated proofreading comments from 11-16 afternoon
+%
+% Revision 1.4  1995/11/16  23:58:29  brunner
 % Alphabetized option list
 %
 % Revision 1.3  1995/11/14  21:23:55  brunner
 
 \section{Compiling Converse, Charm, and Charm++ Programs}
 
-The shell script, {\tt charmc}, is a versatile program to standardize
+The {\tt charmc} program standardizes compiling and linking procedures
 compiling and linking procedures among various machines and operating
-systems.  The script selects the appropriate libraries to compile
-Charm, Charm++, or Converse programs.  It also standardizes compiling
-and linking procedures and options for sequential C and C++ programs
-on the supported systems.  The {\tt charmc} program is executed in the
-following way:
+systems.  The program selects the appropriate libraries to compile
+Charm, Charm++, or Converse programs.  It also allows a standard
+compiling method for sequential C and C++ programs on the supported
+systems.  The {\tt charmc} program is executed in as follows:
 
 \begin{verbatim}
 charmc [options] input-files
@@ -43,14 +45,30 @@ charmc [options] input-files
 
 Files with the following extensions are handled by {\verb+charmc+}
 \begin{description}
-\item[{\verb+.p+}] Charm code
-\item[{\verb+.P+}] Charm++ code
-\item[{\verb+.c+}] C code
-\item[{\verb+.C+}] C++ code
-\item[{\verb+.o+}] Object files
-\item[{\verb+.a+}] Library files
+\item[{\verb+.p+} -- ] Charm code
+\item[{\verb+.P+} -- ] Charm++ code
+\item[{\verb+.c+} -- ] C code
+\item[{\verb+.C+} -- ] C++ code
+\item[{\verb+.o+} -- ] Object files
+\item[{\verb+.a+} -- ] Library files
 \end{description}
 
+Many of the machine dependent commands and options used by {\tt
+charmc} are configured in the file {\tt conv-mach.csh}, which can be
+found in the same directory where {\tt charmc} resides.  Local
+modifications to the commands or options {\tt charmc} uses may usually
+be accomplished by editing {\tt conv-mach.csh}.
+
+When {\tt charmc} is run, it first identifies where the Charm
+directory resides by examining the {\tt CHARMBIN} environment
+variable, and then by looking at the parent directory that {\tt
+charmc} was run from.  If it can't find the charm system files, it
+exits.  Then it examines the filenames passed to it, and runs the
+command specified on the command line (see below) or in {\tt
+conv-mach.csh} according to the file suffix.  Finally, it removes any
+temporary files it created, unless overridden by the {\tt -save}
+option.
+
 \subsection{Compiling with a user-defined load-balance strategy}
 
 The {\tt charmc} script is designed to link in either one of the
@@ -63,147 +81,157 @@ placed in the {\em Converse} library directory.  Then that strategy
 can be linked with a user program using the {\tt -balance} option.
 
 \subsection{Command line options for {\tt charmc}}
+
 The following options are supported by charmc:
+
 \begin{description}
 
-\item[{\tt -balance} {\em load-balance-strategy}]
+\item[{\tt -balance} {\em load-balance-strategy}:]
 
 Selects the desired load balancing strategies.  Currently, only {\tt
 rand}, {\tt acwn}, and {\tt mngr} are supported. If a user-defined
 strategy has been placed in the charm library directory, it may also
 be selected with this option.  Default is {\tt -balance rand}.
        
-\item[{\tt -c}]
+\item[{\tt -c}:]
 
 Ignored.  For compatibility with {\tt cc} and {\tt ld}.
 
-\item[{\tt -c++} {\em C++ compiler}]
+\item[{\tt -c++} {\em C++ compiler}:]
 
 Forces the specified C++ compiler to be used.
 
-\item[{\tt -cc} {\em C-compiler}]
+\item[{\tt -cc} {\em C-compiler}:]
 
 Forces the specified C compiler to be used.
 
-\item[{\tt -cp} {\em copy-file}]
+\item[{\tt -cp} {\em copy-file}:]
 
 Creates a copy of the output file in {\em copy-file}.
 
-\item[{\tt -cpp-option} {\em options}]
+\item[{\tt -cpp-option} {\em options}:]
 
 Options passed to the C pre-processor.
 
-\item[{\tt -D*}]
+\item[{\tt -D*}:]
 
-Passed to C preprocessor, C and C++ compilers.
+Passed to C preprocessor, C and C++ compilers.  Commonly used to
+define preprocessor variables from the command line at compile
+time.
 
-\item[{\tt -execmode} {\em execution-mode}]
+\item[{\tt -execmode} {\em execution-mode}:]
 
-Selects the desired execution mode.  Currently supported modes are
-{\tt none}, {\tt summary}, and {\tt projections}. Default is {\tt
--execmode none}.
+Selects the desired execution mode for Charm and Charm++ programs.
+See the Charm manual and the Projections and SummaryTool manuals for
+more information.  Currently supported modes are {\tt none}, {\tt
+summary}, and {\tt projections}. Default is {\tt -execmode none}.
 
-\item[{\tt -I*}]
+\item[{\tt -I*}:]
 
-Passed to C preprocessor, C and C++ compilers.
+Passed to C preprocessor, C and C++ compilers.  Commonly used to
+define a directory search path for preprocessor include files.
 
-\item[{\tt -g}]
+\item[{\tt -g}:]
 
-Causes compiled files to include debugging information.
+Causes compiled files to include debugging information. Default.
 
-\item[{\tt -L*}]
+\item[{\tt -L*}:]
 
-Passed to all linkers.
+Passed to all linkers.  Commonly used to define a directory search
+path for libraries selected by the {\tt -l} command.
+
+\item[{\tt -l*}:]
+
+Specifies libraries which are passed to all linkers.
 
-\item[{\tt -language \{converse|charm|charm++\}}]
+\item[{\tt -language \{converse|charm|charm++\}}:]
 
 Selects compiler and linker options, and appropriate libraries
 to compile the selected language.  Default is {\tt -language charm}.
 
-\item[{\tt -ld} {\em linker}]
+\item[{\tt -ld} {\em linker}:]
 
 Forces the specified linker to be used for {\tt -language charm}.
 
-\item[{\tt -ld++} {\em linker}]
+\item[{\tt -ld++} {\em linker}:]
 
 Forces the specified linker to be used for {\tt -language charm++}.
 
-\item[{\tt -ld++-option} {\em options}]
+\item[{\tt -ld++-option} {\em options}:]
 
 Options passed to the linker for {\tt -language charm++}.
 
-\item[{\tt -ld-option} {\em options}]
+\item[{\tt -ld-option} {\em options}:]
 
 Options passed to the linker for {\tt -language charm}.
 
-\item[{\tt -ldro-option} {\em options}]
+\item[{\tt -ldro-option} {\em options}:]
 
 Options passes to the linker when linking {\tt .o} files.
 
-\item[{\tt -machine} {\em machine-type}]
+\item[{\tt -machine} {\em machine-type}:]
 
-If more than one version of converse/charm/charm++ has been installed,
-allows selection of versions other than the default.  The default
-version is the version last installed. For a list of machine types
-currently supported, see the previous section.
+If more than one version of converse/charm/charm++ has been installed
+in the same charm directory, this option allows selection of versions
+other than the default.  The default {\em machine-type} is the version
+in which the {\tt charmc} being run resides.
 
-\item[{\tt -memory}]
+\item[{\tt -memory}:]
 
 Currently ignored
 
-\item[{\tt -o} {\em output-file}]
+\item[{\tt -NO}:]
+
+Causes no optimization to be used.  Overrides {\tt -O}.
+
+\item[{\tt -O}:]
+
+Causes files to be compiled with default optimization.
+
+\item[{\tt -O*}:]
+
+Passed to C/C++ compiler.  Generally allows the selection of optional
+optimizations.
+
+\item[{\tt -o} {\em output-file}:]
 
 Output file name.
 
-\item[{\tt -queue} {\em queueing strategy}]
+\item[{\tt -queue} {\em queueing strategy}:]
 
 Currently ignored
 
-\item[{\tt -save}]
+\item[{\tt -s}:]
+
+Passed to C and C++ linkers.  Commonly causes symbol table information
+to be stripped from object files, reducing files size, but reducing
+the information available for debugging programs.
+
+\item[{\tt -save}:]
 
 Intermediate files produced by the Charm or Charm++ translator are saved.
 
-\item[{\tt -seq}]
+\item[{\tt -seq}:]
 
 Compiles C and C++ files using the system's sequential/front end
 compilers.
 
-\item[{\tt -use-fastest-cc}]
+\item[{\tt -use-fastest-cc}:]
 
 Some environments provide more than one C compiler (cc and gcc, for
 example).  This option selects the compiler most likely to produce
 faster executing code.
 
-\item[{\tt -use-reliable-cc}]
+\item[{\tt -use-reliable-cc}:]
 
 Some environments provide more than one C compiler (cc and gcc, for
 example).  This option selects the compiler most likely to succesfully
 compile C code.
 
-\item[{\tt -verbose}]
+\item[{\tt -verbose}:]
 
 All commands executed by charmc are echoed to stdout.
 
-\item[{\tt -O}]
-
-Causes files to be compiled with default optimization.  Default.
-
-\item[{\tt -NO}]
-
-Causes no optimization to be used.  Overrides {\tt -O}.
-
-\item[{\tt -O*}]
-
-Passed to C/C++ compiler.
-
-\item[{\tt -l*}]
-
-Specifies libraries which are passed to all linkers.
-
-\item[{\tt -s}]
-
-Passed to C and C++ linkers.
-
 \end{description}
 
 
index 2d1dab15a61756f63a17ebd212e739b74b45dacc..6e33595a4d33f999754dd6fd67da514cd162064c 100644 (file)
 % REVISION HISTORY:
 %
 % $Log$
-% Revision 1.8  1995-11-01 22:13:37  jyelon
+% Revision 1.9  1995-11-17 17:19:37  brunner
+% Incorporated proofreading comments from 11-16 afternoon
+%
+% Revision 1.8  1995/11/01  22:13:37  jyelon
 % *** empty log message ***
 %
 % Revision 1.7  1995/11/01  22:06:30  jyelon
@@ -50,8 +53,8 @@ Our explanation of the installation process will assume that {\tt
 if not, you must mentally translate.
 
 Download the tar-file file appropriate to your machine.  For example,
-if you are installing the version of charm for networks of solaris
-machines, download {\tt net-sun.tar.Z}:
+if you are installing the version of charm for networks of Sun
+workstations running SunOS 4.X, download {\tt net-sun.tar.Z}:
 
 \begin{verbatim}
     % ftp a.cs.uiuc.edu
@@ -134,7 +137,7 @@ of the networked versions, all other users may skip it.
 The network versions utilize many unix processes communicating with
 each other via UDP.  No attempt is currently being made to filter out
 unauthorized packets.  Therefore, it is theoretically possible to
-mount a security attack by sending UDP packets to a executing
+mount a security attack by sending UDP packets to an executing
 converse, charm, or charm++ program's sockets.
 
 The second security issue associated with networked programs is
@@ -171,12 +174,11 @@ notification code:
     % cp conv-host.silent conv-host
 \end{verbatim}
 
-Note: even though the other versions contain programs named {\tt
-conv-host.notify} and\linebreak
-{\tt conv-host.silent}, they never actually
-notify us.  The existence of the extra files is just to make our
-compilation scripts more consistent across versions.  The {\em only}
-versions that ever notify us are the network versions.
+Although versions for some other machines (eg. ncube) contain
+programs named {\tt conv-host.notify} and {\tt conv-host.silent}, they
+never actually notify us.  The existence of the extra files is just to
+make our compilation scripts more consistent across versions.  The
+{\em only} versions that ever notify us are the network versions.
 
 \subsection{Reducing disk usage}
 
index ec43cfedeb2c2843e203b74fcd4b503ca850bfe0..6c00e55eb69c1e1ee42d839192b473ac6e31297b 100644 (file)
 % REVISION HISTORY:
 %
 % $Log$
-% Revision 1.4  1995-11-16 23:59:02  brunner
+% Revision 1.5  1995-11-17 17:19:37  brunner
+% Incorporated proofreading comments from 11-16 afternoon
+%
+% Revision 1.4  1995/11/16  23:59:02  brunner
 % incorporated Attila's simulator section
 %
 % Revision 1.3  1995/11/16  20:58:57  brunner
@@ -26,7 +29,8 @@
 %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section[Executing Charm Programs]{Executing Charm programs}
+\section[Executing Converse/Charm/Charm++ Programs]
+       {Executing Converse/Charm/Charm++ Programs}
 \label{executing charm programs}
 
 The Charm linker produces one executable file.  On machines with a host
@@ -101,22 +105,28 @@ placeholder for an absent argument.
 The number of nodes specified in the nodes file must not be less
 than the number of nodes specified with the {\fexec +p} command
 line option. If the number of nodes specified in the nodes file is
-less than the number of nodes specified with the {\fexec +p} option,
+greater than the number of nodes specified with the {\fexec +p} option,
 {\fexec +p} entries in the nodes file will be used in succession, starting
 with the first entry in the file.
 The name of the nodes fil\index{nodes file}\index{.nodes} itself is
 obtained by  {\fexec conv-host} in the following order:
 \begin{enumerate}
+
 \item  From the command line option {\fexec ++nodesfile}.
+
 \item  If the {\fexec ++nodesfile} option is not given, the value of the 
 environment variable {\fexec NODES} is taken to be the nodes file.
+
 \item  If the environment variable {\fexec NODES} is not set, the file 
-{\fparm .nodes}\index{.nodes}\index{nodes file} in the user's home directory is taken 
-to be the nodes file.
+{\fparm .nodes}\index{.nodes}\index{nodes file} in the user's home
+directory is taken to be the nodes file.
+
 \item  If the above file does not exist, the file 
 {\fparm .nodes}\index{.nodes}\index{nodes file} in the current
-directory is used as  the nodes file.
+directory is used as the nodes file.
+
 \end{enumerate}
+
 The user is required to set up remote login permissions on all nodes
 using the .rhosts file in the home directory.
 
@@ -133,15 +143,20 @@ and debugging purposes. It simulates a message passing system. The
 simulated machine is a collection of processing nodes connected with a
 communication network. Each node is composed of an application
 processor, local memory, and a communication coprocessor.  The
-simulator is a beta version, particularly using the simulator timers
-for performance measurements has not been tested yet.
+simulator is a beta version, and it is not yet proven that the
+simulator timers for performance measurements produce realistic
+results.
 
 In order to run Converse programs with the simulator:
 \begin{itemize}
+
 \item link user program with \verb+<machine>/lib/libck-unimain.o+
+
 \item prepare a configuration file as described below
+
 \item to run, type \verb#pgm +pN# (and possibly other runtime options) where
    N is the number of processors.
+
 \end{itemize}
 
 The basic task of the simulator is to manage the message passing
@@ -162,27 +177,34 @@ treated as comments. Each line contains a keyword followed by some
 numbers. The explanation of each keyword is given below:
 
 \begin{description}
+
 \item[{\tt cpu\_recv\_cost}] $\alpha$ and  $\beta$ values  for the software
                             cost of a message-receive at the application
                             processor.
+
 \item[{\tt cpu\_send\_cost}] $\alpha$ and  $\beta$ values  for the software
                             cost of a message-send at the application
                             processor.
+
 \item[{\tt rcp\_cost}] $\alpha$ and  $\beta$ values for a message-receive 
                        at the communication processor.
+
 \item[{\tt scp\_cost}] $\alpha$ and  $\beta$ values for a message-send
                        at the communication processor.
+
 \item[{\tt net\_cost}] $\alpha$ and  $\beta$ values for a message-send
                        in the netowrk.
+
 \item[{\tt cpu\_queue\_threshold\_number}] max number of messages queued
                        at the application processors's incoming message queue.
-\item[{\tt cpu\_queue\_threshold\_size}] max cumulative size of messages in bytes
-                       queued at the application processors's incoming message 
-                       queue.
+
+\item[{\tt cpu\_queue\_threshold\_size}] max cumulative size of
+                      messages in bytes queued at the application
+                      processors's incoming message queue.
 
 
 \item[{\tt cpu\_queue\_threshold\_number}] max number of messages in the incoming
-                       message queue of communication processor.   
+                       message queue of communication processor.
 
 
 \item[{\tt rcp\_queue\_threshold\_number}] max number of messages in the 
@@ -263,18 +285,23 @@ periodic_interval 0.1
 
 A Charm program accepts the following command line options:
 \begin{description}
+
 \item[{\fexec +pN}] Run the program with N processors. The default is 1.
 Note that on some nonshared memory machines, e.g., nCUBE/2, the user must
 specify the number of processors using the command provided for that
 machine (e.g. {\fexec xnc} on the nCUBE/2).
 In such cases the {\fexec +p} option is ignored.
+
 %\item[{\fexec +mM}] Run the program with M Kwords of memory per
 %processor. The default is 50 Kwords of memory per processor.
+
 %\item[{\fexec +mmM}] Run the program with M Kwords of memory for
 %processor 0.
+
 \item[{\fexec +ss}] Print summary statistics about chare creation.  This option
 prints the total number of chare creation requests, and the total number of
 chare creation requests processed across all processors.
+
 \item[{\fexec +cs}] Print statistics about the number of create chare messages
 requested and processed, the number of messages for chares requested and 
 processed, and the number of messages for branch office chares requested and
@@ -282,9 +309,11 @@ processed, on a per processor basis.  Note that the number of messages
 created and processed for a particular type of message on a given node 
 may not be the same, since a message may be processed by a different
 processor from the one originating the request.
-\item[{\fexec +mems}] Print the Memory Usage Statistics at the end, including
-the number of memory allocation requests and memory free requests, based on
-the size of the memory allocated or freed.
+
+%\item[{\fexec +mems}] Print the Memory Usage Statistics at the end, including
+%the number of memory allocation requests and memory free requests, based on
+%the size of the memory allocated or freed.
+
 \item[{\fexec user\_options}] Options that are be interpreted by the user
 program may be included after all the system options. 
 However, {\fexec user\_options} cannot start with +.
@@ -292,6 +321,7 @@ The {\fexec user\_options} will be passed as arguments to the user program
 via the usual {\fcmd argc/argv} construct to the {\fcmd main}\index{main}
 entry point of the main chare. 
 Charm system options will not appear in {\fcmd argc/argv}.
+
 \end{description}
 
 \subsubsection[Additional Uniprocessor Command Line Options]
@@ -319,18 +349,23 @@ thru $P-1$ (where $P$ is the number of processors) repeatedly.
 The following {\fexec ++} command line options are available in
 the network version\index{network command line options}:
 \begin{description}
+
 \item[{\fexec ++debug}] Run each node under gdb in an xterm window, prompting
 the user to begin execution.
 \index{++debug}
+
 \item[{\fexec ++debug-no-pause}] Run each node under gdb in an xterm window
 immediately (i.e. without prompting the user to begin execution).
 \index{++debug-no-pause}
+
 \item[{\fexec ++maxrsh}] Maximum number of {\fcmd rsh}'s to run at a
 time.
 \index{++maxrsh}
+
 \item[{\fexec ++resend-wait}] Timeout before retransmitting datagrams
 (in msec).
 \index{++resend-wait}
+
 \item[{\fexec ++resend-fail}] Timeout before retransmission fails (in
 msec).\index{++resend-fail}
 This parameter can help the user kill ``runaway'' processes, which may not
@@ -342,15 +377,21 @@ operations are being performed.
 
 \item[{\fexec ++nodesfile}] File containing list of nodes.
 \index{++nodesfile}\index{.nodes}\index{nodes file}
+
 \end{description}
 
 If using the {\fexec ++debug} option, the user must ensure the
 following:
 \index{++debug}
 \begin{enumerate}
-\item {\fexec xterm} and {\fexec gdb} must be in the user's path.
+
+\item {\fexec xterm}, {\fexec xdpyinfo},  and {\fexec gdb} must be in
+the user's path.
+
 \item The path must be set in the {\fexec .cshrc} file, not the {\fexec .login}
 file, because {\fexec rsh} does not run the {\fexec .login} file. 
+
 \item The nodes must be authorized to create windows on the host machine (see
-man page for {\fexec xhost}).
+man page for {\fexec xhost} {\fexec xauth}).
+
 \end{enumerate}