HACKING

   1 Hacking on Connection Manager
   2 *****************************
   3
   4
   5 Build tools requirements
   6 ========================
   7
   8 When building and testing directly from the repository it is important to
   9 have at least automake version 1.10 or later installed. All modern
  10 distributions should default to the latest version, but it seems that
  11 Debian's default is still an earlier version:
  12
  13   Check version
  14     # dpkg -l '*automake*'
  15
  16   Install new version
  17     # apt-get install automake1.10
  18     # update-alternatives --config automake
  19
  20
  21 Working with the source code repository
  22 =======================================
  23
  24 The repository contains two extra scripts that accomplish the bootstrap
  25 process. One is called "bootstrap" which is the basic scripts that uses the
  26 autotools scripts to create the needed files for building and installing.
  27 It makes sure to call the right programs depending on the usage of shared or
  28 static libraries or translations etc.
  29
  30 The second program is called "bootstrap-configure". This program will make
  31 sure to properly clean the repository, call the "bootstrap" script and then
  32 call configure with proper settings for development. It will use the best
  33 options and pass them over to configure. These options normally include
  34 the enabling the maintainer mode and the debugging features.
  35
  36 So while in a normal source project the call "./configure ..." is used to
  37 configure the project with its settings like prefix and extra options. In
  38 case of bare repositories call "./bootstrap-configure" and it will bootstrap
  39 the repository and calls configure with all the correct options to make
  40 development easier.
  41
  42 In case of preparing for a release with "make distcheck", don't use
  43 bootstrap-configure since it could export development specific settings.
  44
  45 So the normal steps to checkout, build and install such a repository is
  46 like this:
  47
  48   Checkout repository
  49     # git clone git://git.kernel.org/pub/scm/network/connman/connman.git
  50     # cd connman
  51
  52   Configure and build
  53     # ./bootstrap-configure
  54     # make
  55
  56   Check installation
  57     # make install DESTDIR=$PWD/x
  58     # find x
  59     # rm -rf x
  60
  61   Check distribution
  62     # make distcheck
  63
  64   Final installation
  65     # sudo make install
  66
  67   Remove autogenerated files
  68     # make maintainer-clean
  69
  70
  71 Running from within the source code repository
  72 ==============================================
  73
  74 When using "./configure --enable-maintainer-mode" the automake scripts will
  75 use the plugins directly from within the repository. This removes the need
  76 to use "make install" when testing "connmand". The "bootstrap-configure"
  77 automatically includes this option.
  78
  79   Run daemon in foreground with debugging
  80     # sudo ./src/connmand -n -d 'plugins/*'
  81
  82 The debugging option -d takes an argument. This argument can be a comma
  83 separated list of file names like 'plugins/wifi.c,plugins/ethernet.c' to
  84 enable debugs in these files. Simple glob style pattern matching is
  85 supported in this list.
  86
  87 For production installations or distribution packaging it is important that
  88 the "--enable-maintainer-mode" option is NOT used.
  89
  90 Some times it is important to restrict the available interfaces. For example
  91 in cases where testing happens over a network connection. The "-i" command
  92 line switch allows to specify a glob pattern for the interface names.
  93
  94   Run daemon for wireless interfaces
  95     # sudo ./src/connmand -n -i wlan*
  96
  97
  98 Debugging the D-Bus interface during runtime
  99 ============================================
 100
 101 Running the daemon with debugging information in the foreground is quite
 102 verbose and sometimes not really helpful. The "monitor-connman" script
 103 allows to monitor "PropertyChanged" D-Bus signals from various interfaces.
 104
 105   During start of daemon
 106     {Manager} [/] Devices = dbus.Array([dbus.ObjectPath('/dev_00_90_CC ...
 107     {Device} [/dev_00_90_CC_xx_xx_xx] Powered = 1
 108     {Device} [/dev_00_90_CC_xx_xx_xx] Networks = dbus.Array( ...
 109
 110   During shutdown of daemon
 111     {Device} [/dev_00_90_CC_xx_xx_xx] Networks = dbus.Array( ...
 112     {Device} [/dev_00_90_CC_xx_xx_xx] Powered = 0
 113     {Manager} [/] Devices = dbus.Array([], ...
 114
 115 Every "PropertyChanged" signal will generate a line of output. Some of them
 116 can get very complex. The first detail inside "{ ... }" is the interface
 117 name (without its service name prefix). The second detail inside "[ ... ]"
 118 is the object path. And after that it is followed by a key and value of
 119 the property that changed.
 120
 121
 122 Generating source code documentation
 123 ====================================
 124
 125 The source code is annotated using the gtk-doc style documentation. This
 126 allows an easy way of generating API documentation. The "bootstrap-configure"
 127 script will use the "--enable-gtk-doc" configure to enable the generation of
 128 the documentation.
 129
 130 To make the gtk-doc process work, the gtk-doc tools need to be installed.
 131 Every distribution should provide a package for this, but the naming of the
 132 package might be different:
 133
 134   Debian
 135     # apt-get install gtk-doc-tools
 136
 137   Ubuntu
 138     # apt-get install gtk-doc-utils
 139
 140   Fedora
 141     # yum install gtk-doc
 142
 143 In case "bootstrap-configure" is not used, the manual steps for generating
 144 the documentation files are like this:
 145
 146   Configuring the repository
 147     # ./configure --enable-gtk-doc
 148
 149   Generate the documentation
 150     # cd doc && make
 151
 152   View documentation
 153     # firefox doc/html/index.html
 154