15488
by Luiz Augusto von Dentz
build: Add initial HACKING |
1 |
Hacking on BlueZ |
2 |
****************
|
|
3 |
||
4 |
Build tools requirements |
|
5 |
========================
|
|
6 |
||
7 |
When building and testing directly from the repository it is important to |
|
19537
by David Frey
Remove obsolete Debian notes from HACKING |
8 |
have at least automake version 1.10 or later installed. |
15488
by Luiz Augusto von Dentz
build: Add initial HACKING |
9 |
|
10 |
||
11 |
Working with the source code repository |
|
12 |
=======================================
|
|
13 |
||
14 |
The repository contains two extra scripts that accomplish the bootstrap |
|
15 |
process. One is called "bootstrap" which is the basic scripts that uses the |
|
16 |
autotools scripts to create the needed files for building and installing. |
|
17 |
It makes sure to call the right programs depending on the usage of shared or |
|
18 |
static libraries or translations etc. |
|
19 |
||
20 |
The second program is called "bootstrap-configure". This program will make |
|
21 |
sure to properly clean the repository, call the "bootstrap" script and then |
|
22 |
call configure with proper settings for development. It will use the best |
|
23 |
options and pass them over to configure. These options normally include |
|
24 |
the enabling the maintainer mode and the debugging features. |
|
25 |
||
26 |
So while in a normal source project the call "./configure ..." is used to |
|
27 |
configure the project with its settings like prefix and extra options. In |
|
28 |
case of bare repositories call "./bootstrap-configure" and it will bootstrap |
|
29 |
the repository and calls configure with all the correct options to make |
|
30 |
development easier. |
|
31 |
||
32 |
In case of preparing for a release with "make distcheck", don't use |
|
33 |
bootstrap-configure since it could export development specific settings. |
|
34 |
||
35 |
So the normal steps to checkout, build and install such a repository is |
|
36 |
like this: |
|
37 |
||
38 |
Checkout repository |
|
39 |
# git clone git://git.kernel.org/pub/scm/bluetooth/bluez.git
|
|
40 |
# cd bluez
|
|
41 |
||
42 |
Configure and build |
|
43 |
# ./bootstrap-configure
|
|
44 |
# make
|
|
45 |
||
46 |
Configure and build with cgcc (Sparse) |
|
47 |
# ./bootstrap-configure CC=cgcc
|
|
48 |
# make
|
|
49 |
||
50 |
Run unit tests |
|
51 |
# make check
|
|
52 |
||
53 |
Check installation |
|
54 |
# make install DESTDIR=$PWD/x
|
|
55 |
# find x
|
|
56 |
# rm -rf x
|
|
57 |
||
58 |
Check distribution |
|
59 |
# make distcheck
|
|
60 |
||
61 |
Final installation |
|
62 |
# sudo make install
|
|
63 |
||
64 |
Remove autogenerated files |
|
65 |
# make maintainer-clean
|
|
66 |
||
67 |
||
68 |
Running from within the source code repository |
|
69 |
==============================================
|
|
70 |
||
71 |
When using "./configure --enable-maintainer-mode" the automake scripts will |
|
72 |
use the plugins directly from within the repository. This removes the need |
|
73 |
to use "make install" when testing "bluetoothd". The "bootstrap-configure" |
|
74 |
automatically includes this option. |
|
75 |
||
76 |
Copy configuration file which specifies the required security policies |
|
77 |
# sudo cp ./src/bluetooth.conf /etc/dbus-1/system.d/
|
|
78 |
||
79 |
Run daemon in foreground with debugging |
|
19091
by Luiz Augusto von Dentz
HACKING: Update instructions on how to run from source tree |
80 |
# sudo ./src/bluetoothd -n -d -f ./src/main.conf
|
15488
by Luiz Augusto von Dentz
build: Add initial HACKING |
81 |
|
82 |
Run daemon with valgrind |
|
18491
by Gowtham Anandha Babu
HACKING: Add suppression file in valgrind cmd |
83 |
# sudo valgrind --trace-children=yes --track-origins=yes --track-fds=yes \
|
84 |
--show-possibly-lost=no --leak-check=full --suppressions=./tools/valgrind.supp \ |
|
19091
by Luiz Augusto von Dentz
HACKING: Update instructions on how to run from source tree |
85 |
./src/bluetoothd -n -d -f ./src/main.conf |
15488
by Luiz Augusto von Dentz
build: Add initial HACKING |
86 |
|
87 |
For production installations or distribution packaging it is important that |
|
88 |
the "--enable-maintainer-mode" option is NOT used. |
|
89 |
||
90 |
Note multiple arguments to -d can be specified, colon, comma or space |
|
91 |
separated. The arguments are relative source code filenames for which |
|
92 |
debugging output should be enabled; output shell-style globs are |
|
93 |
accepted (e.g.: 'plugins/*:src/main.c'). |
|
94 |
||
95 |
Submitting patches |
|
96 |
==================
|
|
97 |
||
98 |
If you fixed a bug or you want to add support for something, patches are |
|
99 |
welcome! In order to ease the inclusion of your patch, it's important to follow |
|
100 |
some rules, otherwise it will likely be rejected by maintainers. |
|
101 |
||
18600
by Luiz Augusto von Dentz
HACKING: Add necessary commands to configure git send-email |
102 |
Make sure the author name and email are set properly: |
103 |
||
104 |
# git config --global user.name <name>
|
|
105 |
# git config --global user.email <email>
|
|
106 |
||
107 |
The preferred way to send patches is by email, using git send-email: |
|
108 |
||
109 |
# git config --global sendemail.smtpencryption <tls>
|
|
110 |
# git config --global sendemail.smtpserver <smtp.gmail.com>
|
|
111 |
# git config --global sendemail.smtpuser <yourname@gmail.com>
|
|
112 |
# git config --global sendemail.smtpserverport <587>
|
|
113 |
# git config sendemail.to linux-bluetooth@vger.kernel.org
|
|
114 |
||
15488
by Luiz Augusto von Dentz
build: Add initial HACKING |
115 |
BlueZ rules for submitting patches follow most of the rules used by Linux kernel |
116 |
(https://www.kernel.org/doc/Documentation/SubmittingPatches) with some remarks: |
|
117 |
||
118 |
1) Do *not* add "Signed-off-by" lines in your commit messages. BlueZ does not |
|
119 |
use them, so including them is actually an error. |
|
120 |
||
121 |
2) Be sure to follow the coding style rules of BlueZ. They are listed in |
|
122 |
doc/coding-style.txt. |
|
123 |
||
124 |
3) Split your patch according to the top-level directories. E.g.: if you added |
|
125 |
a feature that touches files under 'include/', 'src/' and 'drivers/' |
|
126 |
directories, split in three separated patches, taking care not to |
|
127 |
break compilation. |
|
128 |
||
129 |
4) Bug fixes should be sent first as they take priority over new features. |
|
130 |
||
131 |
5) The commit message should follow 50/72 formatting which means the header |
|
132 |
should be limited to 50 characters and the description should be wrapped at 72 |
|
133 |
characters except if it contains quoted information from debug tools like |
|
134 |
backtraces, compiler errors, etc. |
|
18600
by Luiz Augusto von Dentz
HACKING: Add necessary commands to configure git send-email |
135 |
|
136 |
6) Prefix the email subject with [PATCH BlueZ]: |
|
137 |
||
138 |
# git config format.subjectprefix "PATCH BlueZ"
|
|
139 |
||
18610
by Francois Beaufort
HACKING: Fix nit in instructions |
140 |
7) Add a cover letter when introducing a new feature explaning what problem |
18600
by Luiz Augusto von Dentz
HACKING: Add necessary commands to configure git send-email |
141 |
you're trying to solve: |
142 |
||
143 |
# git format-patch --cover-letter -M origin/master -o outgoing/
|
|
144 |
# edit outgoing/0000-*
|
|
145 |
||
18610
by Francois Beaufort
HACKING: Fix nit in instructions |
146 |
8) Submit: |
18600
by Luiz Augusto von Dentz
HACKING: Add necessary commands to configure git send-email |
147 |
|
148 |
# git send-email outgoing/*
|