FAQ

Performance

pygccxml is being regularly optimised for performance, but it still may be slow in certain cases.

Before all, it is highly recommended to benchmark your application if performance is important to you. There are multiple tools out there for benchmarking python applications. We currently are using the following two command lines / tools:

python -m cProfile -o profile_data.pyprof script_to_profile.py
pyprof2calltree -i profile_data.pyprof -k

Of course optimising pygccxml alone will not help in all cases. The bottlenecks can also be in the code calling pygccxml, to make sure to benchmark the whole process. Any help on the performance side is also welcome.

Some things you may try (in order of priority):

  1. You might want to consider making the declaration tree as small as possible and only store those declarations that somehow have an influence on the bindings. Ideally, this is done as early as possible and luckily castxml and gccxml provide an option that allows you to reduce the number of declarations that need to be parsed.

    You can specify one or more declarations using the -fxml-start (gccxml) or -castxml-start (castxml) options when running the xml generator. For example, if you specify the name of a particular class, only this class and all its members will get written. Ideally, your project should already use a dedicated namespace, which you can then use as a starting point. All declarations stemming from system headers will be ignored (except for those declarations that are actually used within your library).

    In the pygccxml package you can set the value for these flags by using the start_with_declarations attribute of the pygccxml.parser.config_t object that you are passing to the parser.

  2. You can pass the following flag to the read_files method:

    compilation_mode=pygccxml.parser.COMPILATION_MODE.ALL_AT_ONCE

  3. If you want to cache the declarations tree, there is a caching mechanism provided by pygccxml. You will find an example of this mechanism in the examples section.

__va_list_tag and other hidden declarations

When parsing with CastXML, the XML tree can contain declarations named __va_list_tag. If the compiler is llvm 3.9, __NSConstantString_tag and __NSConstantString declarations may also be present.

These declarations are internal declarations, coming from the std c++ library headers you include, and are often not needed. They are for example polluting the declarations tree when running pyplusplus.

By default, pygccxml will ignore these declarations. To still read these declarations from the xml file, a config flag can be set (config.flags = ["f1"]), or a flag can be passed as argument the config setup (flags=["f1"]).