[[PageOutline(2-4)]] = Installation = First, please check that your system meets the [wiki:Requirements] for freeDiameter. == Installing from pre-compiled packages == When available, this is the easy way to install {{{freeDiameter}}} framework on your machine, because it takes care of all the software dependencies for you. * [wiki:DebRepository Debian and Ubuntu] packages information. * [wiki:FedRepository Fedora, CentOS, and RHEL] packages information. * [wiki:OWRTRepository OpenWRT] package information. == Installing from source == If there is no pre-compiled package for your platform, or if you need to change some compilation options, please follow these instructions. === Obtaining the source code === The recommended method is to use [http://mercurial.selenic.com/ Mercurial SCM] to retrieve the source code. This allows to update easily to latest development version, keep track of your changes, and so on. {{{ # The first time, you need to clone the repository as follow: $ hg clone http://www.freediameter.net/hg/freeDiameter # Later when you want to retrieve the latest changes: $ hg pull -u # To retrieve a specified tagged version (see with 'hg tags') $ hg update 1.1.0-rc3 }}} Alternatively, you can retrieve the source code by HTTP protocol as follow: * Browse to [http://www.freediameter.net/hg/freeDiameter] * Select any revision in the ''changes'' or ''tags'' lists (default is 'tip', the latest) * Then click on one of the {{{bz2}}}, {{{zip}}}, or {{{gz}}} link at the top. * You can alternatively directly access the following URL to retrieve the most recent source: [http://www.freediameter.net/hg/freeDiameter/archive/tip.tar.gz]. === Configuring the build === #cmakeflags This step is equivalent to the traditional ''./configure'' except that we use [http://www.cmake.org CMake] which provides a much nicer interface. You will therefore need to install {{{cmake}}} if it is not yet available on your machine. Note that there are several nice Graphical User Interfaces (GUI) available for CMake. It is highly recommended to build {{{freeDiameter}}} outside of the source repository. {{{ $ mkdir fDbuild $ cd fDbuild $ cmake [CMAKE_OPTIONS] /path/to/freeDiameter/source }}} Note that you can either specify the CMAKE_OPTIONS directly on the command line, or later by running: {{{ $ cmake /path/to/freeDiameter/source $ make edit_cache }}} The following options are available when configuring {{{freeDiameter}}}: ==== Parameters to control file paths ==== CMAKE_INSTALL_PREFIX:: This is the prefix under which all freeDiameter files will be installed. Default is {{{/usr/local}}}. Overwrite on the command line with for example ''-DCMAKE_INSTALL_PREFIX:STRING=/usr''. DEFAULT_CONF_PATH:: This is the default directory where the {{{freeDiameter}}} framework will look for its configuration file, when specified as a relative file name. The default value is {{{${CMAKE_INSTALL_PREFIX}/etc/freeDiameter}}}. INSTALL_HEADERS_SUFFIX:: Where the development header files are installed, relative to ${CMAKE_INSTALL_PREFIX}. The default is {{{include/freeDiameter}}}. INSTALL_DAEMON_SUFFIX:: Where the binary executable files are installed, relative to ${CMAKE_INSTALL_PREFIX}. The default is {{{bin}}}. INSTALL_LIBRARY_SUFFIX:: Where the {{{freeDiameter}}} framework libraries are installed, relative to ${CMAKE_INSTALL_PREFIX}. The default is {{{lib}}}. INSTALL_EXTENSIONS_SUFFIX:: Where the {{{freeDiameter}}} extensions files are installed and searched at runtime, relative to ${CMAKE_INSTALL_PREFIX}. The default is {{{${INSTALL_LIBRARY_SUFFIX}/freeDiameter}}}. ==== Parameters for dependencies ==== It is possible to overwrite the default location for libraries and tools dependencies. We are not going to give an exhaustive list here, here are two examples: Use an alternate GNUTLS library installed under ''/usr/local'':: {{{ -DGNUTLS_INCLUDE_DIR:PATH=/usr/local/include -DGCRYPT_INCLUDE_DIR:PATH=/usr/local/include -DGNUTLS_LIBRARY:FILEPATH=/usr/local/lib/libgnutls.so }}} Use a different flex executable:: {{{ -DFLEX_EXECUTABLE:FILEPATH=/usr/local/bin/flex }}} ==== Parameters to control the framework behavior ==== CMAKE_BUILD_TYPE:: This is specifies the set of flags that are passed to the C compiler and linker. Valid build types are: * "''Debug''" -- recommended for developers, * "''Profiling''" * "''!DebugValgrind''" -- use to monitor execution with valgrind * "''!DebianPackage''" -- use for releases * "''!MaxPerformance''" -- strips all debug support including error messages, use only for performance tests. DISABLE_SCTP (BOOL):: Set this option to ON to strip all SCTP-related code from the framework. The default is OFF. SCTP_USE_MAPPED_ADDRESSES (BOOL):: Previous implementations of the SCTP socket extensions did not have a proper handling of mixed IP and IPv6 situations. This parameter allows to pass all IP addresses in IPv6-mapped format, suppressing the problems. However, with recent implementations, having native IP format should not be an issue. DIAMID_IDNA_IGNORE (BOOL), DIAMID_IDNA_REJECT (BOOL):: By default, the {{{freeDiameter}}} framework accepts Diameter Identities and Realms provided in native language (UTF-8 encoded), and process these according to the IDN transformation rules (stringprep) (you know, that xn--... thing). It allows to use IDN names in the configuration file. However, by specifying one of these options, you can change this behavior to either pass blindly (will send invalid AVPs in the network) or reject (the framework will terminate) any IDN. Either option removes the dependency of the framework on the GNU libidn library. ==== Parameters to control extensions build ==== ALL_EXTENSIONS (BOOL):: Set this value to ON in order to build all available extensions. You can always customize the extensions you will actually load in the framework configuration file. Beware however that some extensions may have additional requirements (such as database support) and the compilation time will increase when this option is set. When the option is not set, you can select/deselect the individual extensions with the next option: BUILD_* (BOOL):: You can select the extensions individually with these options. For example, set BUILD_APP_ACCT:BOOL=ON in order to build the [wiki:app_acct.fdx] extension. ==== Parameters for debug / development only ==== DEBUG_SCTP (BOOL):: If SCTP is not disabled, set this option to turn on extra debug messages in SCTP code. Useful for debugging only. ERRORS_ON_TODO (BOOL):: The TODO("...") macro is used in the code for incomplete features. Turn on this option to trig a compilation error wherever this macro appears, to find it easily (if you don't like ''grep'') BUILD_TESTING (BOOL):: Set this value to ON in order to build the tests, then run with ''make test'' command. TEST_TIMEOUT:: If this value is set (to an integer), it overwrites the default timeout value for the tests. The default is 120 seconds. TEST_APP_ACCT (BOOL):: If BUILD_TESTING and BUILD_APP_ACCT are true, this option can be selected to build the additional test for [wiki:app_acct.fdx]. This test requires a PostgreSQL environment installed, this is why it is separated. You also need to specify the TEST_APP_ACCT_CONNINFO variable to allow the test to access its database, as for example TEST_APP_ACCT_CONNINFO="host=localhost port=5432 dbname=acct user=acct". === Compiling === Hopefully, once you have completed the ''cmake'' configuration, you only need to run: {{{ $ make }}} This will compile all source files and produce the binaries. If you want a more detailed output, you can also use: {{{ $ make VERBOSE=1 }}} === Installing === Once the compilation is complete, you can install in the configured paths with: {{{ $ make install }}} (this might require ''sudo'' depending on the configured target directories) Please note that there is no ''make uninstall'' target generated by CMake. Refer to CMake documentation to find how to cleanly remove all that has been installed. Note that the framework can be run without installation, as long as the configuration file contains the full path to extensions that must be loaded. ----