Navigation


Changes between Version 12 and Version 13 of Developers


Ignore:
Timestamp:
Mar 1, 2011, 11:10:52 AM (10 years ago)
Author:
Sebastien Decugis
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Developers

    v12 v13  
    1 [[PageOutline(1-3)]]
    2 = Information for developers =
     1= Developers Corner =
    32
    4 The project is managed with [http://mercurial.selenic.com/ mercurial]. You can access the repository at this address: [http://www.freediameter.net/hg/freeDiameter]
     3The developers mailing-list is: dev@freediameter.net
     4 * [http://lists.freediameter.net/pipermail/help/ Archives]
     5 * [http://lists.freediameter.net/cgi-bin/mailman/listinfo/help Subscribe]
    56
    6 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 [http://lists.freediameter.net/cgi-bin/mailman/listinfo/dev here] and check the archives [http://lists.freediameter.net/pipermail/dev/ there]. The tickets system can also be used.
     7You may also find the following pages of interest:
     8 * [wiki:Dev/Overview An overview of freeDiameter source code]
     9 * [wiki:Dev/API Description of the freeDiameter API]
     10 * [wiki:Dev/Extending A guide to writting a freeDiameter extension]
     11 * [wiki:Dev/Embedding A guide to embedding freeDiameter in another project]
    712
    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!
     13If you are looking for information on obtaining the source code and compiling it, please check the [wiki:Installation] page.
    10014
    10115----