readme

彩信浏览器

This directory contains the source for pyambulant, a two-way bridge between
Python and C++ to allow embedding Ambulant in Python as well as extending
Ambulant from Python.

If you want to simply use the bridge to enable using Ambulant from
within a Python program (as opposed to extend or modify it): head
straight for the "player_pyqt" subdirectory which has an example
and some instructions. There is one thing you may have to change here
in this directory before the bridge will build correctly: setup.py
has some hardcoded Ambulant configure options (qt, sdl, ffmpeg) that
you may need to adjust. Also, library pathnames may be slightly
different on your system (Mac uses "-lqt", Linux uses "-lqt-mt").

The bridge is automatically generated by parsing the Ambulant header files
and generating the bridge methods and objects from the function and method
signatures. As of this writing (January 2006) generating the bridge requires
a development-Python (from the svn repository) because it uses a version of
the bgen tool that is newer than in the most recent Python distribution.
Once the bridge has been created it can be compiled for a normal distribution
Python, though.

Whenever the Ambulant header files have changed significantly the bridge
source code will have to be rebuilt. This is done by running
"make regenerate-pyambulant". This depends on a number of Python sourcefiles
that may also need some adjustments, see below.

The source files in this directory are:

bgenBackSupport.py and bgenCxxSupport.py:
	These are extensions for bgen to allow it to generate a C++ bridge
	(in stead of a C bridge). These will probably not need modification
	when the Ambulant headers change.
setup.py:
	Standard Python distutils build script, which builds the extension module.
	May need modifications if new libraries are added, etc.
genobjects.py:
	Script that governs which C++ header files are read, which C++ classes are
	Python-visible, their Python name and (optionally) their Python inheritance.
	May need to be modified if new classes are added that need to be visible
	in Python.
ambulantgen.py, ambulantincludegen.py, ambulantobjgen.py and ambulanttypetest.py:
	Intermediate files, may or may not be available. Leave them alone.
ambulantsupport.py:
	Second pass of the generation process, contains the type declarations for
	types (and classes) that are bridged between C++ and Python. This file
	needs to be adapted when new C++ types are to be bridged to Python. There's
	also a section that lists synonym types, because bgen does not handle
	namespaces optimally.
	
	In addition, it contains the "othermethods" initializations for the
	reverse bridge (calling Python objects from C++). As the C++ bridging
	objects need to completely implement the corresponding virtual classes
	any methods that are not being bridged need dummy (or workaround)
	implementations. Add them here if you get compiler error messages
	about incomplete classes while compiling ambulantinterface.cpp.
	
	Finally this file drives the C++ code generation process, so if additional
	header files need to be included or something else needs to be tweaked this
	is the place to look.
ambulantscan.py:
	First pass of the generation process: parsing the header files, filtering
	the classes, methods and functions and transforming C++ calling sequences
	to more Pythonesque calling sequences. the "input" variable in main()
	contains the list of input files, which may need to be extended if new
	header files are added.
	
	The makeblacklistnames() method returns a list of methods that should not
	be bridged.
	
	The makeblacklisttypes() method returns a list of types that should not be
	bridged to Python. Note that not bridging a type automatically means that any
	C++ method or function that uses this type as argument or return value will
	also be blacklisted automatically.
	
	Makegreylist() returns a list of (ifdef, methodlist) pairs. The methods in
	methodlist will be generated, but bracketed by the given ifdef. Use this to
	generate methods only whenever some C preprocessor symbol is defined.
	
	Makerepairinstructions() returns the list of function call signature modifications
	that needs to be made. This is a very powerful mechanism, but also rather complicated.
	Check what is there and look at ambulantgen.py, and maybe you will understand
	how it works.
ambulantmodule.h and ambulantmodule.cpp:
	Definitions and implementation of the forward bridge, which allows calling
	C++ methods (and subclassing C++ classes) from Python. Generated, don't touch.
ambulantinterface.h and ambulantinterface.cpp:
	Definitions and implementation of the reverse bridge, which allows calling Python
	methods (and subclassing Python classes) from C++. Generated, don't touch.
ambulantutilities.h and ambulantutilities.cpp:
	Hand-written code (and definitions) for bridging a couple of types that need
	some special handling. Will probably not need modification often, unless you need
	support for bridging new "difficult" types.