d007621521d41b4ff303816058af0c11c1d46189
[ghc.git] / ghc / docs / users_guide / utils.lit
1 %************************************************************************
2 %*                                                                      *
3 \section[utils]{Other Haskell utility programs}
4 \index{utilities, Haskell}
5 %*                                                                      *
6 %************************************************************************
7
8 This section describes other program(s) which we distribute, that help
9 with the Great Haskell Programming Task.
10
11 %************************************************************************
12 %*                                                                      *
13 \subsection[mkdependHS]{Makefile dependencies in Haskell: using \tr{mkdependHS}}
14 \index{mkdependHS}
15 \index{Makefile dependencies}
16 \index{dependencies in Makefiles}
17 %*                                                                      *
18 %************************************************************************
19
20 It is reasonably straightforward to set up a \tr{Makefile} to use with
21 GHC, assuming you name your source files the same as your modules.
22 Thus:
23 \begin{verbatim}
24 HC      = ghc
25 HCFLAGS = -fhaskell-1.3 -cpp -hi-diffs $(EXTRA_HC_OPTS)
26
27 SRCS = Main.lhs Foo.lhs Bar.lhs
28 OBJS = Main.o   Foo.o   Bar.o
29
30 .SUFFIXES : .o .lhs
31 .lhs.o:
32         $(RM) $@
33         $(HC) -c $< $(HCFLAGS)
34
35 cool_pgm : $(OBJS)
36         $(RM) $@
37         $(HC) -o $@ $(HCFLAGS) $(OBJS)
38 \end{verbatim}
39
40 The only thing lacking in the above \tr{Makefile} is interface-file
41 dependencies.  If \tr{Foo.lhs} imports module \tr{Bar} and the
42 \tr{Bar} interface changes, then \tr{Foo.lhs} needs to be recompiled.
43
44 Putting dependencies of the form \tr{Foo.o : Bar.hi} into your
45 \tr{Makefile} by hand is rather error-prone.  Don't worry---never
46 fear, \tr{mkdependHS} is here! (and is distributed as part of GHC)
47 Add the following to your \tr{Makefile}:
48 \begin{verbatim}
49 depend :
50         mkdependHS -- $(HCFLAGS) -- $(SRCS)
51 \end{verbatim}
52
53 Now, before you start compiling, and any time you change the
54 \tr{imports} in your program, do \tr{make depend} before you do
55 \tr{make cool_pgm}.  \tr{mkdependHS} will append the needed
56 dependencies to your \tr{Makefile}.
57
58 A few caveats about this simple scheme: (a)~You may need to compile
59 some modules explicitly to create their interfaces in the first place
60 (e.g., \tr{make Bar.o} to create \tr{Bar.hi}).  (b)~You may have to
61 type \tr{make} more than once for the dependencies to have full
62 effect.  However, a \tr{make} run that does nothing {\em does} mean
63 ``everything's up-to-date.''  (c) This scheme will work with
64 mutually-recursive modules but, again, it may take multiple
65 iterations to ``settle.''
66
67 %************************************************************************
68 %*                                                                      *
69 \subsection[hstags]{Emacs `TAGS' for Haskell: \tr{hstags}}
70 \index{hstags}
71 \index{TAGS for Haskell}
72 %*                                                                      *
73 %************************************************************************
74
75 `Tags' is a facility for indexing the definitions of
76 programming-language things in a multi-file program, and then using
77 that index to jump around among these definitions.
78
79 Rather than scratch your head, saying ``Now where did we define
80 `foo'?'', you just do (in Emacs) \tr{M-. foo RET}, and You're There!
81 Some people go wild over this stuff...
82
83 GHC comes with a program \tr{hstags}, which build Emacs-able TAGS
84 files.  The invocation syntax is:
85 \begin{verbatim}
86 hstags [GHC-options] file [files...]
87 \end{verbatim}
88
89 The best thing is just to feed it your GHC command-line flags.
90 A good Makefile entry might be:
91 \begin{verbatim}
92 tags:
93         $(RM) TAGS
94         hstags $(GHC_FLAGS) *.lhs
95 \end{verbatim}
96
97 The only flags of its own are: \tr{-v} to be verbose; \tr{-a} to
98 **APPEND** to the TAGS file, rather than write to it.
99
100 Shortcomings: (1)~Instance declarations don't get into the TAGS file
101 (but the definitions inside them do); as instances aren't named, this
102 is probably just as well.  (2)~Data-constructor definitions don't get
103 in.  Go for the corresponding type constructor instead.
104
105 (Actually, GHC also comes with \tr{etags} [for C], and \tr{perltags}
106 [for You Know What].  And---I cannot tell a lie---there is Denis
107 Howe's \tr{fptags} [for Haskell, etc.] in the \tr{ghc/CONTRIB}
108 section...)
109
110 %************************************************************************
111 %*                                                                      *
112 \subsection[happy]{``Yacc for Haskell'': \tr{happy}}
113 \index{happy}
114 \index{Yacc for Haskell}
115 \index{parser generator for Haskell}
116 %*                                                                      *
117 %************************************************************************
118
119 Andy Gill and Simon Marlow have written a parser-generator for
120 Haskell, called \tr{happy}.\index{happy parser generator} \tr{Happy}
121 is to Haskell what \tr{Yacc} is to C.
122
123 You can get \tr{happy} by FTP from \tr{ftp.dcs.glasgow.ac.uk} in
124 \tr{pub/haskell/happy}, the file \tr{happy-0.8.tar.gz}.
125
126 \tr{Happy} is at its shining best when compiled by GHC.
127
128 %************************************************************************
129 %*                                                                      *
130 \subsection[pphs]{Pretty-printing Haskell: \tr{pphs}}
131 \index{pphs}
132 \index{pretty-printing Haskell code}
133 %*                                                                      *
134 %************************************************************************
135
136 Andrew Preece has written
137 \tr{pphs},\index{pphs}\index{pretty-printing Haskell}
138 a utility to pretty-print Haskell code in LaTeX documents.
139 Keywords in bolds, variables in italics---that sort of thing.  It is
140 good at lining up program clauses and equals signs, things that are
141 very tiresome to do by hand.
142
143 The code is distributed with GHC in \tr{ghc/CONTRIB/pphs}.