Information for developers

The project is managed with ​mercurial. You can access the repository at this address: ​http://www.freediameter.net/hg/freeDiameter

The repository is read-only. If you want to submit patches, please use the developers mailing-list ​dev@freediameter.net. You can subscribe to the list ​here and check the archives ​there. The tickets system can also be used.

Last but not least, please feel free to contribute to the website! Thank you.

Developer's quick start

Although you can find a lot of information on Mercurial and CMake on the Internet, the following are a few useful tips and tricks for starting development with freeDiameter.

Clone the repository

The following command will fetch the latest source tree in a freeDiameter directory:

hg clone http://www.freediameter.net/hg/freeDiameter

Update your source tree

When you already have cloned the repository, you can retrieve updates from upstream with the command bellow:

hg pull -u

If you have made local changes, Mercurial will attempt to merge everything by it-self, which is very convenient. If you need archiving your changes, you might have a look at ​Mercurial Queues.

Build and test

Files/Directories named test.* are ignored by Mercurial in the freeDiameter package ([source:.hgignore]). The following files can reside in your tree without interacting with the repository, and simplify your build-and-test process:

$ ls test.conf/
CMakeFlags   freeDiameter.conf  myextension.conf

$ cat test.rebuild
#!/bin/bash -x
rm -rf test.build
cp -Rs `pwd`/test.conf test.build
cd test.build
cmake `cat CMakeFlags` ..
make

This allows you to save your configuration files in test.conf directory, and rebuild the whole tree from scratch in a different folder by simply running the test.rebuild script.

Useful CMake flags for development

The following flags are useful for configuring the source, for example in CMakeFlags file (see previous point).

-DCMAKE_BUILD_TYPE:STRING=Debug

This impacts both the compiler's flags (including symbols for debug) and freeDiameter itself (allowing some slow tracing options such as --dbg-func).

-DSKIP_TESTS:BOOL=OFF

Allows the compilation of the unit tests, called by running make test.

-DBUILD_TEST_APP:BOOL=ON

Compile the test application extension test_app.fdx.

Developer's useful files

Here is a list of files that anyone starting with freeDiameter should read first:

[source:freeDiameter/include/freeDiameter include/freeDiameter] directory

This directory contains the header files that describe the API for freeDiameter. Typically, a new extension should start by including the [source:freeDiameter/include/freeDiameter/extension.h extension.h] file like this:

#include <freeDiameter/extension.h>

The directory contains:

• [source:freeDiameter/include/freeDiameter/extension.h extension.h]: Includes the other files, and provides a macro that can be useful to define the extension entry point.
• [source:freeDiameter/include/freeDiameter/freeDiameter.h freeDiameter.h]: detail of the functions available in the daemon, including the description of the callback functions the extension must register.
• [source:freeDiameter/include/freeDiameter/libfreeDiameter.h libfreeDiameter.h]: detail of the functions available in the library, as well as macros that can be used for logging and debugging.
• [source:freeDiameter/include/freeDiameter/freeDiameter-host.h.in freeDiameter-host.h.in]: This contains the host-specific configuration, generated by CMake.

[source:freeDiameter/extensions/_sample Sample extension] directory

This is a skeleton that shows the basic structure of an extension. Other extensions also provide more complex examples, such as how to parse a configuration file or how to register a callback on some messages.

[source:freeDiameter/extensions/CMakeLists.txt extensions/CMakeLists.txt]

The file that must be modified in order to add a new extension and have it compiled along.

If you create a new extension for freeDiameter, please consider sharing with others. There are many benefits in doing so, both for others (obviously) and for you.

The source code can be hosted here if you want, please contact ​dev@freediameter.net if you have any question.

Thank you!

---