Add some details about the monitor-connman script
[platform/upstream/connman.git] / 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.moblin.org/projects/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
81
82 For production installations or distribution packaging it is important that
83 the "--enable-maintainer-mode" option is NOT used.
84
85 Some times it is important to restrict the available interfaces. For example
86 in cases where testing happens over a network connection. The "-i" command
87 line switch allows to specify a glob pattern for the interface names.
88
89   Run daemon for wireless interfaces
90     # sudo ./src/connmand -n -i wlan*
91
92
93 Debugging the D-Bus interface during runtime
94 ============================================
95
96 Running the daemon with debugging information in the foreground is quite
97 verbose and sometimes not really helpful. The "monitor-connman" script
98 allows to monitor "PropertyChanged" D-Bus signals from various interfaces.
99
100   During start of daemon
101     {Manager} [/] Devices = dbus.Array([dbus.ObjectPath('/dev_00_90_CC ...
102     {Device} [/dev_00_90_CC_xx_xx_xx] Powered = 1
103     {Device} [/dev_00_90_CC_xx_xx_xx] Networks = dbus.Array( ...
104
105   During shutdown of daemon
106     {Device} [/dev_00_90_CC_xx_xx_xx] Networks = dbus.Array( ...
107     {Device} [/dev_00_90_CC_xx_xx_xx] Powered = 0
108     {Manager} [/] Devices = dbus.Array([], ...
109
110 Every "PropertyChanged" signal will generate a line of output. Some of them
111 can get very complex. The first detail inside "{ ... }" is the interface
112 name (without its service name prefix). The second detail inside "[ ... ]"
113 is the object path. And after that it is followed by a key and value of
114 the property that changed.
115
116
117 Generating source code documentation
118 ====================================
119
120 The source code is annotated using the gtk-doc style documentation. This
121 allows an easy way of generating API documentation. The "bootstrap-configure"
122 script will use the "--enable-gtk-doc" configure to enable the generation of
123 the documentation.
124
125 To make the gtk-doc process work, the gtk-doc tools need to be installed.
126 Every distribution should provide a package for this, but the naming of the
127 package might be different:
128
129   Ubuntu/Debian
130     # apt-get install gtk-doc-utils
131
132   Fedora
133     # yum install gtk-doc
134
135 In case "bootstrap-configure" is not used, the manual steps for generating
136 the documentation files are like this:
137
138   Configuring the repository
139     # ./configure --enable-gtk-doc
140
141   Generate the documentation
142     # cd doc && make
143
144   View documentation
145     # firefox doc/html/index.html
146