|
|
Running Pyste |
 |
 |
 |
To run Pyste, you will need:
Installation for the tools is available in their respective webpages.
GCCXML must be accessible in the PATH environment variable, so
that Pyste can call it. How to do this varies from platform to platform.
|
Well, now let's fire it up:
>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
Options explained:
The -I and -D are preprocessor flags, which are needed by GCCXML to parse the header files correctly and by Pyste to find the header files declared in the interface files.
--out names the output file (default: <module>.cpp), or in multiple mode, names a output directory for the files (default: <module>).
--no-using tells Pyste to don't declare "using namespace boost;" 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.
Use --pyste-ns 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.
--debug will write in the current directory a xml file as outputted by GCCXML for each header parsed. Useful for bug reports.
--file-list 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.
The other options are explained below, in Multiple Mode and Cache.
-h, --help, -v, --version are self-explaining, I believe. ;)
So, the usage is simple enough:
>python pyste.py --module=mymodule file.pyste file2.pyste ...
will generate a file mymodule.cpp in the same dir where the command was executed. Now you can compile the file using the same instructions of the tutorial.
Don't worry: normally GCCXML 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.
Plus, Pyste automatically uses the contents of the environment variable INCLUDE if it exists. Visual C++ users should run the Vcvars32.bat file, which for Visual C++ 6 is normally located at:
C:\Program Files\Microsoft Visual Studio\VC98\bin\Vcvars32.bat
with that, you should have little trouble setting up the flags.
|
A note about Psyco Although you don't have to install Psyco 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. |
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).
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:
>python pyste.py --module=mymodule file1.pyste file2.pyste
This will create the files mymodule/file1.cpp and mymodule/file2.cpp. You can then later do:
>python pyste.py --module=mymodule file3.pyste
and mymodule/file3.cpp will be generated.
But compiling and linking this files won't be sufficient to generate your extension. You have to also generate a file named main.cpp; call pyste with all the Pyste files of your extension, and use the --generate-main option:
>python pyste.py --module=mymodule --generate-main file1.pyste file2.pyste file3.pyste
Now compile and link all this files together and your extension is ready for use.
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 GCCXML (since being a front-end to GCC, it has to compile the header files) and reading back the XML generated.
When you use the --cache-dir=<dir> option, Pyste will dump in the specified directory the generated XMLs to a file named after the Pyste file, with the extension .pystec. The next time you run with this option, Pyste will use the cache, instead of calling GCCXML again:
>python pyste.py --module=mymodule --cache-dir=cache file1.pyste
Will generate file1.cpp and cache/file1.pystec. 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.
When you run Pyste with --only-create-cache, all the cache files will be created again, but no code will be generated.
|
|
|
Copyright © 2003 Bruno da Silva de Oliveira
Copyright © 2002-2003 Joel de Guzman
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)