doc/charm++/compile.tex

   1 The {\tt charmc} program, located in ``charm/bin'', standardizes
   2 compiling and linking procedures
   3 among various machines and operating systems.  ``charmc'' is
   4 a general-purpose tool for compiling and
   5 linking, not only restricted to \charmpp{} programs.
   6
   7 Charmc can perform the following tasks.  The (simplified) syntax for
   8 each of these modes is shown.  Caution: in reality, one almost always
   9 has to add some command-line options in addition to the simplified
  10 syntax shown below.  The options are described next.
  11
  12 \begin{alltt}
  13  * Compile C                            charmc -o pgm.o pgm.c
  14  * Compile C++                          charmc -o pgm.o pgm.C
  15  * Link                                 charmc -o pgm   obj1.o obj2.o obj3.o...
  16  * Compile + Link                       charmc -o pgm   src1.c src2.ci src3.C
  17  * Create Library                       charmc -o lib.a obj1.o obj2.o obj3.o...
  18  * Translate Charm++ Interface File     charmc file.ci
  19 \end{alltt}
  20 % * CPM preprocessing                charmc -gen-cpm file.c
  21
  22 Charmc automatically figures out where the charm lib and include
  23 directories are --- at no point do you have to configure this
  24 information.  However, the code that finds the lib and include
  25 directories can be confused if you remove charmc from its normal
  26 directory, or rearrange the directory tree.  Thus, the files in the
  27 \kw{charm/bin}, \kw{charm/include}, and \kw{charm/lib} directories
  28 must be left where they are relative to each other.
  29
  30 The following command-line options are available to users of charmc:
  31
  32 \begin{description}
  33
  34 \item[{\tt -o} {\em output-file}:]
  35
  36 Output file name.  Note: charmc only ever produces one output file at
  37 a time.  Because of this, you cannot compile multiple source files at
  38 once, unless you then link or archive them into a single output-file.
  39 If exactly one source-file is specified, then an output file will be
  40 selected by default using the obvious rule (eg, if the input file if
  41 pgm.c, the output file is pgm.o).  If multiple input files are
  42 specified, you must manually specify the name of the output file,
  43 which must be a library or executable.
  44
  45 \item[{\tt -c}:]
  46
  47 Ignored.  There for compatibility with {\tt cc}.
  48
  49 \item[{\tt -D{\em symbol}[={\em value}]}:]
  50
  51 Defines preprocessor variables from the command line at compile time.
  52
  53 \item[{\tt -I}:]
  54
  55 Add a directory to the search path for preprocessor include files.
  56
  57 \item[{\tt -g}:]
  58
  59 Causes compiled files to include debugging information.
  60
  61 \item[{\tt -L*}:]
  62
  63 Add a directory to the search path for libraries selected by
  64 the {\tt -l} command.
  65
  66 \item[{\tt -l*}:]
  67
  68 Specifies libraries to link in.
  69
  70 \item[{\tt -module {\em m1}[,{\em m2}[,...]]}]
  71 Specifies additional \charmpp{} modules to link in.
  72 Similar to {\tt -l}, but also registers \charmpp{} parallel objects.
  73 See the library's documentation for whether to use {\tt -l} or {\tt -module}.
  74
  75 \item[{\tt -optimize}:]
  76
  77 Causes files to be compiled with maximum optimization.
  78
  79 \item[{\tt -no-optimize}:]
  80
  81 If this follows -O on the command line, it turns optimization back off.
  82 This is just a convenience for simple-minded makefiles.
  83
  84 \item[{\tt -production}:]
  85
  86 Enable architecture-specific production-mode features. For instance,
  87 use available hardware features more aggressively. It's probably a bad
  88 idea to build some objects with this, and others without.
  89
  90 \item[{\tt -s}:]
  91
  92 Strip the executable of debugging symbols.  Only meaningful when
  93 producing an executable.
  94
  95 \item[{\tt -verbose}:]
  96
  97 All commands executed by charmc are echoed to stdout.
  98
  99 \item[{\tt -seq}:]
 100
 101 Indicates that we're compiling sequential code.  On parallel machines
 102 with front ends, this option also means that the code is for the front
 103 end.  This option is only valid with C and C++ files.
 104
 105 \item[{\tt -use-fastest-cc}:]
 106
 107 Some environments provide more than one C compiler (cc and gcc, for
 108 example).  Usually, charmc prefers the less buggy of the two.  This
 109 option causes charmc to switch to the most aggressive compiler,
 110 regardless of whether it's buggy or not.
 111
 112 \item[{\tt -use-reliable-cc}:]
 113
 114 Some environments provide more than one C compiler (cc and gcc, for
 115 example).  Usually, charmc prefers the less buggy of the two, but
 116 not always.  This option causes charmc to switch to the most reliable
 117 compiler, regardless of whether it produces slow code or not.
 118
 119 \item[{\tt -language \{converse|charm++|ampi|fem|f90charm\}}:]
 120
 121 When linking with charmc, one must specify the ``language''.  This
 122 is just a way to help charmc include the right libraries.  Pick the
 123 ``language'' according to this table:
 124
 125 \begin{itemize}
 126 \item{{\bf Charm++} if your program includes \charmpp{}, C++, and C.}
 127 \item{{\bf Converse} if your program includes C or C++.}
 128 \item{{\bf f90charm} if your program includes f90 Charm interface.}
 129 \end{itemize}
 130
 131 \item[{\tt -balance} {\em seed load-balance-strategy}:]
 132
 133 When linking any \converse{} program (including any \charmpp{} or sdag program),
 134 one must include a seed load-balancing
 135 library.  There are currently three to choose from: {\tt rand}, {\tt
 136 test}, and {\tt neighbor} are supported.  Default is {\tt -balance rand}.
 137
 138 When linking with {\tt neighbor} seed load balancer, one can also specify
 139 a virtual tolpogy for constructing neighbors during run-time using
 140 {\tt +LBTopo topo}, where {\em topo} can be one of (a) ring, (b) mesh2d,
 141 (c) mesh3d and (d) graph. The default is mesh2d.
 142
 143 \item[{\tt -tracemode} {\em tracing-mode}:]
 144
 145 Selects the desired degree of tracing for \charmpp{} programs.
 146 See the \charmpp{} manual and the \projections{} manuals for
 147 more information.  Currently supported modes are {\tt none}, {\tt
 148 summary}, and {\tt projections}. Default is {\tt -tracemode none}.
 149
 150
 151 \item[{\tt -memory} {\em memory-mode}:]
 152 Selects the implementation of \kw{malloc} and \kw{free}
 153 to use.  Select a memory mode from the table below.
 154
 155 \begin{itemize}
 156 \item{{\bf os} Use the operating system's standard memory routines.}
 157 \item{{\bf gnu} Use a set of GNU memory routines.}
 158 \item{{\bf paranoid} Use an error-checking set of routines.
 159 These routines will detect common mistakes such as buffer
 160 overruns, underruns, double-deletes, and use-after-delete.
 161 The extra checks slow down programs, so this version should
 162 not be used in production code.}
 163 \item{{\bf leak} Use a special set of memory routines and
 164 annotation functions for detecting memory leaks.
 165 Call CmiMemoryMark() to mark allocated memory as OK,
 166 do work which you suspect is leaking memory,
 167 then call CmiMemorySweep(const char *tag) to check.}
 168 \item{{\bf verbose} Use a tracing set of memory routines.
 169 Every memory-related call results in a line printed to
 170 standard out.}
 171 \item{{\bf default} Use the default, which depends on the version of \charmpp.}
 172 \end{itemize}
 173
 174
 175 \item[{\tt -c++} {\em C++ compiler}:]
 176
 177 Forces the specified C++ compiler to be used.
 178
 179 \item[{\tt -cc} {\em C-compiler}:]
 180
 181 Forces the specified C compiler to be used.
 182
 183 \item[{\tt -cp} {\em copy-file}:]
 184
 185 Creates a copy of the output file in {\em copy-file}.
 186
 187 \item[{\tt -cpp-option} {\em options}:]
 188
 189 Options passed to the C pre-processor.
 190
 191 \item[{\tt -ld} {\em linker}:]
 192
 193 Use this option only when compiling programs that do not include C++
 194 modules.  Forces charmc to use the specified linker.
 195
 196 \item[{\tt -ld++} {\em linker}:]
 197
 198 Use this option only when compiling programs that include C++
 199 modules.  Forces charmc to use the specified linker.
 200
 201 \item[{\tt -ld++-option} {\em options}:]
 202
 203 Options passed to the linker for {\tt -language charm++}.
 204
 205 \item[{\tt -ld-option} {\em options}:]
 206
 207 Options passed to the linker for {\tt -language converse}.
 208
 209 \item[{\tt -ldro-option} {\em options}:]
 210
 211 Options passes to the linker when linking {\tt .o} files.
 212
 213
 214 \end{description}