<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>The Binding Generator C->Haskell: Usage of C->Haskell</TITLE>
<LINK HREF="c2hs-3.html" REL=next>
<LINK HREF="c2hs-1.html" REL=previous>
<LINK HREF="c2hs.html#toc2" REL=contents>
</HEAD>
<BODY>
<A HREF="c2hs-3.html">Next</A>
<A HREF="c2hs-1.html">Previous</A>
<A HREF="c2hs.html#toc2">Contents</A>
<HR>
<H2><A NAME="s2">2. Usage of C->Haskell</A></H2>
<P>Let's have a brief look at how to call the tool and how to use the generated
interfaces.
<P>
<H2><A NAME="ss2.1">2.1 Usage of <CODE>c2hs</CODE></A>
</H2>
<P>C->Haskell is implemented by the executable <CODE>c2hs</CODE>. It is usually
called as
<P>
<BLOCKQUOTE>
<CODE>c2hs </CODE><EM>lib</EM><CODE>.h </CODE><EM>Lib</EM><CODE>.chs</CODE>
</BLOCKQUOTE>
<P>where <EM>lib</EM><CODE>.h</CODE> is the header file and <EM>Lib</EM><CODE>.chs</CODE> the Haskell
binding module, which define the C- and Haskell-side interface, respectively.
If no errors occur, the result is a pure Haskell module <EM>Lib</EM><CODE>.hs</CODE>,
which implements the Haskell API of the library.
<P>The executable <CODE>c2hs</CODE> has a couple more options:
<P>
<BLOCKQUOTE><CODE>
<PRE>
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
-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
-o FILE --output=FILE output result to FILE (should end in .hs)
-v --version show version information
--old-ffi[=OLDFFI] use the FFI without `Ptr a'
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)
</PRE>
</CODE></BLOCKQUOTE>
<P>The most useful of these is probably <CODE>--cppopts=</CODE> (or <CODE>-C</CODE>). If the C
header file needs any special options (like <CODE>-D</CODE> or <CODE>-I</CODE>) to go through
the C pre-processor, here is the place to pass them. A call may look like
this:
<P>
<BLOCKQUOTE>
<CODE>c2hs --cppopts='-I/some/obscure/dir -DEXTRA' </CODE><EM>lib</EM><CODE>.h </CODE><EM>Lib</EM><CODE>.chs</CODE>
</BLOCKQUOTE>
<P>Do not forget the quotes if you have more than one option that you want to
pass to the pre-processor.
<P>Often, <EM>lib</EM><CODE>.h</CODE> will not be in the current directory, but in one of the
header file directories. Apart from the current directory, C->Haskell
looks in two places for the header: first, in the standard include directory
of the used system, this is usually <CODE>/usr/include</CODE> and
<CODE>/usr/local/include</CODE>; and second, it will look in every directory that
is mentioned in a <CODE>-IDIR</CODE> option passed to the pre-processor via
<CODE>--cppopts</CODE>.
<P>If the compiled binding module contains import hooks, C->Haskell needs to
find the <CODE>.chi</CODE> (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
<CODE>--include=INCLUDE</CODE> option has to be used to indicate the location, where
<CODE>INCLUDE</CODE> is a colon-separated list of directories. Multiple such options
are admissible. Later paths are searched first.
<P>
<H2><A NAME="ss2.2">2.2 Compilation of a Generated Haskell API</A>
</H2>
<P>C->Haskell comes with a marshalling library, called <CODE>C2HS</CODE>, which is
imported by virtually all library bindings. Consequently, you will have to
tell the Haskell compiler where to find the interface files when you compile a
generated interface and you have to tell the linker where to find the library
archive of <CODE>C2HS</CODE>. To simplify this usually operating and compilation
system-dependent process, C->Haskell comes with a simple configuration
manager, in the form of the executable <CODE>c2hs-conf</CODE>. It can be used to
inquire information for compilation and linking and pass that information on
to the Haskell compiler. The call
<P>
<BLOCKQUOTE><CODE>
c2hs-config --cflags
</CODE></BLOCKQUOTE>
<P>returns all flags that need to be given to the Haskell compiler for
compilation and
<P>
<BLOCKQUOTE><CODE>
c2hs-config --lib
</CODE></BLOCKQUOTE>
<P>returns all flags necessary for linking. Overall, you may want to use a call
like the following to compile a generated library module:
<P>
<BLOCKQUOTE>
<CODE>ghc `c2hs-config --cflags` -c </CODE><EM>Lib</EM><CODE>.hs</CODE>
</BLOCKQUOTE>
<P>The backquotes cause the shell to call <CODE>c2hs-config</CODE> and substitute the
call by the flags returned. This, of course, also works in a makefile.
<P>Furthermore, <CODE>c2hs-config</CODE> can also be used to locate the executable of the
tool itself, by calling
<P>
<BLOCKQUOTE><CODE>
c2hs-config --c2hs
</CODE></BLOCKQUOTE>
<P>This slightly simplifies configuration management of libraries generated by
C->Haskell, as it is sufficient to know the location of <CODE>c2hs-config</CODE> to
access all other components of C->Haskell.
<P>
<P>
<HR>
<A HREF="c2hs-3.html">Next</A>
<A HREF="c2hs-1.html">Previous</A>
<A HREF="c2hs.html#toc2">Contents</A>
</BODY>
</HTML>
