Guide for Debian Maintainers

Osamu Aoki

Abstract

This tutorial document describes the building of the Debian package to ordinary Debian users and prospective developers using the debmake command.

It is focused on the modern packaging style and comes with many simple examples.

  • POSIX shell script packaging
  • Python3 script packaging
  • C with Makefile/Autotools/CMake
  • multiple binary packages with shared library etc.

This “Guide for Debian Maintainers” can be considered as the successor to the “Debian New Maintainers’ Guide”.


Table of Contents

Preface
1. Overview
2. Prerequisites
2.1. People around Debian
2.2. How to contribute
2.3. Social dynamics of Debian
2.4. Technical reminders
2.5. Debian documentation
2.6. Help resources
2.7. Archive situation
2.8. Contribution approaches
2.9. Novice maintainer
3. Tool Setups
3.1. Email address
3.2. mc
3.3. git
3.4. quilt
3.5. devscripts
3.6. pbuilder
3.7. git-buildpackage
3.8. HTTP proxy
3.9. Private Debian repository
4. Simple Example
4.1. Big picture
4.2. What is debmake?
4.3. What is debuild?
4.4. Step 1: Get the upstream source
4.5. Step 2: Generate template files with debmake
4.6. Step 3: Modification to the template files
4.7. Step 4: Building package with debuild
4.8. Step 3 (alternative): Modification to the upstream source
4.8.1. Patch by diff -u
4.8.2. Patch by dquilt
4.8.3. Patch by dpkg-source --commit
5. Basics
5.1. Packaging workflow
5.2. Package name and version
5.3. Native Debian package
5.4. debian/rules
5.4.1. dh
5.4.2. Simple debian/rules
5.4.3. Customized debian/rules
5.4.4. Variables for debian/rules
5.4.5. Reproducible build
5.5. debian/control
5.5.1. Split of the Debian binary package
5.5.1.1. debmake -b
5.5.1.2. Package split scenario and examples
5.5.1.3. The library package name
5.5.2. Substvar
5.5.3. binNMU safe
5.6. debian/changelog
5.7. debian/copyright
5.8. debian/patches/*
5.8.1. dpkg-source -x
5.8.2. dquilt and dpkg-source
5.9. debian/upstream/signing-key.pgp
5.10. debian/watch and DFSG
5.11. Other debian/*
5.12. Customization of the Debian packaging
5.13. Recording in VCS (standard)
5.14. Recording in VCS (alternative)
5.15. Rebuilding non-native package without extraneous diffs
5.15.1. Fix by debian/rules clean
5.15.2. Fix using VCS
5.15.3. Fix by extend-diff-ignore
5.16. Native Debian source package without extraneous files
5.17. Upstream build systems
5.17.1. Autotools
5.17.2. CMake
5.17.3. Python distutils
5.18. Debugging information
5.18.1. New -dbgsym package (Strech 9.0 and after)
5.18.2. Old -dbg package (Jessie 8.0 or before)
5.19. Library package
5.19.1. Library symbols
5.19.2. Library transition
5.20. Multiarch
5.20.1. The multiarch library path
5.20.2. The multiarch header file path
5.20.3. The multiarch *.pc file path
5.21. Compiler hardening
5.22. Bug report
5.23. debconf
5.24. Continuous integration
6. debmake options
6.1. Shortcut options (-a, -i)
6.1.1. Python module
6.2. Upstream snapshot (-d, -t)
6.3. debmake -cc
6.4. debmake -k
6.5. debmake -j
6.6. debmake -x
6.7. debmake -P
6.8. debmake -T
7. Tips
7.1. debdiff
7.2. dget
7.3. debc
7.4. piuparts
7.5. debsign
7.6. dput
7.7. bts
7.8. git-buildpackage
7.8.1. gbp import-dscs --debsnap
7.9. Upstream git repository
7.10. chroot
7.11. New Debian revision
7.12. New upstream release
7.12.1. uupdate + tarball
7.12.2. uscan
7.12.3. gbp
7.12.4. gbp + uscan
7.13. 3.0 source format
7.14. CDBS
7.15. Build under UTF-8
7.16. UTF-8 conversion
7.17. Upload orig.tar.gz
7.18. Skipped uploads
7.19. Advanced packaging
7.20. Other distros
7.21. Debug
8. More Examples
8.1. Cherry-pick templates
8.2. No Makefile (shell, CLI)
8.3. Makefile (shell, CLI)
8.4. setup.py (Python3, CLI)
8.5. Makefile (shell, GUI)
8.6. setup.py (Python3, GUI)
8.7. Makefile (single-binary)
8.8. Makefile.in + configure (single-binary)
8.9. Autotools (single-binary)
8.10. CMake (single-binary)
8.11. Autotools (multi-binary)
8.12. CMake (multi-binary)
8.13. Internationalization
8.14. Details
A. debmake(1) manpage
A.1. NAME
A.2. SYNOPSIS
A.3. DESCRIPTION
A.3.1. optional arguments:
A.4. EXAMPLES
A.5. HELPER PACKAGES
A.6. CAVEAT
A.7. DEBUG
A.8. AUTHOR
A.9. LICENSE
A.10. SEE ALSO