|
From: Roman <rom...@us...> - 2006-04-06 06:20:16
|
Update of /cvsroot/pygccxml/source/pyplusplus/docs/tutorials In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv434/pyplusplus/docs/tutorials Added Files: module_builder.rest www_configuration.py Log Message: adding missing files --- NEW FILE: module_builder.rest --- ==================== pyplusplus tutorials ==================== .. contents:: Table of contents **All written here is relevant to CVS version.** ------------------- What is pyplusplus? ------------------- .. include:: ./../definition.rest -------- Concepts -------- `pyplusplus`_ introduces few concepts: **code creator** ---------------- Class, that is responsible to create some specific code. For example, ``include_t`` code creator is responsible to create C++ include directive. **compound code creator** ------------------------- Code creator, that contains an ordered set of other code creators. For example, ``module_t`` is compaund code creator, because it keeps all code creators. **code creators tree** ---------------------- Good definition is needed, meanwhile I can make next anology of code creators with XML DOM 1) code creators - DOM nodes 2) code creators tree - XML DOM 3) module - DOM Document **module creator** ------------------ Factory, that is repososible to create all necessary code creators, for a given set of C++ declarations. **file writer(s)** ------------------ Classes, that are responsible for writing all code produced by ``module_t`` into file(s). -------- Overview -------- Code generation process using `pyplusplus`_ consists from few steps: 1. Read C++ declarations. 2. Create code creators tree. 3. Customize code creators. 4. Write code to files. Later, in this article I am going to explain every step. Before doing this, I would like to give you small advice: please `download`_ `pyplusplus`_ `GUI`_ and run it. There is one good reason for doing this: code generator wizard. `pyplusplus`_ GUI contains small and simple wizard that will generate `pyplusplus`_ code from your settings. You have to know nothing about API - just few clicks with you mouse and you will get the code. Enjoy. .. _`download`: ./download.html .. _`GUI`: ./examples/pyplusplus_demo.png To do: add reference to the code!!! ----------------------------- Step 1: Read C++ declarations ----------------------------- During this step C++ source files are parsed and all declarations are read. `pyplusplus`_ is not involved in this step at all. You should use `pygccxml`_. Fortunately it is very easy to setup\\use `pygccxml`_: :: import os from pygccxml import parser from pygccxml import declarations from pyplusplus import code_creators from pyplusplus import module_creator from pyplusplus import file_writers class settings: gccxml_path = '/home/roman/gccxml/bin' working_dir = '/tmp' #configurating parser parser_config = parser.config_t( gccxml_path=settings.gccxml_path, working_directory=settings.working_dir ) #reading all declarations decls_all = parser.parse( ['hello_world.hpp'], parser_config ) #filtering declarations decls = declarations.filtering.by_location( decls_all, [settings.working_dir] ) `pygccxml`_ does not parse C++ files, but use `GCC-XML`_ to do the job. So, the first thing that you should do is to setup `GCC-XML`_ binary location. The only way to do it is to create ``parser.config_t`` class instance. ``parser.config_t.__init__`` method takes few arguments: * `GCC-XML`_ binary location * working directory, this will help `GCC-XML`_ to locate included files * list of additional include directories * list of defined\\undefined symbols * ..., please see documentation of `pygccxml`_ for more information Now, when we created configuration for parser, we can actually read all declarations from source files. Function ``parse`` of module ``parser`` will do it. It will read all declarations that are found in your file and files included from the file. This means, that variable ``decls_all`` contains some declarations, that we do not want to export. So there is a need to apply some filter. In my example I remove all declarations that have been defined in files, outside of our working directory. We finished this step. The result of this step is that we have a set of declarations that we want to export. --------------------------------- Step 2: Create code creators tree --------------------------------- During this step `pyplusplus`_ will create one or more code creator for every C++ declaration, that should be exported. At the end of this step ``module_t`` class instances is created. Lets see some code: :: #creating code creators tree extmodule = module_creator.create( decls=decls, module_name="hello_world",recursive=False ) What is going on? First of all this is a first time we actualy use `pyplusplus`_. `pyplusplus`_ contains a package, named ``module_creator`` that contains functionality that create code creator(s) for every declaration. In this case I want to export all declarations from ``decls`` list. I also set exported module name to "hello_world". The 3rd parameter needs more explanation. ``decls`` argument could be interpreted as * list of all declaration to be exported * list of top level declarations. all declarations should be exported recursively. In order to clarify the use of ``decls`` argument, argument ``recursive`` is used. In my case ``decls`` variable holds a list of all declarations that should be exported, so I set ``recursive`` to be ``False``. Actually, we finished this step. ------------------------------- Step 3: Customize code creators ------------------------------- This step is optional. Inspite of being "optional" this step allows you to change code before it has been generated. You can create and add custom code creatpors. Or you can modify an exising one. Or even more you can delete code creators. There are few function that will help you to locate desired code creator by different criterias. In my case I only want to set user defined directories. Thus allowing `pyplusplus`_ to generate nice( shorter ) include directives: :: extmodule.user_defined_directories.append( parser_config.working_directory ) That's all for this step. --------------------------- Step 4: Write code to files --------------------------- :: file_writers.write_file( extmodule, 'bindings.cpp' ) I think that code above is self explained. I write ``extmodule`` into ``bindings.cpp`` file. It is also possible to write ``extmodule`` into multiple files: :: file_writers.write_multiple_files( extmodule, '.' ) The code above split extension module source to few files. This is very useful option. It saves compilation time. -------------- Congratulation -------------- Congratulation! You've done. You can find the whole listing of the program within CVS/pyplusplus/examples/tutorials. Enjoy. .. _`pyplusplus` : ./pyplusplus.html .. _`pygccxml` : ./../pygccxml/pygccxml.html .. _`boost.python`: http://www.boost.org/libs/python/doc/index.html .. _`SourceForge`: http://sourceforge.net/index.php .. _`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: --- NEW FILE: www_configuration.py --- name = 'tutorials' main_html_file = 'module_builder.html' |
