2.3. The layout of installed files
Prev | Chapter 2. Installing GHC | Next

## 2.3. The layout of installed files

This section describes what files get installed where. You don't need to know it if you are simply installing GHC, but it is vital information if you are changing the implementation.

GHC is installed in two directory trees:

Library directory,

  known as `$(libdir)`, holds all the support files needed to run GHC. On Unix, this directory is usually something like `/usr/lib/ghc/ghc-5.02`.

Binary directory

  known as `$(bindir)`, holds executables that the user is expected to invoke. Notably, it contains `ghc` and `ghci`. On Unix, this directory can be anywhere, but is typically something like `/usr/local/bin`. On Windows, however, this directory must be `$(libdir)/bin`.

When GHC runs, it must know where its library directory is. It finds this out in one of two ways:

- `$(libdir)` is passed to GHC using the `-B` flag. On Unix (but not Windows), the installed `ghc` is just a one-line shell script that invokes the real GHC, passing a suitable `-B` flag. [All the user-supplied flags follow, and a later `-B` flag overrides an earlier one, so a user-supplied one wins.]

- On Windows (but not Unix), if no `-B` flag is given, GHC uses a system call to find the directory in which the running GHC executable lives, and derives `$(libdir)` from that. [Unix lacks such a system call.] That is why `$(bindir)` must be `$(libdir)/bin`.

### 2.3.1. The binary directory

The binary directory, `$(bindir)`, contains user-visible executables, notably `ghc` and `ghci`. You should add it to your `$PATH`.

On Unix, the user-invokable `ghc` invokes `$(libdir)/ghc-`version``, passing a suitable `-B` flag to tell `ghc-`version`` where `$(libdir)` is. Similarly `ghci`, except the extra flag `--interactive` is passed.

On Win32, the user-invokable `ghc` binary is the Real Thing (no intervening shell scripts or `.bat` files). Reason: we sometimes invoke GHC with very long command lines, and `cmd.exe` (which executes `.bat` files) truncates them. Similarly `ghci` is a C wrapper program that invokes `ghc --interactive` (passing on all other arguments), not a `.bat` file.

### 2.3.2. The library directory

The layout of the library directory, `$(libdir)`, is almost identical on Windows and Unix, as follows. Differences between Windows and Unix are annotated `[Win32 only]` and are commented below.

      $(libdir)/
        package.conf           GHC package configuration
        ghc-usage.txt          Message displayed by ghc ––help
        ghci-usage.txt         Message displayed by ghci ––help

        bin/                   [Win32 only]  User-visible binaries
            ghc.exe
            ghci.exe

        unlit                  Remove literate markup

        touchy.exe             [Win32 only]
        perl.exe               [Win32 only]
        gcc.exe                [Win32 only]

        ghc-x.xx               GHC executable [Unix only]

        ghc-split              Asm code splitter
        ghc-asm                Asm code mangler

        gcc-lib/               [Win32 only] Support files for gcc
            specs              gcc configuration

            cpp0.exe           gcc support binaries
            as.exe
            ld.exe

            crt0.o              Standard
               ..etc..          binaries

            libmingw32.a        Standard
               ..etc..          libraries

            *.h                 Include files

        hslibs-imports/         GHC interface files for the...
            ghc/*.hi            ...'ghc' library

        include/                 C header files
            StgMacros.h           GHC-specific
            ..etc..               header files

            mingw/*.h            [Win32 only] Mingwin header files

        lib/                    GHC's library
            base-2.1
            ..etc..

        libHSrts*.a             GHC RTS archive
        libHSghc.a              GHC package archive

        HSrts.o                 GHC RTS linkable, used by ghci
        HSghc.o                 GHC package linkable, used by ghci

Note that:

- `$(libdir)` also contains support binaries. These are not expected to be on the user's `PATH`, but are invoked directly by GHC. In the Makefile system, this directory is also called `$(libexecdir)`, but you are not free to change it. It must be the same as `$(libdir)`.

- We distribute `gcc` with the Win32 distribution of GHC, so that users don't need to install `gcc`, nor need to care about which version it is. All `gcc`'s support files are kept in `$(libdir)/gcc-lib/`.

- Similarly, we distribute `perl` and a `touch` replacement (`touchy.exe`) with the Win32 distribution of GHC.

- The support programs `ghc-split` and `ghc-asm` are Perl scripts. The first line says `#!/usr/bin/perl`; on Unix, the script is indeed invoked as a shell script, which invokes Perl; on Windows, GHC invokes `$(libdir)/perl.exe` directly, which treats the `#!/usr/bin/perl` as a comment. Reason: on Windows we want to invoke the Perl distributed with GHC, rather than assume some installed one.

Prev | Up | Next
2.2. Installing on Windows | Home | Chapter 3. Using GHCi