Fold integer-gmp.git into ghc.git (re #8545)
[ghc.git] / docs / users_guide / utils.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <chapter id="utils">
3 <title>Other Haskell utility programs</title>
4 <indexterm><primary>utilities, Haskell</primary></indexterm>
5
6 <para>This section describes other program(s) which we distribute,
7 that help with the Great Haskell Programming Task.</para>
8
9 <!-- comment: hasktags was dropped in GHC 6.12
10
11 <sect1 id ="hasktags">
12 <title>Ctags and Etags for Haskell: <command>hasktags</command></title>
13 <indexterm><primary><command>hasktags</command></primary></indexterm>
14 <indexterm><primary>CTAGS for Haskell</primary></indexterm>
15
16 <para><command>hasktags</command> is a very simple Haskell program that produces ctags "tags" and etags "TAGS" files for Haskell programs.</para>
17
18 <para>When loaded into an editor such an NEdit, Vim, or Emacs, this allows one to easily navigate around a multi-file program, finding definitions of functions, types, and constructors.</para>
19
20 <para>Invocation Syntax:</para>
21
22 <screen>
23 hasktags files
24 </screen>
25
26 <para>This will read all the files listed in <option>files</option> and produce a ctags "tags" file and an etags "TAGS" file in the current directory.</para>
27
28 <para>Example usage</para>
29
30 <screen>
31 find -name \*.\*hs | xargs hasktags
32 </screen>
33
34 <para>This will find all haskell source files in the current directory and below, and create tags files indexing them in the current directory.</para>
35
36 <para><command>hasktags</command> is a simple program that uses simple
37 parsing rules to find definitions of functions, constructors, and types. It isn't guaranteed to find everything, and will sometimes create false index entries, but it usually gets the job done fairly well. In particular, at present, functions are only indexed if a type signature is given for them.</para>
38
39 <para>Before hasktags, there used to be <command>fptags</command> and <command>hstags</command>, which did essentially the same job, however neither of these seem to be maintained any more.</para>
40
41 <sect2>
42 <title>Using tags with your editor</title>
43
44 <para>With NEdit, load the "tags" file using "File/Load Tags File". Use "Ctrl-D" to search for a tag.</para>
45
46 <para>With XEmacs, load the "TAGS" file using "visit-tags-table". Use "M-." to search for a tag.</para>
47
48
49 </sect2>
50
51 </sect1>
52
53 -->
54 <!-- comment: hstags doesn't work anymore
55
56 <sect1 id="hstags">
57 <title>Emacs `TAGS' for Haskell: <command>hstags</command></title>
58 <indexterm><primary><command>hstags</command></primary></indexterm>
59 <indexterm><primary>TAGS for Haskell</primary></indexterm>
60
61 <para>`Tags' is a facility for indexing the definitions of
62 programming-language things in a multi-file program, and then
63 using that index to jump around among these definitions.</para>
64
65 <para>Rather than scratch your head, saying &ldquo;Now where did
66 we define `foo'?&rdquo;, you just do (in Emacs) <Literal>M-. foo
67 RET</Literal>, and You're There! Some people go wild over this
68 stuff&hellip;</para>
69
70 <para>GHC comes with a program <command>hstags</command>, which
71 build Emacs-able TAGS files. The invocation syntax is:</para>
72
73 <screen>
74 hstags [GHC-options] file [files...]
75 </screen>
76
77 <para>The best thing is just to feed it your GHC command-line
78 flags. A good Makefile entry might be:</para>
79
80 <programlisting>
81 tags:
82 $(RM) TAGS
83 hstags $(GHC_FLAGS) *.lhs
84 </programlisting>
85
86 <para>The only flags of its own are: <Option>-v</Option> to be
87 verbose; <Option>-a</Option> to <Emphasis>APPEND</Emphasis> to the
88 TAGS file, rather than write to it.</para>
89
90 <para>Shortcomings: (1)&nbsp;Instance declarations don't get into
91 the TAGS file (but the definitions inside them do); as instances
92 aren't named, this is probably just as well.
93 (2)&nbsp;Data-constructor definitions don't get in. Go for the
94 corresponding type constructor instead.</para>
95
96 <para>Actually, GHC also comes with <command>etags</command>
97 &lsqb;for C&rsqb;, and <command>perltags</command> &lsqb;for You
98 Know What&rsqb;. And&mdash;I cannot tell a lie&mdash;there is
99 Denis Howe's <command>fptags</command> &lsqb;for Haskell,
100 etc.&rsqb; in the <Filename>ghc/CONTRIB</Filename>
101 section&hellip;)</para>
102
103 </sect1>
104 -->
105
106 <sect1 id="happy">
107 <title>&ldquo;Yacc for Haskell&rdquo;: <command>happy</command></title>
108
109 <indexterm><primary>Happy</primary></indexterm>
110 <indexterm><primary>Yacc for Haskell</primary></indexterm>
111 <indexterm><primary>parser generator for Haskell</primary></indexterm>
112
113 <para>Andy Gill and Simon Marlow have written a parser-generator
114 for Haskell, called
115 <command>happy</command>.<indexterm><primary>happy parser
116 generator</primary></indexterm> <command>Happy</command> is to
117 Haskell what <command>Yacc</command> is to C.</para>
118
119 <para>You can get <command>happy</command> from <ulink
120 url="http://www.haskell.org/happy/">the Happy
121 Homepage</ulink>.</para>
122
123 <para><command>Happy</command> is at its shining best when
124 compiled by GHC.</para>
125
126 </sect1>
127
128 <!-- we don't distribute this anymore
129 <sect1 id="pphs">
130 <title>Pretty-printing Haskell: <command>pphs</command></title>
131 <indexterm><primary>pphs</primary></indexterm>
132 <indexterm><primary>pretty-printing Haskell code</primary></indexterm>
133
134 <para>Andrew Preece has written
135 <command>pphs</command>,<indexterm><primary>pphs</primary></indexterm><indexterm><primary>pretty-printing
136 Haskell</primary></indexterm> a utility to pretty-print Haskell
137 code in LaTeX documents. Keywords in bolds, variables in
138 italics&mdash;that sort of thing. It is good at lining up program
139 clauses and equals signs, things that are very tiresome to do by
140 hand.</para>
141
142 <para>The code is distributed with GHC in
143 <Filename>ghc/CONTRIB/pphs</Filename>.</para>
144 </sect1>
145 -->
146
147 <sect1 id="hsc2hs">
148 <title>Writing Haskell interfaces to C code:
149 <command>hsc2hs</command></title>
150 <indexterm><primary><command>hsc2hs</command></primary>
151 </indexterm>
152
153 <para>The <command>hsc2hs</command> command can be used to automate
154 some parts of the process of writing Haskell bindings to C code.
155 It reads an almost-Haskell source with embedded special
156 constructs, and outputs a real Haskell file with these constructs
157 processed, based on information taken from some C headers. The
158 extra constructs deal with accessing C data from Haskell.</para>
159
160 <para>It may also output a C file which contains additional C
161 functions to be linked into the program, together with a C header
162 that gets included into the C code to which the Haskell module
163 will be compiled (when compiled via C) and into the C file. These
164 two files are created when the <literal>#def</literal> construct
165 is used (see below).</para>
166
167 <para>Actually <command>hsc2hs</command> does not output the Haskell
168 file directly. It creates a C program that includes the headers,
169 gets automatically compiled and run. That program outputs the
170 Haskell code.</para>
171
172 <para>In the following, &ldquo;Haskell file&rdquo; is the main
173 output (usually a <literal>.hs</literal> file), &ldquo;compiled
174 Haskell file&rdquo; is the Haskell file after
175 <command>ghc</command> has compiled it to C (i.e. a
176 <literal>.hc</literal> file), &ldquo;C program&rdquo; is the
177 program that outputs the Haskell file, &ldquo;C file&rdquo; is the
178 optionally generated C file, and &ldquo;C header&rdquo; is its
179 header file.</para>
180
181 <sect2>
182 <title>command line syntax</title>
183
184 <para><command>hsc2hs</command> takes input files as arguments,
185 and flags that modify its behavior:</para>
186
187 <variablelist>
188 <varlistentry>
189 <term><literal>-o FILE</literal> or
190 <literal>--output=FILE</literal></term>
191 <listitem>
192 <para>Name of the Haskell file.</para>
193 </listitem>
194 </varlistentry>
195
196 <varlistentry>
197 <term><literal>-t FILE</literal> or
198 <literal>--template=FILE</literal></term>
199 <listitem>
200 <para>The template file (see below).</para>
201 </listitem>
202 </varlistentry>
203
204 <varlistentry>
205 <term><literal>-c PROG</literal> or
206 <literal>--cc=PROG</literal></term>
207 <listitem>
208 <para>The C compiler to use (default:
209 <command>gcc</command>)</para>
210 </listitem>
211 </varlistentry>
212
213 <varlistentry>
214 <term><literal>-l PROG</literal> or
215 <literal>--ld=PROG</literal></term>
216 <listitem>
217 <para>The linker to use (default:
218 <command>gcc</command>).</para>
219 </listitem>
220 </varlistentry>
221
222 <varlistentry>
223 <term><literal>-C FLAG</literal> or
224 <literal>--cflag=FLAG</literal></term>
225 <listitem>
226 <para>An extra flag to pass to the C compiler.</para>
227 </listitem>
228 </varlistentry>
229
230 <varlistentry>
231 <term><literal>-I DIR</literal></term>
232 <listitem>
233 <para>Passed to the C compiler.</para>
234 </listitem>
235 </varlistentry>
236
237 <varlistentry>
238 <term><literal>-L FLAG</literal> or
239 <literal>--lflag=FLAG</literal></term>
240 <listitem>
241 <para>An extra flag to pass to the linker.</para>
242 </listitem>
243 </varlistentry>
244
245 <varlistentry>
246 <term><literal>-i FILE</literal> or
247 <literal>--include=FILE</literal></term>
248 <listitem>
249 <para>As if the appropriate <literal>#include</literal>
250 directive was placed in the source.</para>
251 </listitem>
252 </varlistentry>
253
254 <varlistentry>
255 <term><literal>-D NAME[=VALUE]</literal> or
256 <literal>--define=NAME[=VALUE]</literal></term>
257 <listitem>
258 <para>As if the appropriate <literal>#define</literal>
259 directive was placed in the source.</para>
260 </listitem>
261 </varlistentry>
262
263 <varlistentry>
264 <term><literal>--no-compile</literal></term>
265 <listitem>
266 <para>Stop after writing out the intermediate C program to disk.
267 The file name for the intermediate C program is the input file name
268 with <literal>.hsc</literal> replaced with <literal>_hsc_make.c</literal>.</para>
269 </listitem>
270 </varlistentry>
271
272 <varlistentry>
273 <term><literal>-k</literal> or
274 <literal>--keep-files</literal></term>
275 <listitem>
276 <para>Proceed as normal, but do not delete any intermediate files.</para>
277 </listitem>
278 </varlistentry>
279
280 <varlistentry>
281 <term><literal>-x</literal> or
282 <literal>--cross-compile</literal></term>
283 <listitem>
284 <para>Activate cross-compilation mode (see <xref linkend="hsc2hs_cross"/>).</para>
285 </listitem>
286 </varlistentry>
287
288 <varlistentry>
289 <term><literal>--cross-safe</literal></term>
290 <listitem>
291 <para>Restrict the .hsc directives to those supported by the
292 <literal>--cross-compile</literal> mode (see <xref linkend="hsc2hs_cross"/>).
293 This should be useful if your <literal>.hsc</literal> files
294 must be safely cross-compiled and you wish to keep
295 non-cross-compilable constructs from creeping into them.</para>
296 </listitem>
297 </varlistentry>
298
299
300 <varlistentry>
301 <term><literal>-?</literal> or <literal>--help</literal></term>
302 <listitem>
303 <para>Display a summary of the available flags and exit successfully.</para>
304 </listitem>
305 </varlistentry>
306
307 <varlistentry>
308 <term><literal>-V</literal> or <literal>--version</literal></term>
309 <listitem>
310 <para>Output version information and exit successfully.</para>
311 </listitem>
312 </varlistentry>
313 </variablelist>
314
315 <para>The input file should end with .hsc (it should be plain
316 Haskell source only; literate Haskell is not supported at the
317 moment). Output files by default get names with the
318 <literal>.hsc</literal> suffix replaced:</para>
319
320 <informaltable>
321 <tgroup cols="2">
322 <tbody>
323 <row>
324 <entry><literal>.hs</literal></entry>
325 <entry>Haskell file</entry>
326 </row>
327 <row>
328 <entry><literal>_hsc.h</literal></entry>
329 <entry>C header</entry>
330 </row>
331 <row>
332 <entry><literal>_hsc.c</literal></entry>
333 <entry>C file</entry>
334 </row>
335 </tbody>
336 </tgroup>
337 </informaltable>
338
339 <para>The C program is compiled using the Haskell compiler. This
340 provides the include path to <filename>HsFFI.h</filename> which
341 is automatically included into the C program.</para>
342
343 </sect2>
344 <sect2><title>Input syntax</title>
345
346 <para>All special processing is triggered by
347 the <literal>#</literal> operator. To output
348 a literal <literal>#</literal>, write it twice:
349 <literal>##</literal>. Inside string literals and comments
350 <literal>#</literal> characters are not processed.</para>
351
352 <para>A <literal>#</literal> is followed by optional
353 spaces and tabs, an alphanumeric keyword that describes
354 the kind of processing, and its arguments. Arguments look
355 like C expressions separated by commas (they are not
356 written inside parens). They extend up to the nearest
357 unmatched <literal>)</literal>, <literal>]</literal> or
358 <literal>}</literal>, or to the end of line if it occurs outside
359 any <literal>() [] {} '' "" /**/</literal> and is not preceded
360 by a backslash. Backslash-newline pairs are stripped.</para>
361
362 <para>In addition <literal>#{stuff}</literal> is equivalent
363 to <literal>#stuff</literal> except that it's self-delimited
364 and thus needs not to be placed at the end of line or in some
365 brackets.</para>
366
367 <para>Meanings of specific keywords:</para>
368
369 <variablelist>
370
371 <varlistentry>
372 <term><literal>#include &lt;file.h&gt;</literal></term>
373 <term><literal>#include "file.h"</literal></term>
374 <listitem>
375 <para>The specified file gets included into the C program,
376 the compiled Haskell file, and the C header.
377 <literal>&lt;HsFFI.h&gt;</literal> is included
378 automatically.</para>
379 </listitem>
380 </varlistentry>
381
382 <varlistentry>
383 <term><literal>#define name</literal></term>
384 <term><literal>#define name value</literal></term>
385 <term><literal>#undef name</literal></term>
386 <listitem>
387 <para>Similar to <literal>#include</literal>. Note that
388 <literal>#includes</literal> and
389 <literal>#defines</literal> may be put in the same file
390 twice so they should not assume otherwise.</para>
391 </listitem>
392 </varlistentry>
393
394 <varlistentry>
395 <term><literal>#let name parameters = "definition"</literal></term>
396 <listitem>
397 <para>Defines a macro to be applied to the Haskell
398 source. Parameter names are comma-separated, not
399 inside parens. Such macro is invoked as other
400 <literal>#</literal>-constructs, starting with
401 <literal>#name</literal>. The definition will be
402 put in the C program inside parens as arguments of
403 <literal>printf</literal>. To refer to a parameter,
404 close the quote, put a parameter name and open the
405 quote again, to let C string literals concatenate.
406 Or use <literal>printf</literal>'s format directives.
407 Values of arguments must be given as strings, unless the
408 macro stringifies them itself using the C preprocessor's
409 <literal>#parameter</literal> syntax.</para>
410 </listitem>
411 </varlistentry>
412
413 <varlistentry>
414 <term><literal>#def C_definition</literal></term>
415 <listitem>
416 <para>The definition (of a function, variable, struct or
417 typedef) is written to the C file, and its prototype or
418 extern declaration to the C header. Inline functions are
419 handled correctly. struct definitions and typedefs are
420 written to the C program too. The
421 <literal>inline</literal>, <literal>struct</literal> or
422 <literal>typedef</literal> keyword must come just after
423 <literal>def</literal>.</para>
424 </listitem>
425 </varlistentry>
426
427 <varlistentry>
428 <term><literal>#if condition</literal></term>
429 <term><literal>#ifdef name</literal></term>
430 <term><literal>#ifndef name</literal></term>
431 <term><literal>#elif condition</literal></term>
432 <term><literal>#else</literal></term>
433 <term><literal>#endif</literal></term>
434 <term><literal>#error message</literal></term>
435 <term><literal>#warning message</literal></term>
436 <listitem>
437 <para>Conditional compilation directives are passed
438 unmodified to the C program, C file, and C header. Putting
439 them in the C program means that appropriate parts of the
440 Haskell file will be skipped.</para>
441 </listitem>
442 </varlistentry>
443
444 <varlistentry>
445 <term><literal>#const C_expression</literal></term>
446 <listitem>
447 <para>The expression must be convertible to
448 <literal>long</literal> or <literal>unsigned
449 long</literal>. Its value (literal or negated literal)
450 will be output.</para>
451 </listitem>
452 </varlistentry>
453
454 <varlistentry>
455 <term><literal>#const_str C_expression</literal></term>
456 <listitem>
457 <para>The expression must be convertible to const char
458 pointer. Its value (string literal) will be output.</para>
459 </listitem>
460 </varlistentry>
461
462 <varlistentry>
463 <term><literal>#type C_type</literal></term>
464 <listitem>
465 <para>A Haskell equivalent of the C numeric type will be
466 output. It will be one of
467 <literal>{Int,Word}{8,16,32,64}</literal>,
468 <literal>Float</literal>, <literal>Double</literal>,
469 <literal>LDouble</literal>.</para>
470 </listitem>
471 </varlistentry>
472
473 <varlistentry>
474 <term><literal>#peek struct_type, field</literal></term>
475 <listitem>
476 <para>A function that peeks a field of a C struct will be
477 output. It will have the type
478 <literal>Storable b => Ptr a -> IO b</literal>.
479
480 The intention is that <literal>#peek</literal> and
481 <literal>#poke</literal> can be used for implementing the
482 operations of class <literal>Storable</literal> for a
483 given C struct (see the
484 <literal>Foreign.Storable</literal> module in the library
485 documentation).</para>
486 </listitem>
487 </varlistentry>
488
489 <varlistentry>
490 <term><literal>#poke struct_type, field</literal></term>
491 <listitem>
492 <para>Similarly for poke. It will have the type
493 <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
494 </listitem>
495 </varlistentry>
496
497 <varlistentry>
498 <term><literal>#ptr struct_type, field</literal></term>
499 <listitem>
500 <para>Makes a pointer to a field struct. It will have the type
501 <literal>Ptr a -> Ptr b</literal>.</para>
502 </listitem>
503 </varlistentry>
504
505 <varlistentry>
506 <term><literal>#offset struct_type, field</literal></term>
507 <listitem>
508 <para>Computes the offset, in bytes, of
509 <literal>field</literal> in
510 <literal>struct_type</literal>. It will have type
511 <literal>Int</literal>.</para>
512 </listitem>
513 </varlistentry>
514
515 <varlistentry>
516 <term><literal>#size struct_type</literal></term>
517 <listitem>
518 <para>Computes the size, in bytes, of
519 <literal>struct_type</literal>. It will have type
520 <literal>Int</literal>.</para>
521 </listitem>
522 </varlistentry>
523
524 <varlistentry>
525 <term><literal>#enum type, constructor, value, value, ...</literal></term>
526 <listitem>
527 <para>A shortcut for multiple definitions which use
528 <literal>#const</literal>. Each <literal>value</literal>
529 is a name of a C integer constant, e.g. enumeration value.
530 The name will be translated to Haskell by making each
531 letter following an underscore uppercase, making all the rest
532 lowercase, and removing underscores. You can supply a different
533 translation by writing <literal>hs_name = c_value</literal>
534 instead of a <literal>value</literal>, in which case
535 <literal>c_value</literal> may be an arbitrary expression.
536 The <literal>hs_name</literal> will be defined as having the
537 specified <literal>type</literal>. Its definition is the specified
538 <literal>constructor</literal> (which in fact may be an expression
539 or be empty) applied to the appropriate integer value. You can
540 have multiple <literal>#enum</literal> definitions with the same
541 <literal>type</literal>; this construct does not emit the type
542 definition itself.</para>
543 </listitem>
544 </varlistentry>
545 </variablelist>
546
547 </sect2>
548
549 <sect2>
550 <title>Custom constructs</title>
551
552 <para><literal>#const</literal>, <literal>#type</literal>,
553 <literal>#peek</literal>, <literal>#poke</literal> and
554 <literal>#ptr</literal> are not hardwired into the
555 <command>hsc2hs</command>, but are defined in a C template that is
556 included in the C program: <filename>template-hsc.h</filename>.
557 Custom constructs and templates can be used too. Any
558 <literal>#</literal>-construct with unknown key is expected to
559 be handled by a C template.</para>
560
561 <para>A C template should define a macro or function with name
562 prefixed by <literal>hsc_</literal> that handles the construct
563 by emitting the expansion to stdout. See
564 <filename>template-hsc.h</filename> for examples.</para>
565
566 <para>Such macros can also be defined directly in the
567 source. They are useful for making a <literal>#let</literal>-like
568 macro whose expansion uses other <literal>#let</literal> macros.
569 Plain <literal>#let</literal> prepends <literal>hsc_</literal>
570 to the macro name and wraps the definition in a
571 <literal>printf</literal> call.</para>
572
573 </sect2>
574
575 <sect2 id="hsc2hs_cross">
576 <title>Cross-compilation</title>
577
578 <para><command>hsc2hs</command> normally operates by creating, compiling,
579 and running a C program. That approach doesn't work when cross-compiling --
580 in this case, the C compiler's generates code for the target machine,
581 not the host machine. For this situation, there's
582 a special mode <command>hsc2hs --cross-compile</command> which can generate
583 the .hs by extracting information from compilations only -- specifically,
584 whether or not compilation fails.
585 </para>
586
587 <para>Only a subset of <literal>.hsc</literal> syntax is supported by
588 <literal>--cross-compile</literal>. The following are unsupported:
589 <itemizedlist>
590 <listitem><literal>#{const_str}</literal></listitem>
591 <listitem><literal>#{let}</literal></listitem>
592 <listitem><literal>#{def}</literal></listitem>
593 <listitem>Custom constructs</listitem>
594 </itemizedlist>
595 </para>
596 </sect2>
597
598 </sect1>
599
600 </chapter>
601
602 <!-- Emacs stuff:
603 ;;; Local Variables: ***
604 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
605 ;;; End: ***
606 -->