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[@-f blah@]
  85         Use @blah@ as the makefile, rather than @makefile@
  86         or @Makefile@.  If @blah@ doesn't exist, @mkdependHS@ creates it.
  87         We often use @-f .depend@ to put the dependencies in @.depend@ and
  88         then @include@ the file @.depend@ into @Makefilpe@.
  89
  90 \item[@-o <osuf>@]
  91         Use @.<osuf>@ as the "target file" suffix ( default: @o@).
  92         Multiple @-o@ flags are permitted (GHC2.05 onwards).  Thus "@-o hc -o o@"
  93         will generate dependencies for @.hc@ and @.o@ files.
  94
  95 \item[@-s <suf>@]
  96                 Make extra dependencies that declare that files with
  97                 suffix @.<suf>_<osuf>@ depend on interface files with suffix @.<suf>_hi@, or
  98                 (for @{-# SOURCE #-}@ imports) on @.hi-boot@.
  99                 Multiple @-s@ flags are permitted.
 100                 For example, "@-o hc -s a -s b@" will
 101                 make dependencies for @.hc@ on @.hi@, @.a_hc@ on @.a_hi@, and @.b_hc@ on @.b_hi@.
 102                 (Useful in conjunction with NoFib "ways".)
 103
 104 \item[@--exclude-module=<file>@]
 105                 Regard @<file>@ as "stable"; i.e., exclude it from having
 106                 dependencies on it.
 107
 108 \item[@-x@]      same as @--exclude-module@
 109
 110 \item[@--exclude-directory=<dirs>@]
 111                 Regard the colon-separated list of directories @<dirs>@ as containing stable,
 112                 don't generate any dependencies on modules therein.
 113
 114 \item[@-Xdirs@]      same as @--exclude-directory@.
 115
 116 \item[@--include-module=<file>@]
 117                 Regard @<file>@ as not "stable"; i.e., generate dependencies
 118                 on it (if any). This option is normally used in conjunction
 119                 with the @--exclude-directory@ option.
 120 \end{description}
 121
 122
 123 %************************************************************************
 124 %*                                                                      *
 125 \subsection[hstags]{Emacs `TAGS' for Haskell: \tr{hstags}}
 126 \index{hstags}
 127 \index{TAGS for Haskell}
 128 %*                                                                      *
 129 %************************************************************************
 130
 131 `Tags' is a facility for indexing the definitions of
 132 programming-language things in a multi-file program, and then using
 133 that index to jump around among these definitions.
 134
 135 Rather than scratch your head, saying ``Now where did we define
 136 `foo'?'', you just do (in Emacs) \tr{M-. foo RET}, and You're There!
 137 Some people go wild over this stuff...
 138
 139 GHC comes with a program \tr{hstags}, which build Emacs-able TAGS
 140 files.  The invocation syntax is:
 141 \begin{verbatim}
 142 hstags [GHC-options] file [files...]
 143 \end{verbatim}
 144
 145 The best thing is just to feed it your GHC command-line flags.
 146 A good Makefile entry might be:
 147 \begin{verbatim}
 148 tags:
 149         $(RM) TAGS
 150         hstags $(GHC_FLAGS) *.lhs
 151 \end{verbatim}
 152
 153 The only flags of its own are: \tr{-v} to be verbose; \tr{-a} to
 154 **APPEND** to the TAGS file, rather than write to it.
 155
 156 Shortcomings: (1)~Instance declarations don't get into the TAGS file
 157 (but the definitions inside them do); as instances aren't named, this
 158 is probably just as well.  (2)~Data-constructor definitions don't get
 159 in.  Go for the corresponding type constructor instead.
 160
 161 (Actually, GHC also comes with \tr{etags} [for C], and \tr{perltags}
 162 [for You Know What].  And---I cannot tell a lie---there is Denis
 163 Howe's \tr{fptags} [for Haskell, etc.] in the \tr{ghc/CONTRIB}
 164 section...)
 165
 166 %************************************************************************
 167 %*                                                                      *
 168 \subsection[happy]{``Yacc for Haskell'': \tr{happy}}
 169 \index{happy}
 170 \index{Yacc for Haskell}
 171 \index{parser generator for Haskell}
 172 %*                                                                      *
 173 %************************************************************************
 174
 175 Andy Gill and Simon Marlow have written a parser-generator for
 176 Haskell, called \tr{happy}.\index{happy parser generator} \tr{Happy}
 177 is to Haskell what \tr{Yacc} is to C.
 178
 179 You can get \tr{happy} by FTP from \tr{ftp.dcs.gla.ac.uk} in
 180 \tr{pub/haskell/happy}, the file \tr{happy-0.8.tar.gz}.
 181
 182 \tr{Happy} is at its shining best when compiled by GHC.
 183
 184 %************************************************************************
 185 %*                                                                      *
 186 \subsection[pphs]{Pretty-printing Haskell: \tr{pphs}}
 187 \index{pphs}
 188 \index{pretty-printing Haskell code}
 189 %*                                                                      *
 190 %************************************************************************
 191
 192 Andrew Preece has written
 193 \tr{pphs},\index{pphs}\index{pretty-printing Haskell}
 194 a utility to pretty-print Haskell code in LaTeX documents.
 195 Keywords in bolds, variables in italics---that sort of thing.  It is
 196 good at lining up program clauses and equals signs, things that are
 197 very tiresome to do by hand.
 198
 199 The code is distributed with GHC in \tr{ghc/CONTRIB/pphs}.