1 | <html> |
---|
2 | <head> |
---|
3 | <!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> |
---|
4 | <title>Running Pyste</title> |
---|
5 | <link rel="stylesheet" href="theme/style.css" type="text/css"> |
---|
6 | <link rel="prev" href="introduction.html"> |
---|
7 | <link rel="next" href="the_interface_files.html"> |
---|
8 | </head> |
---|
9 | <body> |
---|
10 | <table width="100%" height="48" border="0" cellspacing="2"> |
---|
11 | <tr> |
---|
12 | <td><img src="../../../../boost.png"> |
---|
13 | </td> |
---|
14 | <td width="85%"> |
---|
15 | <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Running Pyste</b></font> |
---|
16 | </td> |
---|
17 | </tr> |
---|
18 | </table> |
---|
19 | <br> |
---|
20 | <table border="0"> |
---|
21 | <tr> |
---|
22 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
---|
23 | <td width="30"><a href="introduction.html"><img src="theme/l_arr.gif" border="0"></a></td> |
---|
24 | <td width="20"><a href="the_interface_files.html"><img src="theme/r_arr.gif" border="0"></a></td> |
---|
25 | </tr> |
---|
26 | </table> |
---|
27 | <p> |
---|
28 | To run Pyste, you will need:</p> |
---|
29 | <ul><li>Python 2.2, available at <a href="http://www.python.org"> |
---|
30 | python's website</a>.</li><li>The great <a href="http://effbot.org"> |
---|
31 | elementtree</a> library, from Fredrik Lundh.</li><li>The excellent <a href="http://www.gccxml.org"> |
---|
32 | GCCXML</a>, from Brad King.</li></ul><p> |
---|
33 | Installation for the tools is available in their respective webpages.</p> |
---|
34 | <table width="80%" border="0" align="center"> |
---|
35 | <tr> |
---|
36 | <td class="note_box"> |
---|
37 | |
---|
38 | <img src="theme/note.gif"></img> <a href="http://www.gccxml.org"> |
---|
39 | GCCXML</a> must be accessible in the PATH environment variable, so |
---|
40 | that Pyste can call it. How to do this varies from platform to platform. |
---|
41 | </td> |
---|
42 | </tr> |
---|
43 | </table> |
---|
44 | <a name="ok__now_what_"></a><h2>Ok, now what?</h2><p> |
---|
45 | Well, now let's fire it up:</p> |
---|
46 | <code><pre> |
---|
47 | |
---|
48 | >python pyste.py |
---|
49 | |
---|
50 | Pyste version 0.9.26 |
---|
51 | |
---|
52 | Usage: |
---|
53 | pyste [options] interface-files |
---|
54 | |
---|
55 | where options are: |
---|
56 | --module=<name> The name of the module that will be generated; |
---|
57 | defaults to the first interface filename, without |
---|
58 | the extension. |
---|
59 | -I <path> Add an include path |
---|
60 | -D <symbol> Define symbol |
---|
61 | --multiple Create various cpps, instead of only one |
---|
62 | (useful during development) |
---|
63 | --out=<name> Specify output filename (default: <module>.cpp) |
---|
64 | in --multiple mode, this will be a directory |
---|
65 | --no-using Do not declare "using namespace boost"; |
---|
66 | use explicit declarations instead |
---|
67 | --pyste-ns=<name> Set the namespace where new types will be declared; |
---|
68 | default is the empty namespace |
---|
69 | --debug Writes the xml for each file parsed in the current |
---|
70 | directory |
---|
71 | --cache-dir=<dir> Directory for cache files (speeds up future runs) |
---|
72 | --only-create-cache Recreates all caches (doesn't generate code). |
---|
73 | --generate-main Generates the _main.cpp file (in multiple mode) |
---|
74 | --file-list A file with one pyste file per line. Use as a |
---|
75 | substitute for passing the files in the command |
---|
76 | line. |
---|
77 | -h, --help Print this help and exit |
---|
78 | -v, --version Print version information |
---|
79 | |
---|
80 | |
---|
81 | </pre></code><p> |
---|
82 | Options explained:</p> |
---|
83 | <p> |
---|
84 | The <tt>-I</tt> and <tt>-D</tt> are preprocessor flags, which are needed by <a href="http://www.gccxml.org"> |
---|
85 | GCCXML</a> to parse |
---|
86 | the header files correctly and by Pyste to find the header files declared in the |
---|
87 | interface files.</p> |
---|
88 | <p> |
---|
89 | <tt>--out</tt> names the output file (default: <tt><module>.cpp</tt>), or in multiple mode, |
---|
90 | names a output directory for the files (default: <tt><module></tt>).</p> |
---|
91 | <p> |
---|
92 | <tt>--no-using</tt> tells Pyste to don't declare "<tt>using namespace boost;</tt>" in the |
---|
93 | generated cpp, using the namespace boost::python explicitly in all declarations. |
---|
94 | Use only if you're having a name conflict in one of the files.</p> |
---|
95 | <p> |
---|
96 | Use <tt>--pyste-ns</tt> to change the namespace where new types are declared (for |
---|
97 | instance, the virtual wrappers). Use only if you are having any problems. By |
---|
98 | default, Pyste uses the empty namespace.</p> |
---|
99 | <p> |
---|
100 | <tt>--debug</tt> will write in the current directory a xml file as outputted by <a href="http://www.gccxml.org"> |
---|
101 | GCCXML</a> |
---|
102 | for each header parsed. Useful for bug reports.</p> |
---|
103 | <p> |
---|
104 | <tt>--file-list</tt> names a file where each line points to a Pyste file. Use this instead |
---|
105 | to pass the pyste files if you have a lot of them and your shell has some command line |
---|
106 | size limit.</p> |
---|
107 | <p> |
---|
108 | The other options are explained below, in <a href="#multiple_mode"> |
---|
109 | <b>Multiple Mode</b></a> and |
---|
110 | <a href="#cache"> |
---|
111 | <b>Cache</b></a>.</p> |
---|
112 | <p> |
---|
113 | <tt>-h, --help, -v, --version</tt> are self-explaining, I believe. ;)</p> |
---|
114 | <p> |
---|
115 | So, the usage is simple enough:</p> |
---|
116 | <code><pre>>python pyste.py --module=mymodule file.pyste file2.pyste ...</pre></code><p> |
---|
117 | will generate a file <tt>mymodule.cpp</tt> in the same dir where the command was |
---|
118 | executed. Now you can compile the file using the same instructions of the |
---|
119 | <a href="../../doc/tutorial/doc/html/python/hello.html"> |
---|
120 | tutorial</a>. </p> |
---|
121 | <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> |
---|
122 | Don't worry: normally <a href="http://www.gccxml.org"> |
---|
123 | GCCXML</a> is already configured correctly for your plataform, |
---|
124 | so the search path to the standard libraries and the standard defines should |
---|
125 | already be set. You only have to set the paths to other libraries that your code |
---|
126 | needs, like Boost, for example.</p> |
---|
127 | <p> |
---|
128 | Plus, Pyste automatically uses the contents of the environment variable |
---|
129 | <tt>INCLUDE</tt> if it exists. Visual C++ users should run the <tt>Vcvars32.bat</tt> file, |
---|
130 | which for Visual C++ 6 is normally located at:</p> |
---|
131 | <code><pre> |
---|
132 | <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 |
---|
133 | </span></pre></code> |
---|
134 | <p> |
---|
135 | with that, you should have little trouble setting up the flags.</p> |
---|
136 | <table width="80%" border="0" align="center"> |
---|
137 | <tr> |
---|
138 | <td class="note_box"> |
---|
139 | <img src="theme/note.gif"></img><b>A note about Psyco</b><br><br> |
---|
140 | Although you don't have to install <a href="http://psyco.sourceforge.net/"> |
---|
141 | Psyco</a> to |
---|
142 | use Pyste, if you do, Pyste will make use of it to speed up the wrapper |
---|
143 | generation. Speed ups of 30% can be achieved, so it's highly recommended. |
---|
144 | </td> |
---|
145 | </tr> |
---|
146 | </table> |
---|
147 | <a name="multiple_mode"></a><h2>Multiple Mode</h2><p> |
---|
148 | The multiple mode is useful in large projects, where the presence of multiple |
---|
149 | classes in a single file makes the compilation unpractical (excessive memory |
---|
150 | usage, mostly). </p> |
---|
151 | <p> |
---|
152 | The solution is make Pyste generate multiple files, more specifically one cpp |
---|
153 | file for each Pyste file. This files will contain a function named after the |
---|
154 | file, for instance Export_MyPysteFile, which will contain all the code to export |
---|
155 | the classes, enums, etc. You can pass as much files as you want this way:</p> |
---|
156 | <code><pre>>python pyste.py --module=mymodule file1.pyste file2.pyste</pre></code><p> |
---|
157 | This will create the files <tt>mymodule/file1.cpp</tt> and <tt>mymodule/file2.cpp</tt>. You |
---|
158 | can then later do:</p> |
---|
159 | <code><pre>>python pyste.py --module=mymodule file3.pyste</pre></code><p> |
---|
160 | and <tt>mymodule/file3.cpp</tt> will be generated.</p> |
---|
161 | <p> |
---|
162 | But compiling and linking this files won't be sufficient to generate your |
---|
163 | extension. You have to also generate a file named <tt>main.cpp</tt>; call pyste with |
---|
164 | <b>all</b> the Pyste files of your extension, and use the <tt>--generate-main</tt> option:</p> |
---|
165 | <code><pre>>python pyste.py --module=mymodule --generate-main file1.pyste file2.pyste file3.pyste</pre></code><p> |
---|
166 | Now compile and link all this files together and your extension is ready for |
---|
167 | use.</p> |
---|
168 | <a name="cache"></a><h2>Cache</h2><p> |
---|
169 | Pyste now supports a form of cache, which is a way to speed up the code |
---|
170 | generation. Most of the time that Pyste takes to generate the code comes from |
---|
171 | having to execute <a href="http://www.gccxml.org"> |
---|
172 | GCCXML</a> (since being a front-end to GCC, it has to compile the |
---|
173 | header files) and reading back the XML generated. </p> |
---|
174 | <p> |
---|
175 | When you use the <tt>--cache-dir=<dir></tt> option, Pyste will dump in the specified |
---|
176 | directory the generated XMLs to a file named after the Pyste file, with the |
---|
177 | extension <tt>.pystec</tt>. The next time you run with this option, Pyste will use |
---|
178 | the cache, instead of calling <a href="http://www.gccxml.org"> |
---|
179 | GCCXML</a> again:</p> |
---|
180 | <code><pre>>python pyste.py --module=mymodule --cache-dir=cache file1.pyste</pre></code><p> |
---|
181 | Will generate <tt>file1.cpp</tt> and <tt>cache/file1.pystec</tt>. Next time you execute |
---|
182 | this command, the cache file will be used. Note that Pyste doesn't do any check |
---|
183 | to ensure that the cache is up to date, but you can configure your build system to do that for you.</p> |
---|
184 | <p> |
---|
185 | When you run Pyste with <tt>--only-create-cache</tt>, all the cache files will be |
---|
186 | created again, but no code will be generated.</p> |
---|
187 | <table border="0"> |
---|
188 | <tr> |
---|
189 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
---|
190 | <td width="30"><a href="introduction.html"><img src="theme/l_arr.gif" border="0"></a></td> |
---|
191 | <td width="20"><a href="the_interface_files.html"><img src="theme/r_arr.gif" border="0"></a></td> |
---|
192 | </tr> |
---|
193 | </table> |
---|
194 | <br> |
---|
195 | <hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 2002-2003 Joel de Guzman<br><br> |
---|
196 | <font size="2">Permission to copy, use, modify, sell and distribute this document |
---|
197 | is granted provided this copyright notice appears in all copies. This document |
---|
198 | is provided "as is" without express or implied warranty, and with |
---|
199 | no claim as to its suitability for any purpose. </font> </p> |
---|
200 | </body> |
---|
201 | </html> |
---|