README

This is a small package to generate cython code from header file: instead of
having to write all the function declarations and structures by yourself,
xml2cython can use gccxml output files to generate all the declarations
automatically.

DISCLAIMER: I DON'T HAVE TIME TO SPEND ON THIS, AND YOU SHOULD CONSIDER IT UNSUPPORTED
AT THAT POINT. A BETTER SOLUTION TO THE PROBLEM SOLVED BY CYTHON_CODEGEN WOULD BE
SOMETHING BASED ON CLANG.

Dependencies
============

- python
- gccxml (recent build >= 0.9 from CVS)
- codegenlib from ctypeslib

Usage
=====

Say you have a header foo.h you want to wrap with cython. First, you need to
generate an xml file from gccxml. You can use the h2xml script from ctypelibs:

        h2xml -I. foo.h -o foo.xml

You can then generate the cython file with xml2cython:

        xml2cython.py -l 'foo' foo.h foo.xml

This tells xml2cython to generate a cython file from foo.xml, originating from
foo.h by gccxml, and to only pull items whose location match the string foo.

Filters
=======

By default, xml2cython pull out every function in the xml file, and every
'dependency' (necessary to generate correct cython function declarations). This
is likely to generate invalid cython code because of compilers intrisincs and
so on, so you should filter the items pulled out from the xml file.

That's why I implemented of couple of naive filters. For example, say you are
only interested in declarations coming from one header file, like
AudioHardware.h (a header file for CoreAudio framework on Mac OS X). You can
then use:

        xml2cython -l 'AudioHardware.h' CoreAudio/AudioHardware.h AudioHardware.xml

Only functions, enumerations and typedefs coming from this file will be pulled
out. You should be able to use regex (as understood by python regex enging) for
the filter string. Programmatically, it is easy to filter depending on the type
of the item (function, typedef, etc...) but I have not found an easy way to
present this to the user, so you will need to do it by yourself: look at the
cycodegenlib.cycodegen.classify and xml2cython.py generate_main functions to
see how basic filtering works.

Location
========

By default, xml2cython pull out every function in the xml file, and every
'dependency' (necessary to generate correct cython function declarations). This
is likely to generate invalid cython code because of compilers intrisincs and
so on, so you should filter the items pulled out from the xml file.

Location is a gccxml 'concept' related to the origin of each item in the parsed
tree built by gccxml. Location refers to both file and line location for each C
item (structure, typedef, function declaration, etc...). Simply using the -l
option of xml2cython on the name of the header file hence will only pull
functions declared in that file. You can also use a regex, which will be
matched against the file location of each item.

If you need more control, you will likely need to do it by yourself.

Caveat
======

Limitations
-----------

Many. xml2cython is nothing more than an hack to avoid writing by hand cython
files to wrap large API. Since I know nothing about compilers and parsing, it
is likely that the implementation makes you laugh, too.

Many C declarations are not supported by cython (for example complex numbers)
and no check is made that xml2cython generates valid cython code. Any header
file which crashes xml2cython is a bug, but a non-buildable cython file may not
be.

Another problem is that the query system is limited, meaning the generated
files are quickly very big, hence slow to compile with cython. I am adding a
few filters capabilities (to filter on function names, file origin, etc...),
but it is unlikely to get fancy.

That being said, xml2cython is useful :) It can generate valid code for non
trivial header (I am using it successfully to wrap alsa - a C api with > 1000
functions, hundred of typedefs and structures as well as CoreAudio on Mac OS
X).

C vs C++
--------

Unfortunately, gccxml only parses C++ files. So if your header is not C++
compatible, it will not work. No C++ concept is supported by xml2cython, most
of them are removed from the AST by xml2cython to avoid conflict with cython
(which does not support C++ constructs either).

LICENSE
=======

The code is under MIT license (See LICENSE). I don't care about the code I
wrote myself (all the code in this package except gccxmlparser.py): I can
license it do any license you want if you request it. The only reason why I
used this is because I use some code from ctypeslib, under the MIT. If the
license is not acceptable, you should rewrite the parts which depend on
ctypeslib (mostly gccxmlparse as well as type descriptors)/