mirror of
https://github.com/boostorg/python.git
synced 2026-01-20 16:52:15 +00:00
e70bbe4791
Also port some "glaringly obvious" bugfixes from HEAD. Hope it doesn't cause problems. [SVN r35237]
201 lines
9.9 KiB
HTML
201 lines
9.9 KiB
HTML
<html>
|
|
<head>
|
|
<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
|
|
<title>Running Pyste</title>
|
|
<link rel="stylesheet" href="theme/style.css" type="text/css">
|
|
<link rel="prev" href="introduction.html">
|
|
<link rel="next" href="the_interface_files.html">
|
|
</head>
|
|
<body>
|
|
<table width="100%" height="48" border="0" cellspacing="2">
|
|
<tr>
|
|
<td><img src="../../../../boost.png">
|
|
</td>
|
|
<td width="85%">
|
|
<font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Running Pyste</b></font>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<table border="0">
|
|
<tr>
|
|
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
|
|
<td width="30"><a href="introduction.html"><img src="theme/l_arr.gif" border="0"></a></td>
|
|
<td width="20"><a href="the_interface_files.html"><img src="theme/r_arr.gif" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
To run Pyste, you will need:</p>
|
|
<ul><li>Python 2.2, available at <a href="http://www.python.org">
|
|
python's website</a>.</li><li>The great <a href="http://effbot.org">
|
|
elementtree</a> library, from Fredrik Lundh.</li><li>The excellent <a href="http://www.gccxml.org">
|
|
GCCXML</a>, from Brad King.</li></ul><p>
|
|
Installation for the tools is available in their respective webpages.</p>
|
|
<table width="80%" border="0" align="center">
|
|
<tr>
|
|
<td class="note_box">
|
|
|
|
<img src="theme/note.gif"></img> <a href="http://www.gccxml.org">
|
|
GCCXML</a> must be accessible in the PATH environment variable, so
|
|
that Pyste can call it. How to do this varies from platform to platform.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<a name="ok__now_what_"></a><h2>Ok, now what?</h2><p>
|
|
Well, now let's fire it up:</p>
|
|
<code><pre>
|
|
|
|
>python pyste.py
|
|
|
|
Pyste version 0.9.26
|
|
|
|
Usage:
|
|
pyste [options] interface-files
|
|
|
|
where options are:
|
|
--module=<name> The name of the module that will be generated;
|
|
defaults to the first interface filename, without
|
|
the extension.
|
|
-I <path> Add an include path
|
|
-D <symbol> Define symbol
|
|
--multiple Create various cpps, instead of only one
|
|
(useful during development)
|
|
--out=<name> Specify output filename (default: <module>.cpp)
|
|
in --multiple mode, this will be a directory
|
|
--no-using Do not declare "using namespace boost";
|
|
use explicit declarations instead
|
|
--pyste-ns=<name> Set the namespace where new types will be declared;
|
|
default is the empty namespace
|
|
--debug Writes the xml for each file parsed in the current
|
|
directory
|
|
--cache-dir=<dir> Directory for cache files (speeds up future runs)
|
|
--only-create-cache Recreates all caches (doesn't generate code).
|
|
--generate-main Generates the _main.cpp file (in multiple mode)
|
|
--file-list A file with one pyste file per line. Use as a
|
|
substitute for passing the files in the command
|
|
line.
|
|
-h, --help Print this help and exit
|
|
-v, --version Print version information
|
|
|
|
|
|
</pre></code><p>
|
|
Options explained:</p>
|
|
<p>
|
|
The <tt>-I</tt> and <tt>-D</tt> are preprocessor flags, which are needed by <a href="http://www.gccxml.org">
|
|
GCCXML</a> to parse
|
|
the header files correctly and by Pyste to find the header files declared in the
|
|
interface files.</p>
|
|
<p>
|
|
<tt>--out</tt> names the output file (default: <tt><module>.cpp</tt>), or in multiple mode,
|
|
names a output directory for the files (default: <tt><module></tt>).</p>
|
|
<p>
|
|
<tt>--no-using</tt> tells Pyste to don't declare "<tt>using namespace boost;</tt>" in the
|
|
generated cpp, using the namespace boost::python explicitly in all declarations.
|
|
Use only if you're having a name conflict in one of the files.</p>
|
|
<p>
|
|
Use <tt>--pyste-ns</tt> to change the namespace where new types are declared (for
|
|
instance, the virtual wrappers). Use only if you are having any problems. By
|
|
default, Pyste uses the empty namespace.</p>
|
|
<p>
|
|
<tt>--debug</tt> will write in the current directory a xml file as outputted by <a href="http://www.gccxml.org">
|
|
GCCXML</a>
|
|
for each header parsed. Useful for bug reports.</p>
|
|
<p>
|
|
<tt>--file-list</tt> names a file where each line points to a Pyste file. Use this instead
|
|
to pass the pyste files if you have a lot of them and your shell has some command line
|
|
size limit.</p>
|
|
<p>
|
|
The other options are explained below, in <a href="#multiple_mode">
|
|
<b>Multiple Mode</b></a> and
|
|
<a href="#cache">
|
|
<b>Cache</b></a>.</p>
|
|
<p>
|
|
<tt>-h, --help, -v, --version</tt> are self-explaining, I believe. ;)</p>
|
|
<p>
|
|
So, the usage is simple enough:</p>
|
|
<code><pre>>python pyste.py --module=mymodule file.pyste file2.pyste ...</pre></code><p>
|
|
will generate a file <tt>mymodule.cpp</tt> in the same dir where the command was
|
|
executed. Now you can compile the file using the same instructions of the
|
|
<a href="../../doc/tutorial/doc/html/python/hello.html">
|
|
tutorial</a>. </p>
|
|
<a name="wait____how_do_i_set_those_i_and_d_flags_"></a><h2>Wait... how do I set those I and D flags?</h2><p>
|
|
Don't worry: normally <a href="http://www.gccxml.org">
|
|
GCCXML</a> is already configured correctly for your plataform,
|
|
so the search path to the standard libraries and the standard defines should
|
|
already be set. You only have to set the paths to other libraries that your code
|
|
needs, like Boost, for example.</p>
|
|
<p>
|
|
Plus, Pyste automatically uses the contents of the environment variable
|
|
<tt>INCLUDE</tt> if it exists. Visual C++ users should run the <tt>Vcvars32.bat</tt> file,
|
|
which for Visual C++ 6 is normally located at:</p>
|
|
<code><pre>
|
|
<span class=identifier>C</span><span class=special>:\</span><span class=identifier>Program </span><span class=identifier>Files</span><span class=special>\</span><span class=identifier>Microsoft </span><span class=identifier>Visual </span><span class=identifier>Studio</span><span class=special>\</span><span class=identifier>VC98</span><span class=special>\</span><span class=identifier>bin</span><span class=special>\</span><span class=identifier>Vcvars32</span><span class=special>.</span><span class=identifier>bat
|
|
</span></pre></code>
|
|
<p>
|
|
with that, you should have little trouble setting up the flags.</p>
|
|
<table width="80%" border="0" align="center">
|
|
<tr>
|
|
<td class="note_box">
|
|
<img src="theme/note.gif"></img><b>A note about Psyco</b><br><br>
|
|
Although you don't have to install <a href="http://psyco.sourceforge.net/">
|
|
Psyco</a> to
|
|
use Pyste, if you do, Pyste will make use of it to speed up the wrapper
|
|
generation. Speed ups of 30% can be achieved, so it's highly recommended.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<a name="multiple_mode"></a><h2>Multiple Mode</h2><p>
|
|
The multiple mode is useful in large projects, where the presence of multiple
|
|
classes in a single file makes the compilation unpractical (excessive memory
|
|
usage, mostly). </p>
|
|
<p>
|
|
The solution is make Pyste generate multiple files, more specifically one cpp
|
|
file for each Pyste file. This files will contain a function named after the
|
|
file, for instance Export_MyPysteFile, which will contain all the code to export
|
|
the classes, enums, etc. You can pass as much files as you want this way:</p>
|
|
<code><pre>>python pyste.py --module=mymodule file1.pyste file2.pyste</pre></code><p>
|
|
This will create the files <tt>mymodule/file1.cpp</tt> and <tt>mymodule/file2.cpp</tt>. You
|
|
can then later do:</p>
|
|
<code><pre>>python pyste.py --module=mymodule file3.pyste</pre></code><p>
|
|
and <tt>mymodule/file3.cpp</tt> will be generated.</p>
|
|
<p>
|
|
But compiling and linking this files won't be sufficient to generate your
|
|
extension. You have to also generate a file named <tt>main.cpp</tt>; call pyste with
|
|
<b>all</b> the Pyste files of your extension, and use the <tt>--generate-main</tt> option:</p>
|
|
<code><pre>>python pyste.py --module=mymodule --generate-main file1.pyste file2.pyste file3.pyste</pre></code><p>
|
|
Now compile and link all this files together and your extension is ready for
|
|
use.</p>
|
|
<a name="cache"></a><h2>Cache</h2><p>
|
|
Pyste now supports a form of cache, which is a way to speed up the code
|
|
generation. Most of the time that Pyste takes to generate the code comes from
|
|
having to execute <a href="http://www.gccxml.org">
|
|
GCCXML</a> (since being a front-end to GCC, it has to compile the
|
|
header files) and reading back the XML generated. </p>
|
|
<p>
|
|
When you use the <tt>--cache-dir=<dir></tt> option, Pyste will dump in the specified
|
|
directory the generated XMLs to a file named after the Pyste file, with the
|
|
extension <tt>.pystec</tt>. The next time you run with this option, Pyste will use
|
|
the cache, instead of calling <a href="http://www.gccxml.org">
|
|
GCCXML</a> again:</p>
|
|
<code><pre>>python pyste.py --module=mymodule --cache-dir=cache file1.pyste</pre></code><p>
|
|
Will generate <tt>file1.cpp</tt> and <tt>cache/file1.pystec</tt>. Next time you execute
|
|
this command, the cache file will be used. Note that Pyste doesn't do any check
|
|
to ensure that the cache is up to date, but you can configure your build system to do that for you.</p>
|
|
<p>
|
|
When you run Pyste with <tt>--only-create-cache</tt>, all the cache files will be
|
|
created again, but no code will be generated.</p>
|
|
<table border="0">
|
|
<tr>
|
|
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
|
|
<td width="30"><a href="introduction.html"><img src="theme/l_arr.gif" border="0"></a></td>
|
|
<td width="20"><a href="the_interface_files.html"><img src="theme/r_arr.gif" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 2002-2003 Joel de Guzman<br><br>
|
|
<font size="2">Distributed under
|
|
the Boost Software License, Version 1.0. (See accompanying file
|
|
LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) </font> </p>
|
|
</body>
|
|
</html>
|