[[setup]]
=== Tool setups

Although these are not necessary the requirement, basic tool setups are described as below for us to share the common baseline working environment.

CAUTION: Tool setups presented here are only meant as an example and may not be up-to-date with the latest packages on the system.  Please make sure to read pertinent documentation and update the configuration.


[[bash]]
==== Setting up *bash*

Various Debian maintenance tools offered by the *devscripts* package and *debmake* recognize your email address and name to use by the shell environment variables *$DEBEMAIL* and *$DEBFULLNAME*.

Let's set up these by adding the following lines to *\~/.bashrc* footnote:[This assumes you are using Bash as your login shell. If you use some other login shell such as Z shell, use their corresponding configuration files instead of *~/.bashrc*.].

.Add to the *~/.bashrc* file
----
DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME
----

[[mc]]
==== Setting up *mc*

The *mc* offers very easy ways to manage files.  It can open the binary *deb* file to check its content by pressing the Enter key over the binary *deb* file by using the *dpkg-deb* command as its back-end.  Let's set up its easy *chdir* support as follows.

.Add to the *~/.bashrc* file
----
# mc related
export HISTCONTROL=ignoreboth
. /usr/lib/mc/mc.sh
----

[[git]]
==== Setting up *git*

You may wish to set several global configuration in *~/.gitconfig* such as your name and email address used by Git by the following.

----
$ git config --global user.name "Name Surname"
$ git config --global user.email yourname@example.com
----

If you are too accustomed to the CVS or Subversion commands, you may wish to set several command aliases by the following.

----
$ git config --global alias.ci "commit -a"
$ git config --global alias.co checkout
----

You can check your global configuration by the following.

----
$ git config --global --list
----

TIP: It is essential to use the *gitk* command to work with the history of the Git repository.  

[[quilt]]
==== Setting up *quilt*

The program *quilt* offers a basic method for recording modifications to the upstream source for the Debian packaging. It's useful to have a slightly customized default suitable for the Debian packaging.

In order to avoid changing the behavior of the *quilt* command itself, let's create an alias *dquilt* for the Debian packaging by adding the following lines to the *~/.bashrc* file. The second line provides the same shell completion feature of the *quilt* command to the *dquilt* command.

.Add to the *~/.bashrc* file
----
alias dquilt="quilt --quiltrc=${HOME}/.quiltrc-dpkg"
complete -F _quilt_completion $_quilt_complete_opt dquilt
----

Then let's create *~/.quiltrc-dpkg* as follows.

----
d=. ; while [ ! -d $d/debian -a `readlink -e $d` != / ]; do d=$d/..; done
if [ -d $d/debian ] && [ -z $QUILT_PATCHES ]; then
    # if in Debian packaging tree with unset $QUILT_PATCHES
    QUILT_PATCHES="debian/patches"
    QUILT_PATCH_OPTS="--reject-format=unified"
    QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
    QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
    QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33"
    if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
fi
----

See *quilt*(1) and file:///usr/share/doc/quilt/quilt.html[How To Survive With Many Patches or Introduction to Quilt] on how to use the *quilt* command.

[[devscripts]]
==== Setting up *devscripts*

The *debuild* command runs the *dpkg-buildpackage* and *lintian* commands under the current build environment with the sanitized environment variables to create all the files necessary for uploading a Debian package.

Let's create *~/.devscripts* as follows.

----
DEBSIGN_KEYID='Your_GPG_keyID'
DEBUILD_LINTIAN_OPTS=-i -I --show-overrides
----

With these, packages are signed by your specified GPG key ID (good for sponsoring packages) and checked in detail by the *lintian* command.

Currently, RSA key with 4096 bits is good idea.  See http://keyring.debian.org/creating-key.html[Creating a new GPG key].

[[pbuilder]]
==== Setting up *pbuilder* + *cowbuilder* + *eatmydata* + *ccache* + *lintian* + ...

The *pbuilder* package provides the clean room (*chroot*) build environment. 

Let's customize it with several helper packages.

* The *cowbuilder* package to boost the chroot creation speed.
* The *eatmydata* package to boost the *dpkg* speed.
* The *ccache* package to boost the *gcc* speed.
* The parallel *make* to boost the build speed.
* The *lintian* package to find bugs in the package.
* The *bash*, *mc*, and *vim* packages in case build fails.

Let's create *~/.pbuilderrc* as follows.

----
AUTO_DEBSIGN="${AUTO_DEBSIGN:-no}"
PDEBUILD_PBUILDER=cowbuilder
HOOKDIR="/var/cache/pbuilder/hooks"
#MIRRORSITE=" http://ftp.us.debian.org/debian/"
MIRRORSITE="http://cdn.debian.net/debian/"
#APTCACHE=/var/cache/pbuilder/aptcache
APTCACHE=/var/cache/apt/archives
#BUILDRESULT=/var/cache/pbuilder/result/
BUILDRESULT=../
EXTRAPACKAGES="ccache lintian eatmydata"
# enable eatmydata for pbuilder
if [ -z "$LD_PRELOAD" ]; then
  LD_PRELOAD=/usr/lib/libeatmydata/libeatmydata.so
else
  LD_PRELOAD="$LD_PRELOAD":/usr/lib/libeatmydata/libeatmydata.so
fi
export LD_PRELOAD
# enable ccache for pbuilder
export PATH="/usr/lib/ccache:${PATH}"
export CCACHE_DIR="/var/cache/pbuilder/ccache"
BINDMOUNTS="${CCACHE_DIR}"
# parallel make
DEBBUILDOPTS=-j8
-----

NOTE: The parallel *make* may fail for some existing packages.

Let's create a hook scripts as follows.

*/var/cache/pbuilder/hooks/A10ccache*
----
#!/bin/sh
set -e
# increase the ccache caching size
ccache -M 4G
# output the current statistics
ccache -s
----

*/var/cache/pbuilder/hooks/B90lintian*
----
#!/bin/sh
set -e
apt-get -y --force-yes install lintian
echo "+++ lintian output +++"
su -c "lintian -i -I --show-overrides /tmp/buildd/*.changes; :" -l pbuilder
echo "+++ end of lintian output +++"
----

*/var/cache/pbuilder/hooks/C10shell*
----
#!/bin/sh
set -e
apt-get -y --force-yes install vim bash mc
# invoke shell if build fails
cd /tmp/buildd/*/debian/..
/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
----

NOTE: All these scripts need to be world executable: `-rwxr-xr-x 1 root root`

[[gbp]]
==== Setting up *git-buildpackage*

You may wish to set several global configuration in *~/.gbp.conf*

----
# Configuration file for "gbp <command>"

[DEFAULT]
# the default build command:
builder = git-pbuilder -i -I -us -uc
# use pristine-tar:
pristine-tar = True
# Use color when on a terminal, alternatives: on/true, off/false or auto
color = auto
----

[[chroot]]
==== Setting up *chroot*

A nice http://en.wikipedia.org/wiki/Chroot[chroot] environment can be organized with the *pbuilder*, *cowbuilder*, and *git-buildpackage* packages as described in <<pbuilder>>.
footnote:[This is *git-pbuilder* style using the *cowbuilder* package.  See https://wiki.debian.org/git-pbuilder .  Be careful since many HOWTOs use different organization.]

Here is a quick summary of how all the available commands fit together.  There are many ways to do the same thing.

* *dpkg-buildpackage* = core of package building tool
* *debuild* = *dpkg-buildpackage* + *lintian* (build under the sanitized environment variables)
* *pbuilder* = core of the Debian chroot environment tool
* *pdebuild* = *pbuilder* + *dpkg-buildpackage* (build in the chroot)
* *cowbuilder* = speed up the *pbuilder* execution
* *git-pbuilder* = the easy-to-use commandline syntax for *pdebuild* (used by *gbp buildpackge*)
* *gbp* = manage the Debian source under the git
* *gbp buildpackge* = *pbuilder* + *dpkg-buildpackage* + *gbp*

A clean *sid* distribution chroot environment can be used as follows. 

* The chroot filesystem creation command for the *sid* distribution
** *pbuilder create*
** *git-pbuilder create*
* The master chroot filesystem path for the *sid* distribution chroot
** */var/cache/pbuilder/base.cow*
* The package build command for the *sid* distribution chroot
** *pdebuild*
** *git-pbuilder*
** *gbp buildpackage*
* The command to update the *sid* chroot
** *pbuilder --update*
** *git-pbuilder --update*
* The command to login to the *sid* chroot to modify it
** *git-pbuilder --login --save-after-login*

An arbitrary 'dist' distribution environment can be used as follows.

* The chroot filesystem creation command for the 'dist' distribution
** *pbuilder create --distribution* 'dist'
** *DIST=*'dist' *git-pbuilder create*
* The master chroot filesystem path for the 'dist' distribution chroot
** path: */var/cache/pbuilder/base-*'dist'*.cow*
* The package build command for the 'dist' distribution chroot
** *pdebuild \-- --basepath=/var/cache/pbuilder/base-*'dist'*.cow*
** *DIST=*'dist' *git-pbuilder*
** *gbp buildpackage --git-dist=*'dist'
* The command to update the 'dist' chroot
** *pbuilder update --basepath=/var/cache/pbuilder/base-*'dist'*.cow*
** *DIST=*'dist' *git-pbuilder --update*
* The command to login to the *sid* chroot to modify it
** *pbuilder --login --basepath=/var/cache/pbuilder/base-*'dist'*.cow --save-after-login*
** *DIST=*'dist' *git-pbuilder --login --save-after-login*

TIP: A custom environment with some pre-loaded packages needed for the new experimental packages, this *git-pbuilder --login --save-after-login* command is quite handy.

TIP: If your old chroot is missing packages such as *eatmydata*, *ccache*, and *lintian*, you may want to install these with the *git-pbuilder --login --save-after-login* command.

TIP: The chroot filesystem can be cloned simply by copying with "*cp -a base-*'dist'*.cow base-*'customdist'*.cow*".  The new chroot can be accessed as "*gbp buildpackage --git-dist=*'customdist'" and "*DIST=*'customdist' *git-pbuilder ...*".

