[Kamailio-Devel] autogeneration of database code and docs

[Henning Westerholt]

Hi all,

i just added functionality to make database table and column names of the 
userblacklist configurable with help of autogenerated functions from the XML 
source that is also used for the SQL schemes.

I think this is especially useful for modules that have several larger tables, 
like the carrierroute module, which will be also probably converted to use 
this code. But for many of the smaller modules the actual implementation that 
works is just fine at the moment, so i won't start now to convert all 
modules.

But especially new code should be implemented that way, so i want add some 
notes about how this all work together, how a new module could be created.

1. Database

Start with the layout of the database. This means the creation of two XML file 
in the db/schema directory, one with the name kamailio-$modname.xml, and one 
with the actual database scheme, which is referenced from the first file. The 
module name should be the same as the table name, if you've only one table, 
otherwise choose the first table name [1]. Please don't ommit the
"description" field for each column, as this will be later also used to 
generate the documentation for the module. The easiest thing to start is 
probably just modify an existing file.

2. Test scheme

Run "make dbschema" in the scheme directory, see if the SQL is correct created 
(e.g. in scripts/mysql) and matches your requirements. Add the table name to 
the scripts/kamdbctl.base standard, extra or presence tables as appropriate. 
Test if "kamdbctl create" creates a new database with your table.

3. Test code generation

Run "make modules" in the scheme directory, see if the .h and .c file is 
correct generated in the directory of your module. Take a look to this file, 
in order if this match your requirements.

4. Module implementation

Create the basic module exports and initialization stuff for your module. 
Include the generated header. Add the generated "db_init" and "db_vars" 
function to your "mod_init" function, add the "db_open" function to 
your "child_init" function, add the "db_close" function to your "mod_destroy" 
function. Add the DB_URL, DB_TABLE and DB_COLS macros to your "params" 
export. Initialize the db_url variable [2]. Try to compile.

5. Documentation

Run "make dbdoc" in the scheme directory, see if the .xml file is correct 
generated in the docs directory of your module. Create a basic XML file with 
author informations and references to the admin content. Add a entity (link) 
to the generated documentation, preferable after the admin content. Run "make 
modules-readme modules=modules/$modname" in the trunk directory, see if the 
README is correct generated. Review the documentation.

6. Test module :-)


Please take a look at the 
http://devel.kamailio.org/svn/trunk/modules/userblacklist/db_userblacklist.h
http://devel.kamailio.org/svn/trunk/modules/userblacklist/db_userblacklist.c
files for an example at the autogenerated code.

The usage of the macros and the functions can be seen in the 
http://devel.kamailio.org/svn/trunk/modules/userblacklist/userblacklist.c
file.

The documentation can be reviewed in the usual place:
http://www.kamailio.org/docs/modules/devel/userblacklist.html#id2452156


Any comments are appreciated,

Henning



[1] This is a know limitiation of the actual implementation, and will be 
addressed.
[2] This should also be generated from the XML, i need to introduce some flags 
to be able to differ between read-only and read-write default URL.