c2hs
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.
c2hs