1 %************************************************************************
3 <sect>Other Haskell utility programs
6 <nidx>utilities, Haskell</nidx>
8 %************************************************************************
10 This section describes other program(s) which we distribute, that help
11 with the Great Haskell Programming Task.
13 %************************************************************************
15 <sect1>Makefile dependencies in Haskell: using @mkdependHS@
16 <label id="mkdependHS">
18 <nidx>mkdependHS</nidx>
19 <nidx>Makefile dependencies</nidx>
20 <nidx>dependencies in Makefiles</nidx>
22 %************************************************************************
24 You run @mkdependHS@ like this:
26 mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
30 ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
32 To see @mkdependHS@'s command-line flags, give it a duff flag,
33 e.g., @mkdependHS -help@.
35 In general, if module @A@ contains the line
39 then @mkdependHS@ will generate a dependency line of the form:
43 If module @A@ contains the line
45 import {-# SOURCE #-} B ...blah...
47 then @mkdependHS@ will generate a dependency line of the form:
51 (See Section <ref name="Interface files" id="hi-files"> for details of interface files.)
52 If @A@ imports multiple modules, then there will be multiple lines with @A.o@ as the
55 By default, @mkdependHS@ generates all the dependencies, and then
56 concatenates them onto the end of
57 @makefile@ (or @Makefile@ if @makefile@ doesn't exist) bracketed by
58 the lines "@# DO NOT DELETE: Beginning of Haskell dependencies@" and
59 "@# DO NOT DELETE: End of Haskell dependencies@". If these lines
60 already exist in the @makefile@, @mkdependHS@ deletes the old
63 @mkdependHS@ takes GHC options between @--@ brackets.
64 It understands the following ones. Any options between @--@ brackets
65 that it doesn't understand are simply ignored; this way you can feed your
66 Makefile's standard GHC options to @mkdependHS@ un-filtered.
69 <tag>@-cpp@</tag> Run the C pre-processor over the input files. The
71 <tag>@-D<blah>@</tag> A cpp @#define@; usual meaning.
73 <tag>@-i<dirs>@</tag> Add @<dirs>@ (colon-separated) to list of directories
74 to search for "import"ed modules.
76 <tag>@-I<dir>@</tag> Add @<dir>@ to list of directories to search for
77 .h files (i.e., usual meaning).
79 <tag>@-syslib <blah>@</tag> This program uses this GHC system library; take
80 appropriate action (e.g., recognise when they are
81 "import"ing a module from that library).
84 Here are the @mkdependHS@-specific options (not between @--@'s):
86 <tag>@-v@</tag> Be verbose.
87 <tag>@-v -v@</tag> Be very verbose.
88 <tag>@-w@</tag> Turn off warnings about interface file shadowing.
90 Use @blah@ as the makefile, rather than @makefile@
91 or @Makefile@. If @blah@ doesn't exist, @mkdependHS@ creates it.
92 We often use @-f .depend@ to put the dependencies in @.depend@ and
93 then @include@ the file @.depend@ into @Makefilpe@.
95 <tag>@-o <osuf>@</tag>
96 Use @.<osuf>@ as the "target file" suffix ( default: @o@).
97 Multiple @-o@ flags are permitted (GHC2.05 onwards). Thus "@-o hc -o o@"
98 will generate dependencies for @.hc@ and @.o@ files.
100 <tag>@-s <suf>@</tag>
101 Make extra dependencies that declare that files with
102 suffix @.<suf>_<osuf>@ depend on interface files with suffix @.<suf>_hi@, or
103 (for @{-# SOURCE #-}@ imports) on @.hi-boot@.
104 Multiple @-s@ flags are permitted.
105 For example, "@-o hc -s a -s b@" will
106 make dependencies for @.hc@ on @.hi@, @.a_hc@ on @.a_hi@, and @.b_hc@ on @.b_hi@.
107 (Useful in conjunction with NoFib "ways".)
109 <tag>@--exclude-module=<file>@</tag>
110 Regard @<file>@ as "stable"; i.e., exclude it from having
113 <tag>@-x@</tag> same as @--exclude-module@
115 <tag>@--exclude-directory=<dirs>@</tag>
116 Regard the colon-separated list of directories @<dirs>@ as containing stable,
117 don't generate any dependencies on modules therein.
119 <tag>@-Xdirs@</tag> same as @--exclude-directory@.
121 <tag>@--include-module=<file>@</tag>
122 Regard @<file>@ as not "stable"; i.e., generate dependencies
123 on it (if any). This option is normally used in conjunction
124 with the @--exclude-directory@ option.
125 <tag>@--include-prelude@</tag>
126 Regard prelude libraries as unstable, i.e., generate dependencies
127 on the prelude modules used (including @Prelude@).
128 This option is normally only used by the various system libraries. If
129 a @-syslib@ option is used, dependencies will also be
130 generated on the library's interfaces.
134 %************************************************************************
136 <sect1>Emacs `TAGS' for Haskell: @hstags@
140 <nidx>TAGS for Haskell</nidx>
142 %************************************************************************
144 `Tags' is a facility for indexing the definitions of
145 programming-language things in a multi-file program, and then using
146 that index to jump around among these definitions.
148 Rather than scratch your head, saying ``Now where did we define
149 `foo'?'', you just do (in Emacs) @M-. foo RET@, and You're There!
150 Some people go wild over this stuff...
152 GHC comes with a program @hstags@, which build Emacs-able TAGS
153 files. The invocation syntax is:
155 hstags [GHC-options] file [files...]
158 The best thing is just to feed it your GHC command-line flags.
159 A good Makefile entry might be:
163 hstags $(GHC_FLAGS) *.lhs
166 The only flags of its own are: @-v@ to be verbose; @-a@ to
167 **APPEND** to the TAGS file, rather than write to it.
169 Shortcomings: (1)~Instance declarations don't get into the TAGS file
170 (but the definitions inside them do); as instances aren't named, this
171 is probably just as well. (2)~Data-constructor definitions don't get
172 in. Go for the corresponding type constructor instead.
174 (Actually, GHC also comes with @etags@ [for C], and @perltags@
175 [for You Know What]. And---I cannot tell a lie---there is Denis
176 Howe's @fptags@ [for Haskell, etc.] in the @ghc/CONTRIB@
179 %************************************************************************
181 <sect1>``Yacc for Haskell'': @happy@
185 <nidx>Yacc for Haskell</nidx>
186 <nidx>parser generator for Haskell</nidx>
188 %************************************************************************
190 Andy Gill and Simon Marlow have written a parser-generator for
191 Haskell, called @happy@.<nidx>happy parser generator</nidx> @Happy@
192 is to Haskell what @Yacc@ is to C.
194 You can get @happy@ by FTP from @ftp.dcs.gla.ac.uk@ in
195 @pub/haskell/happy@, the file @happy-0.8.tar.gz@.
197 @Happy@ is at its shining best when compiled by GHC.
199 %************************************************************************
201 <sect1>Pretty-printing Haskell: @pphs@
205 <nidx>pretty-printing Haskell code</nidx>
207 %************************************************************************
209 Andrew Preece has written
210 @pphs@,<nidx>pphs</nidx><nidx>pretty-printing Haskell</nidx>
211 a utility to pretty-print Haskell code in LaTeX documents.
212 Keywords in bolds, variables in italics---that sort of thing. It is
213 good at lining up program clauses and equals signs, things that are
214 very tiresome to do by hand.
216 The code is distributed with GHC in @ghc/CONTRIB/pphs@.