cduce.docbook 8.02 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

<refentry id="cduce">

<refmeta>
<refentrytitle>cduce</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>cduce</refname>
12
<refpurpose>The CDuce compiler/interpreter/toplevel</refpurpose>
13 14 15
</refnamediv>

<refsynopsisdiv>
16 17


18 19
<cmdsynopsis>
<command>cduce</command>
20 21
<arg choice="opt" rep="repeat">
  <option>OPTIONS</option>
22
</arg>
23 24 25 26 27
<arg choice="opt" rep="repeat"><option>--arg <filename>argument</filename></option></arg>
</cmdsynopsis>

<cmdsynopsis>
<command>cduce</command>
28
<arg choice="opt" rep="repeat">
29 30 31
  <option>OPTIONS</option>
</arg>
<arg choice="opt">
32
  <option><filename>file[.cd]</filename></option>
33
</arg>
34
<arg choice="opt" rep="repeat"><option>--arg <filename>argument</filename></option></arg>
35
</cmdsynopsis>
36

37 38 39 40 41
<cmdsynopsis>
<command>cduce --compile</command>
<arg choice="opt" rep="repeat">
  <option>OPTIONS</option>
</arg>
42
<arg choice="opt">
43 44 45
  <option><filename>file[.cd]</filename></option>
</arg>
</cmdsynopsis>
46

47 48 49 50 51 52 53 54 55 56
<cmdsynopsis>
<command>cduce --run</command>
<arg choice="opt" rep="repeat">
  <option>OPTIONS</option>
</arg>
<arg choice="opt" rep="repeat">
  <option><filename>file[.cdo]</filename></option>
</arg>
<arg choice="opt" rep="repeat"><option>--arg <filename>argument</filename></option></arg>
</cmdsynopsis>
57 58 59 60 61
</refsynopsisdiv>

<refsect1>
<title>Description</title>
<para>
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
According to the command line arguments, 
the <command>cduce</command> command behaves
either as an interactive toplevel, an interpreter, a compiler, or
a loader.

When no input file is given, the command operates as an interactive
toplevel. Toplevel phrases are processed after each
<command>;;</command>. Mutually recursive declarations of types or
functions must be contained in a single adjacent sequence of phrases
(without <command>;;</command> inbetween).

With the <option>--compile</option> option, 
the command produces a .cdo file with intermediate code.
One or several .cdo files can be run
later by <command>cduce --run</command>.
When a .cd file is given, but not the <option>--compile</option>,
the unit is compiled and immediatly evaluated, without
producing a .cdo file.

All the arguments that follow the <option>--arg</option> option are
passed to the CDuce program (useless in <option>--compile</option>
mode).
84 85
</para>

86 87 88 89 90 91 92 93
<para> In order to allow persistence in the toplevel(options
<option>--dump</option>, <option>--load</option>, and
<option>--save</option>) to operate, you must quit the toplevel with
<command>#quit</command> toplevel directive and not with
<command>Ctrl-D</command> or <command>Ctrl-C</command>. This
persistence mechanism is deprecated since the introduction of separate
compilation and will be removed in future releases.  </para>

94 95
</refsect1>

96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
<refsect1>
<title>CDuce/OCaml interface</title>

<para>
If the CDuce/OCaml interface is enabled, the compiler
looks for a corresponding <filename>foo.cmi</filename> file when
compiling a <filename>foo.cd</filename> unit. 
The resulting <filename>foo.cdo</filename> contains the ML stub code
(to export CDuce values to OCaml, and to import OCaml values into CDuce).

When the unit uses OCaml functions, it is not possible to run it
with the <command>--run</command> option. Instead, you have to compile
and link it with the OCaml linker. Please refer to the man page for the 
<command>cdo2ml</command> command.
</para>

</refsect1>
113 114 115 116

<refsect1>
<title>Options</title>
<para>
117
This program follows usual syntax,
118 119 120 121 122 123 124 125 126
with long options starting with two dashes (`--'). A
summary of the options supported by <command>cduce</command>
is included below.		</para>
		

<refsect2>
<title>Generic Options</title>
<variablelist>

127
<varlistentry>
128
<term><option>--compile</option> <filename>file</filename></term>
129 130
<listitem>
<para>
131 132
Produce a file in an intermediate code that can be run by
<command>cduce --run</command>.
133 134 135 136
</para>
</listitem>
</varlistentry>

137

138
<varlistentry>
139
<term><option>--run</option> <filename>files ...</filename></term>
140
<listitem>
141
<para>
142
Execute .cdo files produced by <command>cduce --compile</command>.
143
</para>
144 145 146
</listitem>
</varlistentry>

147
<varlistentry>
148
<term><option>--verbose</option></term>
149
<listitem>
150 151 152 153
<para>
(for <option>--compile</option>) Display the type of values in the compiled 
unit.
</para>
154 155 156
</listitem>
</varlistentry>

157
<varlistentry>
158
<term><option>--obj-dir</option> <filename>dir</filename></term>
159
<listitem>
160 161 162 163
<para>
(for <option>--compile</option>) Set the directory where to create
the .cdo file.
</para>
164 165 166 167
</listitem>
</varlistentry>

<varlistentry>
168
<term><option>-I</option> <filename>dir</filename></term>
169
<listitem>
170 171 172
<para>
Add <filename>dir</filename> to the list of directory used to find .cdo and .cmi files.
</para>
173 174 175
</listitem>
</varlistentry>

176

177
<varlistentry>
178
<term><option>--stdin</option></term>
179 180
<listitem>
<para>
181
Read CDuce script on standard input.
182 183 184 185
</para>
</listitem>
</varlistentry>

186 187 188 189 190 191 192 193 194 195 196
<varlistentry>
<term><option>--no</option> feature</term>
<listitem>
<para>Disable one of the built-in optional features. The list
of feature and their symbolic name can be obtained with the
<option>-v</option> option. Can be used
for instance to turn the Expat parser off, in order to use PXP,
if both have been included at compile time.
</para>
</listitem>
</varlistentry>
197 198

<varlistentry>
199
<term><option>--debug</option></term>
200
<listitem>
201
<para>Pprint profiling/debugging information.
202 203 204
</para>
</listitem>
</varlistentry>
205 206

<varlistentry>
207
<term><option>-v</option>, <option>--version</option></term>
208
<listitem>
209
<para>Show version information and exit.</para>
210 211 212
</listitem>
</varlistentry>

213 214 215 216 217 218
<varlistentry>
<term><option>--license</option></term>
<listitem>
<para>Show license information and exit.</para>
</listitem>
</varlistentry>
219 220

<varlistentry>
221
<term><option>--dump <filename>file</filename></option></term>
222
<listitem>
223 224 225 226 227
<para>
(Deprecated)
This option is equivalent to restore the environment previously saved in
<filename>file</filename> by the <option>--load <filename>file</filename></option> <option>--save <filename>file</filename></option>.
</para>
228 229 230
</listitem>
</varlistentry>

231 232 233 234 235 236 237 238 239 240 241 242 243
<varlistentry>
<term><option>--load <filename>file</filename></option></term>
<listitem>
<para>
(Deprecated)
Restore the environment previously saved in
<filename>file</filename> by the <option>--save</option> option.
</para>
</listitem>
</varlistentry>



244

245 246 247
<varlistentry>
<term><option>--save <filename>file</filename></option></term>
<listitem>
248 249 250
<para>
(Deprecated)
This options allows persistence between several invocations of the
251 252 253 254 255 256 257
interpreter: the current environment (i.e., the set defined types and values) is saved in
<filename>file</filename> when the interpreter terminates so that it
can be succesively restored by using <option>--load</option> option
</para>
</listitem>
</varlistentry>

258
<varlistentry>
259
<term><option>--help</option></term>
260
<listitem>
261
<para>Display a short help message and exit.</para>
262 263
</listitem>
</varlistentry>
264 265


266 267
</variablelist>

268

269 270 271 272 273 274 275 276
</refsect2>

<refsect2>
<title>PROGRAM OPTIONS</title>
<para>
<variablelist>

<varlistentry>
277
<term><option>--arg <filename>arguments</filename></option></term>
278 279 280

<listitem>
<para>
281
All the arguments following <option>--arg</option> are passed to the CDuce
282 283 284
program. They can be fetched from the CDuce program 
with the built-in operator <command>argv</command> (of type <command>[] -> [ String*
]</command>).
285 286 287 288 289 290 291 292 293 294 295 296
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>

</refsect1>
	
<refsect1>
<title>Reporting bugs</title>
<para>
297
Report bugs to <email>devel@cduce.org</email>.
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318
</para>

</refsect1>



	
<refsect1>
<title>SEE ALSO</title>
<para>
A complete documentation, reference manual, tutorial, technical articles on
implementation and theoretical issues, benchmarks, source code, mailing lists
and forums can be found on the <emphasis>CDuce</emphasis> website:
<filename>http://www.cduce.org</filename>.
</para>

</refsect1>

<refsect1>
<title>AUTHOR</title>
<para>
319 320
Alain Frisch <email>&lt;Alain.Frisch@ens.fr&gt;</email>. Small contributions by
Giuseppe Castagna <email>&lt;Giuseppe.Castagna@ens.fr&gt;</email>, Julien Demouth <email>&lt;Julien.Demouth@ens.fr&gt;</email>, and Stefano Zacchiroli <email>&lt;zack@di.ens.fr&gt;</email>.
321 322 323 324 325 326 327 328
</para>

</refsect1>




</refentry>