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>@-cpp@</tag>       Run the C pre-processor over the input files. The
  70                         default is not to.
  71 <tag>@-D<blah>@</tag>   A cpp @#define@; usual meaning.
  72
  73 <tag>@-i<dirs>@</tag>   Add @<dirs>@ (colon-separated) to list of directories
  74                 to search for "import"ed modules.
  75
  76 <tag>@-I<dir>@</tag>    Add @<dir>@ to list of directories to search for
  77                 .h files (i.e., usual meaning).
  78
  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).
  82 </descrip>
  83
  84 Here are the @mkdependHS@-specific options (not between @--@'s):
  85 <descrip>
  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.
  89 <tag>@-f blah@</tag>
  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@.
  94
  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.
  99
 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".)
 108
 109 <tag>@--exclude-module=<file>@</tag>
 110                 Regard @<file>@ as "stable"; i.e., exclude it from having
 111                 dependencies on it.
 112
 113 <tag>@-x@</tag>      same as @--exclude-module@
 114
 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.
 118
 119 <tag>@-Xdirs@</tag>      same as @--exclude-directory@.
 120
 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.
 131 </descrip>
 132
 133
 134 %************************************************************************
 135 %*                                                                      *
 136 <sect1>Emacs `TAGS' for Haskell: @hstags@
 137 <label id="hstags">
 138 <p>
 139 <nidx>hstags</nidx>
 140 <nidx>TAGS for Haskell</nidx>
 141 %*                                                                      *
 142 %************************************************************************
 143
 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.
 147
 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...
 151
 152 GHC comes with a program @hstags@, which build Emacs-able TAGS
 153 files.  The invocation syntax is:
 154 <tscreen><verb>
 155 hstags [GHC-options] file [files...]
 156 </verb></tscreen>
 157
 158 The best thing is just to feed it your GHC command-line flags.
 159 A good Makefile entry might be:
 160 <tscreen><verb>
 161 tags:
 162         $(RM) TAGS
 163         hstags $(GHC_FLAGS) *.lhs
 164 </verb></tscreen>
 165
 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.
 168
 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.
 173
 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@
 177 section...)
 178
 179 %************************************************************************
 180 %*                                                                      *
 181 <sect1>``Yacc for Haskell'': @happy@
 182 <label id="happy">
 183 <p>
 184 <nidx>happy</nidx>
 185 <nidx>Yacc for Haskell</nidx>
 186 <nidx>parser generator for Haskell</nidx>
 187 %*                                                                      *
 188 %************************************************************************
 189
 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.
 193
 194 You can get @happy@ by FTP from @ftp.dcs.gla.ac.uk@ in
 195 @pub/haskell/happy@, the file @happy-1.5-src.tar.gz@.
 196
 197 @Happy@ is at its shining best when compiled by GHC.
 198
 199 %************************************************************************
 200 %*                                                                      *
 201 <sect1>Pretty-printing Haskell: @pphs@
 202 <label id="pphs">
 203 <p>
 204 <nidx>pphs</nidx>
 205 <nidx>pretty-printing Haskell code</nidx>
 206 %*                                                                      *
 207 %************************************************************************
 208
 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.
 215
 216 The code is distributed with GHC in @ghc/CONTRIB/pphs@.