load help;

@[name]
tool
@[name]

@[title]
Dao Tools
@[title]



@[name]
tool.standard
@[name]

@[title]
Standard Dao Tools
@[title]




@[name]
tool.standard.daomake
@[name]

@[title]
DaoMake Tool
@[title]

@[text]

DaoMake is a make tool based on Dao, it can be easily configure
to generate appropriate make files for different platforms.

@[text]




@[name]
tool.standard.daomake.options
@[name]

@[title]
Command Line Options
@[title]

@[text]


DaoMake supports the following command line options:

@[table]
##Options             ##Meaning
##--platform          &&platform name for which to generate makefiles;
##--mode              &&building mode (release, debug or profile);
##--suffix            &&makefile suffix (default none);
##--reset             &&reset package searching caches;
##--help              &&print this help information;
##--option-OPT=value  &&create an option entry;
##--define-DEF=value  &&pass a definition to the compiler;
@[table]

@[text]





@[name]
tool.standard.daomake.project
@[name]

@[title]
Project File
@[title]

@[text]


A DaoMake project file is a regular Dao script file that configure
the project using some dedicated types and methods.
The following is simple DaoMake project file (say myproject.dao),
@[code]
project = DaoMake::Project( "MyProject" )

project_objs = project.AddObjects( { "myfile1.c", "myfile2.c" } )
project_exe  = project.AddExecutable( "myexe", project_objs )
@[code]
To generate Makefile for this project, simply run the following
in the same directory as the project file,
@[code]
$$ daomake --platform PLATFORM myproject.dao
@[code]
where PLATFORM can be one of the followings:
@[list]
-- linux
-- macosx
-- freebsd
-- openbsd
-- mingw
-- minix
-- haiku
@[list]
If the project file is not passed as a command line argument to DaoMake,
it will assume it is a file named @[green]makefile.dao@[green].


DaoMake provides a number of types, methods and global variables
for configuring projects. The most important ones are:
@[green]Project@[green], @[green]Target@[green] and @[green]Objects@[green],
which are all subtypes of the compiling unit type @[green]Unit@[green].


@[subsection]
DaoMake::Project
@[subsection]

@[list]
--@[code]Project(name:string)=>Project@[code]
--@[code]AddObjects(self:Project,sources:list<string>,headers:list<string>={})=>Objects@[code]
--@[code]AddExecutable(self:Project,name:string,objs:Objects,...:Objects)=>Target@[code]
--@[code]AddSharedLibrary(self:Project,name:string,objs:Objects,...:Objects)=>Target@[code]
--@[code]AddStaticLibrary(self:Project,name:string,objs:Objects,...:Objects)=>Target@[code]
--@[code]AddCommand(self:Project,name:string,command:string,...:string)=>Target@[code]
--@[code]AddDirectory(self:Project,name:string,path:string,...:string)=>Target@[code]
--@[code]Install(self:Project,dest:string,target:Target,...:Target)@[code]
--@[code]Install(self:Project,dest:string,file:string,...:string)@[code]
--@[code]Install(self:Project,dest:string,headers:list<string>)@[code]
--@[code]SourcePath(self:Project)=>string@[code]
--@[code]BinaryPath(self:Project)=>string@[code]
--@[code]AddVariable(self:Project,name:string,value:string)@[code]
--@[code]ExportLibrary(self:Project,name:string,cflag:string,lflag:string,shlib='',stlib='')@[code]
--@[code]ExportPath(self:Project,name:string,path:string)@[code]
--@[code]GetPath(self:Project,name:string)=>string@[code]
--@[code]GenerateFinder(self:Project,bl:enum<FALSE,TRUE>=$TRUE)@[code]
@[list]



@[subsection]
DaoMake::Target
@[subsection]

@[list]
--@[code]Name(self:Target)=>string@[code]
--@[code]AddObjects(self:Target,objects:Objects,...:Objects)@[code]
--@[code]AddCommand(self:Target,command:string,...:string)@[code]
--@[code]AddTest(self:Target,test:string,...:string)@[code]
--@[code]AddDependency(self:Target,target:Target,...:Target)@[code]
--@[code]EnableDynamicExporting(self:Target,bl:enum<FALSE,TRUE>=$TRUE)@[code]
--@[code]EnableDynamicLinking(self:Target,bl:enum<FALSE,TRUE>=$TRUE)@[code]
--@[code]SetTargetPath(self:Target,path:string)@[code]
--@[code]Install(self:Target,dest:string)@[code]
@[list]




@[subsection]
DaoMake::Objects
@[subsection]

@[list]
--@[code]AddHeaders(file:string,...:string)@[code]
--@[code]AddSources(file:string,...:string)@[code]
@[list]




@[subsection]
DaoMake::Objects
@[subsection]

@[list]
--@[code]AddDefinition(self:Unit,name:string,value='')@[code]
--@[code]AddIncludePath(self:Unit,path:string,...:string)@[code]
--@[code]AddLinkingPath(self:Unit,path:string,...:string)@[code]
--@[code]AddCompilingFlag(self:Unit,flag:string,...:string)@[code]
--@[code]AddLinkingFlag(self:Unit,flag:string,...:string)@[code]
--@[code]AddRpath(self:Unit,flag:string,...:string)@[code]
--@[code]UseImportLibrary(self:Unit,pro:Project,...:string)@[code]
--@[code]UseSharedLibrary(self:Unit,pro:Project,...:string)@[code]
--@[code]UseStaticLibrary(self:Unit,pro:Project,...:string)@[code]
--@[code]MakeDefinitions(self:Unit)=>string@[code]
--@[code]MakeIncludePaths(self:Unit)=>string@[code]
--@[code]MakeLinkingPaths(self:Unit)=>string@[code]
--@[code]MakeCompilingFlags(self:Unit)=>string@[code]
--@[code]MakeLinkingFlags(self:Unit)=>string@[code]
@[list]




@[subsection]
DaoMake Methods
@[subsection]

@[list]
--@[code]FindPackage(name:string,opt:enum<OPTIONAL,REQUIRED>=$OPTIONAL)=>Project@[code]
--@[code]FindFile(file:string,hints:list<string>={})=>string@[code]
--@[code]TestCompile(code:string,lflag='',cflag='',cxx=0)=>int@[code]
--@[code]Option(name:string,value:enum<OFF,ON>)=>enum<OFF,ON>@[code]
--@[code]Option(name:string,value='')=>string@[code]
--@[code]MakefileSuffix()=>string@[code]
--@[code]Shell(command:string)=>string@[code]
--@[code]GetEnv(name:string)=>string@[code]
--@[code]SourcePath()=>string@[code]
--@[code]BinaryPath()=>string@[code]
--@[code]MakeRpath(path:string,...:string)=>string@[code]
--@[code]BuildMode()=>enum<RELEASE,DEBUG,PROFILE>@[code]
--@[code]SetTestTool(test:string,log_option='--log')@[code]
--@[code]IsFile(path:string)=>int@[code]
--@[code]IsDir(path:string)=>int@[code]
--@[code]Platform()=>string@[code]
--@[code]IsPlatform(platform:string)=>int@[code]
--@[code]Is64Bit()=>int@[code]
@[list]




@[subsection]
DaoMake Globals
@[subsection]

@[list]
--@[code]DaoMake::Settings@[code]
--@[code]DaoMake::Compilers@[code]
--@[code]DaoMake::Linkers@[code]
--@[code]DaoMake::Includes@[code]
@[list]




@[text]







@[name]
tool.standard.clangdao
@[name]

@[title]
ClangDao for Automatic Wrapping
@[title]

@[text]

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


@[subsection]
Module Definition File
@[subsection]

A configuration or definition file is normally required to wrap a C/C++ library.
This defintion 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,
@[code(cxx)]
#define module_name MyModule
#undef module_name

#include "myModule.h"
@[code(cxx)]
With this, four files will be generated with wrapping codes
(where @[green]xxx@[green] is the suffix of the definition file):
@[list]
--@[green]dao_MyModule.h@[green]:

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++ class to allow re-implementation by derived Dao classes.

--@[green]dao_MyModule.xxx@[green]

This file constains mostly the wrappers for global constant numbers and global functions.
The entry function for the module is also placed in this file.

--@[green]dao_MyModule2.xxx@[green]

This file contains mostly type information structures and the wrappers 
for C++ class member functions.

--@[green]dao_MyModule3.xxx@[green]

This file contains mostly re-implemented C++ virtual functions in such a way that,
when they are executed, they will first check and call Dao re-implementation of
the virtual functions.
@[list]


For C++, proxy classes may be created for wrapping to allow Dao to access the
protected member methods, to turn off this, the following macro can be defined:
@[code(cxx)]
#define CLANGDAO_SKIP_PROTECTED
@[code(cxx)]

Also by default, the functions and types declared in the header files that
are not directly included the definition file will also be wrapped.
To avoid this, the following macro can be defined:
@[code(cxx)]
#define CLANGDAO_SKIP_EXTERNAL
@[code(cxx)]


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



@[subsection]
Wrapping Hints
@[subsection]

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


@[text]