ghc/docs/users_guide/utils.sgml

   1 <Chapter id="utils">
   2 <Title>Other Haskell utility programs
   3 </Title>
   4
   5 <IndexTerm><Primary>utilities, Haskell</Primary></IndexTerm>
   6
   7 <Para>
   8 This section describes other program(s) which we distribute, that help
   9 with the Great Haskell Programming Task.
  10 </Para>
  11
  12 <Sect1 id="mkdependHS">
  13 <Title>Makefile dependencies in Haskell: using <Literal>mkdependHS</Literal>
  14 </Title>
  15
  16 <Para>
  17 <IndexTerm><Primary>mkdependHS</Primary></IndexTerm>
  18 <IndexTerm><Primary>Makefile dependencies</Primary></IndexTerm>
  19 <IndexTerm><Primary>dependencies in Makefiles</Primary></IndexTerm>
  20 </Para>
  21
  22 <Para>
  23 You run <Literal>mkdependHS</Literal> like this:
  24
  25 <Screen>
  26 mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
  27 </Screen>
  28
  29 or
  30
  31 <Screen>
  32 ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
  33 </Screen>
  34
  35 To see <Literal>mkdependHS</Literal>'s command-line flags, give it a duff flag,
  36 e.g., <Literal>mkdependHS -help</Literal>.
  37 </Para>
  38
  39 <Para>
  40 In general, if module <Literal>A</Literal> contains the line
  41
  42 <ProgramListing>
  43 import B ...blah...
  44 </ProgramListing>
  45
  46 then <Literal>mkdependHS</Literal> will generate a dependency line of the form:
  47
  48 <ProgramListing>
  49 A.o : B.hi
  50 </ProgramListing>
  51
  52 If module <Literal>A</Literal> contains the line
  53
  54 <ProgramListing>
  55 import {-# SOURCE #-} B ...blah...
  56 </ProgramListing>
  57
  58 then <Literal>mkdependHS</Literal> will generate a dependency line of the form:
  59
  60 <ProgramListing>
  61 A.o : B.hi-boot
  62 </ProgramListing>
  63
  64 (See <XRef LinkEnd="hi-files"> for details of interface files.)
  65 If <Literal>A</Literal> imports multiple modules, then there will be multiple lines with <Literal>A.o</Literal> as the
  66 target.
  67 </Para>
  68
  69 <Para>
  70 By default, <Literal>mkdependHS</Literal> generates all the dependencies, and then
  71 concatenates them onto the end of
  72 <Literal>makefile</Literal> (or <Literal>Makefile</Literal> if <Literal>makefile</Literal> doesn't exist) bracketed by
  73 the lines "<Literal>&num; DO NOT DELETE: Beginning of Haskell dependencies</Literal>" and
  74 "<Literal>&num; DO NOT DELETE: End of Haskell dependencies</Literal>".  If these lines
  75 already exist in the <Literal>makefile</Literal>, <Literal>mkdependHS</Literal> deletes the old
  76 dependencies first.
  77 </Para>
  78
  79 <Para>
  80 <Literal>mkdependHS</Literal> takes GHC options between <Literal>--</Literal> brackets.
  81 It understands the following ones. Any options between <Literal>--</Literal> brackets
  82 that it doesn't understand are simply ignored; this way you can feed your
  83 Makefile's standard GHC options to <Literal>mkdependHS</Literal> un-filtered.
  84 <VariableList>
  85
  86 <VarListEntry>
  87 <Term><Literal>-cpp</Literal></Term>
  88 <ListItem>
  89 <Para>
  90 Run the C pre-processor over the input files. The
  91 default is not to.
  92 </Para>
  93 </ListItem>
  94 </VarListEntry>
  95 <VarListEntry>
  96 <Term><Literal>-D&lt;blah&gt;</Literal></Term>
  97 <ListItem>
  98 <Para>
  99 A cpp <Literal>&num;define</Literal>; usual meaning.
 100 </Para>
 101 </ListItem>
 102 </VarListEntry>
 103 <VarListEntry>
 104 <Term><Literal>-i&lt;dirs&gt;</Literal></Term>
 105 <ListItem>
 106 <Para>
 107 Add <Literal>&lt;dirs&gt;</Literal> (colon-separated) to list of directories
 108 to search for "import"ed modules.
 109 </Para>
 110 </ListItem>
 111 </VarListEntry>
 112 <VarListEntry>
 113 <Term><Literal>-I&lt;dir&gt;</Literal></Term>
 114 <ListItem>
 115 <Para>
 116 Add <Literal>&lt;dir&gt;</Literal> to list of directories to search for
 117 .h files (i.e., usual meaning).
 118 </Para>
 119 </ListItem>
 120 </VarListEntry>
 121 <VarListEntry>
 122 <Term><Literal>-syslib &lt;blah&gt;</Literal></Term>
 123 <ListItem>
 124 <Para>
 125 This program uses this GHC system library; take
 126 appropriate action (e.g., recognise when they are
 127 "import"ing a module from that library).
 128 </Para>
 129 </ListItem>
 130 </VarListEntry>
 131 </VariableList>
 132 </Para>
 133
 134 <Para>
 135 Here are the <Literal>mkdependHS</Literal>-specific options (not between <Literal>--</Literal>'s):
 136 <VariableList>
 137
 138 <VarListEntry>
 139 <Term><Literal>-v</Literal></Term>
 140 <ListItem>
 141 <Para>
 142 Be verbose.
 143 </Para>
 144 </ListItem>
 145 </VarListEntry>
 146 <VarListEntry>
 147 <Term><Literal>-v -v</Literal></Term>
 148 <ListItem>
 149 <Para>
 150 Be very verbose.
 151 </Para>
 152 </ListItem>
 153 </VarListEntry>
 154 <VarListEntry>
 155 <Term><Literal>-w</Literal></Term>
 156 <ListItem>
 157 <Para>
 158 Turn off warnings about interface file shadowing.
 159 </Para>
 160 </ListItem>
 161 </VarListEntry>
 162 <VarListEntry>
 163 <Term><Literal>-f blah</Literal></Term>
 164 <ListItem>
 165 <Para>
 166 Use <Literal>blah</Literal> as the makefile, rather than <Literal>makefile</Literal>
 167 or <Literal>Makefile</Literal>.  If <Literal>blah</Literal> doesn't exist, <Literal>mkdependHS</Literal> creates it.
 168 We often use <Literal>-f .depend</Literal> to put the dependencies in <Literal>.depend</Literal> and
 169 then <Literal>include</Literal> the file <Literal>.depend</Literal> into <Literal>Makefilpe</Literal>.
 170 </Para>
 171 </ListItem>
 172 </VarListEntry>
 173 <VarListEntry>
 174 <Term><Literal>-o &lt;osuf&gt;</Literal></Term>
 175 <ListItem>
 176 <Para>
 177 Use <Literal>.&lt;osuf&gt;</Literal> as the "target file" suffix ( default: <Literal>o</Literal>).
 178 Multiple <Literal>-o</Literal> flags are permitted (GHC2.05 onwards).  Thus "<Literal>-o hc -o o</Literal>"
 179 will generate dependencies for <Literal>.hc</Literal> and <Literal>.o</Literal> files.
 180 </Para>
 181 </ListItem>
 182 </VarListEntry>
 183 <VarListEntry>
 184 <Term><Literal>-s &lt;suf&gt;</Literal></Term>
 185 <ListItem>
 186 <Para>
 187 Make extra dependencies that declare that files with
 188 suffix <Literal>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</Literal> depend on interface files with suffix <Literal>.&lt;suf&gt;&lowbar;hi</Literal>, or
 189 (for <Literal>&lcub;-&num; SOURCE &num;-&rcub;</Literal> imports) on <Literal>.hi-boot</Literal>.
 190 Multiple <Literal>-s</Literal> flags are permitted.
 191 For example, "<Literal>-o hc -s a -s b</Literal>" will
 192 make dependencies for <Literal>.hc</Literal> on <Literal>.hi</Literal>, <Literal>.a&lowbar;hc</Literal> on <Literal>.a&lowbar;hi</Literal>, and <Literal>.b&lowbar;hc</Literal> on <Literal>.b&lowbar;hi</Literal>.
 193 (Useful in conjunction with NoFib "ways".)
 194 </Para>
 195 </ListItem>
 196 </VarListEntry>
 197 <VarListEntry>
 198 <Term><Literal>--exclude-module=&lt;file&gt;</Literal></Term>
 199 <ListItem>
 200 <Para>
 201 Regard <Literal>&lt;file&gt;</Literal> as "stable"; i.e., exclude it from having
 202 dependencies on it.
 203 </Para>
 204 </ListItem>
 205 </VarListEntry>
 206 <VarListEntry>
 207 <Term><Literal>-x</Literal></Term>
 208 <ListItem>
 209 <Para>
 210 same as <Literal>--exclude-module</Literal>
 211 </Para>
 212 </ListItem>
 213 </VarListEntry>
 214 <VarListEntry>
 215 <Term><Literal>--exclude-directory=&lt;dirs&gt;</Literal></Term>
 216 <ListItem>
 217 <Para>
 218 Regard the colon-separated list of directories <Literal>&lt;dirs&gt;</Literal> as containing stable,
 219 don't generate any dependencies on modules therein.
 220 </Para>
 221 </ListItem>
 222 </VarListEntry>
 223 <VarListEntry>
 224 <Term><Literal>-Xdirs</Literal></Term>
 225 <ListItem>
 226 <Para>
 227 same as <Literal>--exclude-directory</Literal>.
 228 </Para>
 229 </ListItem>
 230 </VarListEntry>
 231 <VarListEntry>
 232 <Term><Literal>--include-module=&lt;file&gt;</Literal></Term>
 233 <ListItem>
 234 <Para>
 235 Regard <Literal>&lt;file&gt;</Literal> as not "stable"; i.e., generate dependencies
 236 on it (if any). This option is normally used in conjunction
 237 with the <Literal>--exclude-directory</Literal> option.
 238 </Para>
 239 </ListItem>
 240 </VarListEntry>
 241 <VarListEntry>
 242 <Term><Literal>--include-prelude</Literal></Term>
 243 <ListItem>
 244 <Para>
 245 Regard prelude libraries as unstable, i.e., generate dependencies
 246 on the prelude modules used (including <Literal>Prelude</Literal>).
 247 This option is normally only used by the various system libraries. If
 248 a <Literal>-syslib</Literal> option is used, dependencies will also be
 249 generated on the library's interfaces.
 250 </Para>
 251 </ListItem>
 252 </VarListEntry>
 253 </VariableList>
 254 </Para>
 255
 256 </Sect1>
 257
 258 <Sect1 id="hstags">
 259 <Title>Emacs `TAGS' for Haskell: <Literal>hstags</Literal>
 260 </Title>
 261
 262 <Para>
 263 <IndexTerm><Primary>hstags</Primary></IndexTerm>
 264 <IndexTerm><Primary>TAGS for Haskell</Primary></IndexTerm>
 265 </Para>
 266
 267 <Para>
 268 `Tags' is a facility for indexing the definitions of
 269 programming-language things in a multi-file program, and then using
 270 that index to jump around among these definitions.
 271 </Para>
 272
 273 <Para>
 274 Rather than scratch your head, saying ``Now where did we define
 275 `foo'?'', you just do (in Emacs) <Literal>M-. foo RET</Literal>, and You're There!
 276 Some people go wild over this stuff&hellip;
 277 </Para>
 278
 279 <Para>
 280 GHC comes with a program <Literal>hstags</Literal>, which build Emacs-able TAGS files.  The invocation syntax is:
 281
 282 <Screen>
 283 hstags [GHC-options] file [files...]
 284 </Screen>
 285
 286 </Para>
 287
 288 <Para>
 289 The best thing is just to feed it your GHC command-line flags.
 290 A good Makefile entry might be:
 291
 292 <ProgramListing>
 293 tags:
 294         $(RM) TAGS
 295         hstags $(GHC_FLAGS) *.lhs
 296 </ProgramListing>
 297
 298 </Para>
 299
 300 <Para>
 301 The only flags of its own are: <Literal>-v</Literal> to be verbose; <Literal>-a</Literal> to
 302 **APPEND** to the TAGS file, rather than write to it.
 303 </Para>
 304
 305 <Para>
 306 Shortcomings: (1)&nbsp;Instance declarations don't get into the TAGS file
 307 (but the definitions inside them do); as instances aren't named, this
 308 is probably just as well.  (2)&nbsp;Data-constructor definitions don't get
 309 in.  Go for the corresponding type constructor instead.
 310 </Para>
 311
 312 <Para>
 313 (Actually, GHC also comes with <Literal>etags</Literal> &lsqb;for C&rsqb;, and <Literal>perltags</Literal>
 314 &lsqb;for You Know What&rsqb;.  And&mdash;I cannot tell a lie&mdash;there is Denis
 315 Howe's <Literal>fptags</Literal> &lsqb;for Haskell, etc.&rsqb; in the <Literal>ghc/CONTRIB</Literal>
 316 section&hellip;)
 317 </Para>
 318
 319 </Sect1>
 320
 321 <Sect1 id="happy">
 322 <Title>``Yacc for Haskell'': <Literal>happy</Literal>
 323 </Title>
 324
 325 <Para>
 326 <IndexTerm><Primary>happy</Primary></IndexTerm>
 327 <IndexTerm><Primary>Yacc for Haskell</Primary></IndexTerm>
 328 <IndexTerm><Primary>parser generator for Haskell</Primary></IndexTerm>
 329 Andy Gill and Simon Marlow have written a parser-generator for
 330 Haskell, called <Literal>happy</Literal>.<IndexTerm><Primary>happy parser generator</Primary></IndexTerm> <Literal>Happy</Literal>
 331 is to Haskell what <Literal>Yacc</Literal> is to C.
 332 </Para>
 333
 334 <Para>
 335 You can get <Literal>happy</Literal> by FTP from <Literal>ftp.dcs.gla.ac.uk</Literal> in
 336 <Literal>pub/haskell/happy</Literal>, the file <Literal>happy-1.5-src.tar.gz</Literal>.
 337 </Para>
 338
 339 <Para>
 340 <Literal>Happy</Literal> is at its shining best when compiled by GHC.
 341 </Para>
 342
 343 </Sect1>
 344
 345 <Sect1 id="pphs">
 346 <Title>Pretty-printing Haskell: <Literal>pphs</Literal>
 347 </Title>
 348
 349 <Para>
 350 <IndexTerm><Primary>pphs</Primary></IndexTerm>
 351 <IndexTerm><Primary>pretty-printing Haskell code</Primary></IndexTerm>
 352 </Para>
 353
 354 <Para>
 355 Andrew Preece has written
 356 <Literal>pphs</Literal>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing Haskell</Primary></IndexTerm>
 357 a utility to pretty-print Haskell code in LaTeX documents.
 358 Keywords in bolds, variables in italics&mdash;that sort of thing.  It is
 359 good at lining up program clauses and equals signs, things that are
 360 very tiresome to do by hand.
 361 </Para>
 362
 363 <Para>
 364 The code is distributed with GHC in <Literal>ghc/CONTRIB/pphs</Literal>.
 365 </Para>
 366
 367 </Sect1>
 368
 369 </Chapter>