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 It is reasonably straightforward to set up a \tr{Makefile} to use with
  21 GHC, assuming you name your source files the same as your modules.
  22 Thus:
  23 \begin{verbatim}
  24 HC      = ghc
  25 HCFLAGS = -recomp -cpp -hi-diffs $(EXTRA_HC_OPTS)
  26
  27 SRCS = Main.lhs Foo.lhs Bar.lhs
  28 OBJS = Main.o   Foo.o   Bar.o
  29
  30 .SUFFIXES : .o .hi .lhs
  31 .o.hi:
  32         @:
  33 .lhs.o:
  34         $(RM) $@
  35         $(HC) -c $< $(HCFLAGS)
  36
  37 cool_pgm : $(OBJS)
  38         $(RM) $@
  39         $(HC) -o $@ $(HCFLAGS) $(OBJS)
  40 \end{verbatim}
  41
  42 Note the cheesy \tr{.o.hi} rule: It records the dependency of the
  43 interface (\tr{.hi}) file on the source.  The rule says a \tr{.hi}
  44 file can be made from a \tr{.o} file by doing... nothing.  Which is
  45 true.
  46
  47 (Sophisticated \tr{make} variants may achieve some of the above more
  48 elegantly.  What we've shown should work with any \tr{make}.)
  49
  50 The only thing lacking in the above \tr{Makefile} is interface-file
  51 dependencies.  If \tr{Foo.lhs} imports module \tr{Bar} and the
  52 \tr{Bar} interface changes, then \tr{Foo.lhs} needs to be recompiled.
  53
  54 Putting dependencies of the form \tr{Foo.o : Bar.hi} into your
  55 \tr{Makefile} by hand is rather error-prone.  Don't worry---never
  56 fear, \tr{mkdependHS} is here! (and is distributed as part of GHC)
  57 Add the following to your \tr{Makefile}:
  58 \begin{verbatim}
  59 depend :
  60         mkdependHS -- $(HCFLAGS) -- $(SRCS)
  61 \end{verbatim}
  62
  63 Now, before you start compiling, and any time you change the
  64 \tr{imports} in your program, do \tr{make depend} before you do
  65 \tr{make cool_pgm}.  \tr{mkdependHS} will append the needed
  66 dependencies to your \tr{Makefile}.
  67
  68 Please note the use of the recompilation checker (the \tr{-recomp}
  69 \index{-recomp option} flag).  Without it, your dependencies will be
  70 {\em inadequate} to cope with the Haskell~1.3 module system!  See
  71 \sectionref{recomp} for more details about the recompilation checker!
  72
  73 A few caveats about this simple scheme: (a)~You may need to compile
  74 some modules explicitly to create their interfaces in the first place
  75 (e.g., \tr{make Bar.o} to create \tr{Bar.hi}).  (b)~You may have to
  76 type \tr{make} more than once for the dependencies to have full
  77 effect.  However, a \tr{make} run that does nothing {\em does} mean
  78 ``everything's up-to-date.''  (c) This scheme will work with
  79 mutually-recursive modules but, again, it may take multiple
  80 iterations to ``settle.''
  81
  82 To see \tr{mkdependHS}'s command-line flags, give it a duff flag,
  83 e.g., \tr{mkdependHS -help}.
  84
  85 %************************************************************************
  86 %*                                                                      *
  87 \subsection[hstags]{Emacs `TAGS' for Haskell: \tr{hstags}}
  88 \index{hstags}
  89 \index{TAGS for Haskell}
  90 %*                                                                      *
  91 %************************************************************************
  92
  93 NB: \tr{hstags} is temporarily dead at version~2.01.  Sigh.
  94
  95 `Tags' is a facility for indexing the definitions of
  96 programming-language things in a multi-file program, and then using
  97 that index to jump around among these definitions.
  98
  99 Rather than scratch your head, saying ``Now where did we define
 100 `foo'?'', you just do (in Emacs) \tr{M-. foo RET}, and You're There!
 101 Some people go wild over this stuff...
 102
 103 GHC comes with a program \tr{hstags}, which build Emacs-able TAGS
 104 files.  The invocation syntax is:
 105 \begin{verbatim}
 106 hstags [GHC-options] file [files...]
 107 \end{verbatim}
 108
 109 The best thing is just to feed it your GHC command-line flags.
 110 A good Makefile entry might be:
 111 \begin{verbatim}
 112 tags:
 113         $(RM) TAGS
 114         hstags $(GHC_FLAGS) *.lhs
 115 \end{verbatim}
 116
 117 The only flags of its own are: \tr{-v} to be verbose; \tr{-a} to
 118 **APPEND** to the TAGS file, rather than write to it.
 119
 120 Shortcomings: (1)~Instance declarations don't get into the TAGS file
 121 (but the definitions inside them do); as instances aren't named, this
 122 is probably just as well.  (2)~Data-constructor definitions don't get
 123 in.  Go for the corresponding type constructor instead.
 124
 125 (Actually, GHC also comes with \tr{etags} [for C], and \tr{perltags}
 126 [for You Know What].  And---I cannot tell a lie---there is Denis
 127 Howe's \tr{fptags} [for Haskell, etc.] in the \tr{ghc/CONTRIB}
 128 section...)
 129
 130 %************************************************************************
 131 %*                                                                      *
 132 \subsection[happy]{``Yacc for Haskell'': \tr{happy}}
 133 \index{happy}
 134 \index{Yacc for Haskell}
 135 \index{parser generator for Haskell}
 136 %*                                                                      *
 137 %************************************************************************
 138
 139 Andy Gill and Simon Marlow have written a parser-generator for
 140 Haskell, called \tr{happy}.\index{happy parser generator} \tr{Happy}
 141 is to Haskell what \tr{Yacc} is to C.
 142
 143 You can get \tr{happy} by FTP from \tr{ftp.dcs.gla.ac.uk} in
 144 \tr{pub/haskell/happy}, the file \tr{happy-0.8.tar.gz}.
 145
 146 \tr{Happy} is at its shining best when compiled by GHC.
 147
 148 %************************************************************************
 149 %*                                                                      *
 150 \subsection[pphs]{Pretty-printing Haskell: \tr{pphs}}
 151 \index{pphs}
 152 \index{pretty-printing Haskell code}
 153 %*                                                                      *
 154 %************************************************************************
 155
 156 Andrew Preece has written
 157 \tr{pphs},\index{pphs}\index{pretty-printing Haskell}
 158 a utility to pretty-print Haskell code in LaTeX documents.
 159 Keywords in bolds, variables in italics---that sort of thing.  It is
 160 good at lining up program clauses and equals signs, things that are
 161 very tiresome to do by hand.
 162
 163 The code is distributed with GHC in \tr{ghc/CONTRIB/pphs}.