1. Installation

It follows a brief discussion of the installation from source. There is, however, a file INSTALL in the source distribution, which is more frequently updated and should be consulted in any case.

1.1 Where is the Source?

The master site of C->Haskell is at http://www.cse.unsw.edu.au/~chak/haskell/c2hs/. It has all the latest information and sources. Furthermore, it explains how to get access to the C->Haskell Darcs repository and has references to pre-compiled binaries.

1.2 What Else Do I Need?

You need a Haskell system supported by C->Haskell. Currently, this is only the Glasgow Haskell Compiler (GHC), which you can obtain from http://haskell.org/ghc/. Furthermore, you need the Haskell package system Cabal. See the INSTALL file for details on supported versions.

To build the documentation, you will also need the SGML Tools, which you find at your nearest sunsite or Linux mirror or at ftp://ftp.lip6.fr/pub/sgml-tools/. On an up-to-date Linux system, the tools are probably already installed.

1.3 I Got Everything, and Now?

The short answer is

% gzip -cd <package>.tar.gz | tar xvf -  # unpack the sources
% cd <package>                           # change to the toplevel directory
% ./Setup.hs configure                   # configure the build system
% ./Setup.hs build                       # build everything
[ Become root if necessary ]
% ./Setup.hs install                     # install c2hs

In the INSTALL file, there are more details.

Optionally, you can build the documentation by issuing make doc and install it with make install-doc.

sect>Usage of C->Haskell

Let's have a brief look at how to call the tool and how to use the generated interfaces.

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.

1.5 Compilation of a Generated Haskell API

C->Haskell comes with a marshalling library, called C2HS, which needs to be explicitly imported into Haskell binding modules. The library contains functions that users might use explicitly, but also functions that C->Haskell will generate for some classes of bindings. The library takes the form of a single Haskell module, whose c2hs places in the same directory as the generated binding whenever it is given the --copy-library (or -l) option.