HACKING - vendor/opensource/bluez - Git at Google

 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 --suppressions=./tools/valgrind.supp \
    ./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.

 Make sure the author name and email are set properly:

   # git config --global user.name <name>
   # git config --global user.email <email>

 The preferred way to send patches is by email, using git send-email:

   # git config --global sendemail.smtpencryption <tls>
   # git config --global sendemail.smtpserver <smtp.gmail.com>
   # git config --global sendemail.smtpuser <yourname@gmail.com>
   # git config --global sendemail.smtpserverport <587>
   # git config sendemail.to linux-bluetooth@vger.kernel.org

 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.

 6) Prefix the email subject with [PATCH BlueZ]:

   # git config format.subjectprefix "PATCH BlueZ"

 7) Add a cover letter when introducing a new feature explaning what problem
 you're trying to solve:

   # git format-patch --cover-letter -M origin/master -o outgoing/
   # edit outgoing/0000-*

 8) Submit:

   # git send-email outgoing/*
	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 --suppressions=./tools/valgrind.supp \
	./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.

	Make sure the author name and email are set properly:

	# git config --global user.name <name>
	# git config --global user.email <email>

	The preferred way to send patches is by email, using git send-email:

	# git config --global sendemail.smtpencryption <tls>
	# git config --global sendemail.smtpserver <smtp.gmail.com>
	# git config --global sendemail.smtpuser <yourname@gmail.com>
	# git config --global sendemail.smtpserverport <587>
	# git config sendemail.to linux-bluetooth@vger.kernel.org

	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.

	6) Prefix the email subject with [PATCH BlueZ]:

	# git config format.subjectprefix "PATCH BlueZ"

	7) Add a cover letter when introducing a new feature explaning what problem
	you're trying to solve:

	# git format-patch --cover-letter -M origin/master -o outgoing/
	# edit outgoing/0000-*

	8) Submit:

	# git send-email outgoing/*