[pygccxml-commit] SF.net SVN: pygccxml: [693] pyplusplus_dev/docs/documentation/ best_practices.rest

[<mb...@us...>]

Revision: 693
          http://svn.sourceforge.net/pygccxml/?rev=693&view=rev
Author:   mbaas
Date:     2006-10-30 08:43:55 -0800 (Mon, 30 Oct 2006)

Log Message:
-----------
Added a section about how to keep the declaration tree small (using the -fxml-start option of gccxml).

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/best_practices.rest

Modified: pyplusplus_dev/docs/documentation/best_practices.rest
===================================================================
--- pyplusplus_dev/docs/documentation/best_practices.rest	2006-10-28 12:38:46 UTC (rev 692)
+++ pyplusplus_dev/docs/documentation/best_practices.rest	2006-10-30 16:43:55 UTC (rev 693)
@@ -88,8 +88,37 @@
 .. _`this error` : http://boost.org/libs/python/doc/v2/faq.html#c1204
 .. __ : ./../../pygccxml/design.html
 
+* Keep the declaration tree small.
 
+  When parsing the header files to build the declaration tree, there will also
+  be the occasional "junk" declaration inside the tree that is not relevant to
+  the bindings you want to generate. These extra declarations come from header
+  files that were included somewhere in the header files that you were actually
+  parsing (e.g. if that library uses the STL or OpenGL or other system headers
+  then the final declaration tree will contain those declarations, too).
+  It can happen that the majority of declarations in your declaration tree are
+  such "junk" declarations that are not required for generating your bindings
+  and that just slow down the generation process (reading the declaration cache
+  and doing queries will take longer).
 
+  To speed up your generation process 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 gccxml provides an option that allows you to reduce
+  the number of declarations that it will store in the output XML file. You can
+  specify one or more declarations using the ``-fxml-start`` option and only
+  those sub-tree starting at the specified declarations will be written. For
+  example, if you specify the name of a particular class, only this class
+  and all its members will get written. Or if your project already uses
+  a dedicated namespace you can simply use this namespace as a starting point
+  and 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 the ``-fxml-start``
+  option using the ``start_with_declarations`` attribute of the 
+  ``pygccxml.parser.config_t`` object that you are passing to the parser.
+
+
 .. _`Py++` : ./../pyplusplus.html
 .. _`pygccxml` : ./../../pygccxml/pygccxml.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.