Dear All,
I start a new thread related to the wrapper generation, especially the
way the files needed by SWIG are created from OpenCascade headers. This
thread is an answer to Brian's request: "I have a some experience with
SWIG, but I've never used pygcc_xml. It would be useful if Thomas could
briefly describe the approach he's taking in making the wrappers. In
particular, assuming pygcc_xml can construct .i files covering the
common cases, how do you handle special cases? Do you just added a few
manually created .i files?".
This post maybe be quite important if you:
- wish to hack the SWIG files available in the source distribution,
- want to contribute to the project and help to make the pythonOCC
wrapper better.
Here is then a first small post that I will precise according to your
questions (if you have any).
1. The use of SWIG as the wrapper generator
There are many ways to access C++ libraries with Python. SIP,
Boost/Python, SWIG, ctypes etc. are possible solutions and the choice of
SWIG for pythonOCC was made in April or May 2008, after 3 months of
development with Boost/Python.
To generate a python wrapper to a C++ libray with SWIG, you need:
- the header files (in our case, the thousands of .hxx files located in
the $CASROOT/inc folder),
- the lib files (under Windows, availble in the $CASROOT/win32/lib folder),
- a set of SWIG ascii files. These file have the extension '.i'
2. Many python modules necessary to wrap many² OpenCascade packages
First let's be on the same definitions about modules and packages: an
OpenCascade *package* is a set of C++ classes/methods dedicated to a
specific field. For instance, AIS (Advanced Interactive System) is a
package that handle data visualization/selection. All the
classes/methods are described in a set of header files that being whit
AIS_. Just enter 'ls AIS_*.hxx' (under linux) or 'dir AIS_*.hxx'
(Windows) from the /inc directory, and you'll get 97 results
(OpenCascade 6.3.0):
22/08/2008 17:31 10 690 AIS_AngleDimension.hxx
22/08/2008 17:31 4 952 AIS_AttributeFilter.hxx
...
22/08/2008 17:31 1 704 AIS_TypeOfIso.hxx
22/08/2008 17:31 1 315 AIS_TypeOfPlane.hxx
All the classes/methods of AIS are wrapped in one python *module*, that
is, a python script named AIS.py and a library file (_AIS.pyd under
Windows or _AIS.so under Linux). To use AIS features, you just have to do:
>> from AIS import *
SWIG automatically created the AIS.py ans _AIS.so files from the
previous headers and a set of .i files:
AIS.i
AIS_dependencies.i
AIS_headers.i
pythonOCC is a bit special in the sense that all the .i files, for each
OpenCascade package, are generated automatically by a python script
named 'SWIG_generator.py'.
3. Special cases?
Brian asks a *very* good question: "how do you handle special cases?".
The question can be answered by this simple observation: pythonOCC
covers thousands of classes and dozain of thousands methods whereas the
SWIG_generator.py script is 'only' 867 lines of code. It means that
there are very very few special cases and that I tried to have the most
standardized solution as possible, to *avoid* special cases. However,
despite all my efforts, there are still a few 'special cases' that are
handled with if/then/else or try/except blocks in the generator script.
For instance, the line 297-298:
"""
if sys.platform=='win32' and module_name=='WNT':
return True
"""
deals with a special case.
It's important at this point to note that all special cases are handled
in the generator_script. There is no manual tweak of resulting SWIG
files. That means that the whole pythonOCC is obtained with only 3
python scripts: setup.py, environment.py, SWIG_generator.py and
Module.py. These 4 scripts are necessary and sufficient for compiling
pythonOCC.
Two pythonOCC modules are not wrappers to OpenCascade packages: Misc and
Visualization. I will write a special post for these strange modules.
4. The 4 python scripts
- environment.py : the file that contains platform specific paths. You
have to hack this file so that pythonOCC compile on your machine,
- setup.py : the distutil based compilation script. Will be replaced by
scons script as soon as it is ready.
- SWIG_generator.py: see point 3
- Modules.py: the list of OCC packages that will have to be wrapped by a
python module.
5. How are generated the .i files required by SWIG?
The method I used is unique, in the sense that I did not yet see any
other open source project using both GCCXML, pygccxml, pyplusplus and
SWIG. GCCXML/pygccxml is an amazing couple of tools:
- from a set of C++ headers, GCCXML produces an XML file that contains
a description of all classes/methods/functions/typedefs/enums etc. This
XML file is not really human readable and may be huge (upon 20Mb),
- pygccxml reads this XML file and allow an access to the information
with Python. With gccxml, you can for instance easily get the list of
classes that are defined in a set of C++ headers,
- pyplusplus is based on pygccxml and produces Boost/python C++ code
that can be compiled to create a python wrapper. I gave up with
Boost/Python after three months of use: it's a mess, each OpenCascade
package require at least 2 days of full-time work. Knowing that
OpenCascade is about 400 different packages, 400*2 = 800 days of work!
In other words, ice of the Antarctic would have disappear before
pythonOCC is released. SWIG is quite more simple to use and, most
important, it's really fast to develop a small python wrapper.
pyplusplus was then use to automatically generate, instead of Boost
code, SWIG compliant code: it's the SWIG_generator.py script.
This is the end of the first Part of this thread. Next chapter will be
dedicated to the process that go from an OpenCascade set of headers to 3
SWIG files: a loop over the MODULES list, class/method detection,
typedef and enums handling. I will also introduce you to an issue that
is still opened, and that explains why a few methods defined in
OpenCascade headers are not available in the pythonOCC wrapper.
Best Regards,
Thomas
_______________________________________________
Pythonocc-users mailing list
Pythonocc-users@gna.org
https://mail.gna.org/listinfo/pythonocc-users
