# Building/installing nhc98

### The Brief Version

If you are in a hurry to get started, here's the brief version of the install procedure:

        $ ./configure  [ --prefix=/usr/local ]
        $ make [ all ]
        [ perhaps become root ]
        $ make install

### Upgrading from an earlier version

If you already have an older version of nhc98 installed, you do not need to do anything special when upgrading to a newer version - the newer will overwrite the older.

### System Requirements

Currently, nhc98 assumes a 32-bit processor, or a 32-bit emulation mode on a 64-bit processor. Basically, if your C compiler accepts the -m32 flag, then you will be OK. (If it doesn't, you will see build errors pretty immediately!)

Users of Windows 95/98/SE/Me/NT/2k/XP/Vista/7/etc, please see these special Windows instructions first.

For the binary release, we assume you have a good C compiler (usually gcc), and a sh compatible with the Bourne shell.

If you want to use the graphical debugging tool hood, you will need to have Java on your PATH.

For the source release, you need the usual C compilation management tools (gcc, ar, GNU make, etc.). To build nhc98 without another Haskell compiler, you need at least 16Mb of memory, and about 150Mb of disk space (300Mb if you build for all forms of profiling as well). If you already have another Haskell compiler, ghc-6.6 or later (ensure you have the filepath package), then building nhc98 will require at least 64Mb of memory, and 300Mb of free disk space. If you don't have ghc for your machine, then don't worry, nhc98 will build quite happily using just a C compiler. (The basic build is much faster, but the resulting compiler will be slower.) You can also build nhc98 using an earlier version of nhc98 if you want, but we don't do that by default because the build time can be slow.

### Download it

You have the option of building nhc98 from a source tree, or installing a binary-only distribution. You only need to collect the single package you require.

The current distribution packages can be found at

        http://www.cs.york.ac.uk/fp/nhc98/download.html

Using tar and gunzip, unpack your chosen package, and cd to the base directory (called nhc98-x.xx, where the x's are the version number). Note that all the documentation available on the web is also included in all packages, although the web versions will of course be more up-to-date. Your local copy of the release notes is in docs/status.html.

### Configuration

An automatic configuration utility is supplied, called configure. In brief, the default behaviour is to build under targets in the current directory, and to install various components under /usr/local, in the subdirectories bin, lib/nhc98, include/nhc98, and man/man1. The config script has several useful options to override the default build and installation behaviours. Use the --help option for brief details, and see the page about configuration options for full details.

Important: The config script searches your system for other Haskell compilers. If it guesses wrongly, you can edit the file script/hmake.config to fix things up, then re-run configure. Your changes will not be undone.

### Installing from a binary distribution

Simply run

        ./configure
        make install

to install nhc98. The default location is under /usr/local, but you may alter the installation location using either of the --prefix= or --installdir= options to configure. There are various other configuration options also.

### Building and installing from sources

All object files are created in a separate directory tree from the sources. This means it is possible to build concurrently for different machines from the same shared source tree. You can also build the heap profiling and time profiling versions of the prelude and runtime system concurrently if you wish.

The current distribution of the compiler will build for any machine with 32-bit words. (Sorry, no 64-bit support yet.) All questions of machine endian-ness are handled automatically during configuration. If you are not using gcc as your C compiler, please ensure that your CC environment variable is set appropriately at the configuration stage. (The C compiler is used as a portable backend for nhc98, and is always required.) For instance,

        CC=cc   ./configure --buildwith=...

Run ./configure with any options you require. (You should supply installation directory options at this stage.) This will attempt to detect any existing Haskell compilers and guess which one to build nhc98 with. If you have more than one available, we will choose, in order of preference, ghc, then hbc. If neither of these is found, nhc98 will be built from the bootstrapping C sources included in the package. (You can build nhc98 using an earlier version of nhc98 if you want using the configure options, but it is not selected by default.)

Decide what profiling features you want to use - make help gives a list of useful individual targets, such as basic, heapprofile, and timeprofile.

Then run make with your chosen targets, or make all to build all the possible facilities. (A simple make without targets builds everything.)

The time taken to build nhc98 depends on your machine, operating system, which compiler you are using, and whether you have asked for just the basic libraries or extra profiling libraries. Here are some sample build times:

| ix86 machine: | powerpc machine:
| Linux 500MHz | Linux 2.4GHz | Cygwin 2.4GHz | MacOS X 1.3GHz
--- | --- | --- | --- | ---
build compiler | basic | all | basic | all | basic | all | basic | all
gcc | 9m | 26m | 4m | 12m | 22m | - | 9m | 26m
ghc | 31m | 1h11 | 10m | 26m | 37m | 118m | 23m | -
hbc | - | - | 12m | 27m | - | - | - | -
nhc98 | 50m | 3h33 | 23m | 1h15 | - | - | - | -

Finally, when you have built all the components you require, type make install to copy the components to their final location. (You may need to become root for this step, depending on the final location you selected at configure time.) As an alternative to installing in a system-wide location, it is also possible to use all the nhc98 tools in-place in the build tree by adding the script directory to your PATH - if you wish to conserve disk space by removing temporary intermediate files from the build tree, use make clean.

#### Cross-compiling

Nhc98 can now be built to work as a cross-compiler, using an already present toolchain as backend, that will be remembered by binaries and scripts after installation.

If you ever change your tool chain, you may edit the bin/nhc98 script, whereas you may be better off rebuilding everything.

The cross-compiler mode is activated by the --target flag who takes the name of the target architecture as parameter. This argument is actually free, but you should follow the established convention: naming after the processor-OS-vendor. A good bet is to use whatever prefix your cross-compiler has.

Some other options are mandatory when the target flag is set. Run ./configure --help to know which.

A typical invocation would look like:

`$CC=/usr/local/uclibc-0.9.28-3/arm/bin/arm-linux-gcc STRIP=/usr/local/uclibc-0.9.28-3/arm/bin/arm-linux-strip ./configure --target=arm-linux --endian=-DLOW_BYTE_FIRST --ccoption="-O3" --ldoption="" --cabal-parse=/home/sylvain/bin/nhc98/lib/nhc98/ix86-Linux/cabal-parse --hostcc=gcc --hoststrip=strip --prefix=/home/sylvain/bin/nhc98-arm-linux --installdir=/home/sylvain/bin/nhc98-arm-linux`

`$make`

`$make install`

### Problems?

Ok, so now you should have all the components of a working compiler. If you have any problems, mail `nhc-bugs@haskell.org` with a description (and a bugfix if you have one!).

#### Common gotchas

- You cannot build nhc98 from a directory with spaces in it.
- If you bootstrap from C sources, and the build segfaults, check the output of '`ulimit -s`'. If the user process stacksize is set to 8192 or less, this is the cause. Increase it, either with '`ulimit -s unlimited`', or if that fails, '`ulimit -s hard`'.

### Can you help us?

If you have built nhc98 for a machine not currently listed on the download page and would like to contribute it as a binary package for others to download, it is very easy to do. After building and installing, type `make binDist' before you tidy up with `make clean'. Then upload the resulting tarfile to somewhere we can access it, send an email to let us know about it, and we will copy it to our central download site.

### Keeping up-to-date

If you use nhc98 regularly, please join the nhc-users mailing list for discussion of features, bugfixes, and so on.

The latest updates to these pages are available on the WWW from `http://www.haskell.org/nhc98/`

This page last modified: 27th August 2008
York Functional Programming Group