1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
A broad overview is presented here for the basic rules of Debian packaging focusing on the non-native Debian package in the ``*3.0 (quilt)*'' format.
NOTE: Some details are intentionally skipped for clarity. Please read the manpages of the *dpkg-source*(1), *dpkg-buildpackage*(1), *dpkg*(1), *dpkg-deb*(1), *deb*(5), etc.
The Debian source package is a set of input files used to build the Debian binary package and is not a single file.
The Debian binary package is a special archive file which holds a set of installable binary data with its associated information.
A single Debian source package may generate multiple Debian binary packages defined in the *debian/control* file.
The non-native Debian package in the ``*3.0 (quilt)*'' format is the most normal Debian source package format.
NOTE: There are many wrapper scripts. Use them to streamline your workflow but make sure to understand the basics of their internals.
[[workflow]]
=== Packaging workflow
The Debian packaging workflow to create a Debian binary package involves generating several specifically named files (see <<name-version>>) as defined in the ``Debian Policy Manual''.
The oversimplified method for the Debian packaging workflow can be summarized in 5 steps as follows.
1. The upstream tarball is downloaded as the 'package-version'**.tar.gz** file.
2. The upstream tarball is untarred to create many files under the 'package-version'**/** directory.
3. The upstream tarball is copied (or symlinked) to the particular filename 'packagename_version'**.orig.tar.gz**.
* the character separating 'package' and 'version' is changed from *-* (hyphen) to *_* (underscore)
* *.orig* is added in the file extension.
4. The Debian package specification files are added to the upstream source under the 'package-version'**/debian/** directory.
* Required specification files under the *debian/* directory:
*debian/rules*::
The executable script for building the Debian package (see <<rules>>)
*debian/control*::
The package configuration file containing the source package name, the source build dependencies, the binary package name, the binary dependencies, etc. (see <<control>>)
*debian/changelog*::
The Debian package history file defining the upstream package version and the Debian revision in its first line (see <<changelog>>)
*debian/copyright*::
The copyright and license summary (see <<copyright>>)
* Optional specification files under the *debian/** (see <<debianconf>>):
* The *debmake* command invoked in the 'package-version/' directory provides the initial set of these template configuration files.
** Required specification files are generated even with the *-x0* option.
** The *debmake* command does not overwrite any existing configuration files.
* These files must be manually edited to their perfection according to the ``Debian Policy Manual'' and ``Debian Developer's Reference''.
5. The *dpkg-buildpackage* command (usually from its wrapper *debuild* or *pdebuild*) is invoked in the 'package-version/' directory to make the Debian source and binary packages by invoking the *debian/rules* script.
* The current directory is set as: *$(CURDIR)=*'/path/to/package-version/'
* Create the Debian source package in the ``*3.0 (quilt)*'' format using *dpkg-source*(1)
** 'package_version'.*orig.tar.gz* (copy or symlink of 'package-version'.*tar.gz*)
** 'package_version-revision'.*debian.tar.xz* (tarball of 'package-version'/*debian/**)
** 'package_version-revision'.*dsc*
* Build the source using ``*debian/rules build*'' into *$(DESTDIR)*
** *DESTDIR=debian*/'binarypackage/' (single binary package)
** *DESTDIR=debian/tmp/* (multi binary package)
* Create the Debian binary package using *dpkg-deb*(1), *dpkg-genbuildinfo*(1), and *dpkg-genchanges*(1).
** 'binarypackage_version-revision_arch'.*deb*
** ... (There may be multiple Debian binary package files.)
** 'package_version-revision_arch'.*changes*
6. Check the quality of the Debian package with the *lintian* command. (recommended)
* Follow the rejection guidelines from https://ftp-master.debian.org/[ftp-master].
** https://ftp-master.debian.org/REJECT-FAQ.html[REJECT-FAQ]
** https://ftp-master.debian.org/NEW-checklist.html[NEW checklist]
** https://ftp-master.debian.org/#lintianrejects[Lintian Autorejects] (https://ftp-master.debian.org/static/lintian.tags[lintian tag list])
7. Sign the 'package_version-revision'.*dsc* and 'package_version-revision_arch'.*changes* files with the *debsign* command using your private GPG key.
8. Upload the set of the Debian source and binary package files with the *dput* command to the Debian archive.
Here, please replace each part of the filename as:
* the 'package' part with the Debian source package name
* the 'binarypackage' part with the Debian binary package name
* the 'version' part with the upstream version
* the 'revision' part with the Debian revision
* the 'arch' part with the package architecture
TIP: Many patch management and VCS usage strategies for the Debian packaging are practiced. You don't need to use all of them.
TIP: There is very extensive documentation in https://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html[Chapter 6. Best Packaging Practices] in the ``Debian Developer's Reference''. Please read it.
[[debhelper]]
==== The *debhelper* package
Although a Debian package can be made by writing a *debian/rules* script without using the *debhelper* package, it is impractical to do so. There are too many modern ``Policy'' required features to be addressed, such as application of the proper file permissions, use of the proper architecture dependent library installation path, insertion of the installation hook scripts, generation of the debug symbol package, generation of package dependency information, generation of the package information files, application of the proper timestamp for reproducible build, etc.
*Debhelper* package provides a set of useful scripts in order to simplify Debian's packaging workflow and reduce the burden of package maintainers. When properly used, they will help packagers handle and implement ``Policy'' required features automatically.
The modern Debian packaging workflow can be organized into a simple modular workflow by:
* using the *dh* command to invoke many utility scripts automatically from the *debhelper* package, and
* configuring their behavior with declarative configuration files in the *debian/* directory.
You should almost always use *debhelper* as your package's build dependency. This document also assumes that you are using a fairly contemporary version of *debhelper* to handle packaging works in the following contents.
|
