jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'document-python-options'

Browse source 
* document-python-options:
  Changes file update
  Python -newvwm command line option remains undocumented
  Document all the Python command line options
  Python command line options tidyup
  Remove redundant Python options: -nocastmode -nodirvtable -noextranative -nofastproxy
  Tidy up Python command line options help text
This commit is contained in:
William S Fulton 2018-12-18 19:54:25 +00:00
commit 61074d43ba
5 changed files with 79 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

4
CHANGES.current
View file

@ -184,7 +184,11 @@ Version 4.0.0 (in progress)
-newrepr -newrepr
-noaliasobj0 -noaliasobj0
-nobuildnone -nobuildnone
-nocastmode
-nodirvtable
-noextranative
-nofastinit -nofastinit
-nofastproxy
-nofastquery -nofastquery
-nomodern -nomodern
-nomodernargs -nomodernargs

3
Doc/Manual/Contents.html
View file

@ -1592,7 +1592,8 @@
<li><a href="Python.html#Python_nn9">Using your module</a> <li><a href="Python.html#Python_nn9">Using your module</a>
<li><a href="Python.html#Python_nn10">Compilation of C++ extensions</a> <li><a href="Python.html#Python_nn10">Compilation of C++ extensions</a>
<li><a href="Python.html#Python_nn11">Compiling for 64-bit platforms</a> <li><a href="Python.html#Python_nn11">Compiling for 64-bit platforms</a>
<li><a href="Python.html#Python_nn12">Building Python Extensions under Windows</a> <li><a href="Python.html#Python_nn12">Building Python extensions under Windows</a>
<li><a href="Python.html#Python_commandline">Additional Python commandline options</a>
</ul> </ul>
<li><a href="Python.html#Python_nn13">A tour of basic C/C++ wrapping</a> <li><a href="Python.html#Python_nn13">A tour of basic C/C++ wrapping</a>
<ul> <ul>

50
Doc/Manual/Python.html
View file

@ -21,7 +21,8 @@
<li><a href="#Python_nn9">Using your module</a> <li><a href="#Python_nn9">Using your module</a>
<li><a href="#Python_nn10">Compilation of C++ extensions</a> <li><a href="#Python_nn10">Compilation of C++ extensions</a>
<li><a href="#Python_nn11">Compiling for 64-bit platforms</a> <li><a href="#Python_nn11">Compiling for 64-bit platforms</a>
<li><a href="#Python_nn12">Building Python Extensions under Windows</a> <li><a href="#Python_nn12">Building Python extensions under Windows</a>
<li><a href="#Python_commandline">Additional Python commandline options</a>
</ul> </ul>
<li><a href="#Python_nn13">A tour of basic C/C++ wrapping</a> <li><a href="#Python_nn13">A tour of basic C/C++ wrapping</a>
<ul> <ul>
@ -798,7 +799,7 @@ and -m64 allow you to choose the desired binary format for your Python
extension. extension.
</p> </p>
<H3><a name="Python_nn12">38.2.8 Building Python Extensions under Windows</a></H3> <H3><a name="Python_nn12">38.2.8 Building Python extensions under Windows</a></H3>
<p> <p>
@ -810,6 +811,7 @@ are built with Visual Studio 2003), the standard <tt>python setup.py
build</tt> should just work. build</tt> should just work.
</p> </p>
<p> <p>
As of python2.5, the distutils support building extensions with MingGW out As of python2.5, the distutils support building extensions with MingGW out
of the box. Following the instruction here: of the box. Following the instruction here:
@ -927,6 +929,50 @@ SWIG Wiki</a>.
</p> </p>
<H3><a name="Python_commandline">38.2.9 Additional Python commandline options</a></H3>
<p>
The following table lists the additional commandline options available for the Python module. They can also be seen by using:
</p>
<div class="code"><pre>
swig -python -help
</pre></div>
<table summary="Python specific options">
<tr>
<th>Python specific options</th>
</tr>
<tr><td>-builtin </td><td>Create Python built-in types rather than proxy classes, for better performance</td></tr>
<tr><td>-castmode </td><td>Enable the casting mode, which allows implicit cast between types in Python</td></tr>
<tr><td>-debug-doxygen-parser </td><td>Display doxygen parser module debugging information</td></tr>
<tr><td>-debug-doxygen-translator </td><td>Display doxygen translator module debugging information</td></tr>
<tr><td>-dirvtable </td><td>Generate a pseudo virtual table for directors for faster dispatch</td></tr>
<tr><td>-doxygen </td><td>Convert C++ doxygen comments to pydoc comments in proxy classes</td></tr>
<tr><td>-extranative </td><td>Return extra native wrappers for C++ std containers wherever possible</td></tr>
<tr><td>-fastproxy </td><td>Use fast proxy mechanism for member methods</td></tr>
<tr><td>-globals &lt;name&gt; </td><td>Set &lt;name&gt; used to access C global variable (default: 'cvar')</td></tr>
<tr><td>-interface &lt;mod&gt;</td><td>Set low-level C/C++ module name to &lt;mod&gt; (default: module name prefixed by '_')</td></tr>
<tr><td>-keyword </td><td>Use keyword arguments</td></tr>
<tr><td>-nofastunpack </td><td>Use traditional UnpackTuple method to parse the argument functions</td></tr>
<tr><td>-noh </td><td>Don't generate the output header file</td></tr>
<tr><td>-noproxy </td><td>Don't generate proxy classes</td></tr>
<tr><td>-nortti </td><td>Disable the use of the native C++ RTTI with directors</td></tr>
<tr><td>-nothreads </td><td>Disable thread support for the entire interface</td></tr>
<tr><td>-olddefs </td><td>Keep the old method definitions when using -fastproxy</td></tr>
<tr><td>-py3 </td><td>Generate code with Python 3 specific features and syntax</td></tr>
<tr><td>-relativeimport </td><td>Use relative Python imports</td></tr>
<tr><td>-threads </td><td>Add thread support for all the interface</td></tr>
<tr><td>-O </td><td>Enable the following optimization options: -fastdispatch -fastproxy -fvirtual</td></tr>
</table>
<p>
Many of these options are covered later on and their use should become clearer by the time you have finished reading this section on SWIG and Python.
</p>
<H2><a name="Python_nn13">38.3 A tour of basic C/C++ wrapping</a></H2> <H2><a name="Python_nn13">38.3 A tour of basic C/C++ wrapping</a></H2>

5
Examples/test-suite/li_implicit.i
View file

@ -1,4 +1,7 @@
%module("nocastmode") li_implicit %module li_implicit
// Tests nocastmode
#pragma SWIG nowarn=SWIGWARN_PP_CPP_WARNING #pragma SWIG nowarn=SWIGWARN_PP_CPP_WARNING
%include implicit.i %include implicit.i

53
Source/Modules/python.cxx
View file

@ -106,35 +106,29 @@ enum autodoc_t {
static const char *usage1 = "\ static const char *usage1 = "\
Python Options (available with -python)\n\ Python Options (available with -python)\n\
-builtin - Create new python built-in types, rather than proxy classes, for better performance\n\ -builtin - Create Python built-in types rather than proxy classes, for better performance\n\
-castmode - Enable the casting mode, which allows implicit cast between types in python\n\ -castmode - Enable the casting mode, which allows implicit cast between types in Python\n\
-dirvtable - Generate a pseudo virtual table for directors for faster dispatch \n\
-doxygen - Convert C++ doxygen comments to pydoc comments in proxy classes \n\
-debug-doxygen-parser - Display doxygen parser module debugging information\n\ -debug-doxygen-parser - Display doxygen parser module debugging information\n\
-debug-doxygen-translator - Display doxygen translator module debugging information\n\ -debug-doxygen-translator - Display doxygen translator module debugging information\n\
-extranative - Return extra native C++ wraps for std containers when possible \n\ -dirvtable - Generate a pseudo virtual table for directors for faster dispatch\n\
-fastproxy - Use fast proxy mechanism for member methods \n\ -doxygen - Convert C++ doxygen comments to pydoc comments in proxy classes\n\
-globals <name> - Set <name> used to access C global variable [default: 'cvar']\n\ -extranative - Return extra native wrappers for C++ std containers wherever possible\n\
-interface <lib>- Set the lib name to <lib>\n\ -fastproxy - Use fast proxy mechanism for member methods\n\
-globals <name> - Set <name> used to access C global variable (default: 'cvar')\n\
-interface <mod>- Set low-level C/C++ module name to <mod> (default: module name prefixed by '_')\n\
-keyword - Use keyword arguments\n"; -keyword - Use keyword arguments\n";
static const char *usage2 = "\ static const char *usage2 = "\
-newvwm - New value wrapper mode, use only when everything else fails \n\ -nofastunpack - Use traditional UnpackTuple method to parse the argument functions\n\
-nocastmode - Disable the casting mode (default)\n\
-nodirvtable - Don't use the virtual table feature, resolve the python method each time (default)\n\
-noexcept - No automatic exception handling\n\
-noextranative - Don't use extra native C++ wraps for std containers when possible (default) \n\
-nofastunpack - Use traditional UnpackTuple method to parse the argument functions (default) \n\
-nofastproxy - Use traditional proxy mechanism for member methods (default) \n\
-noh - Don't generate the output header file\n"; -noh - Don't generate the output header file\n";
static const char *usage3 = "\ static const char *usage3 = "\
-noproxy - Don't generate proxy classes \n\ -noproxy - Don't generate proxy classes\n\
-nortti - Disable the use of the native C++ RTTI with directors\n\ -nortti - Disable the use of the native C++ RTTI with directors\n\
-nothreads - Disable thread support for the entire interface\n\ -nothreads - Disable thread support for the entire interface\n\
-olddefs - Keep the old method definitions when using -fastproxy\n\ -olddefs - Keep the old method definitions when using -fastproxy\n\
-py3 - Generate code with Python 3 specific features and syntax\n\ -py3 - Generate code with Python 3 specific features and syntax\n\
-relativeimport - Use relative python imports \n\ -relativeimport - Use relative Python imports\n\
-threads - Add thread support for all the interface\n\ -threads - Add thread support for all the interface\n\
-O - Enable the following optimization options: \n\ -O - Enable the following optimization options:\n\
-fastdispatch -fastproxy -fvirtual\n\ -fastdispatch -fastproxy -fvirtual\n\
\n"; \n";
@ -351,9 +345,6 @@ public:
} else if (strcmp(argv[i], "-dirvtable") == 0) { } else if (strcmp(argv[i], "-dirvtable") == 0) {
dirvtable = 1; dirvtable = 1;
Swig_mark_arg(i); Swig_mark_arg(i);
} else if (strcmp(argv[i], "-nodirvtable") == 0) {
dirvtable = 0;
Swig_mark_arg(i);
} else if (strcmp(argv[i], "-doxygen") == 0) { } else if (strcmp(argv[i], "-doxygen") == 0) {
doxygen = 1; doxygen = 1;
scan_doxygen_comments = 1; scan_doxygen_comments = 1;
@ -370,29 +361,21 @@ public:
} else if (strcmp(argv[i], "-fastproxy") == 0) { } else if (strcmp(argv[i], "-fastproxy") == 0) {
fastproxy = 1; fastproxy = 1;
Swig_mark_arg(i); Swig_mark_arg(i);
} else if (strcmp(argv[i], "-nofastproxy") == 0) {
fastproxy = 0;
Swig_mark_arg(i);
} else if (strcmp(argv[i], "-olddefs") == 0) { } else if (strcmp(argv[i], "-olddefs") == 0) {
olddefs = 1; olddefs = 1;
Swig_mark_arg(i); Swig_mark_arg(i);
} else if (strcmp(argv[i], "-castmode") == 0) { } else if (strcmp(argv[i], "-castmode") == 0) {
castmode = 1; castmode = 1;
Swig_mark_arg(i); Swig_mark_arg(i);
} else if (strcmp(argv[i], "-nocastmode") == 0) {
castmode = 0;
Swig_mark_arg(i);
} else if (strcmp(argv[i], "-extranative") == 0) { } else if (strcmp(argv[i], "-extranative") == 0) {
extranative = 1; extranative = 1;
Swig_mark_arg(i); Swig_mark_arg(i);
} else if (strcmp(argv[i], "-noextranative") == 0) {
extranative = 0;
Swig_mark_arg(i);
} else if (strcmp(argv[i], "-noh") == 0) { } else if (strcmp(argv[i], "-noh") == 0) {
no_header_file = 1; no_header_file = 1;
Swig_mark_arg(i); Swig_mark_arg(i);
} else if (strcmp(argv[i], "-newvwm") == 0) { } else if (strcmp(argv[i], "-newvwm") == 0) {
/* Turn on new value wrapper mode */ /* Turn on new value wrapper mode */
/* Undocumented option, did have -help text: New value wrapper mode, use only when everything else fails */
Swig_value_wrapper_mode(1); Swig_value_wrapper_mode(1);
no_header_file = 1; no_header_file = 1;
Swig_mark_arg(i); Swig_mark_arg(i);
@ -435,8 +418,12 @@ public:
strcmp(argv[i], "-newrepr") == 0 || strcmp(argv[i], "-newrepr") == 0 ||
strcmp(argv[i], "-noaliasobj0") == 0 || strcmp(argv[i], "-noaliasobj0") == 0 ||
strcmp(argv[i], "-nobuildnone") == 0 || strcmp(argv[i], "-nobuildnone") == 0 ||
strcmp(argv[i], "-nocastmode") == 0 ||
strcmp(argv[i], "-nocppcast") == 0 || strcmp(argv[i], "-nocppcast") == 0 ||
strcmp(argv[i], "-nodirvtable") == 0 ||
strcmp(argv[i], "-noextranative") == 0 ||
strcmp(argv[i], "-nofastinit") == 0 || strcmp(argv[i], "-nofastinit") == 0 ||
strcmp(argv[i], "-nofastproxy") == 0 ||
strcmp(argv[i], "-nofastquery") == 0 || strcmp(argv[i], "-nofastquery") == 0 ||
strcmp(argv[i], "-nomodern") == 0 || strcmp(argv[i], "-nomodern") == 0 ||
strcmp(argv[i], "-nomodernargs") == 0 || strcmp(argv[i], "-nomodernargs") == 0 ||
@ -507,13 +494,15 @@ public:
castmode = 1; castmode = 1;
} }
if (Getattr(options, "nocastmode")) { if (Getattr(options, "nocastmode")) {
castmode = 0; Printf(stderr, "Deprecated module option: %s. This option is no longer supported.\n", "nocastmode");
SWIG_exit(EXIT_FAILURE);
} }
if (Getattr(options, "extranative")) { if (Getattr(options, "extranative")) {
extranative = 1; extranative = 1;
} }
if (Getattr(options, "noextranative")) { if (Getattr(options, "noextranative")) {
extranative = 0; Printf(stderr, "Deprecated module option: %s. This option is no longer supported.\n", "noextranative");
SWIG_exit(EXIT_FAILURE);
} }
if (Getattr(options, "outputtuple")) { if (Getattr(options, "outputtuple")) {
Printf(stderr, "Deprecated module option: %s. This option is no longer supported.\n", "outputtuple"); Printf(stderr, "Deprecated module option: %s. This option is no longer supported.\n", "outputtuple");