  The Binding Generator C->Haskell
  Manuel M. T. Chakravarty, chak@cse.unsw.edu.au
  v0.7, 18 June 2001

  C->Haskell is an interface generator that simplifies the development
  of Haskell bindings to C libraries.  The tool processes existing C
  header files that determine data layout and function signatures on the
  C side in conjunction with Haskell modules that specify Haskell-side
  type signatures and marshaling details.  Hooks embedded in the Haskell
  code signal access to C structures and functions -- they are expanded
  by the interfacing tool in dependence on information from the corre-
  sponding C header file.  Another noteworthy property is the
  lightweight nature of the approach.  More background information is
  available in a research paper discussing C->Haskell, which is at
  <http://www.cse.unsw.edu.au/~chak/papers/papers.html#c2hs>.
  ______________________________________________________________________

  Table of Contents


  1. Installation

     1.1 Where is the Source?
     1.2 What Else Do I Need?
     1.3 I Got Everything, and Now?

  2. Usage of C->Haskell

     2.1 Usage of
     2.2 Compilation of a Generated Haskell API

  3. Implementation of Haskell Binding Modules

     3.1 Import Hooks
     3.2 Context Hooks
     3.3 Type Hooks
     3.4 Sizeof Hooks
     3.5 Enumeration Hooks
     3.6 Call Hooks
     3.7 Get Hooks
     3.8 Set Hooks
     3.9 Pointer Hooks
     3.10 Grammar Rules

  4. The Haskell FFI Marshalling Library

  5. Bug Reports and Suggestions

  6. Copyright

  7. GNU Free Documentation License

  8. Release Notes

     8.1 Version 0.9.9 "Blue Ginger"
     8.2 Version 0.8.2 "Gentle Moon"
     8.3 Version 0.8.1 "Gentle Moon"
     8.4 Version 0.7.10 "Afterthought"
     8.5 Version 0.7.9 "Afterthought"
     8.6 Version 0.7.8
     8.7 Version 0.7.7
     8.8 Version 0.7.6
     8.9 Version 0.7.5



  ______________________________________________________________________

  CCooppyyrriigghhtt && DDiissttrriibbuuttiioonn

  Copyright (c) [1999..2001] by Manuel M. T. Chakravarty.  The manual is
  distributed under the terms GNU Free Documentation License available
  from <http://www.fsf.org/copyleft/fdl.html>.

  The master copy of this document is at
  <http://www.cse.unsw.edu.au/~chak/haskell/c2hs/>; the source is in
  SGML, which allows you to produce a selection of standard formats,
  including HTML and Postscript.


  CCoonnttrriibbuuttiioonnss

  If you have any comments, suggestions, or contributions, please send
  them to chak@cse.unsw.edu.au.



  11..  IInnssttaallllaattiioonn

  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..11..  WWhheerree iiss tthhee SSoouurrccee??

  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
  anonymous CVS access to C->Haskell's repository and may have pre-
  compiled binaries for easier installation.


  11..22..  WWhhaatt EEllssee DDoo II NNeeeedd??

  You need a Haskell system supported by C->Haskell.  Currently this is
  only the _G_l_a_s_g_o_w _H_a_s_k_e_l_l _C_o_m_p_i_l_e_r _(_G_H_C_), which you can obtain from
  <http://haskell.org/ghc/>.  You need a fairly recent version of the
  Haskell compiler.  C->Haskell uses a compiler support library called
  the _C_o_m_p_i_l_e_r _T_o_o_l_k_i_t.  In the main distribution, the Compiler Toolkit
  is already contained in the source tar ball -- be sure to download a
  file named c2hs-_x._y._z.tar.gz, were _x._y._z is the version number of the
  package.

  To build the documentation, you will also need the _S_G_M_L _T_o_o_l_s, 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1..33..  II GGoott EEvveerryytthhiinngg,, aanndd NNooww??

  The short answer is


       % gzip -cd c2hs.X.Y.Z.tar.gz | tar xvf -  # unpack the sources
       % cd c2hs.X.Y.Z                           # change to the toplevel directory
       % ./configure                             # run the `configure' script
       % make                                    # build everything
       [ Become root if necessary ]
       % make install                            # install the tool

  In the INSTALL file, there are more details.

  Optionally, you can build the documentation by issuing make doc.



  22..  UUssaaggee ooff CC-->>HHaasskkeellll

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


  22..11..  UUssaaggee ooff cc22hhss

  C->Haskell is implemented by the executable c2hs.  It is usually
  called as


       c2hs _l_i_b.h _L_i_b.chs


  where _l_i_b.h is the header file and _L_i_b.chs the Haskell binding module,
  which define the C- and Haskell-side interface, respectively.  If no
  errors occur, the result is a pure Haskell module _L_i_b.hs, which
  implements the Haskell API of the library.

  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
         -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)




  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' _l_i_b.h _L_i_b.chs


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

  Often, _l_i_b.h 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 /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.  Later paths are searched first.


  22..22..  CCoommppiillaattiioonn ooff aa GGeenneerraatteedd HHaasskkeellll AAPPII

  C->Haskell comes with a marshalling library, called C2HS, 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 C2HS.  To simplify this usually
  operating and compilation system-dependent process, C->Haskell comes
  with a simple configuration manager, in the form of the executable
  c2hs-conf.  It can be used to inquire information for compilation and
  linking and pass that information on to the Haskell compiler.  The
  call


       c2hs-config --cflags


  returns all flags that need to be given to the Haskell compiler for
  compilation and


       c2hs-config --lib


  returns all flags necessary for linking.  Overall, you may want to use
  a call like the following to compile a generated library module:


       ghc `c2hs-config --cflags` -c _L_i_b.hs


  The backquotes cause the shell to call c2hs-config and substitute the
  call by the flags returned.  This, of course, also works in a
  makefile.

  Furthermore, c2hs-config can also be used to locate the executable of
  the tool itself, by calling


       c2hs-config --c2hs


  This slightly simplifies configuration management of libraries
  generated by C->Haskell, as it is sufficient to know the location of
  c2hs-config to access all other components of C->Haskell.






  33..  IImmpplleemmeennttaattiioonn ooff HHaasskkeellll BBiinnddiinngg MMoodduulleess

  A discussion of binding modules, the principles behind the tool, and a
  discussion of related work can be found in a research paper located at
  <http://www.cse.unsw.edu.au/~chak/papers/papers.html#c2hs>.  All
  features described in the paper, except enum define hooks are
  implemented in the tool, but since the publication of the paper, the
  tool has been extended further.

  Furthermore, the distribution contains examples that illustrate the
  use of C->Haskell.  In the source distribution, these examples are
  located below the directories tests and examples.  The latter contains
  a binding for the Gnome <http://www.gnome.org> HTTP 1.1 library ghttp.
  The sources of the marshalling library C2HS are in the directory lib
  and contain a fair amount of comments, which should help getting you
  started.

  Since version 0.8.1 the interface of the marshalling library C2HS
  changed.  The new interface essentially consists of the new Haskell
  FFI Marshalling Library.  More details about this library are provided
  in the next section.  For backward compatibilitym the old interface
  (i.e., the pre-0.8.1 interface) can still be used by importing
  C2HSDeprecated instead of C2HS.

  The remainder of this section describes the hooks that are available
  in binding modules.


  33..11..  IImmppoorrtt HHooookkss


       {#import [qualified] _m_o_d_i_d#}


  Is translated into the same syntactic form in Haskell, which implies
  that it may be followed by an explicit import list.  Moreover, it
  implies that the module _m_o_d_i_d is also generated by C->Haskell and
  instructs the tool to read the file _m_o_d_i_d.chi.

  If an explicit output file name is given (--output option), this name
  determines the basename for the .chi file of the currently translated
  module.

  Currently, only pointer hooks generate information that is stored in a
  .chi file and needs to be incorporated into any client module that
  makes use of these pointer types.  It is, however, regarded as good
  style to use import hooks for any module generated by C->Haskell.


  33..22..  CCoonntteexxtt HHooookkss


       {#context [header = _h_e_a_d_e_r] [lib = _l_i_b] [prefix = _p_r_e_f_i_x]#}


  Context hooks define a set of global configuration options.
  Currently, there are three parameters all of which are strings:

  +o  _h_e_a_d_e_r is the C header file containing the definitions, which are
     bound in the current binding module.

  +o  _l_i_b is a dynamic library that contains symbols needed by the
     present binding.

  +o  _p_r_e_f_i_x is an identifier prefix that may be omitted in the lexemes
     of identifiers referring to C definitions in any binding hook.  The
     is useful as C libraries often use a prefix, such as gtk_, as a
     form of poor man's name spaces.  Any occurrence of underline
     characters between a prefix and the main part of an identifier must
     also be dropped.  Case is not relevant in a prefix.  In case of a
     conflict of the abbreviation with an explicitly defined identifier,
     the explicit definition takes preference.

  All three parameters are optional.  An example of a context hook is
  the following:

       {#context header = "gtkwidget.h" prefix = "gtk"#}


  If a binding module contains a binding hook, it must be the first hook
  in the module.


  33..33..  TTyyppee HHooookkss


       {#type _i_d_e_n_t#}


  A type hooks maps a C type to a Haskell type.  As an example, consider


       type GInt = {#type gint#}


  The type must be a defined type, primitive types, such as int, are not
  admissible.


  33..44..  SSiizzeeooff HHooookkss


       {#sizeof _i_d_e_n_t#}


  A sizeof hooks maps a C type to its size in bytes.  As an example,
  consider


       gIntSize :: IntgIntSize  = {#sizeof gint#}


  The type must be a defined type, primitive types, such as int, are not
  admissible.  The size of primitive types can always be obtained using
  Storable.sizeOf.


  33..55..  EEnnuummeerraattiioonn HHooookkss


       {#enum _c_i_d [as _h_s_i_d] {_a_l_i_a_s_1 , ... , _a_l_i_a_s_n} [with prefix = _p_r_e_f]
       [deriving (_c_l_i_d_1 , ... , _c_l_i_d_n)]#}


  Rewrite the C enumeration called _c_i_d into a Haskell data type
  declaration, which is made an instance of Enum such that the ordinals
  match those of the enumeration values in C.  This takes explicit
  enumeration values in the C definitions into account.  If _h_s_i_d is
  given, this is the name of the Haskell data type.  The identifiers
  _c_l_i_d_1 to _c_l_i_d_n are added to the deriving clause of the Haskell type.


  By default, the names of the C enumeration are used for the
  constructors in Haskell.  If _a_l_i_a_s_1 is underscoreToCase, the original
  C names are capitalised and the use of underscores is rewritten to
  caps.  Moreover, _a_l_i_a_s_1 to _a_l_i_a_s_n may be aliases of the form _c_i_d as
  _h_s_i_d, which map individual C names to Haskell names.  Instead of the
  global prefix introduced by a context hook, a local prefix _p_r_e_f can
  optionally be specified.

  As an example, consider


       {#enum WindowType {underscoreToCase} deriving (Eq)#}


  NNoottee:: The enum define hooks described in the C->Haskell are not
  implemented yet.


  33..66..  CCaallll HHooookkss


       {#call [fun] [unsafe] _c_i_d [as _h_s_i_d]#}


  A call hook rewrites to a call to the C function _c_i_d and also ensures
  that the appropriate foreign import declaration is generated.  The
  tags fun and unsafe specify that the external function is purely
  functional and cannot re-enter the Haskell runtime, respectively.  If
  _h_s_i_d is present, it is used as the identifier for the foreign
  declaration, which otherwise defaults to the _c_i_d.

  As an example, consider



       sin :: Float -> Float
       sin  = {#call fun sin as "_sin"#}





  33..77..  GGeett HHooookkss


       {#get _a_p_a_t_h#}


  A get hook supports accessing a member value of a C structure.  The
  hook itself yields a function that, when given the address of a
  structure of the right type, performs the structure access.  The
  member that is to be extracted is specified by the access path _a_p_a_t_h.
  Access paths are formed as follows (following a subset of the C
  expression syntax):

  +o  The root of any access path is a simple identifier, which denotes
     either a type name or struct tag.

  +o  An access path of the form *_a_p_a_t_h denotes dereferencing of the
     pointer yielded by accessing the access path _a_p_a_t_h.

  +o  An access path of the form _a_p_a_t_h._c_i_d specifies that the value of
     the struct member called _c_i_d should be accessed.

  +o  Finally, an access path of the form _a_p_a_t_h->_c_i_d, as in C, specifies
     a combination of dereferencing and member selection.
  For example, we may have



       visualGetType              :: Visual -> IO VisualType
       visualGetType (Visual vis)  = liftM cToEnum $ {#get Visual->type#} vis





  33..88..  SSeett HHooookkss


       {#get _a_p_a_t_h#}


  Set hooks are formed in the same way as get hooks, but yield a
  function that assigns a value to a member of a C structure.  These
  functions expect a pointer to the structure as the first and the value
  to be assigned as the second argument.  For example, we may have


       {#set sockaddr_in.sin_family#} addr_in (cFromEnum AF_NET)



  33..99..  PPooiinntteerr HHooookkss


       {#pointer [*] _c_i_d [as _h_s_i_d] [foreign | stable] [newtype | -> _h_s_i_d_2]#}


  A pointer hook facilitates the mapping of C to Haskell pointer types.
  In particular, it enables the use of ForeignPtr and StablePtr types
  and defines type name translations for pointers to non-basic types.
  In general, such a hook establishes an association between the C type
  _c_i_d or *_c_i_d and the Haskell type _h_s_i_d, where the latter defaults to
  _c_i_d if not explicitly given.  The identifier _c_i_d will usually be a
  type name, but in the case of *_c_i_d may also be a struct, union, or
  enum tag.  If both a type name and a tag of the same name are
  available, the type name takes precedence.  Optionally, the Haskell
  representation of the pointer can be by a ForeignPtr or StablePtr
  instead of a plain Ptr.  If the newtype tag is given, the Haskell type
  _h_s_i_d is defined as a newtype rather than a transparent type synonym.
  In case of a newtype, the type argument to the Haskell pointer type
  will be _h_s_i_d, which gives a cyclic definition, but the type argument
  is here really only used as a unique type tag.  Without newtype, the
  default type argument is (), but another type can be specified after
  the symbol ->.

  For example, we may have



       {#pointer *GtkObject as Object foreign newtype#}




  This will generate a new type Object as follows:



       newtype Object = Object (ForeignPtr Object)

  which allows to export Object as an abstract type and facilitates type
  checking at call sites of imported functions using the encapsulated
  foreign pointer.  The latter is achieved by C->Haskell as follows.
  The tool remembers the association of the C type *GtkObject with the
  Haskell type Object, and so, it generates for the C function



       void gtk_unref_object (GtkObject *obj);




  the import declaration



       foreign import gtk_unref_object :: Object -> IO ()




  This function can obviously only be applied to pointers of the right
  type, and thus, protects against the common mistake of confusing the
  order of pointer arguments in function calls.

  However, as the Haskell FFI does not allow to return ForeignPtrs from
  function calls, the tool will use the type Ptr HsName in this case,
  where HsName is the Haskell name of the type.  In the above example,
  that would be Ptr Object.

  As an example that does not represent the pointer as an abstract type,
  consider the C type declaration:



       typedef struct {int x, y;} *point;




  We can represent it in Haskell as




       data Point = Point {x :: Int, y :: Int}
       {#pointer point as PointPtr -> Point#}




  which will translate to



       data Point = Point {x :: Int, y :: Int}
       type PointPtr = Ptr Point




  and establish a type association between point and PointPtr.

  _R_e_s_t_r_i_c_t_i_o_n_: The name _c_i_d cannot be a basic C type (such as int), it
  must be a defined name.
  33..1100..  GGrraammmmaarr RRuulleess

  The following grammar rules define the syntax of binding hooks:


       hook     -> `{#' inner `#}'
       inner    -> `import' ['qualified'] ident
                 | `context' ctxt
                 | `type' ident
                 | `sizeof' ident
                 | `enum' idalias trans [`with' prefix] [deriving]
                 | `call' [`fun'] [`unsafe'] idalias
                 | `get' apath
                 | `set' apath
                 | `pointer' ['*'] idalias ptrkind

       ctxt     -> [`header' `=' string] [`lib' `=' string] [prefix]
       idalias  -> ident [`as' ident]
       prefix   -> `prefix' `=' string
       deriving -> `deriving' `(' ident_1 `,' ... `,' ident_n `)'
       apath    -> ident
                 | `*' apath
                 | apath `.' ident
                 | apath `->' ident
       trans    -> `{' alias_1 `,' ... `,' alias_n `}'
       alias    -> `underscoreToCase'
                 | ident `as' ident
       ptrkind  -> [`foreign' | `stable'] ['newtype' | '->' ident]





  44..  TThhee HHaasskkeellll FFFFII MMaarrsshhaalllliinngg LLiibbrraarryy

  The Haskell FFI Marshalling Library is a proposed standard library for
  foreign function interoperability.  The interface of the C2HS
  marshalling library as of version 0.8.1 of the tool is a slight
  extension of the Haskell FFI Marshalling Library, which is documented
  in the following.

  The library is partitioned into a language independent and a C
  specific component.  All features of the former are available from the
  module Foreign and all features of the later from CForeign.
  Nevertheless, the following module hierarchy is part of the interface
  definition:

  +o  Foreign

  +o  Int

  +o  Word

  +o  Ptr

  +o  ForeignPtr

  +o  StablePtr

  +o  Storable

  +o  MarshalAlloc

  +o  MarshalArray


  +o  MarshalError

  +o  MarshalUtils

  +o  CForeign

  +o  CTypes

  +o  CTypesISO

  +o  CError

  +o  CString

     It is recommended to access this functionality in C->Haskell
     binding modules by merely importing C2HS.



  55..  BBuugg RReeppoorrttss aanndd SSuuggggeessttiioonnss

  Please address any bug reports and suggestions to
  chak@cse.unsw.edu.au.  A good bug report contains information on the
  used operating system and Haskell compiler as well as the version of
  C->Haskell that you have been using.  You can obtain the version
  information by running c2hs-config --version.  If possible a concise
  example illustrating your problem would be appreciated.



  66..  CCooppyyrriigghhtt

  C->Haskell is Copyright (C) [1999..2001] Manuel M. T. Chakravarty

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or (at
  your option) any later version.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

  This manual is Copyright (c) [2000..2001] by Manuel M. T. Chakravarty.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1 or
  any later version published by the Free Software Foundation; with no
  Invariant Sections, with no Front-Cover Texts, and with the no Back-
  Cover Texts.  A copy of the license is included in the section
  entitled "GNU Free Documentation License".


  77..  GGNNUU FFrreeee DDooccuummeennttaattiioonn LLiicceennssee

  The GNU Free Documentation License is available at
  <http://www.fsf.org/copyleft/fdl.html>.





  88..  RReelleeaassee NNootteess

  Important changes (especially those affecting the semantics of the
  tool) are documented in the following.


  88..11..  VVeerrssiioonn 00..99..99 ""BBlluuee GGiinnggeerr""


  +o  Bug fixes

  +o  Library names in foreign imports have been removed until the
     convention of the new FFI is implemented (they are currently
     _s_i_l_e_n_t_l_y omitted)

  +o  Added sizeof hooks; sizeof of type names is now also supported in
     constant expressions

  +o  Local prefix for enum hooks; courtesy of Armin Sander

  +o  Added import hooks

  +o  The documentation includes a description of binding hooks

  +o  Added pointer hooks, which were derived from code for a similar
     feature by Axel Simon; this includes proper treatment of
     parametrised pointers

  +o  Integrated deriving option for enum hooks, which was contributed by
     Axel Simon

  +o  Adapted to GHC 5.0


  88..22..  VVeerrssiioonn 00..88..22 ""GGeennttllee MMoooonn""


  +o  Adaptation layer for legacy StablePtr interface

  +o  Forgot to export FunPtr and associated functions from C2HS

  +o  Forgot to export some names in C2HSDeprecated

  +o  Added support for gcc's __builtin_va_list


  88..33..  VVeerrssiioonn 00..88..11 ""GGeennttllee MMoooonn""


  +o  Library adapted to New FFI; the old interface can still be used by
     importing C2HSDeprecated

  +o  FFI Library specification added to the documentation


  88..44..  VVeerrssiioonn 00..77..1100 ""AAfftteerrtthhoouugghhtt""


  +o  CygWin support; based on suggestions by Anibal Maffioletti
     Rodrigues de DEUS <anibaldedeus@email.com>

  +o  IntConv instances for Int8, Word8, and Char




  88..55..  VVeerrssiioonn 00..77..99 ""AAfftteerrtthhoouugghhtt""


  +o  Debugged the stripping of prefixes from enumerators; prefixes are
     now generally stripped, independent of whether they can be stripped
     from all enumerators of a given enumeration type

  +o  Comma now correctly required after underscoreToCase.  WWAARRNNIINNGG:: TThhiiss
     bbrreeaakkss ssoouurrccee ccoommppaattiibbiilliittyy wwiitthh pprreevviioouuss vveerrssiioonnss..


  88..66..  VVeerrssiioonn 00..77..88


  +o  Provisional support for GHC 4.08

  +o  Corrected constant folding


  88..77..  VVeerrssiioonn 00..77..77

  Ignores any occurrence of #pragma.


  88..88..  VVeerrssiioonn 00..77..66

  Bug fixes and support for long long.


  88..99..  VVeerrssiioonn 00..77..55

  This is mainly a bug fix release.  In particular, the space behaviour
  of C->Haskell has been significantly improved.

  IMPORTANT NOTE: From this release on, library names in lib tags in
  context hooks should _n_o_t contain a suffix (i.e., omit .so etc).






























