| <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> |