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