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 win32.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):

    make EXTRA_CONFIGURE_OPTS=--prefix=$HOME
    make clean
    $HOME/bin/hugs $HOME/lib/hugs/demos/Say
    putStr (say "  /Hugs")
    :quit


Long version:

 1) 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.

 2) Build Hugs and the libraries

        cd hugs98
        make EXTRA_CONFIGURE_OPTS=--exec-prefix=/usr/local/solaris

    This starts by running the configure script, which 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
        libraries/Makefile    -- controls conversion of libraries

    plus some others related to documentation, testing and examples.

    EXTRA_CONFIGURE_OPTS can contain any number of options to the
    configure script.  You can omit it if there are none.
    Read config.txt to find out about general configuration options.
    Hugs-specific options are listed at the end of this file.

    It then builds the executables, calls the shell script
    libraries/tools/make_bootlib to generate a subset of the libraries
    in libraries/bootlib, and then calls another shell script
    libraries/tools/convert_libraries to convert the Haskell library
    packages under packages into libraries under hugsdir for use by
    Hugs, using the Cabal library (from the bootlib just created).
    (libraries/hugsbase/Hugs contains Hugs-specific modules that are
    also copied into hugsdir.)

    If all that worked, you should now have a working Hugs system,
    runnable in-place.  Even if a few of the libraries had error, you
    should still have a runnable system.  At this point, you might like
    to run a few tests to make sure everything's working:

        HUGSDIR=hugsdir src/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
    "cd libraries; make LibStatus", which creates a file LibStatus
    giving the status of each module in packages -- 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-char-encoding
 --enable-char-encoding=locale
 --enable-char-encoding=utf8

   Use a byte encoding of Chars for I/O and other system calls (as well
   as Haskell source):
     locale (or no argument): the encoding is determined by the LC_CTYPE
	category of the current locale.  Note that the encodings in some
	locales cannot represent all Unicode characters.
     utf8: the UTF-8 encoding (which covers all of Char) is always used.
	Note that this option also disables readline, so the locale-based
	option with a UTF-8 locale may be preferable if you have recent
	enough libraries.
   You can usually omit this option, in which case locale will be used
   if it is available on your system.

   You will then need to run Hugs in an environment that supports your
   chosen encoding.  For example (with the appropriate locale settings):
	UTF-8 works with glibc 2.2, xterm 4.0, bash 2.05b and readline 4.3
	EUC multi-byte charsets work with multilingual wterm or rxvt
	Single-byte charsets work in most environments
	Single- and multi-byte charsets work under Win32.  (The locale
	used is the "user-default ANSI code page", which may be set
	using the "Regional Options" tab of the regional and language
	control panel.)

 --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 Hugs.Internals

 --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.

There used to be a --with-preprocessor option, enabling the use of a
preprocessor for processing Haskell source files before compiling them
with Hugs.  It's turned on by default at the moment.  To turn it off,
change USE_PREPROCESSOR in src/options.h.

   This is an experimental feature and may change in future versions.

   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.
