HACKING

Hacking on Connection Manager
*****************************


Build tools requirements
========================

When building and testing directly from the repository it is important to
have at least automake version 1.10 or later installed. All modern
distributions should default to the latest version, but it seems that
Debian's default is still an earlier version:

  Check version
    # dpkg -l '*automake*'

  Install new version
    # apt-get install automake1.10
    # update-alternatives --config automake


Working with the source code repository
=======================================

The repository contains two extra scripts that accomplish the bootstrap
process. One is called "bootstrap" which is the basic scripts that uses the
autotools scripts to create the needed files for building and installing.
It makes sure to call the right programs depending on the usage of shared or
static libraries or translations etc.

The second program is called "bootstrap-configure". This program will make
sure to properly clean the repository, call the "bootstrap" script and then
call configure with proper settings for development. It will use the best
options and pass them over to configure. These options normally include
the enabling the maintainer mode and the debugging features.

So while in a normal source project the call "./configure ..." is used to
configure the project with its settings like prefix and extra options. In
case of bare repositories call "./bootstrap-configure" and it will bootstrap
the repository and calls configure with all the correct options to make
development easier.

In case of preparing for a release with "make distcheck", don't use
bootstrap-configure since it could export development specific settings.

So the normal steps to checkout, build and install such a repository is
like this:

  Checkout repository
    # git clone git://git.kernel.org/pub/scm/network/connman/connman.git
    # cd connman

  Configure and build
    # ./bootstrap-configure
    # make

  Check installation
    # make install DESTDIR=$PWD/x
    # find x
    # rm -rf x

  Check distribution
    # make distcheck

  Final installation
    # sudo make install

  Remove autogenerated files
    # make maintainer-clean


Running from within the source code repository
==============================================

When using "./configure --enable-maintainer-mode" the automake scripts will
use the plugins directly from within the repository. This removes the need
to use "make install" when testing "connmand". The "bootstrap-configure"
automatically includes this option.

  Run daemon in foreground with debugging
    # sudo ./src/connmand -n -d 'plugins/*'

The debugging option -d takes an argument. This argument can be a comma
separated list of file names like 'plugins/wifi.c,plugins/ethernet.c' to
enable debugs in these files. Simple glob style pattern matching is
supported in this list.

For production installations or distribution packaging it is important that
the "--enable-maintainer-mode" option is NOT used.

Some times it is important to restrict the available interfaces. For example
in cases where testing happens over a network connection. The "-i" command
line switch allows to specify a glob pattern for the interface names.

  Run daemon for wireless interfaces
    # sudo ./src/connmand -n -i wlan*


Debugging the D-Bus interface during runtime
============================================

Running the daemon with debugging information in the foreground is quite
verbose and sometimes not really helpful. The "monitor-connman" script
allows to monitor "PropertyChanged" D-Bus signals from various interfaces.

Every "PropertyChanged" signal will generate a line of output. Some of them
can get very complex. The first detail inside "{ ... }" is the interface
name (without its service name prefix). The second detail inside "[ ... ]"
is the object path. And after that it is followed by a key and value of
the property that changed.


Generating source code documentation
====================================

The source code is annotated using the gtk-doc style documentation. This
allows an easy way of generating API documentation. The "bootstrap-configure"
script will use the "--enable-gtk-doc" configure to enable the generation of
the documentation.

To make the gtk-doc process work, the gtk-doc tools need to be installed.
Every distribution should provide a package for this, but the naming of the
package might be different:

  Debian
    # apt-get install gtk-doc-tools

  Ubuntu
    # apt-get install gtk-doc-utils

  Fedora
    # yum install gtk-doc

In case "bootstrap-configure" is not used, the manual steps for generating
the documentation files are like this:

  Configuring the repository
    # ./configure --enable-gtk-doc

  Generate the documentation
    # cd doc && make

  View documentation
    # firefox doc/html/index.html