← Back to branch summary

~cyphermox/connman/1.10

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Package Import Robot
  • Author(s): Mathieu Trudel-Lapierre, Andrew Brouwers, Mathieu Trudel-Lapierre
  • Date: 2012-05-24 22:09:35 UTC
  • mfrom: (1.1.3)
  • Revision ID: package-import@ubuntu.com-20120524220935-2hayi74rmyxopr5v
Tags: 1.0-1
http://bugs.debian.org/583925
http://bugs.debian.org/672989
http://bugs.debian.org/583928
[ Andrew Brouwers ]
* New upstream release (closes: #583925, #672989)
* Add debian/watch (closes: #583928)
* Update to compat 8 + standards version 3.9.3
  - Remove debian/tmp from install files
* debian/control: 
  - Remove obsolete deps (cdbs, quilt, dpkg-dev, ppp-dev, dhcp3-client)
    (use source format 3.0, too)
  - Add missing deps: iptables-dev, gnutls-dev
  - Add recommends for wpa_supplicant (wifi) + bluez (bluetooth)
  - Add a connman-doc package
* debian/rules:
  - Convert from cdbs -> dh; most of the details outling patches and source
    mangling should be obsolete with regular stable tarball releases;
    simplify the rules file accordingly
  - Add support for openvpn + openconnect to configure
  - Specify systemd unit-file location to provide upstream systemd unit
* Remove NM compatibility mode from default init-script options (no longer
  available upstream); remove connman.default accordingly
* Use dh_installinit for initscript install, and eliminate post/pre-install
  files used to manage the init script; thanks to Patrik Flykt for the
  suggestion!
* Update debian/copyright for DEP5 + GPL-2 simplification
* Punt debian/README.source - docs/*.txt should be covered by copyright
  now - update note accordingly

[ Mathieu Trudel-Lapierre ]
* debian/control:
  - Set VCS-* fields to new location.
  - Add a Conflicts: network-manager, wicd to the connman binary package,
    since they all try to manage the same network devices.
  - Fix my name in uploaders for proper signing.
  - Add a Depends for dbus, lsb-base to connman.
* debian/copyright: updated and fixed to adhere to DEP-5 format.
* debian/rules:
  - override dh_auto_install to fail on files that aren't installed; also
    clean up on .la files.
  - clean up on the debian/connman.init file we copy in installinit.
  - use --restart-on-upgrade for dh_installinit
* debian/patches/01-init-script-lsb-headers.patch: more fixes to the init
  script:
  - set LSB Default-Stop, add NAME, drop 'set -e'.
  - add support for a "status" command.
* debian/control, debian/compat: bump to compat level 9, to get the hardening
  flags at build time.
* debian/connman.install, debian/connman-dev.install: make the paths multiarch
  aware (since that comes along with compat 9).
* debian/connman.postinst, debian/rules: disable the connman init script on
  install if NetworkManager or wicd are installed. See README.Debian.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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