4.5. Modes of operation
Prev | Chapter 4. Using GHC | Next

## 4.5. Modes of operation

GHC's behaviour is firstly controlled by a mode flag. Only one of these flags may be given, but it does not necessarily need to be the first option on the command-line.

If no mode flag is present, then GHC will enter make mode (Section 4.5.1, “Using ghc `--make`”) if there are any Haskell source files given on the command line, or else it will link the objects named on the command line to produce an executable.

The available mode flags are:

`ghc --interactive`

  Interactive mode, which is also available as ghci. Interactive mode is described in more detail in Chapter 2, Using GHCi.

`ghc --make`

  In this mode, GHC will build a multi-module Haskell program automatically, figuring out dependencies for itself. If you have a straightforward Haskell program, this is likely to be much easier, and faster, than using make. Make mode is described in Section 4.5.1, “Using ghc `--make`”.

  This mode is the default if there are any Haskell source files mentioned on the command line, and in this case the `--make` option can be omitted.

`ghc -e` `expr`

  Expression-evaluation mode. This is very similar to interactive mode, except that there is a single expression to evaluate (`expr`) which is given on the command line. See Section 4.5.2, “Expression evaluation mode” for more details.

`ghc -E`
`ghc -C`
`ghc -S`
`ghc -c`

  This is the traditional batch-compiler mode, in which GHC can compile source files one at a time, or link objects together into an executable. See Section 4.5.3, “Batch compiler mode”.

`ghc -M`

  Dependency-generation mode. In this mode, GHC can be used to generate dependency information suitable for use in a `Makefile`. See Section 4.7.12, “Dependency generation”.

`ghc --mk-dll`

  DLL-creation mode (Windows only). See Section 12.6.1, “Creating a DLL”.

`ghc --help`
`ghc -?`

  Cause GHC to spew a long usage message to standard output and then exit.

`ghc --show-iface `file``

  Read the interface in `file` and dump it as text to `stdout`. For example `ghc --show-iface M.hi`.

`ghc --supported-extensions`
`ghc --supported-languages`

  Print the supported language extensions.

`ghc --show-options`

  Print the supported command line options. This flag can be used for autocompletion in a shell.

`ghc --info`

  Print information about the compiler.

`ghc --version`
`ghc -V`

  Print a one-line string including GHC's version number.

`ghc --numeric-version`

  Print GHC's numeric version number only.

`ghc --print-libdir`

  Print the path to GHC's library directory. This is the top of the directory tree containing GHC's libraries, interfaces, and include files (usually something like `/usr/local/lib/ghc-5.04` on Unix). This is the value of `$libdir` in the package configuration file (see Section 4.9, “ Packages ”).

### 4.5.1. Using ghc `--make`

In this mode, GHC will build a multi-module Haskell program by following dependencies from one or more root modules (usually just `Main`). For example, if your `Main` module is in a file called `Main.hs`, you could compile and link the program like this:

    ghc --make Main.hs

In fact, GHC enters make mode automatically if there are any Haskell source files on the command line and no other mode is specified, so in this case we could just type

    ghc Main.hs

Any number of source file names or module names may be specified; GHC will figure out all the modules in the program by following the imports from these initial modules. It will then attempt to compile each module which is out of date, and finally, if there is a `Main` module, the program will also be linked into an executable.

The main advantages to using `ghc --make` over traditional `Makefile`s are:

- GHC doesn't have to be restarted for each compilation, which means it can cache information between compilations. Compiling a multi-module program with `ghc --make` can be up to twice as fast as running `ghc` individually on each source file.

- You don't have to write a `Makefile`.

- GHC re-calculates the dependencies each time it is invoked, so the dependencies never get out of sync with the source.

- Using the `-j` flag, you can compile modules in parallel. Specify `-jN` to compile `N` jobs in parallel.

Any of the command-line options described in the rest of this chapter can be used with `--make`, but note that any options you give on the command line will apply to all the source files compiled, so if you want any options to apply to a single source file only, you'll need to use an `OPTIONS_GHC` pragma (see Section 4.2.2, “Command line options in source files”).

If the program needs to be linked with additional objects (say, some auxiliary C code), then the object files can be given on the command line and GHC will include them when linking the executable.

For backward compatibility with existing make scripts, when used in combination with `-c`, the linking phase is omitted (same as `--make` `-no-link`).

Note that GHC can only follow dependencies if it has the source file available, so if your program includes a module for which there is no source file, even if you have an object and an interface file for the module, then GHC will complain. The exception to this rule is for package modules, which may or may not have source files.

The source files for the program don't all need to be in the same directory; the `-i` option can be used to add directories to the search path (see Section 4.7.3, “The search path”).

### 4.5.2. Expression evaluation mode

This mode is very similar to interactive mode, except that there is a single expression to evaluate which is specified on the command line as an argument to the `-e` option:

    ghc -e expr

Haskell source files may be named on the command line, and they will be loaded exactly as in interactive mode. The expression is evaluated in the context of the loaded modules.

For example, to load and run a Haskell program containing a module `Main`, we might say

    ghc -e Main.main Main.hs

or we can just use this mode to evaluate expressions in the context of the `Prelude`:

    $ ghc -e "interact (unlines.map reverse.lines)"
    hello
    olleh

### 4.5.3. Batch compiler mode

In batch mode, GHC will compile one or more source files given on the command line.

The first phase to run is determined by each input-file suffix, and the last phase is determined by a flag. If no relevant flag is present, then go all the way through to linking. This table summarises:

Phase of the compilation system | Suffix saying “start here” | Flag saying “stop after” | (suffix of) output file
--- | --- | --- | ---
literate pre-processor | `.lhs` | - | `.hs`
C pre-processor (opt.) | `.hs` (with `-cpp`) | `-E` | `.hspp`
Haskell compiler | `.hs` | `-C`, `-S` | `.hc`, `.s`
C compiler (opt.) | `.hc` or `.c` | `-S` | `.s`
assembler | `.s` | `-c` | `.o`
linker | `other` | - | `a.out`

Thus, a common invocation would be:

    ghc -c Foo.hs

to compile the Haskell source file `Foo.hs` to an object file `Foo.o`.

Note: What the Haskell compiler proper produces depends on what backend code generator is used. See Section 4.11, “GHC Backends” for more details.

Note: C pre-processing is optional, the `-cpp` flag turns it on. See Section 4.12.3, “Options affecting the C pre-processor” for more details.

Note: The option `-E` runs just the pre-processing passes of the compiler, dumping the result in a file.

Note: The option `-C` is only available when GHC is built in unregisterised mode. See Section 4.11.4, “Unregisterised compilation” for more details.

#### 4.5.3.1. Overriding the default behaviour for a file

As described above, the way in which a file is processed by GHC depends on its suffix. This behaviour can be overridden using the `-x` option:

`-x` `suffix`

  Causes all files following this option on the command line to be processed as if they had the suffix `suffix`. For example, to compile a Haskell module in the file `M.my-hs`, use `ghc -c -x hs M.my-hs`.

Prev | Up | Next
4.4. Meaningful file suffixes | Home | 4.6. Verbosity options