== About ==
PyBindGen is (surprise!) a python bindings generator.  The main features are:

 * Is written in clean, PEP 8 compliant, and pylint checked, Python code;
 * Generates clean C or C++ code, nearly as readable as code written
   manually by a developer;
 * Generated code is self contained and does not require any external
   libraries or macros; after generating the python module only python
   header files are required, nothing else.
 * Does not require Boost.Python (no C++ template magic, also works in C);
 * The interface for code generation is a simple Python API, not some
   obscure interface definition language.  Additionally PyBindGen can
   parse header files with gccxml, if gccxml and pygccxml are
   installed in the system.
 * Can be easily extended with new type handlers;
 * Type handlers can allocate memory and register cleanup code to free;
 * Supports in, out, and inout parameters (e.g. with pointers or C++ references);
 * Supports multiple return values (e.g. due to out/inout parameters);
 * Supports wrapping of simple C++ classes;
 * Supports virtual methods in classes;
 * Supports reference counted classes and smart pointers;

Notable features NOT implemented:
 * Multiple inheritance; # relatively hard to support, little motivation
 * Exceptions.           # moderate difficulty, likely to be implemented sometime in the future

== Installation ==

NOTE: if checking out pybindgen from bazaar, do not forget to see the
file HACKING for additional instructions.

Before proceeding make sure the system requirements are met.  PyBindGen requires:

1- Python (http://www.python.org)
2- Python development files
3- A C/C++ Compilation tool chain
4- (optional) GCCXML and PyGCCXML (0.9.5 recommended) (http://www.language-binding.net/pygccxml/download.html)

PyBindGen uses WAF (http://code.google.com/p/waf/) as build system.
However, WAF does not have to be previously installed, as it is
shipped with PyBindGen in a single 'waf' script (but note bzr branches
don't come with WAF; see HACKING for instructions to obtain WAF).

To install PyBindGen, issue the following commands:

1. ./waf configure   # optionally you may add the option --prefix /foo/bar 
2. ./waf             # possible options: -jN for parallel build, -p for progress bar
3. ./waf check       # optional step, runs the unit tests
4. ./waf --examples  # optional step, compiles the examples
5. ./waf install     # may require sudo

If by any chance you have trouble with WAF and are just looking to
install PyBindGen, you should know that PyBindGen is entirely
self-contained in the 'pybindgen' directory.  You can simply
recursively copy the entire pybindgen folder into Python's
site-packages directory, and that's it!  PyBindGen is a pure Python
package and does not actually require a C/C++ compiler; it is only
used for code generation unit tests and compiling the example modules.

=== Win32 specific notes ===

Note that if you are compiling on win32, WAF will look for MSVC
(MicroSoft Visual C) by default and give up on finding a C/C++
compiler if not found.  If you do not have MSVC installed but instead
have MinGW or CygWin GCC, you have to tell WAF to look for GCC in the
configure stage:

1. ./waf configure --check-c-compiler=gcc --check-cxx-compiler=g++



== Documentation ==

The following documentation is available:

1. API docs (with introductory tutorial):
   http://pybindgen.googlecode.com/svn/trunk/apidocs/index.html
2. Many simple examples, in the 'examples' directory
3. Advanced examples in the unit tests (tests/)
4. The source code!