boost_1_45_0/libs/python/pyste/doc/running_pyste.html - nest-learning-thermostat/5.1.5/boost - Git at Google

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

 &gt;python pyste.py

 Pyste version 0.9.26

 Usage:
     pyste [options] interface-files

 where options are:
     --module=&lt;name&gt;         The name of the module that will be generated;
                             defaults to the first interface filename, without
                             the extension.
     -I &lt;path&gt;               Add an include path
     -D &lt;symbol&gt;             Define symbol
     --multiple              Create various cpps, instead of only one
                             (useful during development)
     --out=&lt;name&gt;            Specify output filename (default: &lt;module&gt;.cpp)
                             in --multiple mode, this will be a directory
     --no-using              Do not declare &quot;using namespace boost&quot;;
                             use explicit declarations instead
     --pyste-ns=&lt;name&gt;       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=&lt;dir&gt;       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>&lt;module&gt;.cpp</tt>), or in multiple mode,
 names a output directory for the files (default: <tt>&lt;module&gt;</tt>).</p>
 <p>
 <tt>--no-using</tt> tells Pyste to don't declare &quot;<tt>using namespace boost;</tt>&quot; 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>&gt;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>&gt;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>&gt;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>&gt;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=&lt;dir&gt;</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>&gt;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 &copy; 2003 Bruno da Silva de Oliveira<br>Copyright &copy; 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>
	<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>