[NAME]
ALL.tool.standard.clangdao

[TITLE]
ClangDao for Automatic Wrapping

[DESCRIPTION]

ClangDao uses the C/C++ frontend of Clang to parse C/C++ header files  and generate prop
er wrapping codes for Dao. It has been used successfully to generate a number of binding 
for Dao.

 0.1   Module Definition File  

A configuration or definition file is normally required to wrap a C/C++ library. This def
intion file should have C source file suffix for C libraries, and C++ source file suffix 
for C++ libraries. In this file, the list of header files for wrapping should be included
in the standard way. This file may also contain configuration settings and wrapping hints
. All the configuration settings and wrapping hints should be defined as valid C macros.

For example, the following should be used to set the module name, 
     
   1  #define module_name MyModule
   2  #undef module_name
   3  
   4  #include "myModule.h"
     
With this, four files will be generated with wrapping codes (where xxx is the suffix of t
he definition file): 
  *  dao_MyModule.h:
     This file contains mostly declarations, wrapper structs or classes in case that they
     are need to support function pointer field in struct, and virtual function in C++ cl
     ass to allow re-implementation by derived Dao classes. 
  *  dao_MyModule.xxx
     This file constains mostly the wrappers for global constant numbers and global funct
     ions. The entry function for the module is also placed in this file. 
  *  dao_MyModule2.xxx
     This file contains mostly type information structures and the wrappers  for C++ clas
     s member functions. 
  *  dao_MyModule3.xxx
     This file contains mostly re-implemented C++ virtual functions in such a way that, w
     hen they are executed, they will first check and call Dao re-implementation of the v
     irtual functions. 


For C++, proxy classes may be created for wrapping to allow Dao to access the protected m
ember methods, to turn off this, the following macro can be defined: 
     
   1  #define CLANGDAO_SKIP_PROTECTED
     

Also by default, the functions and types declared in the header files that are not direct
ly included the definition file will also be wrapped. To avoid this, the following macro 
can be defined: 
     
   1  #define CLANGDAO_SKIP_EXTERNAL
     


Such definition file can be passed to ClangDao as command line argument in the same way a
s passing C/C++ source file to a Clang or GCC compilers. And similarly, option -I can be 
used to specify searching paths for the header files. Example command line, 
     
   1  $ clangdao -Iinclude module_def.cpp
     


 0.2   Wrapping Hints  

Sometimes C/C++ types are ambiguous from mere type name, for example, for a pointer param
eter, it is impossible to know if it is a pointer or actually an array. There are also ot
her situations where the proper wrapping cannot be inferred from the codes alone. To circ
umvent such problems, wrapping hints can be defined for any function or class that need s
pecial handling.