Building and Installing Hugs from Source
========================================

The following procedure is suggested for installation of Hugs on a Unix
machine (including Linux, *BSD and MacOS X).  For other systems:

    Windows:
        Precompiled binaries are provided, although similar installation
        procedures can be used for these machines if you have a Unix-like
        environment installed: see docs/win32-notes.txt for details.

    Systems without a Unix-like environment:
        These will be more difficult.  You'll have to construct the
        files generated by configure (see below; those in the src/msc
        directory may be a useful starting point) and you'll need to
        convert the libraries.  That will probably have to be done in
        a Unix-like environment.  You should be able to get help on the
        hugs-users mailing list.

Short version (for Unix-like environments):

    cd src/unix
    ./configure --prefix=$HOME
    cd ..
    make install
    make clean
    $HOME/bin/hugs $HOME/lib/hugs/demos/Say
    putStr (say "  /Hugs")
    :quit


Long version:

 0) Choose a directory (or directories) for the Hugs files to go in.
    In the following, we'll assume:

    /usr/local/solaris/bin             user executables
    /usr/local/solaris/lib/hugs        architecture dependent files
    /usr/local/lib/hugs                architecture independent files

    Check that these directories have appropriate permission settings.

 1) Run the configure script:

        cd hugs98/src/unix
        ./configure --exec-prefix=/usr/local/solaris

    This runs many small tests on the compiler, preprocessor, linker,
    etc to determine how your system is configured.  It combines this
    with any configuration flags to generate these files:

        src/Makefile          -- used to control compilation
        src/config.h          -- #included into every C file in Hugs
        src/options.h         -- #included into every C file in Hugs
        src/unix/hugs-package -- script to convert library packages for Hugs

    plus some others related to documentation and testing.

    Read Hugs98/src/unix/INSTALL to find out about general configuration
    options.  Hugs-specific options are listed at the end of this file.

 2) Build Hugs and the libraries

    This step builds the executables, calls the shell script
    src/unix/convert_libraries to convert the Haskell library
    packages under fptools into libraries under hugsdir for use by
    Hugs, and then runs ffihugs to compile modules that use the ffi.
    (libraries/Hugs contains Hugs-specific modules that are also
    copied into hugsdir.)

        cd ..
        make

    You should now have a working Hugs system, runnable in-place.
    At this point, you might like to run a few tests to make sure
    everything's working:

        HUGSDIR=../hugsdir ./hugs
        -- Run a few tests like 1+2, [1..], etc.  Use ":quit" to exit

    Regression tests are run by "make check".  You can also run
    "make LibStatus", which creates a file LibStatus giving the
    status of each module in fptools/libraries -- none of them
    should be ERROR.

 3) Install Hugs in chosen directories

      make install

    (Note that the permissions of the installed files will be affected by
    your "umask" setting.  If you want the installed files to be world
    readable, you need to set umask accordingly.)

    Try a few simple tests:

      /usr/local/solaris/bin/hugs
      [1..10]
      :quit

      cat > echo <<EOF
      #! /usr/local/solaris/bin/runhugs +l

      > module Main(main) where
      > import System(getArgs)
      >
      > main = do { args <- getArgs; putStrLn (unwords args) }
      EOF
      chmod 755 echo
      ./echo Hello World

    Administrators of sites with multiple architectures often prefer to
    install a shell script in /usr/local/bin which will select an
    appropriate binary according to the architecture on which it is
    run rather than a binary.  Configuration should be the same as above
    (use a different --bindir argument for each architecture but, if
    you want, save a small amount of space by using the same --datadir)
    and use a shell script like the following.

      #! /bin/sh

      HW_OS=${HW_OS-`/usr/local/gnu/bin/hw_os`}
      BINDIR=/local/lib/Hugs1.4/$HW_OS
      exec $BINDIR/hugs $*

    This kind of script would also be a good place to set system-wide
    default options (eg to select an editor or to switch on the
    "show types" option).

 4) Cleanup after yourself

    You can now run "make clean" to delete all machine-generated files.
    If you ran "make install", you could delete the entire Hugs source
    tree - but you might want to keep the Hugs98/doc directory.

Hugs specific configuration options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 --enable-ffi / --disable-ffi

   Provide (or not) libraries that use the Foreign Function Interface.
   By default, this is enabled for systems that support dynamic linking,
   so you don't usually need to use this option.  Such systems should
   support static imports; "wrapper" and "dynamic" imports are also
   supported on most common architectures.

 --enable-hopengl

   Provide the HOpenGL libraries, a Haskell binding for OpenGL/GLUT.
   You will need to have the OpenGL/GLUT libraries and header files
   installed for this to work.  On Mac OS X, if you want to use X11
   instead of the "native" libraries, use --enable-hopengl=x11

 --with-pthreads

   Build Hugs with the multi-threaded version of the C library.
   This is needed, for example, if you are linking to a Java virtual
   machine (which is multi-threaded).

 --enable-timer

   Time how long each evaluation takes.

   Timing is included for the purpose of benchmarking the Hugs interpreter,
   comparing its performance across a variety of different machines, and
   with other systems for similar languages.

   It would be somewhat foolish to try to use the timings produced in this
   way for any other purpose.  In particular, using timings to compare the
   performance of different versions of an algorithm is likely to give very
   misleading results.  The current implementation of Hugs as an interpreter,
   without any significant optimizations, means that there are much more
   significant overheads than can be accounted for by small variations in
   Hugs code.

 --enable-profiling

   Gather statistics about heap allocation during evaluation.
   Statistics are written to a file profile.hp which may be viewed
   using the hp2ps program.

   This option makes Hugs use much more memory and run much slower.
   The ":set -d" command can be used to reduce the time overhead by
   controlling the frequency with which statistics are gathered.

 --with-nmake

   Try to generate a Makefile that will work with Microsoft's nmake.

 --disable-large-banner

   Print a single-line startup banner instead of the 9 line banner.
   (This option will cause the "make check" regression tests to fail.)

 --with-gui

   Used when generating Hugs for Windows.  Only works with Borland C++

 --enable-internal-prims

   Enable experimental features used in Hugs98/lib/hugs/HugsInternals.hs

 --enable-stack-dumps

   Enable printing of the top and bottom few objects on the stack when
   stack overflow happens.  This feature is currently (Sept'97) just a
   proof of concept.  We welcome suggestions (and/or code) to make it
   useful for people who don't have an intimate knowledge of how the
   G machine operates.

 --enable-debug
 --enable-tag-checks
 --enable-lint

   For use when debugging Hugs.

 --with-preprocessor

   This is an experimental feature and may change in future versions.
   (It's turned on by default at the moment.)

   Enable the use of a preprocessor for processing Haskell source files
   before compiling them with Hugs.  When configured with preprocessing
   on, you can use the "-F" option to specify which preprocessor to use.
   For example, if your preprocessor is in /users/JFH/bin/hscpp, you might
   say

     :set -F"/users/JFH/bin/hscpp"

   If you have perl and gcc installed on your machine, the following
   script provides a simple cpp-like preprocessor.

     eval "exec perl -S $0 $*"
	  if $running_under_some_random_shell;
     #
     # Reads CPP output and turns #line things into appropriate Haskell
     # pragmas.  This program is derived from the "hscpp" script
     # distributed with the Glasgow Haskell Compiler.
     #
     $Cpp = 'gcc -E -xc -traditional';
     open(INPIPE, "$Cpp @ARGV |") || die "Can't open C pre-processor pipe\n";
     while (<INPIPE>) {
     # line directives come in flavo[u]rs:
     #   s/^#\s*line\s+\d+$/\{\-# LINE \-\}/;   IGNORE THIS ONE FOR NOW
	 s/^#\s*line\s+(\d+)\s+(\".+\")$/\{\-# LINE \1 \2 \-\}/;
	 s/^#\s*(\d+)\s+(\".*\").*/\{\-# LINE \1 \2 \-\}/;
	 print $_;
     }
     close(INPIPE) || exit(1); # exit is so we reflect any errors.
     exit(0);

   Note that Hugs currently ignores the {-# LINE _ _ #-} pragmas so error
   messages will refer to the wrong line numbers.