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.
   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   Disable SELinux
  80     # sudo setenforce 0
  81
  82   Run daemon in foreground with debugging
  83     # sudo ./src/bluetoothd -n -d -f ./src/main.conf
  84
  85   Run daemon with valgrind
  86    # sudo valgrind --trace-children=yes --track-origins=yes --track-fds=yes \
  87    --show-possibly-lost=no --leak-check=full --suppressions=./tools/valgrind.supp \
  88    ./src/bluetoothd -n -d -f ./src/main.conf
  89
  90 For production installations or distribution packaging it is important that
  91 the "--enable-maintainer-mode" option is NOT used.
  92
  93 Note multiple arguments to -d can be specified, colon, comma or space
  94 separated. The arguments are relative source code filenames for which
  95 debugging output should be enabled; output shell-style globs are
  96 accepted (e.g.: 'plugins/*:src/main.c').
  97
  98 Submitting patches
  99 ==================
 100
 101 If you fixed a bug or you want to add support for something, patches are
 102 welcome! In order to ease the inclusion of your patch, it's important to follow
 103 some rules, otherwise it will likely be rejected by maintainers.
 104
 105 Make sure the author name and email are set properly:
 106
 107   # git config --global user.name <name>
 108   # git config --global user.email <email>
 109
 110 The preferred way to send patches is by email, using git send-email:
 111
 112   # git config --global sendemail.smtpencryption <tls>
 113   # git config --global sendemail.smtpserver <smtp.gmail.com>
 114   # git config --global sendemail.smtpuser <yourname@gmail.com>
 115   # git config --global sendemail.smtpserverport <587>
 116   # git config sendemail.to linux-bluetooth@vger.kernel.org
 117
 118 BlueZ rules for submitting patches follow most of the rules used by Linux kernel
 119 (https://www.kernel.org/doc/Documentation/SubmittingPatches) with some remarks:
 120
 121 1) Do *not* add "Signed-off-by" lines in your commit messages. BlueZ does not
 122 use them, so including them is actually an error.
 123
 124 2) Be sure to follow the coding style rules of BlueZ. They are listed in
 125 doc/coding-style.txt.
 126
 127 3) Split your patch according to the top-level directories. E.g.: if you added
 128 a feature that touches files under 'include/', 'src/' and 'drivers/'
 129 directories, split in three separated patches, taking care not to
 130 break compilation.
 131
 132 4) Bug fixes should be sent first as they take priority over new features.
 133
 134 5) The commit message should follow 50/72 formatting which means the header
 135 should be limited to 50 characters and the description should be wrapped at 72
 136 characters except if it contains quoted information from debug tools like
 137 backtraces, compiler errors, etc.
 138
 139 6) Prefix the email subject with [PATCH BlueZ]:
 140
 141   # git config format.subjectprefix "PATCH BlueZ"
 142
 143 7) Add a cover letter when introducing a new feature explaning what problem
 144 you're trying to solve:
 145
 146   # git format-patch --cover-letter -M origin/master -o outgoing/
 147   # edit outgoing/0000-*
 148
 149 8) Submit:
 150
 151   # git send-email outgoing/*