
pure-gen 
========

A Pure C bindings generator. Written by Albert Graef, based on Scott Dillard's
original OpenGL bindings generator.

License
=======

Please check the COPYING file for licensing information. The generator
contains significant portions of the Language.C Haskell library; see
dump-ast.hs for pertinent license and copyright information.

Requirements
============

pure-gen currently requires gcc (-E) as the C preprocessor. It also needs a
version of gcc which understands the -fdirectives-only option, which means gcc
>= 4.3. It will run with older versions of gcc, but then you'll get an error
message from gcc indicating that it doesn't understand the -fdirectives-only
option. pure-gen then won't be able to extract any '#define'd constants from
the header files.

Installation
============

Normally you just run 'make && sudo make install'. This will install the
program under $(prefix)/lib/pure-gen-x.y and create a link to the executable
in $(prefix)/bin. (See The Makefile for further options.) To run the pure-gen
script, you'll need the Pure interpreter, of course.

Alas, since pure-gen's C parser is written in Haskell, there are some notable
additional requirements to make this work, explained in further detail below.

Installing the Required Haskell Bits
---------- --- -------- ------- ----

To build the C parser utility dump-ast, which is written in Haskell, you'll
need a Haskell compiler (ghc has been tested), as well as the Language.C
Haskell library (version 0.3.1 or 0.3.1.1).

ghc can be found at http://www.haskell.org/ghc/.

The Language.C library is most conveniently available through cabal
(http://www.haskell.org/cabal/), see http://www.sivity.net/projects/language.c
for more information. Once cabal is set up on your system, you can install
Language.C by running 'cabal install language-c' (make sure to do 'cabal
update' first so that you get the latest version).

To make this a little easier for people not familiar with Haskell, we have
uploaded statically linked binaries of dump-ast for Linux, both 32 and 64
bits, to the pure-lang Google Group files area. Thus, if you're on a recent
x86/64 Linux system and can't/don't want to install ghc, you can try to put
the appropriate binary into the source directory, rename it to 'dump-ast' and
then run 'sudo make install' without running 'make'. If you're lucky this
might even work. (The binaries are still linked dynamically against libgmp and
libc, there seems no way to avoid that. So if the binaries don't work on your
system because the requisite libraries don't match, then you'll just have to
bite the bullet and compile dump-ast yourself.)

NOTE: The sources of the dump-ast program can be found in dump-ast.hs. This is
a Haskell program which parses a C file given on the command line and writes
the abstract syntax tree (AST) as a collection of terms in Pure-readable
format to stdout. Normally you won't have to invoke dump-ast yourself since
this is handled by pure-gen automatically, but the program may also be useful
for other utilities which have to parse C header files. dump-ast takes the
name of the file to be parsed as the *last* command line parameter, all other
command line arguments are just passed on to the C preprocessor without any
checking. Also note that dump-ast calls gcc to do the preprocessing, so on
Windows you will probably need MinGW installed when running this program.

Usage
=====

The pure-gen script generates bindings for C functions from a C header file.
Try 'pure-gen -h' for help. Basically,

	pure-gen foo.h

generates a Pure module foo.pure with 'extern' declarations for the constants
('#define's and enums) and C routines declared in the given C header file and
(recursively) its includes. pure-gen also understands a bunch of options which
control the contents of the generated modules in different ways.

Complete documentation is available in the manual page. You can also read the
manual online at:
http://pure-lang.googlecode.com/svn/docs/pure-gen.html (html version)
http://pure-lang.googlecode.com/svn/docs/pure-gen.pdf  (pdf version)


Enjoy!
Albert Graef <Dr.Graef at t-online.de>
Scott Dillard
