Home

Michael Steele edited this page Apr 6, 2015 · 11 revisions

c2hs 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 corresponding C header file. Another noteworthy property is the lightweight nature of the approach. The idea for the tool was developed during the implementation of Gtk+HS, a Haskell binding for the GUI toolkit GTK+. The latter is no longer under active development, but its successor, Gtk2Hs, also uses c2hs.

News

  • [31 March 2015] Version 0.25.2 released

  • [28 March 2015] Version 0.25.1 released

  • [13 March 2015] Version 0.24.1 released

  • [22 February 2015] Version 0.23.1 released

  • [25 January 2015] Version 0.22.1 released

  • [2 January 2015] Version 0.21.1 released

  • [4 December 2014] Version 0.20.1 released

  • [11 November 2014] Version 0.19.1 released

  • [12 September 2014] Version 0.18.2 released

  • [31 August 2014] Version 0.18.1 released

  • [19 April 2014] Version 0.17.2 released

  • [11 April 2014] Version 0.17.1 released

  • [12 March 2014] Version 0.16.6 released

  • [11 August 2013] Release of version 0.16.5, which works with GHC 7.6.3.

  • [24 April 2011] Duncan Coutts just released version 0.16.3. It supports marshaller arguments and alignof hooks among some other changes.

  • [3 May 2010] Duncan Coutts just released version 0.16.2, which works with GHC 6.12.

  • [28 February 2009] Duncan Coutts just released version 0.16.0 "Crystal Seed", which uses the new package Language.C that Benedikt Huber recently extracted from C->Haskell's code base. Moreover, it has better support for OS X, implements enum hooks, and had several bugs fixed.

  • [24 November 2007] Duncan Coutts just released version 0.15.1 "Rainy Days". This release builds with GHC 6.4 through to 6.8 and also properly supports OpenBSD and Windows. Moreover, the documentation has been updated.

  • [31 August 2007] Duncan Coutts just released version 0.15.0 "Rainy Days". This release includes Duncan's new parser with excellent gcc compatibility and an improved build system.

  • [2 January 2006] Updated the the C->Haskell darcs repository with modifications by Ganesh Sittampalam to fix a problem when pulling on windows/cygwin.

  • [14 May 2006] The C->Haskell darcs repository moved to darcs.haskell.org and Duncan Coutts is now a second maintainer of the tool. (He's the one who heroically rewrote C->Haskell's parser.)

  • [12 December 2005] Source release 0.14.5 brings in addition to bug fixes support for typedef'ed pointers to structs/unions (thanks to Jelmer Vernooij) and enables to suppress code generation for pointer hooks with a nocode directive.

Currently, the c2hs compiler is available for the Glasgow Haskell Compiler only. However, the only extension needed over Haskell 98 and the H98 FFI Addendum are existential data types. (The latter are only needed for the c2hs compiler itself, but not for the accompanying marshaling libraries.) Partial support for nhc98 is in place, but so far there have always been some bugs in nhc98 that prevented to complete the port.

Download

The code is available from Hackage.

There are also a number of pre-compiled binary packages of c2hs available for different operating systems:

Mailing List

To subscribe to the c2hs mailing list, visit the subscription page. The address of the list is c2hs@haskell.org and there is also an online archive.

GitHub Repository

For those living on the bleeding edge of development, get the latest c2hs code with Git:

git clone git://github.com/haskell/c2hs.git

Inside your copy of the repository, execute autoconf; chmod +x Setup.hs. Afterwards compilation/installation is as from a tar ball (i.e., Cabal style ./Setup.hs configure; ./Setup.hs build; ./Setup.hs install). Details are in the file INSTALL.

NB for Mac users: One of the patches originating from the CVS to Darcs conversion of the repository seems to cause problems on Macs (due to the lack of case distinction in file names). The patch can be circumvented by getting a partial repository as follows:

darcs get --partial http://code.haskell.org/c2hs/

(I don't know if this is still a problem with the new GitHub repo: any Mac users who have problems, let us know!)

Bug reports and feature requests

Bug can be reported and features requested on the GitHub issues tracker at https://github.com/haskell/c2hs/issues.

Documentation

If you plan to install c2hs, you will probably want to read the c2hs User Guide. There is also a research paper about the tool. To get an idea of how to use the interface generator -- after the build -- go to the directory c2hs/tests/, which contains a number of small examples of binding files with matching C header files. Most interesting is Structs.chs as well as Pointer.chs as well as the corresponding C source and header files. The binding file contains instructions on how to generate an executable from it.

Here are two blog posts that provide a more tutorial-style introduction to c2hs:

Future Development

If you have any comments, suggestions, or a bug report, please send them to c2hs@haskell.org. Code contributions are of course especially welcome. Just send us a pull request on GitHub.

License

The code is released under the GNU General Public Licence (GPL). This means that you can basically do with it what you want as long as you contribute improvements of the tool itself back to the community. Any interfaces that you generate with the tool are, however, free from any license restrictions from my side. The situation is exactly the same as with the GNU C Compiler (gcc).