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 <Command>mkdependHS</Command>
  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 <Command>mkdependHS</Command> 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 <Command>mkdependHS</Command>'s command-line flags, give it a duff flag,
  36 e.g., <Command>mkdependHS -help</Command>.
  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 <Command>mkdependHS</Command> 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 <Command>mkdependHS</Command> 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 <Filename>A.o</Filename> as the
  66 target.
  67 </Para>
  68
  69 <Para>
  70 By default, <Command>mkdependHS</Command> generates all the dependencies, and then
  71 concatenates them onto the end of
  72 <Filename>makefile</Filename> (or <Filename>Makefile</Filename> if <Filename>makefile</Filename> 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 <Filename>makefile</Filename>, <Command>mkdependHS</Command> deletes the old
  76 dependencies first.
  77 </Para>
  78
  79 <Para>
  80 <Command>mkdependHS</Command> 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 <Command>mkdependHS</Command> un-filtered.
  84 <VariableList>
  85
  86 <VarListEntry>
  87 <Term><Option>-cpp</Option></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><Option>-D&lt;blah&gt;</Option></Term>
  97 <ListItem>
  98 <Para>
  99 A cpp <Option>&num;define</Option>; usual meaning.
 100 </Para>
 101 </ListItem>
 102 </VarListEntry>
 103 <VarListEntry>
 104 <Term><Option>-i&lt;dirs&gt;</Option></Term>
 105 <ListItem>
 106 <Para>
 107 Add <Filename>&lt;dirs&gt;</Filename> (colon-separated) to list of directories
 108 to search for "import"ed modules.
 109 </Para>
 110 </ListItem>
 111 </VarListEntry>
 112 <VarListEntry>
 113 <Term><Option>-I&lt;dir&gt;</Option></Term>
 114 <ListItem>
 115 <Para>
 116 Add <Filename>&lt;dir&gt;</Filename> to list of directories to search for
 117 .h files (i.e., usual meaning).
 118 </Para>
 119 </ListItem>
 120 </VarListEntry>
 121 <VarListEntry>
 122 <Term><Option>-syslib &lt;blah&gt;</Option></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 <Command>mkdependHS</Command>-specific options (not between <Literal>--</Literal>'s):
 136 <VariableList>
 137
 138 <VarListEntry>
 139 <Term><Option>-v</Option></Term>
 140 <ListItem>
 141 <Para>
 142 Be verbose.
 143 </Para>
 144 </ListItem>
 145 </VarListEntry>
 146 <VarListEntry>
 147 <Term><Option>-v -v</Option></Term>
 148 <ListItem>
 149 <Para>
 150 Be very verbose.
 151 </Para>
 152 </ListItem>
 153 </VarListEntry>
 154 <VarListEntry>
 155 <Term><Option>-w</Option></Term>
 156 <ListItem>
 157 <Para>
 158 Turn off warnings about interface file shadowing.
 159 </Para>
 160 </ListItem>
 161 </VarListEntry>
 162 <VarListEntry>
 163 <Term><Option>-f blah</Option></Term>
 164 <ListItem>
 165 <Para>
 166 Use <Filename>blah</Filename> as the makefile, rather than <Filename>makefile</Filename>
 167 or <Filename>Makefile</Filename>.  If <Filename>blah</Filename> doesn't exist, <Command>mkdependHS</Command> creates it.
 168 We often use <Option>-f .depend</Option> to put the dependencies in <Filename>.depend</Filename> and
 169 then <Command>include</Command> the file <Filename>.depend</Filename> into <Filename>Makefile</Filename>.
 170 </Para>
 171 </ListItem>
 172 </VarListEntry>
 173 <VarListEntry>
 174 <Term><Option>-o &lt;osuf&gt;</Option></Term>
 175 <ListItem>
 176 <Para>
 177 Use <Filename>.&lt;osuf&gt;</Filename> as the "target file" suffix ( default: <Literal>o</Literal>).
 178 Multiple <Option>-o</Option> flags are permitted (GHC2.05 onwards).  Thus "<Option>-o hc -o o</Option>"
 179 will generate dependencies for <Filename>.hc</Filename> and <Filename>.o</Filename> files.
 180 </Para>
 181 </ListItem>
 182 </VarListEntry>
 183 <VarListEntry>
 184 <Term><Option>-s &lt;suf&gt;</Option></Term>
 185 <ListItem>
 186 <Para>
 187 Make extra dependencies that declare that files with
 188 suffix <Filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</Filename> depend on interface files with suffix <Filename>.&lt;suf&gt;&lowbar;hi</Filename>, or
 189 (for <Literal>&lcub;-&num; SOURCE &num;-&rcub;</Literal> imports) on <Filename>.hi-boot</Filename>.
 190 Multiple <Option>-s</Option> flags are permitted.
 191 For example, <Option>-o hc -s a -s b</Option> will
 192 make dependencies for <Filename>.hc</Filename> on <Filename>.hi</Filename>, <Filename>.a&lowbar;hc</Filename> on <Filename>.a&lowbar;hi</Filename>, and <Filename>.b&lowbar;hc</Filename> on <Filename>.b&lowbar;hi</Filename>.
 193 (Useful in conjunction with NoFib "ways".)
 194 </Para>
 195 </ListItem>
 196 </VarListEntry>
 197 <VarListEntry>
 198 <Term><Option>--exclude-module=&lt;file&gt;</Option></Term>
 199 <ListItem>
 200 <Para>
 201 Regard <Filename>&lt;file&gt;</Filename> as "stable"; i.e., exclude it from having
 202 dependencies on it.
 203 </Para>
 204 </ListItem>
 205 </VarListEntry>
 206 <VarListEntry>
 207 <Term><Option>-x</Option></Term>
 208 <ListItem>
 209 <Para>
 210 same as <Option>--exclude-module</Option>
 211 </Para>
 212 </ListItem>
 213 </VarListEntry>
 214 <VarListEntry>
 215 <Term><Option>--exclude-directory=&lt;dirs&gt;</Option></Term>
 216 <ListItem>
 217 <Para>
 218 Regard the colon-separated list of directories <Filename>&lt;dirs&gt;</Filename> as containing stable,
 219 don't generate any dependencies on modules therein.
 220 </Para>
 221 </ListItem>
 222 </VarListEntry>
 223 <VarListEntry>
 224 <Term><Option>-Xdirs</Option></Term>
 225 <ListItem>
 226 <Para>
 227 same as <Option>--exclude-directory</Option>.
 228 </Para>
 229 </ListItem>
 230 </VarListEntry>
 231 <VarListEntry>
 232 <Term><Option>--include-module=&lt;file&gt;</Option></Term>
 233 <ListItem>
 234 <Para>
 235 Regard <Filename>&lt;file&gt;</Filename> as not "stable"; i.e., generate dependencies
 236 on it (if any). This option is normally used in conjunction
 237 with the <Option>--exclude-directory</Option> option.
 238 </Para>
 239 </ListItem>
 240 </VarListEntry>
 241 <VarListEntry>
 242 <Term><Option>--include-prelude</Option></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 <Option>-syslib</Option> 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: <Command>hstags</Command>
 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 <Command>hstags</Command>, 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: <Option>-v</Option> to be verbose; <Option>-a</Option> to
 302 <Emphasis>APPEND</Emphasis> 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 <Command>etags</Command> &lsqb;for C&rsqb;, and <Command>perltags</Command>
 314 &lsqb;for You Know What&rsqb;.  And&mdash;I cannot tell a lie&mdash;there is Denis
 315 Howe's <Command>fptags</Command> &lsqb;for Haskell, etc.&rsqb; in the <Filename>ghc/CONTRIB</Filename>
 316 section&hellip;)
 317 </Para>
 318
 319 </Sect1>
 320
 321 <Sect1 id="happy">
 322 <Title>``Yacc for Haskell'': <Command>happy</Command>
 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 <Command>happy</Command>.<IndexTerm><Primary>happy parser generator</Primary></IndexTerm> <Command>Happy</Command>
 331 is to Haskell what <Command>Yacc</Command> is to C.
 332 </Para>
 333
 334 <Para>
 335 You can get <Command>happy</Command> by FTP from <Literal>ftp.dcs.gla.ac.uk</Literal> in
 336 <Filename>pub/haskell/happy</Filename>, the file <Filename>happy-1.5-src.tar.gz</Filename>.
 337 </Para>
 338
 339 <Para>
 340 <Command>Happy</Command> is at its shining best when compiled by GHC.
 341 </Para>
 342
 343 </Sect1>
 344
 345 <Sect1 id="pphs">
 346 <Title>Pretty-printing Haskell: <Command>pphs</Command>
 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 <Command>pphs</Command>,<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 <Filename>ghc/CONTRIB/pphs</Filename>.
 365 </Para>
 366
 367 </Sect1>
 368
 369 </Chapter>