// vim:set filetype=asciidoc:
[[tools]]
== Tool usages

Here are some notable tools around Debian packaging.

NOTE: The descriptions in this section are intentionally brief. Prospective maintainers are strongly encouraged to search for and read all relevant documentation associated with these commands.

NOTE: Examples here use the *gz*-compression.  The *xz*-compression may be used instead.

[[debdiff]]
=== *debdiff*

You can compare file contents in two source Debian packages with the *debdiff* command.

----
[base_dir] $ debdiff old-package.dsc new-package.dsc
----

You can also compare file lists in two sets of binary Debian packages with the *debdiff* command.

----
[base_dir] $ debdiff old-package.changes new-package.changes
----

These are useful to identify what has been changed in the source packages and to check for inadvertent changes made when updating binary packages, such as unintentionally misplacing or removing files.

Debian now enforces the source-only upload when developing packages.  So there may be 2 different ***.changes** files:

* __package_version-revision___**source.changes** for the normal source-only upload
* __package_version-revision_arch__**.changes** for the source+binary upload

[[dget]]
=== *dget*

You can download the set of files for the Debian source package with the *dget* command.

----
[base_dir] $ dget https://www.example.org/path/to/package_version-rev.dsc
----

[[mk-origtargz]]
=== *mk-origtargz*

You can make the upstream tarball **../foo-**__newversion__**.tar.[xg]z** accessible from the Debian source tree as **../foo_**__newversion__**.orig.tar.[xg]z**. This command is useful for renaming and symlinking the upstream tarball to the expected Debian naming convention.

[[origtargz]]
=== *origtargz*

You can fetch the pre-existing orig tarball of a Debian package from various sources, and unpack it with *origtargz* command.

This is basically for *-2*, *-3*, ... revisions.

NOTE: When the upstream tarball is missing, *debmake* automatically produces a required tarball.  This is a convenient feature and good enough for making a private Debian package.  But when making a Debian package for the official Debian repository, you must use exactly the same upstream tarball as the *-1* revision.  For such case, *origtargz* should be used.

[[git-deborig]]
=== *git deborig*

If the upstream project is hosted in a Git repository without an official tarball release, you can generate its orig tarball from the *git* repository for use by the Debian source package. Execute "`git deborig`" from the root of the checked-out source tree.

This is basically for *-1* revisions.

[[dpkg-source-b]]
=== *dpkg-source -b*

The "`*dpkg-source -b*`" command packs the upstream source tree into the Debian source package.

It expects a series of patches in the *debian/patches/* directory and their application sequence in *debian/patches/series*.

It is compatible with *dquilt* (see "`<<quilt-setup>>`") operations and understands the patch application status from the existence of *.pc/applied-patches*.

The *dpkg-buildpackage* command invokes "`**dpkg-source -b**`".

[[dpkg-source-x]]
=== *dpkg-source -x*

The "`**dpkg-source -x**`" command extracts the source tree and applies the patches in the *debian/patches/* directory using the sequence specified in *debian/patches/series* to the upstream source tree. It also adds *.pc/applied-patches*. (See "`<<git-patch-applied>>`".)

The "`*dpkg-source -x --skip-patches*`" command extracts source tree only. It doesn't add *.pc/applied-patches*. (See "`<<git-patch-unapplied>>`".)

Both extracted source trees are ready for building Debian binary packages with *dpkg-buildpackage*, *dbuild*, *sbuild*, etc..

[[debc]]
=== *debc*

You should install generated packages with the *debc* command to test it locally.

----
[base_dir] $ debc package_version-rev_arch.changes
----

[[bts]]
=== *bts*

After uploading the package, you will receive bug reports. It is an important duty of a package maintainer to manage these bugs properly, as described in "`https://www.debian.org/doc/manuals/developers-reference/pkgs.html#bug-handling[5.8. Handling bugs]`" of the "`Debian Developer's Reference`".

The *bts* command is a handy tool to manage bugs on the "`https://www.debian.org/Bugs/[Debian Bug Tracking System]`".

----
[~] $ bts severity 123123 wishlist , tags -1 pending
----

[[dpkg-depcheck]]
=== *dpkg-depcheck*

You can use **dpkg-depcheck**(1) to obtain a good first approximation to the *Build-Depends* line needed by a Debian package.

----
[foo-1.0] $ dpkg-depcheck -b debian/rules build
----
