diff options
Diffstat (limited to 'libs/python/pyste/doc/running_pyste.html')
| -rw-r--r-- | libs/python/pyste/doc/running_pyste.html | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/libs/python/pyste/doc/running_pyste.html b/libs/python/pyste/doc/running_pyste.html new file mode 100644 index 000000000..9bd9a3aee --- /dev/null +++ b/libs/python/pyste/doc/running_pyste.html @@ -0,0 +1,200 @@ +<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> |