ghc/docs/users_guide/utils.lit

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