// vim:set filetype=asciidoc:
[[setup]]
== Tool Setups

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

The *devscripts* package should be installed in the development environment of the maintainer.

It is a good idea to install and set up all of the popular set of packages mentioned in this chapter.  These enable us to share the common baseline working environment, although these are not necessarily absolute requirements.

Please also consider to install the tools mentioned in the "`https://www.debian.org/doc/manuals/developers-reference/tools.html[Overview of Debian Maintainer Tools]`" in the "`Debian Developer's Reference`", as needed.

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.

[[email-setup]]
=== Email setup

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

Let's set these environment variables 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="osamu@debian.org"
DEBFULLNAME="Osamu Aoki"
export DEBEMAIL DEBFULLNAME
----

NOTE: The above is for the author of this manual.  The configuration and operation examples presented in this manual use these email address and name settings.  You must use your email address and name for your system.

[[mc-setup]]
=== *mc* setup

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
----

[[git-setup]]
=== *git* setup

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 "Osamu Aoki"
[~] $ git config --global user.email osamu@debian.org
----

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.

[[quilt-setup]]
=== *quilt* setup

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 "`file:///usr/share/doc/quilt/quilt.html[How To Survive With Many Patches or Introduction to Quilt] (**quilt.html**)`" on how to use the *quilt* command.

See "`<<alt-patch>>`" for example usages.

Note that "`https://manpages.debian.org/unstable/git-buildpackage/gbp-pq.1.en.html[gbp pq]`" is able to consume existing *debian/patches*, automate updating and modifying the patches, and export them back into *debian/patches*, all without using quilt nor the need to learn or configure quilt.

[[open-pgp-key]]
=== *openPGP* setup

The **gpg**(1) command, included in the *gnupg* package, can be used to generate a new https://www.rfc-editor.org/rfc/rfc9580.html[openPGP] key for the Debian package activity as follows.

----
[~] $ gpg --generate-key
gpg (GnuPG) 2.4.7; Copyright (C) 2024 g10 Code GmbH
... [snip] ...
public and secret key created and signed.

pub   ed25519 2026-02-10 [SC] [expires: 2029-02-09]
      ABCDEF0123456789ABCDEF0123456789ABCDEF01
uid                      Osamu Aoki  <osamu@debian.org>
sub   cv25519 2026-02-10 [E] [expires: 2029-02-09]
----

This is an openPGP key based on the https://en.wikipedia.org/wiki/Elliptic-curve_cryptography[Elliptic-curve cryptography (ECC)].

NOTE: If you already have an openPGP key based on the https://en.wikipedia.org/wiki/RSA_cryptosystem[RSA cryptosystem] signed by many others, you can use it.

You can edit and update this openPGP key with:

----
[~] $ gpg --edit-key ABCDEF0123456789ABCDEF0123456789ABCDEF01
... [snip] ...
gpg> save
----

For example, the resulting openPGP key may look like:

----
[~] $ gpg --list-keys ABCDEF0123456789ABCDEF0123456789ABCDEF01
pub   ed25519 2026-02-10 [SC]
      ABCDEF0123456789ABCDEF0123456789ABCDEF01
uid           [ultimate] Osamu Aoki <osamu@debian.org>
sub   cv25519 2026-02-10 [E] [expires: 2030-02-10]
----

// Requirements of the openPGP key for the https://nm.debian.org/[Debian New Members] process are:

// * The key should be type RSA and version 4 or greater, or an Elliptic Curve based key
// * The key should have the sign, certify and encrypt capabilities (subkeys are encouraged)
// * For an RSA key, the primary cryptographic material should be at least 4096 bits

// * «certificate»  == «Transferable Public Key» == «public key»
// * «key» == «Transferable Secret Key» == «secret key»
// https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-algorithms
// https://deb.debian.org/debian/pool/main/d/debian-keyring/ (get the latest from here)
// for f in *; do gpg --list-packets $f |grep "^:.*algo" ; done |sort|uniq -c

// Trend of OpenPGP keys used by Debian developers (2025.09.18):
// * pub rsa4096 / sub rsa4096 pair openPGP keys: about 1296 cases (algo 1, RSA) -- traditional
// * pub ed25519 / sub cv25519 pair openPGP keys: about 43 cases (algo 22, EdDSALegacy) -- new

NOTE: The term "`GPG key`" found in many Debian documents can be considered as a synonym of "`openPGP key`".

// Debian provides OpenPGP encryption and signing tools:
// * The **gpg**(1) command provided by the *gnupg* package (traditional)
// * The **sq**(1) command provided by the *sq* package (newer)

For more on OpenPGP key, see:

* "`https://keyring.debian.org/creating-key.html[Creating a new GPG key]`"
* "`https://wiki.debian.org/Keysigning[Debian wiki: Keysigning]`"
* "`https://wiki.debian.org/Subkeys[Debian wiki: Using OpenPGP subkeys in Debian development]`"
* "`https://wiki.debian.org/FixKeyWithSha1[Debian wiki: FixKeyWithSha1]`" -- updating old OpenPGP keys

[[devscripts-setup]]
=== *devscripts* setup

The *debsign* command, included in the *devscripts* package, is used to sign the Debian package with your private openPGP 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_openPGP_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 "`<<sanitize>>`").

[[sbuild-setup]]
=== *sbuild* setup

The *sbuild* package provides a clean room
("`https://en.wikipedia.org/wiki/Chroot[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
https://buildd.debian.org/[buildd] infrastructure, it is always up to date and
comes 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 set up *sbuild* environment footnote:[Be careful since some older HOWTOs may use different chroot setups.]:

----
[~] $ sudo apt install sbuild piuparts autopkgtest lintian
[~] $ sudo apt install sbuild-debian-developer-setup
[~] $ sudo sbuild-debian-developer-setup -s unstable
----

Let's update your group membership by rebooting the entire system
footnote:[Under some modern GUI Desktop environment, "`logout and login using
GUI`" may not update your system environment such as group membership.]:

----
[~] $ sudo shutdown -r now
----

Let's verify that your group membership includes *sbuild*:

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


Let's create the configuration file *~/.local/sbuild/config.pl* in line with recent Debian
practice of "`https://wiki.debian.org/SourceOnlyUpload[source-only-upload]`" as:

----
[~] $ cat >~/.local/sbuild/config.pl << '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
----

NOTE: There are some exceptional cases such as NEW uploads, uploads with NEW
binary packages, and security uploads where you can't do
https://wiki.debian.org/SourceOnlyUpload[source-only-upload] but are required
to upload with binary packages.  The above configuration needs to be adjusted
for those exceptional cases.

TIP: You may need to add "`**$chroot_mode = "schroot";**`" to *~/.local/sbuild/config.pl* for *piuparts* if it doesn't work well under *unshare*.  See Debian bug: https://bugs.debian.org/1125784[#1125784] and https://bugs.debian.org/1126127[#1126127].

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.

TIP: Many *sbuild* related hints are available at "`<<sbuild>>`" and "`https://wiki.debian.org/sbuild[https://wiki.debian.org/sbuild]`" .

[[chroot-persistent]]
=== Persistent chroot setup

NOTE: Use of independent copied chroot filesystem prevents contaminating the source chroot used by *sbuild*.

For building new experimental packages or for debugging buggy packages, let's setup dedicated persistent chroot "`**source:unstable-amd64-desktop**`" by:

----
[~] $ sudo cp -a /srv/chroot/unstable-amd64-sbuild /srv/chroot/unstable-amd64-desktop
[~] $ sudo tee /etc/schroot/chroot.d/unstable-amd64-desktop-XXXXXX << EOF
[unstable-amd64-desktop]
description=Debian sid/amd64 persistent chroot
groups=root,sbuild
root-groups=root,sbuild
profile=desktop
type=directory
directory=/srv/chroot/unstable-amd64-desktop
union-type=overlay
EOF
----

Here, *desktop* profile is used instead of *sbuild* profile.  Please make sure to adjust */etc/schroot/desktop/fstab* to make package source accessible from inside of the chroot.

You can log into this chroot "`**source:unstable-amd64-desktop**`" by:

----
[~] $ sudo schroot -c source:unstable-amd64-desktop
----

[[gbp-setup]]
=== *gbp* setup

The *git-buildpackage* package offers the **gbp**(1) command.  Its user configuration file is *~/.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
----

[[proxy]]
=== 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.

[[repropro]]
=== Private Debian repository

You can set up a private Debian package repository with the *reprepro* package.

[[vm]]
=== Virtual machines

For testing GUI application, it is a good idea to have virtual machines. Install *virt-manager* and *qemu-kvm* packages.

Use of chroot and virtual machines allows us not to update the whole host PC to the latest *unstable* suite.

[[mDNS]]
=== Local network with virtual machines

In order to access virtual machines easily over the local network, setting up multicast DNS service discovery infrastructure by installing *avahi-utils* is a good idea.

For all running virtual machines and the host PC, we can use each host name appended with *.local* for SSH to access each other.
