pyste.txt

C++的一个好库。。。现在很流行

[doc Pyste Documentation]

[def GCCXML             [@http://www.gccxml.org GCCXML]]
[def Boost.Python       [@../../index.html Boost.Python]]

[page Introduction]

[h2 What is Pyste?]

Pyste is a Boost.Python code generator. The user specifies the classes and
functions to be exported using a simple ['interface file], which following the
Boost.Python's philosophy, is simple Python code. Pyste then uses GCCXML to
parse all the headers and extract the necessary information to automatically
generate C++ code.

[h2 Example]

Let's borrow the class [^World] from the [@../../doc/tutorial/doc/exposing_classes.html tutorial]: 

    struct World
    {
        void set(std::string msg) { this->msg = msg; }
        std::string greet() { return msg; }
        std::string msg;
    };

Here's the interface file for it, named [^world.pyste]:

    Class("World", "world.h")

and that's it!

The next step is invoke Pyste in the command-line:

[pre python pyste.py --module=hello world.pyste]

this will create a file "[^hello.cpp]" in the directory where the command was
run. 

Pyste supports the following features:

* Functions
* Classes
* Class Templates
* Virtual Methods
* Overloading
* Attributes 
* Enums (both "free" enums and class enums)
* Nested Classes
* Support for [^boost::shared_ptr] and [^std::auto_ptr]
* Global Variables

[page Running Pyste]

To run Pyste, you will need:

* Python 2.2, available at [@http://www.python.org python's website].
* The great [@http://effbot.org elementtree] library, from Fredrik Lundh.
* The excellent GCCXML, from Brad King.

Installation for the tools is available in their respective webpages.

[blurb 
[$theme/note.gif] GCCXML must be accessible in the PATH environment variable, so
that Pyste can call it. How to do this varies from platform to platform.
]

[h2 Ok, now what?]

Well, now let's fire it up:

[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
  
'''                        
]

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 [*Multiple Mode]] and
[@#cache [*Cache]].

[^-h, --help, -v, --version] are self-explaining, I believe. ;)

So, the usage is simple enough:

[pre >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
[@../../doc/tutorial/doc/building_hello_world.html tutorial]. 

[h2 Wait... how do I set those I and D flags?]

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.

[blurb [$theme/note.gif][*A note about Psyco][br][br]
Although you don't have to install [@http://psyco.sourceforge.net/ 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.
]


[h2 Multiple Mode]

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:

[pre >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:

[pre >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:

[pre >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.

[h2 Cache]

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:

[pre >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.

[page The Interface Files]

The interface files are the heart of Pyste. The user creates one or more
interface files declaring the classes and functions he wants to export, and then
invokes Pyste passing the interface files to it. Pyste then generates a single
cpp file with Boost.Python code, with all the classes and functions exported.

Besides declaring the classes and functions, the user has a number of other
options, like renaming e excluding classes and member functionis. Those are
explained later on.

[h2 Basics]

Suppose we have a class and some functions that we want to expose to Python
declared in the header [^hello.h]:

    struct World
    {
        World(std::string msg): msg(msg) {} 
        void set(std::string msg) { this->msg = msg; }
        std::string greet() { return msg; }
        std::string msg;
    };

    enum choice { red, blue };
    
    namespace test {
    
    void show(choice c) { std::cout << "value: " << (int)c << std::endl; }
    
    }

We create a file named [^hello.pyste] and create instances of the classes
[^Function], [^Class] and [^Enum]:

    Function("test::show", "hello.h")
    Class("World", "hello.h")
    Enum("choice", "hello.h")

That will expose the class, the free function and the enum found in [^hello.h]. 

[h2 Inheritance]

Pyste automatically generates the correct code (specifying [^bases<>] in the
[^class_] declaration) [*if] the Class() function that exports the base classes
and their children are in the same Pyste file. If that's not the case, you have
to indicate that there's a relationship between the Pyste files using the
[^Import] function specifying the other Pyste file.

Suppose we have two classes, [^A] and [^B], and A is a base class for B. We
create two Pyste files:

[^A.pyste]:

    Class("A", "A.h")

[^B.pyste]:

    Import("A.pyste")
    Class("B", "B.h")

Note that we specify that [^B] needs to know about [^A] to be properly exported.

[page:1 Renaming and Excluding]

You can easily rename functions, classes, member functions, attributes, etc. Just use the
function [^rename], like this:

    World = Class("World", "hello.h")
    rename(World, "IWorld")
    show = Function("choice", "hello.h")
    rename(show, "Show")

You can rename member functions and attributes using this syntax:

    rename(World.greet, "Greet")
    rename(World.set, "Set")
    choice = Enum("choice", "hello.h")
    rename(choice.red, "Red")
    rename(choice.blue, "Blue")

You can exclude functions, classes, member functions, attributes, etc, in the same way,
with the function [^exclude]:

    exclude(World.greet)
    exclude(World.msg)

To access the operators of a class, access the member [^operator] like this
(supposing that [^C] is a class being exported):

    exclude(C.operator['+'])
    exclude(C.operator['*'])
    exclude(C.operator['<<'])

The string inside the brackets is the same as the name of the operator in C++.[br]

[h2 Virtual Member Functions]

Pyste automatically generates wrappers for virtual member functions, but you may
want to disable this behaviour (for performance reasons, for instance) if you do
not plan to override the functions in Python. To do this, use the function
[^final]:

    C = Class('C', 'C.h')
    final(C.foo) # C::foo is a virtual member function

No virtual wrapper code will be generated for the virtual member function
C::foo that way.

[page:1 Policies]

Even thought Pyste can identify various elements in the C++ code, like virtual
member functions, attributes, and so on, one thing that it can't do is to