[pygccxml-commit] SF.net SVN: pygccxml: [370] pygccxml_dev/docs
Brought to you by:
mbaas,
roman_yakovenko
Menu
▾
▴
[pygccxml-commit] SF.net SVN: pygccxml: [370] pygccxml_dev/docs
|
From: <rom...@us...> - 2006-07-30 21:02:25
|
Revision: 370 Author: roman_yakovenko Date: 2006-07-30 14:02:11 -0700 (Sun, 30 Jul 2006) ViewCVS: http://svn.sourceforge.net/pygccxml/?rev=370&view=rev Log Message: ----------- updating documentation Modified Paths: -------------- pygccxml_dev/docs/design.rest pyplusplus_dev/docs/documentation/index.rest pyplusplus_dev/docs/documentation/www_configuration.py Added Paths: ----------- pyplusplus_dev/docs/documentation/best_practices.rest Modified: pygccxml_dev/docs/design.rest =================================================================== --- pygccxml_dev/docs/design.rest 2006-07-30 20:55:48 UTC (rev 369) +++ pygccxml_dev/docs/design.rest 2006-07-30 21:02:11 UTC (rev 370) @@ -226,25 +226,32 @@ Cache classes ------------- -There are few cache classes, that implements different cache strategies. My -advise - don't use them. Your best choice is ``file_configuration_t``, -configured to C++ source file + `GCC-XML`_ generated file. +There are few cache classes, that implements different cache strategies. -* ``file_cache_t`` class, will save all declarations from all files within single - binary file. +1. ``file_configuration_t`` class, that keeps pass to C++ source file and path to + `GCC-XML`_ generated XML file. This class is not a cache class, but it also + allows you to save your time. -* ``directory_cache_t`` class will store one index file called "index.dat" which - is always read by the cache when the cache object is created. Each header file - will have its corresponding \*.cache file that stores the declarations found - in the header file. The index file is used to determine whether a \*.cache file - is still valid or not (by checking if one of the dependent files - (i.e. the header file itself and all included files) have been modified since - the last run). +2. ``file_cache_t`` class, will save all declarations from all files within single + binary file. -As you can guess, ``directory_cache_t`` class gives much better performance, than +3. ``directory_cache_t`` class will store one index file called "index.dat" which + is always read by the cache when the cache object is created. Each header file + will have its corresponding \*.cache file that stores the declarations found + in the header file. The index file is used to determine whether a \*.cache file + is still valid or not (by checking if one of the dependent files + (i.e. the header file itself and all included files) have been modified since + the last run). + +In some cases, ``directory_cache_t`` class gives much better performance, than ``file_cache_t``. Many thanks to Matthias Baas for its implemention. +**Warning**: when `pygccxml`_ writes information to files, using cache classes, +it does not write any version information. It means, that when you upgrade +`pygccxml`_ you have to delete all your cache files. Otherwise you will get very +strange errors. For example: missing attribute. + Patchers -------- Added: pyplusplus_dev/docs/documentation/best_practices.rest =================================================================== --- pyplusplus_dev/docs/documentation/best_practices.rest (rev 0) +++ pyplusplus_dev/docs/documentation/best_practices.rest 2006-07-30 21:02:11 UTC (rev 370) @@ -0,0 +1,107 @@ +============== +Best practices +============== + +.. contents:: Table of contents + +------------ +Introduction +------------ + +`pyplusplus`_ has reach interface and a lot of functionality. Sometimes reach +interface helps, but sometimes it can confuse. This document will describe how +effectivly to use `pyplusplus`_. + +------------ +Big projects +------------ + +Definition +---------- + +First of all, let me to define "big project". "Big project" is a project with +few handred of header files. `pyplusplus`_ was born to create `Python`_ bindings +for such projects. If you take a look `here`__ you will find few such projects, +that use `pyplusplus`_. + +.. __ : ./../../pygccxml/quotes.html + +Tips +---- + +* Create one header file, that will include all project header files. + + Doing it this way makes it so `GCC-XML`_ is only called once and it reduces the + overhead that would occur if you pass `GCC-XML`_ all the files individually. + Namely `GCC-XML`_ would have to run hundreds of times and each call would + actually end up including quite a bit of common code anyway. This way takes a + `GCC-XML`_ processing time from multiple hours with gigabytes of caches to a + couple minutes with a reasonable cache size. + + You can read more about different caches supported by `pygccxml`_ `here`__. + ``module_builder_t.__init__`` methods takes reference to an instance of cache + class or ``None``: + + :: + + from module_builder import * + mb = module_builder_t( ..., cache=file_cache_t( path to project cache file ), ... ) + +* Single header file, will also improve performance compiling the generated bindings. + + When `pyplusplus`_ generated the bindings, you have a lot of .cpp files to + compile. The project you are working on is big. I am sure it takes a lot of + time to compile projects that depend on it. Generated code also depend on it, + more over this code contains a lot of template isnstantiations. So it could + take a great deal of time to compile it. Allen Bierbaum investigated this + problem. He found out that most of the time is really spent processing all the + headers, templates, macros from the project and from the boost library. So he + come to conclusion, that in order to improve compilation speed, user should + be able to control( to be able to generate ) precompiled header file. He + implemented an initial version of the functionality. After small discussion, + we agreed on next interface: + + :: + + class module_builder_t( ... ): + ... + def split_module( self, directory_path, huge_classes=None, precompiled_header=None ): + ... + ... + + ``precompiled_header`` argument could be ``None`` or string, that contains + name of precompiled header file, that will be created in the directory. + `pyplusplus`_ will add to it header files from `boost.python`_ library and + your header files. + + What is ``huge_classes`` argument for? ``huge_classes`` could be ``None`` or + list of references to class declarations. It is there to provide a solution to + `this error`_. ``pyplusplus`` will automaticly split generated code for the + huge classes to few files: + + :: + + mb = module_builder_t( ... ) + ... + my_big_class = mb.class_( my_big_class ) + mb.split_module( ..., huge_classes=[my_big_class], ... ) + + +.. _`this error` : http://boost.org/libs/python/doc/v2/faq.html#c1204 +.. __ : ./../../pygccxml/design.html + + + +.. _`pyplusplus` : ./../pyplusplus.html +.. _`pygccxml` : ./../../pygccxml/pygccxml.html +.. _`boost.python`: http://www.boost.org/libs/python/doc/index.html +.. _`Python`: http://www.python.org +.. _`GCC-XML`: http://www.gccxml.org + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: Modified: pyplusplus_dev/docs/documentation/index.rest =================================================================== --- pyplusplus_dev/docs/documentation/index.rest 2006-07-30 20:55:48 UTC (rev 369) +++ pyplusplus_dev/docs/documentation/index.rest 2006-07-30 21:02:11 UTC (rev 370) @@ -14,14 +14,16 @@ How can you help? * Lets face it: today it is not possible to use `pyplusplus`_ without looking - into source code. `pyplusplus`_ uses `Epydoc`_ to generate documentation from - source files. So, if you found some undocumented piece of code and you understand - what it does, please write documentation string and send it to me. + into source code sometimes. `pyplusplus`_ uses `Epydoc`_ to generate + documentation from source files. So, if you found some undocumented piece of + code and you understand what it does, please write documentation string. * You are reading documentation and my English cause you to scream? Please, fix - those errors and send me new version of document. I will integrate the changes. - + those errors and send me new version of the document. I will integrate the + changes. +* Do you think, that the documentation is not clear, I will be glad to improve it, + just point me to the place. .. _`Epydoc` : http://epydoc.sourceforge.net/ .. _`pyplusplus` : ./../pyplusplus.html Modified: pyplusplus_dev/docs/documentation/www_configuration.py =================================================================== --- pyplusplus_dev/docs/documentation/www_configuration.py 2006-07-30 20:55:48 UTC (rev 369) +++ pyplusplus_dev/docs/documentation/www_configuration.py 2006-07-30 21:02:11 UTC (rev 370) @@ -5,4 +5,5 @@ , 'how_to' : 'how to ... ?' , 'doc_string' : 'documentation string' , 'inserting_code' : 'inserting code' + , 'best_practices' : 'best practices' } \ No newline at end of file This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
