usage.html

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Usage of C➔Haskell</title><link rel="stylesheet" href="fptools.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.70.1" /><link rel="start" href="index.html" title="The Binding Generator C➔Haskell" /><link rel="up" href="index.html" title="The Binding Generator C➔Haskell" /><link rel="prev" href="index.html" title="The Binding Generator C➔Haskell" /><link rel="next" href="implementing.html" title="Implementation of Haskell Binding Modules" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Usage of C➔Haskell</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="implementing.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usage"></a>Usage of C➔Haskell</h2></div></div></div><p>
  Let's have a brief look at how to call the tool and how to use the generated
  interfaces.
  </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id274283"></a>Usage of <span><strong class="command">c2hs</strong></span></h3></div></div></div><p>
    C➔Haskell is implemented by the executable <span><strong class="command">c2hs</strong></span>. The simplest form of usage
    is

</p><pre class="screen">
c2hs <em class="replaceable"><code>Lib</code></em><code class="literal">.chs</code>
</pre><p>

    where <em class="replaceable"><code>Lib</code></em><code class="literal">.chs</code> is the Haskell
    binding module defining the Haskell interface to a C library together with
    the required marshalling code. If <span><strong class="command">c2hs</strong></span> is invoked in this manner, the
    binding module must contain a cpp <code class="literal">#include</code> directive to
    determine the C-side interface of the library. Alternatively, a C header
    file can be specified on the command line, as in

</p><pre class="screen">
c2hs <em class="replaceable"><code>lib</code></em><code class="literal">.h </code><em class="replaceable"><code>Lib</code></em><code class="literal">.chs</code>
</pre><p>

    However, the latter option is only preserved for backwards compatibility and
    not recommended.  If no errors occur, <span><strong class="command">c2hs</strong></span> generates three files:
    </p><div class="orderedlist"><ol type="1"><li><p>
        a pure Haskell module <em class="replaceable"><code>Lib</code></em><code class="literal">.hs</code>,
        which implements the Haskell API of the library
        </p></li><li><p>
         a C header file <em class="replaceable"><code>Lib</code></em><code class="literal">.h</code>
         which some Haskell systems need to compile the generated Haskell code.
        </p></li><li><p>
        a <span><strong class="command">c2hs</strong></span> interface file
        <em class="replaceable"><code>Lib</code></em><code class="literal">.chi</code> that is used by
        other binding modules that import
        <em class="replaceable"><code>Lib</code></em><code class="literal">.hs</code> using an import
        hook (see <a href="implementing.html#import" title="Import Hooks">the section called “Import Hooks”</a>the section on import hooks for details).
        </p></li></ol></div><p>
    </p><p>
    The executable <span><strong class="command">c2hs</strong></span> has a couple more options:
</p><pre class="screen">
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
  -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
               --numeric-version    show version number

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 x86_64-linux, i686-linux, m68k-palmos
</pre><p>

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

</p><pre class="screen">
c2hs --cppopts='-I/some/obscure/dir' --cppopts=-DEXTRA' <em class="replaceable"><code>Lib</code></em>.chs
</pre><p>

    If you have more than one option that you want to pass to the pre-processor
    it is best to use multiple <code class="literal">--cppopts=</code> flags. That way
    there is no need to worry about quoting.
    </p><p>
    Often, <em class="replaceable"><code>lib</code></em><code class="literal">.h</code> will not be in
    the current directory, but in one of the header file directories. <span><strong class="command">c2hs</strong></span>
    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 <code class="filename">/usr/include</code> and
    <code class="filename">/usr/local/include</code>; and second, it will look in every directory
    that is mentioned in a <code class="literal">-IDIR</code> option passed to the
    pre-processor via <code class="literal">--cppopts</code>.
    </p><p>
    If the compiled binding module contains import hooks, C➔Haskell needs to
    find the <code class="literal">.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 class="literal">--include=<em class="replaceable"><code>INCLUDE</code></em></code> option has
    to be used to indicate the location, where
    <em class="replaceable"><code>INCLUDE</code></em> is a colon-separated list of
    directories.  Multiple such options are admissible.  Paths specified later
    are searched first.
    </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id314430"></a>Compilation of a Generated Haskell API</h3></div></div></div><p>
    C➔Haskell comes with a marshalling library, called <code class="literal">C2HS</code>,
    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, which <span><strong class="command">c2hs</strong></span> places in
    the same directory as the generated binding whenever it is given the
    <code class="literal">--copy-library</code> (or <code class="literal">-l</code>) option.
    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="implementing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">The Binding Generator C➔Haskell </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Implementation of Haskell Binding Modules</td></tr></table></div></body></html>