| 8 | | Last but not least, please feel free to contribute to the website! Thank you. |
| 9 | | |
| 10 | | == Developer's quick start == |
| 11 | | |
| 12 | | 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. |
| 13 | | Clone the repository:: |
| 14 | | The following command will fetch the latest source tree in a {{{freeDiameter}}} directory: |
| 15 | | {{{ |
| 16 | | hg clone http://www.freediameter.net/hg/freeDiameter |
| 17 | | }}} |
| 18 | | |
| 19 | | Update your source tree:: |
| 20 | | When you already have cloned the repository, you can retrieve updates from upstream with the command bellow: |
| 21 | | {{{ |
| 22 | | hg pull -u |
| 23 | | }}} |
| 24 | | 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 [http://mercurial.selenic.com/wiki/MqExtension Mercurial Queues]. |
| 25 | | |
| 26 | | Build and test:: |
| 27 | | !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: |
| 28 | | {{{ |
| 29 | | $ ls test.conf/ |
| 30 | | CMakeFlags freeDiameter.conf myextension.conf |
| 31 | | }}} |
| 32 | | {{{ |
| 33 | | $ cat test.rebuild |
| 34 | | #!/bin/bash -x |
| 35 | | rm -rf test.build |
| 36 | | cp -Rs `pwd`/test.conf test.build |
| 37 | | cd test.build |
| 38 | | cmake `cat CMakeFlags` .. |
| 39 | | make |
| 40 | | }}} |
| 41 | | 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. |
| 42 | | |
| 43 | | Useful CMake flags for development:: |
| 44 | | The following flags are useful for configuring the source, for example in CMakeFlags file (see previous point). |
| 45 | | {{{ |
| 46 | | -DCMAKE_BUILD_TYPE:STRING=Debug |
| 47 | | }}} |
| 48 | | This impacts both the compiler's flags (including symbols for debug) and freeDiameter itself (allowing some slow tracing options such as {{{--dbg-func}}}). |
| 49 | | {{{ |
| 50 | | -DSKIP_TESTS:BOOL=OFF |
| 51 | | }}} |
| 52 | | Allows the compilation of the unit tests, called by running {{{make test}}}. |
| 53 | | {{{ |
| 54 | | -DBUILD_TEST_APP:BOOL=ON |
| 55 | | }}} |
| 56 | | Compile the test application extension [wiki:test_app.fdx]. |
| 57 | | |
| 58 | | == Developer's useful files == |
| 59 | | Here is a list of files that anyone starting with freeDiameter should read first: |
| 60 | | |
| 61 | | [source:freeDiameter/include/freeDiameter include/freeDiameter] directory:: |
| 62 | | 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: |
| 63 | | {{{ |
| 64 | | #!C |
| 65 | | #include <freeDiameter/extension.h> |
| 66 | | }}} |
| 67 | | The directory contains: |
| 68 | | * [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. |
| 69 | | * [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. |
| 70 | | * [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. |
| 71 | | * [source:freeDiameter/include/freeDiameter/freeDiameter-host.h.in freeDiameter-host.h.in]: This contains the host-specific configuration, generated by CMake. |
| 72 | | |
| 73 | | [source:freeDiameter/extensions/_sample Sample extension] directory:: |
| 74 | | 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. |
| 75 | | |
| 76 | | [source:freeDiameter/extensions/CMakeLists.txt extensions/CMakeLists.txt]:: |
| 77 | | The file that must be modified in order to add a new extension and have it compiled along. |
| 78 | | |
| 79 | | == New extensions in development == |
| 80 | | |
| 81 | | 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. |
| 82 | | |
| 83 | | The source code can be hosted here if you want, please contact dev@freediameter.net if you have any question. |
| 84 | | |
| 85 | | ''There are currently no known new development in progress.'' |
| 86 | | |
| 87 | | == Testing == |
| 88 | | |
| 89 | | The distribution includes a set of test files and scripts that one can run to check the basic behavior of the daemon. |
| 90 | | |
| 91 | | The easy way to run the unit tests is issuing the command: |
| 92 | | {{{ |
| 93 | | make test |
| 94 | | }}} |
| 95 | | This will run the tests and display the result. |
| 96 | | |
| 97 | | The distribution also comes with a framework for automatic regression testing. All the relevant files are included inside the [source:contrib/nightly_tests] folder -- see the README file for more information. We have a few build slaves for freeDiameter running these scripts nightly and reporting the results into our [http://www.freediameter.net/CDash/index.php?project=freeDiameter freeDiameter Dashboard]. You are very welcome to join the effort and contribute additional configurations. |
| 98 | | |
| 99 | | Thank you! |
| | 13 | If you are looking for information on obtaining the source code and compiling it, please check the [wiki:Installation] page. |
