diff options
Diffstat (limited to 'lib/kross/python/cxx/README.html')
| -rw-r--r-- | lib/kross/python/cxx/README.html | 436 |
1 files changed, 436 insertions, 0 deletions
diff --git a/lib/kross/python/cxx/README.html b/lib/kross/python/cxx/README.html new file mode 100644 index 00000000..d698725a --- /dev/null +++ b/lib/kross/python/cxx/README.html @@ -0,0 +1,436 @@ +<html> + +<head> +<title>PyCXX README</title> + +<style> +H1, H2, H3, H4 {color: #000099; + background-color: lightskyblue} +h3 {position: relative; left: 20px} + +p {position: relative; left: 20px; margin-right: 20px} +pre {color: #0000cc; background-color: #eeeeee; position: relative; left: 40px; margin-right: 80px; + border-style: solid; border-color: black; border-width: thin} +kbd {color: #990000} +p cite, ol cite, ul cite {font-family: monospace; font-style: normal; font-size: normal} +li var, pre var, p var, kbd var {color: #009900; font-style: italic} +li samp, pre samp, p samp, kbd samp {color: #009900; font-weight: bold} +li p {position: relative; left: 0} +table { position: relative; left: 20px; border: solid #888888 1px; background-color: #eeeeee} +table th {border: solid #888888 1px; background-color: #88dd88; color: black} +table td {border: solid #888888 1px} +table td.code {border: solid #888888 1px;font-family: monospace; font-style: normal; font-size: normal} +p.param {background-color: #eeeeee; border-top: lightskyblue solid 4} +</style> +</head> + +<body> + +<h1>PyCXX -- Python C++ Extensions Support</h1> + +<h2>Installation using distutils</h2> + +<h3>Windows Installation and Demo</h3> +<ol> +<li>Fetch <a href="http://prdownloads.sourceforge.net/cxx/pycxx_5_3_1.tar.gz"> +http://prdownloads.sourceforge.net/cxx/pycxx_5_3_1.tar.gz</a> +<li>Expand the archive into a directory of your choosing C:\ for example. Note: WinZip can expand .tar.gz files. +<li>Install the PyCXX files: +<ol> +<li><pre>C:> cd \pycxx_5_3_1</pre> +<li><pre>C:\pycxx_5_3_1> python setup.py install</pre> +</ol> +<li>Install the PyCXX Demo: +<ol> +<li><pre>C:> cd \PYCXX_5_3_1\Demo</pre> +<li><pre>C:\PYCXX_5_3_1\Demo> python setup.py install</pre> +</ol> +<li>Run the demo: +<ol> +<li><pre>C:> python</pre> +<li><pre>>>> import CXX.example</pre> +<li><pre>>>> CXX.example.test()</pre> +<li><pre>>>> r = CXX.example.range( 11, 100, 13 )</pre> +<li><pre>>>> for i in r: print i</pre> +<li><pre>...</pre> +</ol> +</ul> +</ol> + + +<h3>Unix Installation and Demo</h3> +<p>Note: distutils is not available for Python 1.5.2</p> + +<ol> +<li>Fetch <a href="http://prdownloads.sourceforge.net/cxx/pycxx_5_3_1.tar.gz"> +http://prdownloads.sourceforge.net/cxx/PyCXX-V5.3.0.tar.gz</a> +<li>Login as root. root access is typically needed on Unix systems to install the PyCXX files into the Python directories. +<li>Expand the archive into a directory of your choosing ~\ for example. +<li>Install the PyCXX files: +<ol> +<li><pre># cd ~\PYCXX_5_3_1</pre> +<li><pre># python setup.py install</pre> +</ol> +<li>Install the PyCXX Demo: +<ol> +<li><pre># cd ~\PYCXX_5_3_1\Demo</pre> +<li><pre># python setup.py install</pre> +</ol> +<li>Run the demo: +<ol> +<li><pre>~ python</pre> +<li><pre>>>> import CXX.example</pre> +<li><pre>>>> CXX.example.test()</pre> +<li><pre>>>> r = CXX.example.range( 11, 100, 13 )</pre> +<li><pre>>>> for i in r: print i</pre> +<li><pre>...</pre> +</ol> +</ul> +</ol> + +<h2>Installation using Project and Makefile</h2> + +<p>If you cannot or do not wish to use the distutils methods to work with PyCXX a set +of Makefiles and Project files are provided.</p> + +<h3>Windows Installation and Demo</h3> +<p> +<ol> +<li>Fetch <a href="http://prdownloads.sourceforge.net/cxx/PyCXX-V5.3.0.tar.gz"> +http://prdownloads.sourceforge.net/cxx/pycxx_5_3_1.tar.gz</a> +<li>Expand the archive into a directory of your choosing C:\ for example. WinZip can expand .tar.gz files. +<li>Build the example. Using Microsoft Visual C++ 6.0 load the workspace corresponsing to the version of +Python you wish the work with. +<ul> +<li>example_py15.dsw - Python 1.5.2 +<li>example_py20.dsw - Python 2.0 and 2.0.1 +<li>example_py21.dsw - Python 2.1 and 2.1.1 +<li>example_py22.dsw - Python 2.2 and its maintanence release +<li>example_py23.dsw - Python 2.3 and its maintanence release +</ul> +<li>Run the example. (I'll assume you are testing Python 2.3) +<ul> +<li>cd c:\PYCXX_5_3_1\pyds23 +<li>c:\python21\python -c "import example;example.test()" +</ul> +</ol> +</p> +<h3>Unix Installation and Demo</h3> +<p> +<ol> +<li>Fetch <a href="http://prdownloads.sourceforge.net/cxx/PyCXX-V5.3.0.tar.gz"> +http://prdownloads.sourceforge.net/cxx/PyCXX-V5.3.0.tar.gz</a> +<li>Expand the archive into a directory of your choosing ~/ for example. +<li>Select to makefile for your system and python version. +<ul> +<li>example_freebsd_py15.mak - FreeBSD Python 1.5.2 (see <a href="#note_1_5_2">note</a> below) +<li>example_freebsd_py20.mak - FreeBSD Python 2.0, 2.0.1 +<li>example_freebsd_py21.mak - FreeBSD Python 2.1, 2.1.1 +<li>example_freebsd_py22.mak - FreeBSD Python 2.2 +<li>example_linux_py15.mak - Linux Python 1.5.2 +<li>example_linux_py20.mak - Linux Python 2.0, 2.0.1 +<li>example_linux_py21.mak - Linux Python 2.1, 2.1.1 +<li>example_linux_py22.mak - Linux Python 2.2 +</ul> +<li>Build the example. Use GNU make<br> +$ make -f <var>example-makefile</var> example.so +<li>Run the example.<br> +$ make -f <var>example-makefile</var> test +</ol> +</p> + +<p><a id="note_1_5_2">Note:</a> The Unix version of python 1.5.2 may need to be rebuilt so that C++ is support. +If you get reports of undefined symbols like cout or cerr then its likely that python +is not compiled and linked to support C and C++.</p> + +<p>To create a makefile for another vendors Unix follow these steps:</p> +<ol> +<li>copy one of the example make files above. +<li>edit the variables to match your Python installation and C++ compile needs +<li>Proceed to build and test as above. +</ol> +<p>Note: most of the makefile rules to build PyCXX and its example are contained in example_common.mak. +</p> + +<h2>Revision History</h2> +<h3>Version 5.3.1 (19-Jan-2005)</h3> +<p>Support GCC4 and Microsoft .NET 2003 aka MSVC 7.1 + +<h3>Version 5.3 (21-Oct-2004)</h3> +<p>String object now support python string and unicode string objects. +<p>Fix most bugs reported on SourceForge + +<h3>Version 5.2 (27-Nov-2003)</h3> +<p>PyCXX supports Python version 2.3, 2.2, 2.1, 2.0 and 1.5.2 on Windows and Unix.</p> +<p>Fixed problems with keyword functions.</p> +<p>Improve Extension API to give access to names and docs +<p>Support GCC 3.</p> +<p>Added support for custom Exceptions</p> +<p></p> + +<h3>Version 5.1 (2-Aug-2001)</h3> +<p>I'm using the name PyCXX for this package, CXX is far to close to a compilers name.</p> + +<p>PyCXX supports Python version 2.2, 2.1.1, 2.1, 2.0, 2.0.1 and 1.5.2 on Windows and Unix.</p> + +<p>New in this release:</p> +<ul> +<li>Support for the Windows Linker /DELAYLOAD feature. Enable this feature by +defining PY_WIN32_DELAYLOAD_PYTHON_DLL when compiling IndirectPythonInterface.cxx +<li>Remove "CXX/Array.hxx" and associated code - its does not belong in PyCXX +<li>Work on the docs. Mostly to clean up the HTML to allow more extensive work. +<li>Reformated the sources to a consistent style. The mix of styles and tabs sizes +was making working on the sources error prone. +<li>Added workaround to setup.py to allow GCC to compile c++ code. +<li>Added Microsoft Visual C++ 6.0 project files for 1.5, 2.0 and 2.1 builds +<li>Added Unix make files for Linux (tested on RedHat 7.1) and FreeBSD (tested on 4.3) +<li>Merged changes from Tom Malcolmson +</ul> + +<h3>(July 9, 2000)</h3> +<p>Renamed all header files to reflect the CXX include name space and that they are +C++ header files. +<p> +<table cellspacing=0 cellpadding=3px> +<tr><th>Old</th><th>New</th></tr> +<tr><td>#include "CXX_Config.h"</td><td>#include "CXX/Config.hxx"</td> +<tr><td>#include "CXX_Exception.h"</td><td>#include "CXX/Exception.hxx"</td> +<tr><td>#include "CXX_Extensions.h"</td><td>#include "CXX/Extensions.hxx"</td> +<tr><td>#include "CXX_Objects.h"</td><td>#include "CXX/Objects.hxx"</td> +</table> + +<h3>Version 5 (May 18, 2000)</h3> +<p>This version adds Distutils support for installation and some code cleanup.</p> + +<h3>Version 4 (October 11, 1999)</h3> + +<p>This version contains a massive revision to the part of CXX that supports creating +extension objects and extension modules. Barry Scott contributed these changes.</p> + +<p>CXX has always consisted of two parts: the basic CXX_Objects.h and the more +experimental CXX_Extensions.h. We will describe the changes to CXX_Objects first, and then +the changes to CXX_Extensions.h.</p> + +<h3>Changes to CXX_Objects</h3> + +<h4>1. Owned option eliminates need for FromAPI in most cases</h4> + +<p>Object's constructor from PyObject* and method set have a new (backward compatible) +signature:</p> + +<pre> +Object (PyObject* pyob, bool owned = false); +void set(PyObject* pyob, bool owned = false); +</pre> + +<p>Users may call these with owned = true if they own the reference pyob already and want +the Object instance to take over ownership.</p> + +<p>A new inline function Object asObject(PyObject* pyob) returns Object(pyob, true); thus, +one way to construct an object from a pointer returned by the Python API is to call +asObject on it. </p> + +<p>Previously a class FromAPI was provided to solve the problem of taking over an owned +reference. FromAPI will be eliminated in the next release. It is no longer used by CXX +itself or its demos. The new mechanism is much cleaner and more efficient.</p> + +<p>Other classes in CXX have been given the same "owned" option on their +constructors: Int, Float, Long, Complex, SeqBase<T>, Tuple, List, Dict, Module, +Callable.</p> + +<h4>2. Namespace support in compiler assumed</h4> + +<p>Since EGCS / GCC now supports namespaces and the standard library, the need for +CXX_config.h is almost gone. We have eliminated all the macros except for one obscure one +dealing with iterator traits in the standard library.</p> + +<h3>Changes to CXX_Extensions</h3> + +<p>The changes to CXX_Extensions.h are not backward compatible. However, they simplify +coding so much that we think it is worth the disruption.</p> + +<h4>1. Creating an extension module</h4> + +<p>To create an extension module, you inherit from class ExtensionModule templated on +yourself: In the constructor, you make calls to register methods of this class with Python +as extension module methods. In this example, two methods are added (this is a simplified +form of the example in Demo/example.cxx):</p> + +<pre>class example_module : public ExtensionModule<example_module> +{ +public: + example_module() + : ExtensionModule<example_module>( "example" ) + { + add_varargs_method("sum", &example_module::ex_sum, "sum(arglist) = sum of arguments"); + add_varargs_method("test", &example_module::ex_test, "test(arglist) runs a test suite"); + + initialize( "documentation for the example module" ); + } + + virtual ~example_module() {} + +private: + Object ex_sum (const Tuple &a) { ... } + Object ex_test( const Tuple &a) { ... } +}; +</pre> + +<p>To initialize the extension, you just instantiate one static instance (static so it +doesn't destroy itself!):</p> + +<pre> +void initexample() + { + static example_module* example = new example_module; + } +</pre> + +<p>The methods can be written to take Tuples as arguments and return Objects. If +exceptions occur they are trapped for you and a Python exception is generated. So, for +example, the implementation of ex_sum might be:</p> + +<pre> +Object ex_sum (const Tuple &a) + { + Float f(0.0); + for( int i = 0; i < a.length(); i++ ) + { + Float g(a[i]); + f = f + g; + } + return f; + } +</pre> + +<p>class ExtensionModule contains methods to return itself as a Module object, or to +return its dictionary.</p> + +<h4>Creating extension objects</h4> + +<p>Creating extension objects is of course harder since you must specify how the object +behaves and give it methods. This is shown in some detail in the example range.h and range.cxx, +with the test routine rangetest.cxx, in directory Demo.</p> + +<p>Here is a brief overview. You create a class that inherits from PythonExtension +templated upon itself. You override various methods from PythonExtension to implement +behaviors, such as getattr, sequence_item, etc. You can also add methods to the object +that are usable from Python using a similar scheme as for module methods above. </p> + +<p>One of the consequences of inheriting from PythonExtension is that you are inheriting +from PyObject itself. So your class is-a PyObject and instances of it can be passed to the +Python C API. Note: this example uses the namespace feature of CXX. The Py:: 's are not +required if you use the namespace instead.</p> + +<pre> +class range: public Py::PythonExtension<range> { +public: + ... constructors, etc. + + ... methods + // initializer, see below + static void init_type(); + // override functions from PythonExtension + virtual Py::Object repr(); + virtual Py::Object getattr( const char *name ); + + virtual int sequence_length(); + virtual Py::Object sequence_item( int i ); + virtual Py::Object sequence_concat( const Py::Object &j ); + virtual Py::Object sequence_slice( int i, int j ); + + // define python methods of this object + Py::Object amethod (const Py::Tuple& args); + Py::Object value (const Py::Tuple& args); + Py::Object assign (const Py::Tuple& args); +}; +</pre> + +<p> +To initialize the type you provide a static method that you can call from some module's +initializer. This method sets the name, doc string, and indicates which behaviors it +supports. It then adds the methods.</p> + +<pre> +void range::init_type() +{ + behaviors().name("range"); + behaviors().doc("range objects: start, stop, step"); + behaviors().supportRepr(); + behaviors().supportGetattr(); + behaviors().supportSequenceType(); + + add_varargs_method("amethod", &range::amethod, + "demonstrate how to document amethod"); + add_varargs_method("assign", &range::assign); + add_varargs_method("value", &range::value); +} +</pre> + +<h3>Version 3 (June 18, 1999)</h3> + +<p>1. CXX compiles with EGCS snapshot 19990616. EGCS requires a standard library class +random_access_iterator that is not yet available in some other compilers (such as Windows +VC6). Therefore a new switch:</p> + +<p>STANDARD_LIBRARY_HAS_ITERATOR_TRAITS</p> + +<p>has been added to CXX_Config.h that you may need to toggle if you get an error on the +two lines that mention random_access_iterator. The current definition is correct for VC6 +and EGCS-19990616. </p> + +<p>2. A new constructor was added to Module to allow construction from a string containing +the module name. A test was added for this to the demo.</p> + +<h3>Version 2 (Dec. 28, 1998)</h3> + +<p>Fixed definition of extension type to match 1.5.2. This version will presumably not +compile with older versions of Python. This can be fixed by using the previous version's +definition. I did not take the time to find out what these new "flags" are for +nor put in any methods to deal with them.</p> + +<h3>Version 1</h3> + +<p>This is an experimental set of files for supporting the creation of Python extensions +in C++. </p> + +<p>Documentation is in progress at <a href="http://xfiles.llnl.gov">http://xfiles.llnl.gov</a>. +</p> + +<p>To use CXX you use the header files in Include, such as CXX_Objects.h or +CXX_Extensions.h. You must include the sources in Src in your sources to supply parts of +the CXX classes required.</p> + +<p>A demo is included. The Setup file in this directory compiles this demo named +"example". To try the demo, which is also a test routine, you import example and +then execute:</p> + +<pre> +example.test() +</pre> + +<p>You can also play with the extension object whose constructor is named "range":</p> + +<pre> +s = range(1, 100, 2) +print s[2] # should print 5 +</pre> + +<p>Compilation with Microsoft Visual C++ 5.0 will succeed but only if you have Service +Pack 3 installed. Compilation has been known to succeed on a Unix system using KCC by +using:</p> + +<pre> +setenv CCC "KCC -x" +</pre> + +<p>before running makethis.py.</p> + +<p>There is also a python.cxx file for making a stand-alone Python containing this +example, as well as a similar file arraytest.cxx for testing Array.</p> + +<p>Comments to barry@barrys-emacs.org, please.</p> + +<p>Barry Scott</p> +</body> +</html> |