Mention the automake version 1.10 requirement
[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 Generating source code documentation
94 ====================================
95
96 The source code is annotated using the gtk-doc style documentation. This
97 allows an easy way of generating API documentation. The "bootstrap-configure"
98 script will use the "--enable-gtk-doc" configure to enable the generation of
99 the documentation.
100
101 To make the gtk-doc process work, the gtk-doc tools need to be installed.
102 Every distribution should provide a package for this, but the naming of the
103 package might be different:
104
105   Ubuntu/Debian
106     # apt-get install gtk-doc-utils
107
108   Fedora
109     # yum install gtk-doc
110
111 In case "bootstrap-configure" is not used, the manual steps for generating
112 the documentation files are like this:
113
114   Configuring the repository
115     # ./configure --enable-gtk-doc
116
117   Generate the documentation
118     # cd doc && make
119
120   View documentation
121     # firefox doc/html/index.html
122