Chapter 3. Tool Setups

Table of Contents

3.1. Email address
3.2. mc
3.3. git
3.4. quilt
3.5. devscripts
3.6. sbuild
3.7. git-buildpackage
3.8. HTTP proxy
3.9. Private Debian repository
3.10. Virtual machines
3.11. Local network with virtual machines

The build-essential package must be installed in the build environment.

The devscripts package should be installed in the maintainer environment.

Although this is not necessarily an absolute requirement, it is a good idea to install and set up all of the popular set of packages mentioned in this chapter in the maintainer environment. This enables us to share the common baseline working environment. . Please install the tools mentioned in the Overview of Debian Maintainer Tools in the “Debian Developer’s Reference”, as needed, too.

	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. Debian development is a moving target. Please make sure to read the pertinent documentation and update the configuration as needed.

3.1. Email address

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

Let’s setup these packages by adding the following lines to ~/.bashrc ^[7].

Add to the ~/.bashrc file.

DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME

3.2. mc

The mc command 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. It uses the dpkg-deb command as its back-end. Let’s set it up to support easy chdir as follows.

Add to the ~/.bashrc file.

# mc related
if [ -f /usr/lib/mc/mc.sh ]; then
  . /usr/lib/mc/mc.sh
fi

3.3. git

Nowadays, the git command is the essential tool to manage the source tree with history.

The global user configuration for the git command such as your name and email address can be set in ~/.gitconfig as follows.

$ 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 as follows.

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

You can check your global configuration as follows.

$ git config --global --list

	Tip
	It is essential to use some GUI git tools like gitk or gitg to work effectively with the history of the git repository.

3.4. quilt

The quilt command offers a basic method for recording modifications. For the Debian packaging, it should be customized to record modifications in the debian/patches/ directory instead of its default patches/ directory.

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"
. /usr/share/bash-completion/completions/quilt
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:"
    QUILT_COLORS="${QUILT_COLORS}diff_ctx=35:diff_cctx=33"
    if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
fi

See quilt(1) and How To Survive With Many Patches or Introduction to Quilt on how to use the quilt command.

See Section 4.9, “Step 3 (alternative): Modification to the upstream source” for example usages.

3.5. devscripts

The debsign command, included in the devscripts package, is used to sign the Debian package with your private GPG key.

The debuild command, included in the devscripts package, builds the binary package and checks it with the lintian command. It is useful to have verbose outputs from the lintian command.

You can set these up in ~/.devscripts as follows.

DEBUILD_DPKG_BUILDPACKAGE_OPTS="-i -I -us -uc"
DEBUILD_LINTIAN_OPTS="-i -I --show-overrides"
DEBSIGN_KEYID="Your_GPG_keyID"

The -i and -I options in DEBUILD_DPKG_BUILDPACKAGE_OPTS for the dpkg-source command help rebuilding of Debian packages without extraneous contents (see Section 5.17, “Building package without extraneous contents”).

Currently, an RSA key with 4096 bits is a good idea. See Creating a new GPG key.

3.6. sbuild

The sbuild package provides a clean room (chroot) build environment. It offers this efficiently with the help of schroot using the bind-mount feature of the modern Linux kernel.

Since it is the same build environment as the Debian’s buildd infrastructure, it is always up to date and comes with full of useful features.

It can be customized to offer following features:

The schroot package to boost the chroot creation speed.
The lintian package to find bugs in the package.
The piuparts package to find bugs in the package.
The autopkgtest package to find bugs in the package.
The ccache package to boost the gcc speed. (optional)
The libeatmydata1 package to boost the dpkg speed. (optional)
The parallel make to boost the build speed. (optional)

Let’s get started by following https://wiki.debian.org/sbuild .

$ sudo apt install sbuild piuparts autopkgtest lintian
$ sudo usermod -a -G <your_user_name> sbuild

Reboot your system or execute command such as “kill -TERM -1” ^[8]. Then login and check you are a member of sbuild group using id command.

$ id
uid=1000(<yourname>) gid=1000(<yourname>) groups=...,132(sbuild)

Let’s create the configuration file ~/.sbuildrc in line with recent Debian practice https://wiki.debian.org/SourceOnlyUpload as:

cat >~/.sbuildrc << 'EOF'
##############################################################################
# PACKAGE BUILD RELATED (source-only-upload as default)
##############################################################################
# -d
$distribution = 'unstable';
# -A
$build_arch_all = 1;
# -s
$build_source = 1;
# --source-only-changes
$source_only_changes = 1;
# -v
$verbose = 1;

##############################################################################
# POST-BUILD RELATED (turn off functionality by setting variables to 0)
##############################################################################
$run_lintian = 1;
$lintian_opts = ['-i', '-I'];
$run_piuparts = 1;
$piuparts_opts = ['--schroot', 'unstable-amd64-sbuild'];
$run_autopkgtest = 1;
$autopkgtest_root_args = '';
$autopkgtest_opts = [ '--', 'schroot', '%r-%a-sbuild' ];

##############################################################################
# PERL MAGIC
##############################################################################
1;
EOF

Following document assumes that sbuild is configured this way.

Edit this to your needs. Post-build tests can be turned on and off by assigning 1 or 0 to the corresponding variables,

	Warning
	The optional customization may cause negative effects. In case of doubts, disable them.

	Note
	The parallel make may fail for some existing packages and may make the build log difficult to read.

3.7. git-buildpackage

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

# Configuration file for "gbp <command>"

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

	Tip
	The gbp command is the alias of the git-buildpackage command.

3.8. HTTP proxy

You should set up a local HTTP caching proxy to save the bandwidth for the Debian package repository access. There are several choices:

Specialized HTTP caching proxy using the apt-cacher-ng package.
Generic HTTP caching proxy (squid package) configured by squid-deb-proxy package

In order to use this HTTP proxy without manual configuration adjustment, it’s a good idea to install either auto-apt-proxy or squid-deb-proxy-client package to everywhere.

^[7]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.

^[8]Logout from your system via GUI menu may not work.


Chapter 2. Prerequisites		Chapter 4. Simple Example