
========
pure-gen 
========

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

License
=======

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

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

As of version 0.5, pure-gen is now compiled to a native executable. You'll
need Pure 0.21 or later and the basic LLVM toolchain to make this work.

pure-gen also requires gcc (-E) as its C preprocessor *at runtime*. Moreover,
it 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.

Thus, if you're still running an older version of gcc, you'll have to install
gcc 4.3 or later in a location where it doesn't interfere with your system
compiler. Then just set the PURECPP environment variable to the directory
containing the gcc 4.3 binary and all should be fine.

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

Normally you just run ``make && sudo make install``. This will install the
program under $(prefix)/bin and the required dump-ast program under
$(prefix)/lib/pure-gen. By default, pure-gen assumes the same installation
prefix as the installed Pure interpreter. (See The Makefile for further
options.)

As already mentioned, to compile pure-gen.pure you'll need Pure 0.21 or later
and the basic LLVM toolchain (llc+opt); see the Pure INSTALL file for details
on how to get these up and running.

Since pure-gen's C parser is written in Haskell, there are some notable
additional requirements, explained in further detail below.

Once you've run ``make`` successfully and the pure-gen and dump-ast programs
have been built, you can also run a minimal testsuite with ``make check``. This
only tests very basic functionality, but should be enough to make sure that
pure-gen works on your system.

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 6 or later), as well as the Language.C Haskell
library (versions 0.4.2 up to 0.5.0 are known to work). To compile Language.C,
you'll also need the Haskell parser generator tools Alex and Happy.

ghc can be found at http://www.haskell.org/ghc/. Binary packages for ghc, alex
and happy, as well as cabal (a Haskell library installation tool, see below)
should be readily available on most systems nowadays.

If you can't find a precompiled package of Language.C (common package names
are language-c or haskell-language-c), the library is most conveniently
available through cabal (http://www.haskell.org/cabal/), see
https://hackage.haskell.org/package/language-c for more information.

**NOTE:** dump-ast requires Language.C 0.5 or earlier, any later version
is *not* supported yet. If this version isn't readily available for your
platform, you can use the included copy of language-c 0.5.0 and install that
using cabal (run ``make install-cabal``) before running ``make``. Or, if that
doesn't suit you, you can grab the official tarball here and install it
manually by whatever means you prefer:

http://hackage.haskell.org/packages/archive/language-c/0.5.0/language-c-0.5.0.tar.gz.

More information about dump-ast can be found in the README.dump-ast file.

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 https://agraef.github.io/pure-docs/pure-gen.html.

| Albert Graef <aggraef at gmail.com>
| Scott Dillard
