Navigation



Version 5 (modified by Sebastien Decugis, 13 years ago) (diff)

--

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] 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] 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]
The file that must be modified in order to add a new extension and have it compiled along.

If you create new extensions for freeDiameter, please consider sharing them with others! There are many benefits in doing so, both for others and for you. The source code can be hosted here if you want, please contact dev@freediameter.net in that case. Thank you!