The Binding Generator C->Haskell : Installation : Usage of `c2hs`
Previous: I Got Everything, and Now?
Next: Compilation of a Generated Haskell API

## 1.4. Usage of `c2hs`

C->Haskell is implemented by the executable `c2hs`. The simplest form of usage is

> `c2hs` Lib`.chs`

where Lib`.chs` is the Haskell binding module defining the Haskell interface to a C library together with the required marshalling code. If C->Haskell is invoked in this manner, the binding module must contain a cpp `#include` directive to determine the C-side interface of the library. Alternatively, a C header file can be specified on the command line, as in

> `c2hs` lib`.h` Lib`.chs`

However, the latter option is only preserved for backwards compatibility and not recommended. If no errors occur, C->Haskell generates three files: (1) a pure Haskell module Lib`.hs`, which implements the Haskell API of the library, (2) a C header file Lib`.h` which some Haskell systems need to compile the generated Haskell code, and (3) a C->Haskell interface file Lib`.chi` that is used by other binding modules that import Lib`.hs` using an import hook (see the section on import hooks for details).

The executable `c2hs` has a couple more options:

> `

>     Usage: c2hs [ option... ] [header-file] binding-file

>       -C CPPOPTS   --cppopts=CPPOPTS    pass CPPOPTS to the C preprocessor
>       -c CPP       --cpp=CPP            use executable CPP to invoke C preprocessor
>                    --data=DIR           data directory (set by wrapper script)
>       -d TYPE      --dump=TYPE          dump internal information (for debugging)
>       -h, -?       --help               brief help (the present message)
>       -i INCLUDE   --include=INCLUDE    include paths for .chi files
>       -k           --keep               keep pre-processed C header
>       -l           --copy-library       copy `C2HS' library module in
>       -o FILE      --output=FILE        output result to FILE (should end in .hs)
>       -p PLATFORM  --platform=PLATFORM  platform to use for cross compilation
>       -t PATH      --output-dir=PATH    place generated files in PATH
>       -v           --version            show version information

>     The header file must be a C header file matching the given binding file.
>     The dump TYPE can be
>       trace   -- trace compiler phases
>       genbind -- trace binding generation
>       ctrav   -- trace C declaration traversal
>       chs     -- dump the binding file (adds `.dump' to the name)
>     PLATFORM can be i686-pc-linux-gnu, m68k-palmos

> `

The most useful of these is probably `--cppopts=` (or `-C`). If the C header file needs any special options (like `-D` or `-I`) to go through the C pre-processor, here is the place to pass them. A call may look like this:

> `c2hs --cppopts='-I/some/obscure/dir -DEXTRA'` Lib`.chs`

Do not forget the quotes if you have more than one option that you want to pass to the pre-processor.

Often, lib`.h` will not be in the current directory, but in one of the header file directories. C->Haskell leaves locating the header file to the standard C preprocessor, which usually looks in two places for the header: first, in the standard include directory of the used system, this is usually `/usr/include` and `/usr/local/include`; and second, it will look in every directory that is mentioned in a `-IDIR` option passed to the pre-processor via `--cppopts`.

If the compiled binding module contains import hooks, C->Haskell needs to find the `.chi` (C->Haskell interface files) produced while compiling the corresponding binding modules. By default, they will be searched for in the current working directory. If they are located elsewhere, the `--include=INCLUDE` option has to be used to indicate the location, where `INCLUDE` is a colon-separated list of directories. Multiple such options are admissible. Paths specified later are searched first.

The Binding Generator C->Haskell : Installation : Usage of `c2hs`
Previous: I Got Everything, and Now?
Next: Compilation of a Generated Haskell API