Chapter 5. Simple packaging

Table of Contents

5.1. Packaging tarball
5.2. Gesamtbild
5.3. Was ist Debmake?
5.4. Was ist Debuild?
5.5. Schritt 1: Holen der Quellen der Originalautoren
5.6. Step 2: Generate template files with debmake
5.7. Schritt 3: Anpassung der Vorlagendateien
5.8. Step 4: Building package with debuild
5.9. Step 3 (alternatives): Modification to the upstream source
5.10. Patch by diff -u approach
5.11. Patch by dquilt approach
5.12. Patch by dpkg-source --auto-commit approach

There is an old Latin saying: Longum iter est per praecepta, breve et efficax per exempla (It’s a long way by the rules, but short and efficient with examples).

Hier ist ein Beispiel zur Erstellung eines einfachen Debian-Pakets aus einer einfachen C-Quelle mittels einer Makefile als Bausystem.

Nehmen wir an, der Tarball der Originalautoren heißt debhello-0.0.tar.gz.

Diese Art der Quellen soll als Nichtsystemdatei wie folgt instaliert werden:

Basics for the install from the upstream tarball. 

 $ tar -xzmf debhello-0.0.tar.gz
 $ cd debhello-0.0
 $ make
 $ make install

Debian packaging requires changing this make install process to install files to the target system image location instead of the normal location under /usr/local.

[Note]Note

Beispiele zur Erstellung von Debian-Paketen aus anderen, komplizierteren Bausystemen werden in Chapter 13, Weitere Beispiele beschrieben.

The big picture for building a single non-native Debian package from the upstream tarball debhello-0.0.tar.gz can be summarized as:

  • The maintainer obtains the upstream tarball debhello-0.0.tar.gz and untars its contents to the debhello-0.0 directory.
  • The debmake command debianizes the upstream source tree by adding template files only in the debian directory.

    • The debhello_0.0.orig.tar.gz symlink is created pointing to the debhello-0.0.tar.gz file.
    • The maintainer customizes template files.
  • The debuild command builds the binary package from the debianized source tree.

    • debhello-0.0-1.debian.tar.xz is created containing the debian directory.

Big picture of package building. 

 $ tar -xzmf debhello-0.0.tar.gz
 $ cd debhello-0.0
 $ debmake
   ... manual customization
 $ debuild
   ...

[Tip]Tip

The debuild command in this and following examples may be substituted by equivalent commands such as the sbuild command.

[Tip]Tip

If the upstream tarball in the .tar.xz format is available, use it instead of the one in the .tar.gz and .tar.bz2 formats. The xz compression format offers the better compression than the gzip and bzip2 compressions.

[Note]Note

Actual packaging activities are often performed manually without using debmake while referencing only existing similar packages and Debian Policy Manual.

The debmake command is the helper script for the Debian packaging. (Chapter 14, debmake(1)-Handbuchseite”)

  • It creates good template files for the Debian packages.
  • It always sets most of the obvious option states and values to reasonable defaults.
  • Es erstellt den Tarball der Originalautoren und die benötigten Symlinks, falls sie fehlen.
  • Es setzt die bestehenden Konfigurationsdateien im Verzeichnis debian/ nicht außer Kraft.
  • Es unterstützt die Multiarch-Pakete.
  • It provides short extracted license texts as debian/copyright in decent accuracy to help license review.

Diese Funktionalitäten ermöglichen ein einfaches und moderens Paketieren für Debian mit debmake.

In retrospective, I created debmake to simplify this documentation. I consider debmake to be more-or-less a demonstration session generator for tutorial purpose.

The debmake command isn’t the only helper script to make a Debian package. If you are interested alternative packaging helper tools, please see:

Hier ist eine Zusammenfassung von Befehlen, die dem Befehl debuild ähnlich sind.

[Note]Note

Siehe dpkg-buildpackage(1) für die Details.

Let’s get the upstream source.

Download debhello-0.0.tar.gz

 $ wget http://www.example.org/download/debhello-0.0.tar.gz
 ...
 $ tar -xzmf debhello-0.0.tar.gz
 $ tree
.
├── debhello-0.0
│   ├── Makefile
│   ├── README.md
│   └── src
│       └── hello.c
└── debhello-0.0.tar.gz

3 directories, 4 files

Here, the C source hello.c is a very simple one.

hello.c

 $ cat debhello-0.0/src/hello.c
#include <stdio.h>
int
main()
{
        printf("Hello, world!\n");
        return 0;
}

Here, the Makefile supports GNU Coding Standards” and FHS. Notably:

  • build binaries honoring $(CPPFLAGS), $(CFLAGS), $(LDFLAGS), etc.
  • install files with $(DESTDIR) defined to the target system image
  • install files with $(prefix) defined, which can be overridden to be /usr

Makefile

 $ cat debhello-0.0/Makefile
prefix = /usr/local

all: src/hello

src/hello: src/hello.c
        @echo "CFLAGS=$(CFLAGS)" | \
                fold -s -w 70 | \
                sed -e 's/^/# /'
        $(CC) $(CPPFLAGS) $(CFLAGS) $(LDCFLAGS) -o $@ $^

install: src/hello
        install -D src/hello \
                $(DESTDIR)$(prefix)/bin/hello

clean:
        -rm -f src/hello

distclean: clean

uninstall:
        -rm -f $(DESTDIR)$(prefix)/bin/hello

.PHONY: all install clean distclean uninstall

[Note]Note

The echo of the $(CFLAGS) variable is used to verify the proper setting of the build flag in the following example.

Die Ausagabe des Befehls debmake ist sehr ausführlich und erklärt seine Tätigkeiten wie folgt:

The output from the debmake command. 

 $ cd /path/to/debhello-0.0
 $ debmake -x1
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="0.0", rev="1"
I: *** start packaging in "debhello-0.0". ***
I: provide debhello_0.0.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-0.0.tar.gz debhello_0.0.orig.tar.gz
I: pwd = "/path/to/debhello-0.0"
I: parse binary package settings:
I: binary package=debhello Type=bin / Arch=any M-A=foreign
I: analyze the source tree
I: build_type = make
I: scan source for copyright+license text and file extensions
I:  50 %, ext = md
I:  50 %, ext = c
I: check_all_licenses
I: ...
I: check_all_licenses completed for 3 files.
I: bunch_all_licenses
I: format_all_licenses
I: make debian/* template files
I: debmake -x "1" ...
I: creating => debian/control
I: creating => debian/copyright
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra0_changel...
I: creating => debian/changelog
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra0_rules.t...
I: creating => debian/rules
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra0source_f...
I: creating => debian/source/format
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1_README....
I: creating => debian/README.Debian
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1_README....
I: creating => debian/README.source
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1_clean.t...
I: creating => debian/clean
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1_gbp.con...
I: creating => debian/gbp.conf
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1_salsa-c...
I: creating => debian/salsa-ci.yml
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1_watch.t...
I: creating => debian/watch
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1tests_co...
I: creating => debian/tests/control
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1upstream...
I: creating => debian/upstream/metadata
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1patches_...
I: creating => debian/patches/series
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1source.n...
I: creating => debian/source/local-options.ex
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1source.n...
I: creating => debian/source/local-patch-header.ex
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1single_d...
I: creating => debian/dirs
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1single_i...
I: creating => debian/install
I: substituting => /usr/lib/python3/dist-packages/debmake/data/extra1single_l...
I: creating => debian/links
I: $ wrap-and-sort
I: $ wrap-and-sort complete.  Now, debian/* may have a blank line at the top....

The debmake command generates all these template files based on command line options. Since no options are specified, the debmake command chooses reasonable default values for you:

  • Der Quellpaketname: debhello
  • Die Version der Originalautoren: 0.0
  • Deb Binärpaketname: debhello
  • Die Debian-Revision: 1
  • The package type: bin (the ELF binary executable package)
  • The -x option: -x1 (without maintainer script supports for simplicity)
[Note]Note

Here, the debmake command is invoked with the -x1 option to keep this tutorial simple. Use of default -x3 option is highly recommended.

Lassen Sie uns die erstellten Vorlagendateien anschauen.

Der Quellbaum, nach der grundlegenden Ausführung von debmake

 $ cd /path/to
 $ tree
.
├── debhello-0.0
│   ├── Makefile
│   ├── README.md
│   ├── debian
│   │   ├── README.Debian
│   │   ├── README.source
│   │   ├── changelog
│   │   ├── clean
│   │   ├── control
│   │   ├── copyright
│   │   ├── dirs
│   │   ├── gbp.conf
│   │   ├── install
│   │   ├── links
│   │   ├── patches
│   │   │   └── series
│   │   ├── rules
│   │   ├── salsa-ci.yml
│   │   ├── source
│   │   │   ├── format
│   │   │   ├── local-options.ex
│   │   │   └── local-patch-header.ex
│   │   ├── tests
│   │   │   └── control
│   │   ├── upstream
│   │   │   └── metadata
│   │   └── watch
│   └── src
│       └── hello.c
├── debhello-0.0.tar.gz
└── debhello_0.0.orig.tar.gz -> debhello-0.0.tar.gz

8 directories, 24 files

The debian/rules file is the build script provided by the package maintainer. Here is its template file generated by the debmake command.

debian/rules (Vorlagendatei): 

 $ cd /path/to/debhello-0.0
 $ cat debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,-O1

%:
        dh $@

#override_dh_auto_install:
#       dh_auto_install -- prefix=/usr

#override_dh_install:
#       dh_install --list-missing -X.pyc -X.pyo

This is essentially the standard debian/rules file with the dh command. (There are some commented out contents for you to customize it.)

The debian/control file provides the main meta data for the Debian package. Here is its template file generated by the debmake command.

debian/control (Vorlagendatei): 

 $ cat debian/control
Source: debhello
Section: unknown
Priority: optional
Maintainer: "Osamu Aoki" <osamu@debian.org>
Build-Depends: debhelper-compat (= 13)
Standards-Version: 4.6.2
Homepage: <insert the upstream URL, if relevant>
Rules-Requires-Root: no
#Vcs-Git: https://salsa.debian.org/debian/debhello.git
#Vcs-Browser: https://salsa.debian.org/debian/debhello

Package: debhello
Architecture: any
Multi-Arch: foreign
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: auto-generated package by debmake
 This Debian binary package was auto-generated by the
 debmake(1) command provided by the debmake package.

[Warning]Warning

If you leave Section: unknown in the template debian/control file unchanged, the lintian error may cause the build to fail.

Since this is the ELF binary executable package, the debmake command sets Architecture: any and Multi-Arch: foreign. Also, it sets required substvar parameters as Depends: ${shlibs:Depends}, ${misc:Depends}. These are explained in Chapter 6, Basics for packaging”.

[Note]Note

Please note this debian/control file uses the RFC-822 style as documented in 5.2 Source package control files — debian/control of the Debian Policy Manual. The use of the empty line and the leading space are significant.

The debian/copyright file provides the copyright summary data of the Debian package. Here is its template file generated by the debmake command.

debian/copyright (Vorlagendatei): 

 $ cat debian/copyright
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: debhello
Upstream-Contact: <preferred name and address to reach the upstream project>
Source: <url://example.com>
#
# Please double check copyright with the licensecheck(1) command.

Files:     Makefile
           README.md
           src/hello.c
Copyright: __NO_COPYRIGHT_NOR_LICENSE__
License:   __NO_COPYRIGHT_NOR_LICENSE__

#----------------------------------------------------------------------------...
# Files marked as NO_LICENSE_TEXT_FOUND may be covered by the following
# license/copyright files.

Um ein geeignetes Debian-Paket zu erstellen, sind manuelle Anpassungen durch den Betreuer notwendig.

In order to install files as a part of the system files, the $(prefix) value of /usr/local in the Makefile should be overridden to be /usr. This can be accommodated by the following the debian/rules file with the override_dh_auto_install target setting prefix=/usr.

debian/rules (Betreuerversion): 

 $ cd /path/to/debhello-0.0
 $ vim debian/rules
 ... hack, hack, hack, ...
 $ cat debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

override_dh_auto_install:
        dh_auto_install -- prefix=/usr

Exportieren der Umgebungsvariable DH_VERBOSE in der Datei debian/rules zwingt das Werkzeug debhelper dazu, einen feingranularen Baubericht zu erstellen.

Exporting DEB_BUILD_MAINT_OPTION as above sets the hardening options as described in the FEATURE AREAS/ENVIRONMENT in dpkg-buildflags(1). [9]

Durch Exportieren von DEB_CFLAGS_MAINT_APPEND wie oben wird der C-Compiler gezwungen, alle Warnungen auszugeben.

Durch Exportieren von DEB_LDFLAGS_MAINT_APPEND wie oben wird der Linker gezwungen, nur zu linken, wenn die Bibliothek tatsächlich benötigt wird. [10]

The dh_auto_install command for the Makefile based build system essentially runs $(MAKE) install DESTDIR=debian/debhello. The creation of this override_dh_auto_install target changes its behavior to $(MAKE) install DESTDIR=debian/debhello prefix=/usr.

Hier sind die Betreuerversionen der Dateien debian/control und debian/copyright.

debian/control (Betreuerversion): 

 $ vim debian/control
 ... hack, hack, hack, ...
 $ cat debian/control
Source: debhello
Section: devel
Priority: optional
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: debhelper-compat (= 13)
Standards-Version: 4.6.2
Homepage: https://salsa.debian.org/debian/debmake-doc
Rules-Requires-Root: no

Package: debhello
Architecture: any
Multi-Arch: foreign
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: Simple packaging example for debmake
 This Debian binary package is an example package.
 (This is an example only)

debian/copyright (Betreuerversion): 

 $ vim debian/copyright
 ... hack, hack, hack, ...
 $ cat debian/copyright
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: debhello
Upstream-Contact: Osamu Aoki <osamu@debian.org>
Source: https://salsa.debian.org/debian/debmake-doc

Files:     *
Copyright: 2015-2021 Osamu Aoki <osamu@debian.org>
License:   Expat
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),
 to deal in the Software without restriction, including without limitation
 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 and/or sell copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following conditions:
 .
 The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.
 .
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Let’s remove unused template files and edit remaining template files:

  • debian/README.source
  • debian/source/local-option.ex
  • debian/source/local-patch-header.ex
  • debian/patches/series (No upstream patch)
  • clean
  • dirs
  • install
  • links

Vorlagendateien unter debian/. (v=0.0): 

 $ rm -f debian/clean debian/dirs debian/install debian/links
 $ rm -f debian/README.source debian/source/*.ex
 $ rm -rf debian/patches
 $ tree -F debian
debian/
├── README.Debian
├── changelog
├── control
├── copyright
├── gbp.conf
├── rules*
├── salsa-ci.yml
├── source/
│   └── format
├── tests/
│   └── control
├── upstream/
│   └── metadata
└── watch

4 directories, 11 files

[Tip]Tip

Konfigurationsdateien, die vom Befehl dh_* aus dem Paket debhelper verwandt werden, behandeln normalerweise # als Beginn einer Kommentarzeile.

You can create a non-native Debian package using the debuild command or its equivalents (see Section 5.4, “Was ist Debuild?””) in this source tree. The command output is very verbose and explains what it does as follows.

Building package with debuild

 $ cd /path/to/debhello-0.0
 $ debuild
 dpkg-buildpackage -us -uc -ui -i
dpkg-buildpackage: info: source package debhello
dpkg-buildpackage: info: source version 0.0-1
dpkg-buildpackage: info: source distribution unstable
dpkg-buildpackage: info: source changed by Osamu Aoki <osamu@debian.org>
 dpkg-source -i --before-build .
dpkg-buildpackage: info: host architecture amd64
 debian/rules clean
dh clean
   dh_auto_clean
        make -j12 distclean
 ...
 debian/rules binary
dh binary
   dh_update_autotools_config
   dh_autoreconf
   dh_auto_configure
   dh_auto_build
        make -j12 "INSTALL=install --strip-program=true"
make[1]: Entering directory '/path/to/debhello-0.0'
# CFLAGS=-g -O2
 ...
Finished running lintian.

Sie können überprüfen, dass CFLAGS korrekt mit -Wall und -pedantic durch die Variable DEB_CFLAGS_MAINT_APPEND aktualisiert ist.

Wie vom Paket lintian berichtet sollte eine Handbuchseite zum Paket hinzugefügt werden, wie dies in späteren Beispielen gezeigt wird (siehe Chapter 13, Weitere Beispiele). Lassen Sie uns jetzt weitermachen.

Lassen Sie uns die Ergebnisse anschauen.

Die durch den Befehldebuild erstellten Dateien von debhello Version 0.0

 $ cd /path/to
 $ tree -FL 1
./
├── debhello-0.0/
├── debhello-0.0.tar.gz
├── debhello-dbgsym_0.0-1_amd64.deb
├── debhello_0.0-1.debian.tar.xz
├── debhello_0.0-1.dsc
├── debhello_0.0-1_amd64.build
├── debhello_0.0-1_amd64.buildinfo
├── debhello_0.0-1_amd64.changes
├── debhello_0.0-1_amd64.deb
└── debhello_0.0.orig.tar.gz -> debhello-0.0.tar.gz

2 directories, 9 files

You see all the generated files.

  • Das debhello_0.0.orig.tar.gz ist ein Symlink auf den Tarball der Originalautoren.
  • The debhello_0.0-1.debian.tar.xz contains the maintainer generated contents.
  • The debhello_0.0-1.dsc is the meta data file for the Debian source package.
  • The debhello_0.0-1_amd64.deb is the Debian binary package.
  • The debhello-dbgsym_0.0-1_amd64.deb is the Debian debug symbol binary package. See Section 9.21, “-dbgsym package”.
  • The debhello_0.0-1_amd64.build file is the build log file.
  • The debhello_0.0-1_amd64.buildinfo file is the meta data file generated by dpkg-genbuildinfo(1).
  • The debhello_0.0-1_amd64.changes is the meta data file for the Debian binary package.

The debhello_0.0-1.debian.tar.xz contains the Debian changes to the upstream source as follows.

The compressed archive contents of debhello_0.0-1.debian.tar.xz

 $ tar -tzf debhello-0.0.tar.gz
debhello-0.0/
debhello-0.0/src/
debhello-0.0/src/hello.c
debhello-0.0/Makefile
debhello-0.0/README.md
 $ tar --xz -tf debhello_0.0-1.debian.tar.xz
debian/
debian/README.Debian
debian/changelog
debian/control
debian/copyright
debian/gbp.conf
debian/rules
debian/salsa-ci.yml
debian/source/
debian/source/format
debian/tests/
debian/tests/control
debian/upstream/
debian/upstream/metadata
debian/watch

The debhello_0.0-1_amd64.deb contains the binary files to be installed to the target system.

The debhello-debsym_0.0-1_amd64.deb contains the debug symbol files to be installed to the target system.

The binary package contents of all binary packages: 

 $ dpkg -c debhello-dbgsym_0.0-1_amd64.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/lib/
drwxr-xr-x root/root ...  ./usr/lib/debug/
drwxr-xr-x root/root ...  ./usr/lib/debug/.build-id/
drwxr-xr-x root/root ...  ./usr/lib/debug/.build-id/be/
-rw-r--r-- root/root ...  ./usr/lib/debug/.build-id/be/f1e0185834f3c3e2614cf8...
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
lrwxrwxrwx root/root ...  ./usr/share/doc/debhello-dbgsym -> debhello
 $ dpkg -c debhello_0.0-1_amd64.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/bin/
-rwxr-xr-x root/root ...  ./usr/bin/hello
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/debhello/
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/changelog.Debian.gz
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/copyright

The generated dependency list of all binary packages.

The generated dependency list of all binary packages (v=0.0): 

 $ dpkg -f debhello-dbgsym_0.0-1_amd64.deb pre-depends \
            depends recommends conflicts breaks
Depends: debhello (= 0.0-1)
 $ dpkg -f debhello_0.0-1_amd64.deb pre-depends \
            depends recommends conflicts breaks
Depends: libc6 (>= 2.34)

[Caution]Caution

Many more details need to be addressed before uploading the package to the Debian archive.

[Note]Note

If manual adjustments of auto-generated configuration files by the debmake command are skipped, the generated binary package may lack meaningful package description and some of the policy requirements may be missed. This sloppy package functions well under the dpkg command, and may be good enough for your local deployment.

The above example did not touch the upstream source to make the proper Debian package. An alternative approach as the maintainer is to modify files in the upstream source. For example, Makefile may be modified to set the $(prefix) value to /usr.

[Note]Note

The above Section 5.7, “Schritt 3: Anpassung der Vorlagendateien” using the debian/rules file is the better approach for packaging for this example. But let’s continue on with this alternative approaches as a leaning experience.

In the following, let’s consider 3 simple variants of this alternative approach to generate debian/patches/* files representing modifications to the upstream source in the Debian source format 3.0 (quilt). These substitute Section 5.7, “Schritt 3: Anpassung der Vorlagendateien”” in the above step-by-step example:

Please note the debian/rules file used for these examples doesn’t have the override_dh_auto_install target as follows:

debian/rules (alternative maintainer version): 

 $ cd /path/to/debhello-0.0
 $ vim debian/rules
 ... hack, hack, hack, ...
 $ cat debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

Here, the patch file 000-prefix-usr.patch is created using the diff command.

Patch by diff -u

 $ cp -a debhello-0.0 debhello-0.0.orig
 $ vim debhello-0.0/Makefile
 ... hack, hack, hack, ...
 $ diff -Nru debhello-0.0.orig debhello-0.0 >000-prefix-usr.patch
 $ cat 000-prefix-usr.patch
diff -Nru debhello-0.0.orig/Makefile debhello-0.0/Makefile
--- debhello-0.0.orig/Makefile  2024-07-24 10:12:40.382927188 +0900
+++ debhello-0.0/Makefile       2024-07-24 10:12:40.478928659 +0900
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

 $ rm -rf debhello-0.0
 $ mv -f debhello-0.0.orig debhello-0.0

Please note that the upstream source tree is restored to the original state after generating a patch file 000-prefix-usr.patch.

This 000-prefix-usr.patch is edited to be DEP-3 conforming and moved to the right location as below.

000-prefix-usr.patch (DEP-3): 

 $ echo '000-prefix-usr.patch' >debian/patches/series
 $ vim ../000-prefix-usr.patch
 ... hack, hack, hack, ...
 $ mv -f ../000-prefix-usr.patch debian/patches/000-prefix-usr.patch
 $ cat debian/patches/000-prefix-usr.patch
From: Osamu Aoki <osamu@debian.org>
Description: set prefix=/usr patch
diff -Nru debhello-0.0.orig/Makefile debhello-0.0/Makefile
--- debhello-0.0.orig/Makefile
+++ debhello-0.0/Makefile
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

[Note]Note

When generating the Debian source package by dpkg-source via dpkg-buildpackage in the following step of Section 5.8, “Step 4: Building package with debuild, the dpkg-source command assumes that no patch was applied to the upstream source, since the .pc/applied-patches is missing.

Here, the patch file 000-prefix-usr.patch is created using the dquilt command.

dquilt is a simple wrapper of the quilt program. The syntax and function of the dquilt command is the same as the quilt(1) command, except for the fact that the generated patch is stored in the debian/patches/ directory.

Patch by dquilt

 $ dquilt new 000-prefix-usr.patch
Patch debian/patches/000-prefix-usr.patch is now on top
 $ dquilt add Makefile
File Makefile added to patch debian/patches/000-prefix-usr.patch
 ... hack, hack, hack, ...
 $ head -1 Makefile
prefix = /usr
 $ dquilt refresh
Refreshed patch debian/patches/000-prefix-usr.patch
 $ dquilt header -e --dep3
 ... edit the DEP-3 patch header with editor
 $ tree -a
.
├── debian
│   ├── changelog
│   ├── clean
│   ├── control
│   ├── copyright
│   ├── dirs
│   ├── gbp.conf
│   ├── install
│   ├── links
│   ├── patches
│   │   ├── 000-prefix-usr.patch
│   │   └── series
│   ├── README.Debian
│   ├── README.source
│   ├── rules
│   ├── salsa-ci.yml
│   ├── source
│   │   ├── format
│   │   ├── local-options.ex
│   │   └── local-patch-header.ex
│   ├── tests
│   │   └── control
│   ├── upstream
│   │   └── metadata
│   └── watch
├── Makefile
├── .pc
│   ├── 000-prefix-usr.patch
│   │   ├── Makefile
│   │   └── .timestamp
│   ├── applied-patches
│   ├── .quilt_patches
│   ├── .quilt_series
│   └── .version
├── README.md
└── src
    └── hello.c

9 directories, 29 files
 $ cat debian/patches/series
000-prefix-usr.patch
 $ cat debian/patches/000-prefix-usr.patch
Description: set prefix=/usr patch
Author: Osamu Aoki <osamu@debian.org>
Index: debhello-0.0/Makefile
===================================================================
--- debhello-0.0.orig/Makefile
+++ debhello-0.0/Makefile
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

Here, Makefile in the upstream source tree doesn’t need to be restored to the original state for the packaging.

[Note]Note

When generating the Debian source package by dpkg-source via dpkg-buildpackage in the following step of Section 5.8, “Step 4: Building package with debuild, the dpkg-source command assumes that patches were applied to the upstream source, since the .pc/applied-patches exists.

The upstream source tree can be restored to the original state for the packaging.

The upstream source tree (restored): 

 $ dquilt pop -a
Removing patch debian/patches/000-prefix-usr.patch
Restoring Makefile

No patches applied
 $ head -1 Makefile
prefix = /usr/local
 $ tree -a .pc
.pc
├── .quilt_patches
├── .quilt_series
└── .version

1 directory, 3 files

Here, Makefile is restored and the .pc/applied-patches is missing.

Here, the patch file isn’t created in this step but the source files are setup to create debian/patches/* files in the following step of Section 5.8, “Step 4: Building package with debuild”.

Bearbeiten Sie die Quellen der Originalautoren.

Modified Makefile

 $ vim Makefile
 ... hack, hack, hack, ...
 $ head -n1 Makefile
prefix = /usr

Let’s edit debian/source/local-options:

debian/source/local-options for auto-commit

 $ mv debian/source/local-options.ex debian/source/local-options
 $ vim debian/source/local-options
 ... hack, hack, hack, ...
 $ cat debian/source/local-options
# == Patch applied strategy (merge) ==
#
# The source outside of debian/ directory is modified by maintainer and
# different from the upstream one:
#   * Workflow using dpkg-source commit (commit all to VCS after dpkg-source ...
#       https://www.debian.org/doc/manuals/debmake-doc/ch04.en.html#dpkg-sour...
#   * Workflow described in dgit-maint-merge(7)
#
single-debian-patch
auto-commit

Let’s edit debian/source/local-patch-header:

debian/source/local-patch-header for auto-commit

 $ mv debian/source/local-patch-header.ex debian/source/local-patch-header
 $ vim debian/source/local-patch-header
 ... hack, hack, hack, ...
 $ cat debian/source/local-patch-header
Description: debian-changes
Author: Osamu Aoki <osamu@debian.org>

Let’s remove debian/patches/* files and other unused template files.

Remove unused template files. 

 $ rm -f debian/clean debian/dirs debian/install debian/links
 $ rm -f debian/README.source debian/source/*.ex
 $ rm -rf debian/patches
 $ tree debian
debian
├── README.Debian
├── changelog
├── control
├── copyright
├── gbp.conf
├── rules
├── salsa-ci.yml
├── source
│   ├── format
│   ├── local-options
│   └── local-patch-header
├── tests
│   └── control
├── upstream
│   └── metadata
└── watch

4 directories, 13 files

There are no debian/patches/* files at the end of this step.

[Note]Note

When generating the Debian source package by dpkg-source via dpkg-buildpackage in the following step of Section 5.8, “Step 4: Building package with debuild, the dpkg-source command uses options specified in debian/source/local-options to auto-commit modification applied to the upstream source as patches/debian-changes.

Let’s inspect the Debian source package generated after the following Section 5.8, “Step 4: Building package with debuild step and extracting files from debhello-0.0.debian.tar.xz.

Inspect debhello-0.0.debian.tar.xz after debuild

 $ tar --xz -xvf debhello_0.0-1.debian.tar.xz
debian/
debian/README.Debian
debian/changelog
debian/control
debian/copyright
debian/gbp.conf
debian/patches/
debian/patches/debian-changes
debian/patches/series
debian/rules
debian/salsa-ci.yml
debian/source/
debian/source/format
debian/tests/
debian/tests/control
debian/upstream/
debian/upstream/metadata
debian/watch

Let’s check generated debian/patches/* files.

Inspect debian/patches/* after debuild

 $ cat debian/patches/series
debian-changes
 $ cat debian/patches/debian-changes
Description: debian-changes
Author: Osamu Aoki <osamu@debian.org>

--- debhello-0.0.orig/Makefile
+++ debhello-0.0/Makefile
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

The Debian source package debhello-0.0.debian.tar.xz is confirmed to be generated properly with debian/patches/* files for the Debian modification.



[9] This is a cliché to force a read-only relocation link for the hardening and to prevent the lintian warning W: debhello: hardening-no-relro usr/bin/hello. This is not really needed for this example but should be harmless. The lintian tool seems to produce a false positive warning for this case which has no linked library.

[10] This is a cliché to prevent overlinking for the complex library dependency case such as Gnome programs. This is not really needed for this simple example but should be harmless.