How to compile HDoc
===================


The instructions are for *nix systems or Windows with GHC or NHC98 on
Cygwin; I have tested HDoc on Linux, Solaris and Windows.

BTW, "make" stands for GNU make.



Requirements
~~~~~~~~~~~~

To compile HDoc, you need
      ghc   >= 5.00,
  or  ghc   >= 4.06  +  hmake,
  or  nhc98 >= 1.06  +  hamke.

To (re-)generate the scanner/parsers, you need Alex and Happy (see below),
but their output files are included in the distribution, so you don't need
them to compile/run HDoc. ThePrelude.hs is generated form the files
under stdlibs/ by the shell script makePrelLibs.sh which requires awk.



Compiling with GHC or NHC98
~~~~~~~~~~~~~~~~~~~~~~~~~~~

After unpacking the sources, simply do

  $ ./configure
  $ make

You'll get the executable "hdoc". It will run independently from the
sources, so you can copy it anywhere you like.

If make tries to run Alex or Happy (and you don't have it), try
"touch Scanner.hs Parser.hs hsparser/HsParser.hs" so that these files
get newer time stamps than their sources.

The configure script should detect ghc, nhc98, and hmake
automatically. If it doesn't, you can give the following configure
options:
  --with-ghc=GHC             where to find ghc
  --with-ghcflags=FLAGS      flags for ghc
  --with-nhc98=NHC98         where to find nhc98
  --with-nhc98flags=FLAGS    flags for nhc98
  --with-hmake=HMAKE         where to find hmake
  --with-compiler=ghc|nhc98  use ghc or nhc98 to build HDoc

If configure finds ghc and nhc98, then it will default to using ghc to
build HDoc if you don't select a compiler by "--with-compiler=ghc" or
"--with-compiler=nhc98".
N.B.: The argument of "--with-compiler" is not the path to the
compiler but either the string "ghc" or the string "nhc98" (paths can
be given with "--with-ghc" and "--with-nhc98", respectively).


After compiling you can install HDoc with

  $ make install

If you want, you can clean up with

  $ make clean

to delete the object files, and

  $ make distclean

to remove the files generated by configure, too.

To make HDoc's directory very clean, do

  $ make realclean

Note that "make realclean" deletes the Haskell sources for the scanner
and the parsers (see below).



Running HDoc with Hugs98
~~~~~~~~~~~~~~~~~~~~~~~~

!! Note:
   As of HDoc 0.8.0 you *cannot* run HDoc on a standard installation of
   Hugs due to fixed limits built into Hugs; you have to apply a source
   patch and re-compile Hugs. The file patches/hugs-storage.diff contains
   the required patch against the Feb2001 version.

The shell script "hdoc-hugs.sh" will run HDoc from the sources; if you want
to put the script in a directory different from the distribution
directory, you'll have to edit the "HDOCDIR=..." line, so that $HDOCDIR
points to HDoc's directory.

Note: If the current directory contains files that have the same name
      as one of HDoc's source files, Hugs will confuse these files
      with HDoc's files; for example if you have a file Scanner.hs
      and want to run it through HDoc with

      $ /where/you/have/it/hdoc-hugs.sh Scanner.hs
      
      then Hugs will confuse your Scanner.hs with HDoc's Scanner.hs
      (which gives funny results, of course).

HDoc runs *really* slowly on Hugs, so compiling HDoc is recommended.



Regenerating the scanner, the parsers, and ThePrelude.hs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The HDoc distribution comes with pre-generated files included, that is
the files Scanner.hs (generated from Scanner.x), Parser.hs (from
Parser.y), hsparser/HsParser.hs (from hsparser/HsParser.ly), and
ThePrelude.hs (from stdlibs/*.in) are ready for use.

If you do a "make distclean", these files will be deleted and you need
Alex, Happy, and sh+awk to re-generate them (after running configure
again). "make realclean" will also delete the configure script, so
autoconf is required then.

Running "make clean" or "make distclean" is safe, i.e. it does not
delete the generated files.

Running "make gen" will generate the Haskell source files.

I've written a patch for Alex 1.1 which implements DFA minimization
and a trick with the "read" function (to make GHC compile the Scanner
*much* fast and less heap intensive), see
patches/alex-minimize+read-hack.diff. The file Scanner.hs included in
the HDoc distribution is generated with a patched Alex, so if you
re-generate Scanner.hs with an unmodified Alex the heap settings (set
by the configure script) may be too low to compile Scanner.hs on GHC.