[pygccxml-commit] source/pyplusplus/docs/tutorials module_builder.rest,NONE,1.1 www_configuration.py,NONE,1.1

[Roman <rom...@us...>]

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'