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:

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.

    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

    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

        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

    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.