ghc/docs/users_guide/utils.vsgml

   1 %************************************************************************
   2 %*                                                                      *
   3 <sect>Other Haskell utility programs
   4 <label id="utils">
   5 <p>
   6 <nidx>utilities, Haskell</nidx>
   7 %*                                                                      *
   8 %************************************************************************
   9
  10 This section describes other program(s) which we distribute, that help
  11 with the Great Haskell Programming Task.
  12
  13 %************************************************************************
  14 %*                                                                      *
  15 <sect1>Makefile dependencies in Haskell: using @mkdependHS@
  16 <label id="mkdependHS">
  17 <p>
  18 <nidx>mkdependHS</nidx>
  19 <nidx>Makefile dependencies</nidx>
  20 <nidx>dependencies in Makefiles</nidx>
  21 %*                                                                      *
  22 %************************************************************************
  23
  24 You run @mkdependHS@ like this:
  25 <tscreen><verb>
  26   mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
  27 </verb></tscreen>
  28 or
  29 <tscreen><verb>
  30   ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
  31 </verb></tscreen>
  32 To see @mkdependHS@'s command-line flags, give it a duff flag,
  33 e.g., @mkdependHS -help@.
  34
  35 In general, if module @A@ contains the line
  36 <tscreen><verb>
  37         import B ...blah...
  38 </verb></tscreen>
  39 then @mkdependHS@ will generate a dependency line of the form:
  40 <tscreen><verb>
  41         A.o : B.hi
  42 </verb></tscreen>
  43 If module @A@ contains the line
  44 <tscreen><verb>
  45         import {-# SOURCE #-} B ...blah...
  46 </verb></tscreen>
  47 then @mkdependHS@ will generate a dependency line of the form:
  48 <tscreen><verb>
  49         A.o : B.hi-boot
  50 </verb></tscreen>
  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
  53 target.
  54
  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
  61 dependencies first.
  62
  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.
  67 <descrip>
  68
  69 <tag>@-D<blah>@</tag>   A cpp @#define@; usual meaning.
  70
  71 <tag>@-i<dirs>@</tag>   Add @<dirs>@ (colon-separated) to list of directories
  72                 to search for "import"ed modules.
  73
  74 <tag>@-I<dir>@</tag>    Add @<dir>@ to list of directories to search for
  75                 .h files (i.e., usual meaning).
  76
  77 <tag>@-syslib <blah>@</tag> This program uses this GHC system library; take
  78                 appropriate action (e.g., recognise when they are
  79                 "import"ing a module from that library).
  80 </descrip>
  81
  82 Here are the @mkdependHS@-specific options (not between @--@'s):
  83 <descrip>
  84 <tag>@-v@</tag> Be verbose.
  85 <tag>@-v -v@</tag>      Be very verbose.
  86 <tag>@-w@</tag> Turn off warnings about interface file shadowing.
  87 <tag>@-f blah@</tag>
  88         Use @blah@ as the makefile, rather than @makefile@
  89         or @Makefile@.  If @blah@ doesn't exist, @mkdependHS@ creates it.
  90         We often use @-f .depend@ to put the dependencies in @.depend@ and
  91         then @include@ the file @.depend@ into @Makefilpe@.
  92
  93 <tag>@-o <osuf>@</tag>
  94         Use @.<osuf>@ as the "target file" suffix ( default: @o@).
  95         Multiple @-o@ flags are permitted (GHC2.05 onwards).  Thus "@-o hc -o o@"
  96         will generate dependencies for @.hc@ and @.o@ files.
  97
  98 <tag>@-s <suf>@</tag>
  99                 Make extra dependencies that declare that files with
 100                 suffix @.<suf>_<osuf>@ depend on interface files with suffix @.<suf>_hi@, or
 101                 (for @{-# SOURCE #-}@ imports) on @.hi-boot@.
 102                 Multiple @-s@ flags are permitted.
 103                 For example, "@-o hc -s a -s b@" will
 104                 make dependencies for @.hc@ on @.hi@, @.a_hc@ on @.a_hi@, and @.b_hc@ on @.b_hi@.
 105                 (Useful in conjunction with NoFib "ways".)
 106
 107 <tag>@--exclude-module=<file>@</tag>
 108                 Regard @<file>@ as "stable"; i.e., exclude it from having
 109                 dependencies on it.
 110
 111 <tag>@-x@</tag>      same as @--exclude-module@
 112
 113 <tag>@--exclude-directory=<dirs>@</tag>
 114                 Regard the colon-separated list of directories @<dirs>@ as containing stable,
 115                 don't generate any dependencies on modules therein.
 116
 117 <tag>@-Xdirs@</tag>      same as @--exclude-directory@.
 118
 119 <tag>@--include-module=<file>@</tag>
 120                 Regard @<file>@ as not "stable"; i.e., generate dependencies
 121                 on it (if any). This option is normally used in conjunction
 122                 with the @--exclude-directory@ option.
 123 <tag>@--include-prelude@</tag>
 124                 Regard prelude libraries as unstable, i.e., generate dependencies
 125                 on the prelude modules used (including @Prelude@).
 126                 This option is normally only used by the various system libraries. If
 127                 a @-syslib@ option is used, dependencies will also be
 128                 generated on the library's interfaces.
 129 </descrip>
 130
 131
 132 %************************************************************************
 133 %*                                                                      *
 134 <sect1>Emacs `TAGS' for Haskell: @hstags@
 135 <label id="hstags">
 136 <p>
 137 <nidx>hstags</nidx>
 138 <nidx>TAGS for Haskell</nidx>
 139 %*                                                                      *
 140 %************************************************************************
 141
 142 `Tags' is a facility for indexing the definitions of
 143 programming-language things in a multi-file program, and then using
 144 that index to jump around among these definitions.
 145
 146 Rather than scratch your head, saying ``Now where did we define
 147 `foo'?'', you just do (in Emacs) @M-. foo RET@, and You're There!
 148 Some people go wild over this stuff...
 149
 150 GHC comes with a program @hstags@, which build Emacs-able TAGS
 151 files.  The invocation syntax is:
 152 <tscreen><verb>
 153 hstags [GHC-options] file [files...]
 154 </verb></tscreen>
 155
 156 The best thing is just to feed it your GHC command-line flags.
 157 A good Makefile entry might be:
 158 <tscreen><verb>
 159 tags:
 160         $(RM) TAGS
 161         hstags $(GHC_FLAGS) *.lhs
 162 </verb></tscreen>
 163
 164 The only flags of its own are: @-v@ to be verbose; @-a@ to
 165 **APPEND** to the TAGS file, rather than write to it.
 166
 167 Shortcomings: (1)~Instance declarations don't get into the TAGS file
 168 (but the definitions inside them do); as instances aren't named, this
 169 is probably just as well.  (2)~Data-constructor definitions don't get
 170 in.  Go for the corresponding type constructor instead.
 171
 172 (Actually, GHC also comes with @etags@ [for C], and @perltags@
 173 [for You Know What].  And---I cannot tell a lie---there is Denis
 174 Howe's @fptags@ [for Haskell, etc.] in the @ghc/CONTRIB@
 175 section...)
 176
 177 %************************************************************************
 178 %*                                                                      *
 179 <sect1>``Yacc for Haskell'': @happy@
 180 <label id="happy">
 181 <p>
 182 <nidx>happy</nidx>
 183 <nidx>Yacc for Haskell</nidx>
 184 <nidx>parser generator for Haskell</nidx>
 185 %*                                                                      *
 186 %************************************************************************
 187
 188 Andy Gill and Simon Marlow have written a parser-generator for
 189 Haskell, called @happy@.<nidx>happy parser generator</nidx> @Happy@
 190 is to Haskell what @Yacc@ is to C.
 191
 192 You can get @happy@ by FTP from @ftp.dcs.gla.ac.uk@ in
 193 @pub/haskell/happy@, the file @happy-0.8.tar.gz@.
 194
 195 @Happy@ is at its shining best when compiled by GHC.
 196
 197 %************************************************************************
 198 %*                                                                      *
 199 <sect1>Pretty-printing Haskell: @pphs@
 200 <label id="pphs">
 201 <p>
 202 <nidx>pphs</nidx>
 203 <nidx>pretty-printing Haskell code</nidx>
 204 %*                                                                      *
 205 %************************************************************************
 206
 207 Andrew Preece has written
 208 @pphs@,<nidx>pphs</nidx><nidx>pretty-printing Haskell</nidx>
 209 a utility to pretty-print Haskell code in LaTeX documents.
 210 Keywords in bolds, variables in italics---that sort of thing.  It is
 211 good at lining up program clauses and equals signs, things that are
 212 very tiresome to do by hand.
 213
 214 The code is distributed with GHC in @ghc/CONTRIB/pphs@.