New development guidelines

by Daniel-Constantin Mierla (work in progress)

I try to collect a set of recommended guidelines for those that start
a new development for OpenSER. Feel free to contribute.

Whenever you decide to write an extension to OpenSER and make it available to public via project's SVN, do check the existence of same or similar functionality, by asking on devel@lists.kamailio.org mailing list.

OpenSER core part is intended to be the collection of the functions to be used across many modules. Core itself is barely useful alone, you need to load modules to add functionalities. Thus, the recommended way for extensions is to write a module.

* OpenSER has its own memory manager, for private and shared memory. Do use the functions from mem/mem.h and mem/shm_mem.h instead of libc POSIX/SysV. These functions do fallback to POSIX/SysV if a better alternative is not possible. * OpenSER has its own locking mechanisms. Do use functions from locking.h to implement synchronization.

The pseudo-variables are objects with string or integer values that can be used directly in the configuration file. The OpenSER core exports a large set of pseudo-variables. A new variable can be added to core if it exports a value set by core. Nevertheless, new pseudo-variables can be exported by modules, and this is the recommended way.

* the pseudo-variable handler should use PV helper functions exported by pvar.h and are implemented in pvar.c * due to the origin of pseudo-variables, the value of any PV must have string representation

* ask on devel@lists.kamailio.org to see if the enhancements you want to add belong to an existing module. If yes, then your contribution will be integrated in that module, upon submission of a patch via tracker. * naming the module is an important step. Chose a representative name for the functionality exported by your module. * if it is a database driver module, the name must start with db_. You should follow the suggestions written in db-devel * the global variables in your module must be prefixed with some abbreviation related to module's name, to avoid naming conflicts * the functions exported by your module should be prefixed with some abbreviation related to module's name to be easy to identify its origin when reading a configuration file. Also, in this way, naming conflicts are avoided * add comments before implementation of the functions explaining the parameters and returned values * write documentation in SGML format, following the pattern from an existing module * if the module needs database content to work, then you must also supply a XML database scheme file, there are some suggestion avaible at db-schema * in order to install the tables with the openser setup scripts (openserdbctl) you must also add the added tables to the openserdbctl.base and openserctrl files

* the license of the code must be GPL, as OpenSER core is GPL * the copyright holder is your choice, recommended to be you or your company * if you include code that is copyrighted by someone else, please check that the license is GPL compatible and make sure you do not violate the original copyright and the license