change detection time
[charm.git] / doc / pose / sample.tex
1 \section{Compiling, Running and Debugging a Sample \pose{} program}
2
3 Sample code is available in the Charm++ source distribution.  Assuming a
4 net-linux build of Charm++, look in {\tt charm/net-linux/examples/pose}.
5 The SimBenchmark directory contains a synthetic benchmark simulation and is
6 fairly straightforward to understand.
7
8 \subsection{Compiling}
9
10 To build a \pose{} simulation, run {\tt etrans.pl} on each \pose{}
11 module to get the new source files.  {etrans.pl} is a source to source
12 translator.  Given a module name it will translate the {\tt module.h},
13 {\tt module.ci}, and {\tt module.C} files into {\tt module\_sim.h},
14 {\tt module\_sim.ci}, and {\tt module\_sim.C} files.  The translation
15 operation adds wrapper classes for \pose{} objects and handles the
16 interface with strategies and other poser options.
17
18 To facilitate code organization, the {\tt module.C} file can be broken
19 up into multiple files and those files can appended to the {etrans.pl}
20 command line after the module name.  These additional .C files will be
21 translated and their output appended to the {\tt module\_sim.C} file.
22
23 The {\tt -s} switch can be passed to use the sequential simulator feature
24 of \pose{} on your simulation, but you must also build a sequential
25 version when you compile (see below).
26
27 Once the code has been translated, it is a \charmpp{} program that can
28 be compiled with {\tt charmc}.  Please refer to the CHARM++/CONVERSE
29 Installation and Usage Manual for details on the charmc command.  You
30 should build the new source files produced by etrans.pl along with the
31 main program and any other source needed with {\tt charmc}, linking
32 with {\tt -module pose} (or {\tt -module seqpose} for a sequential
33 version) and {\tt -language charm++}.  The SimBenchmark example has a
34 Makefile that shows this process.
35
36 \subsection{Running} 
37
38 To run the program in parallel, a {\tt charmrun} executable was
39 created by {\tt charmc}.  The flag {\tt +p} is used to specify a
40 number of processors to run the program on.  For example:
41
42 \begin{verbatim}
43 > ./charmrun pgm +p4
44 \end{verbatim}
45
46 This runs the executable {\tt pgm} on 4 processors.  For more
47 information on how to use {\tt charmrun} and set up your environment
48 for parallel runs, see the CHARM++/CONVERSE Installation and Usage
49 Manual. 
50
51 \subsection{Debugging}
52
53 Because \pose{} is translated to \charmpp{}, debugging is a little
54 more challenging than normal.  Multi-processor debugging can be
55 achieved with the {\tt charmrun ++debug} option, and debugging is
56 performed on the {\tt module\_sim.C} source files.  The user thus has
57 to track down problems in the original \pose{} source code.  A
58 long-term goal of the \pose{} developers is to eliminate the
59 translation phase and rely on the interface translator of \charmpp{}
60 to provide similar functionality.
61
62 \subsection{Sequential Mode}
63
64 As mentioned above, the same source code can be used to generate a
65 purely sequential \pose{} executable by using the {\tt -s} flag to
66 {\tt etrans.pl} and linking with {\tt -module seqpose}.  This turns
67 off all aspects of synchronization, checkpointing and GVT calculation
68 that are needed for optimistic parallel execution.  Thus you should
69 experience better one-processor times for executables built for
70 sequential execution than those built for parallel execution.  This is
71 convenient for examining how a program scales in comparison to
72 sequential time.  It is also helpful for simulations that are small
73 and fast, or in situations where multiple processors are not
74 available.
75
76
77