From: Luiz Augusto von Dentz <luiz.von.dentz@xxxxxxxxx> --- HACKING | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 HACKING diff --git a/HACKING b/HACKING new file mode 100644 index 0000000..ffca598 --- /dev/null +++ b/HACKING @@ -0,0 +1,129 @@ +Hacking on BlueZ +**************** + +Build tools requirements +======================== + +When building and testing directly from the repository it is important to +have at least automake version 1.10 or later installed. All modern +distributions should default to the latest version, but it seems that +Debian's default is still an earlier version: + + Check version + # dpkg -l '*automake*' + + Install new version + # apt-get install automake1.10 + # update-alternatives --config automake + + +Working with the source code repository +======================================= + +The repository contains two extra scripts that accomplish the bootstrap +process. One is called "bootstrap" which is the basic scripts that uses the +autotools scripts to create the needed files for building and installing. +It makes sure to call the right programs depending on the usage of shared or +static libraries or translations etc. + +The second program is called "bootstrap-configure". This program will make +sure to properly clean the repository, call the "bootstrap" script and then +call configure with proper settings for development. It will use the best +options and pass them over to configure. These options normally include +the enabling the maintainer mode and the debugging features. + +So while in a normal source project the call "./configure ..." is used to +configure the project with its settings like prefix and extra options. In +case of bare repositories call "./bootstrap-configure" and it will bootstrap +the repository and calls configure with all the correct options to make +development easier. + +In case of preparing for a release with "make distcheck", don't use +bootstrap-configure since it could export development specific settings. + +So the normal steps to checkout, build and install such a repository is +like this: + + Checkout repository + # git clone git://git.kernel.org/pub/scm/bluetooth/bluez.git + # cd bluez + + Configure and build + # ./bootstrap-configure + # make + + Configure and build with cgcc (Sparse) + # ./bootstrap-configure CC=cgcc + # make + + Run unit tests + # make check + + Check installation + # make install DESTDIR=$PWD/x + # find x + # rm -rf x + + Check distribution + # make distcheck + + Final installation + # sudo make install + + Remove autogenerated files + # make maintainer-clean + + +Running from within the source code repository +============================================== + +When using "./configure --enable-maintainer-mode" the automake scripts will +use the plugins directly from within the repository. This removes the need +to use "make install" when testing "bluetoothd". The "bootstrap-configure" +automatically includes this option. + + Copy configuration file which specifies the required security policies + # sudo cp ./src/bluetooth.conf /etc/dbus-1/system.d/ + + Run daemon in foreground with debugging + # sudo ./src/bluetoothd -n -d + + Run daemon with valgrind + # sudo valgrind --trace-children=yes --track-origins=yes --track-fds=yes + --show-possibly-lost=no --leak-check=full ./src/bluetoothd -n -d + +For production installations or distribution packaging it is important that +the "--enable-maintainer-mode" option is NOT used. + +Note multiple arguments to -d can be specified, colon, comma or space +separated. The arguments are relative source code filenames for which +debugging output should be enabled; output shell-style globs are +accepted (e.g.: 'plugins/*:src/main.c'). + +Submitting patches +================== + +If you fixed a bug or you want to add support for something, patches are +welcome! In order to ease the inclusion of your patch, it's important to follow +some rules, otherwise it will likely be rejected by maintainers. + +BlueZ rules for submitting patches follow most of the rules used by Linux kernel +(https://www.kernel.org/doc/Documentation/SubmittingPatches) with some remarks: + +1) Do *not* add "Signed-off-by" lines in your commit messages. BlueZ does not +use them, so including them is actually an error. + +2) Be sure to follow the coding style rules of BlueZ. They are listed in +doc/coding-style.txt. + +3) Split your patch according to the top-level directories. E.g.: if you added +a feature that touches files under 'include/', 'src/' and 'drivers/' +directories, split in three separated patches, taking care not to +break compilation. + +4) Bug fixes should be sent first as they take priority over new features. + +5) The commit message should follow 50/72 formatting which means the header +should be limited to 50 characters and the description should be wrapped at 72 +characters except if it contains quoted information from debug tools like +backtraces, compiler errors, etc. -- 1.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
