Debian Policy Manual

version 4.0.0.4

These are the copyright dates of the original Policy manual. Since then, this manual has been updated by many others. No comprehensive collection of copyright notices for subsequent work exists.

This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is available as /usr/share/common-licenses/GPL in the Debian distribution or on the World Wide Web at https://www.gnu.org/licenses/.

2017-06-25

Abstract

This manual describes the policy requirements for the Debian distribution. This includes the structure and contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution.


Table of Contents

1. About this manual
1.1. Scope
1.2. New versions of this document
1.3. Authors and Maintainers
1.4. Related documents
1.5. Definitions
2. The Debian Archive
2.1. The Debian Free Software Guidelines
2.2. Archive areas
2.2.1. The main archive area
2.2.2. The contrib archive area
2.2.3. The non-free archive area
2.3. Copyright considerations
2.4. Sections
2.5. Priorities
3. Binary packages
3.1. The package name
3.2. The version of a package
3.2.1. Version numbers based on dates
3.3. The maintainer of a package
3.4. The description of a package
3.4.1. The single line synopsis
3.4.2. The extended description
3.5. Dependencies
3.6. Virtual packages
3.7. Base system
3.8. Essential packages
3.9. Maintainer Scripts
3.9.1. Prompting in maintainer scripts
4. Source packages
4.1. Standards conformance
4.2. Package relationships
4.3. Changes to the upstream sources
4.4. Debian changelog: debian/changelog
4.5. Copyright: debian/copyright
4.6. Error trapping in makefiles
4.7. Time Stamps
4.8. Restrictions on objects in source packages
4.9. Main building script: debian/rules
4.9.1. debian/rules and DEB_BUILD_OPTIONS
4.10. Variable substitutions: debian/substvars
4.11. Optional upstream source location: debian/watch
4.12. Generated files list: debian/files
4.13. Convenience copies of code
4.14. Source package handling: debian/README.source
5. Control files and their fields
5.1. Syntax of control files
5.2. Source package control files -- debian/control
5.3. Binary package control files -- DEBIAN/control
5.4. Debian source control files -- .dsc
5.5. Debian changes files -- .changes
5.6. List of fields
5.6.1. Source
5.6.2. Maintainer
5.6.3. Uploaders
5.6.4. Changed-By
5.6.5. Section
5.6.6. Priority
5.6.7. Package
5.6.8. Architecture
5.6.9. Essential
5.6.10. Package interrelationship fields: Depends, Pre-Depends, Recommends, Suggests, Breaks, Conflicts, Provides, Replaces, Enhances
5.6.11. Standards-Version
5.6.12. Version
5.6.13. Description
5.6.14. Distribution
5.6.15. Date
5.6.16. Format
5.6.17. Urgency
5.6.18. Changes
5.6.19. Binary
5.6.20. Installed-Size
5.6.21. Files
5.6.22. Closes
5.6.23. Homepage
5.6.24. Checksums-Sha1 and Checksums-Sha256
5.6.25. DM-Upload-Allowed
5.6.26. Version Control System (VCS) fields
5.6.27. Package-List
5.6.28. Package-Type
5.6.29. Dgit
5.7. User-defined fields
5.8. Obsolete fields
5.8.1. DM-Upload-Allowed
6. Package maintainer scripts and installation procedure
6.1. Introduction to package maintainer scripts
6.2. Maintainer scripts idempotency
6.3. Controlling terminal for maintainer scripts
6.4. Exit status
6.5. Summary of ways maintainer scripts are called
6.6. Details of unpack phase of installation or upgrade
6.7. Details of configuration
6.8. Details of removal and/or configuration purging
7. Declaring relationships between packages
7.1. Syntax of relationship fields
7.2. Binary Dependencies - Depends, Recommends, Suggests, Enhances, Pre-Depends
7.3. Packages which break other packages - Breaks
7.4. Conflicting binary packages - Conflicts
7.5. Virtual packages - Provides
7.6. Overwriting files and replacing packages - Replaces
7.6.1. Overwriting files in other packages
7.6.2. Replacing whole packages, forcing their removal
7.7. Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Depends-Arch, Build-Conflicts, Build-Conflicts-Indep, Build-Conflicts-Arch
7.8. Additional source packages used to build the binary - Built-Using
8. Shared libraries
8.1. Run-time shared libraries
8.1.1. ldconfig
8.2. Shared library support files
8.3. Static libraries
8.4. Development files
8.5. Dependencies between the packages of the same library
8.6. Dependencies between the library and other packages
8.6.1. Generating dependencies on shared libraries
8.6.2. Shared library ABI changes
8.6.3. The symbols system
8.6.4. The shlibs system
9. The Operating System
9.1. File system hierarchy
9.1.1. File System Structure
9.1.2. Site-specific programs
9.1.3. The system-wide mail directory
9.1.4. /run and /run/lock
9.2. Users and groups
9.2.1. Introduction
9.2.2. UID and GID classes
9.3. System run levels and init.d scripts
9.3.1. Introduction
9.3.2. Writing the scripts
9.3.3. Interfacing with the initscript system
9.3.4. Boot-time initialization
9.3.5. Example
9.4. Console messages from init.d scripts
9.5. Cron jobs
9.5.1. Cron job file names
9.6. Menus
9.7. Multimedia handlers
9.7.1. Registration of media type handlers with desktop entries
9.7.2. Registration of media type handlers with mailcap entries
9.7.3. Providing media types to files
9.8. Keyboard configuration
9.9. Environment variables
9.10. Registering Documents using doc-base
9.11. Alternate init systems
9.11.1. Event-based boot with upstart
10. Files
10.1. Binaries
10.2. Libraries
10.3. Shared libraries
10.4. Scripts
10.5. Symbolic links
10.6. Device files
10.7. Configuration files
10.7.1. Definitions
10.7.2. Location
10.7.3. Behavior
10.7.4. Sharing configuration files
10.7.5. User configuration files ("dotfiles")
10.8. Log files
10.9. Permissions and owners
10.9.1. The use of dpkg-statoverride
10.10. File names
11. Customized programs
11.1. Architecture specification strings
11.1.1. Architecture wildcards
11.2. Daemons
11.3. Using pseudo-ttys and modifying wtmp, utmp and lastlog
11.4. Editors and pagers
11.5. Web servers and applications
11.6. Mail transport, delivery and user agents
11.7. News system configuration
11.8. Programs for the X Window System
11.8.1. Providing X support and package priorities
11.8.2. Packages providing an X server
11.8.3. Packages providing a terminal emulator
11.8.4. Packages providing a window manager
11.8.5. Packages providing fonts
11.8.6. Application defaults files
11.8.7. Installation directory issues
11.9. Perl programs and modules
11.10. Emacs lisp programs
11.11. Games
12. Documentation
12.1. Manual pages
12.2. Info documents
12.3. Additional documentation
12.4. Preferred documentation formats
12.5. Copyright information
12.5.1. Machine-readable copyright information
12.6. Examples
12.7. Changelog files
A. Introduction and scope of these appendices
B. Binary packages (from old Packaging Manual)
B.1. Creating package files - dpkg-deb
B.2. Package control information files
B.3. The main control information file: control
B.4. Time Stamps
C. Source packages (from old Packaging Manual)
C.1. Tools for processing source packages
C.1.1. dpkg-source - packs and unpacks Debian source packages
C.1.2. dpkg-buildpackage - overall package-building control script
C.1.3. dpkg-gencontrol - generates binary package control files
C.1.4. dpkg-shlibdeps - calculates shared library dependencies
C.1.5. dpkg-distaddfile - adds a file to debian/files
C.1.6. dpkg-genchanges - generates a .changes upload control file
C.1.7. dpkg-parsechangelog - produces parsed representation of a changelog
C.1.8. dpkg-architecture - information about the build and host system
C.2. The Debian package source tree
C.2.1. debian/rules - the main building script
C.2.2. debian/substvars and variable substitutions
C.2.3. debian/files
C.2.4. debian/tmp
C.3. Source packages as archives
C.4. Unpacking a Debian source package without dpkg-source
C.4.1. Restrictions on objects in source packages
D. Control files and their fields (from old Packaging Manual)
D.1. Syntax of control files
D.2. List of fields
D.2.1. Filename and MSDOS-Filename
D.2.2. Size and MD5sum
D.2.3. Status
D.2.4. Config-Version
D.2.5. Conffiles
D.2.6. Obsolete fields
E. Configuration file handling (from old Packaging Manual)
E.1. Automatic handling of configuration files by dpkg
E.2. Fully-featured maintainer script configuration handling
F. Alternative versions of an interface - update-alternatives (from old Packaging Manual)
G. Diversions - overriding a package's version of a file (from old Packaging Manual)
H. Upgrading checklist
H.1. About the checklist
H.2. Version 4.0.0
H.3. Version 3.9.8
H.4. Version 3.9.7
H.5. Version 3.9.6
H.6. Version 3.9.5
H.7. Version 3.9.4
H.8. Version 3.9.3
H.9. Version 3.9.2
H.10. Version 3.9.1
H.11. Version 3.9.0
H.12. Version 3.8.4
H.13. Version 3.8.3
H.14. Version 3.8.2
H.15. Version 3.8.1
H.16. Version 3.8.0
H.17. Version 3.7.3
H.18. Version 3.7.2.2
H.19. Version 3.7.2
H.20. Version 3.7.1
H.21. Version 3.7.0
H.22. Version 3.6.2
H.23. Version 3.6.1
H.24. Version 3.6.0
H.25. Version 3.5.10
H.26. Version 3.5.9
H.27. Version 3.5.8
H.28. Version 3.5.7
H.29. Version 3.5.6
H.30. Version 3.5.5
H.31. Version 3.5.4
H.32. Version 3.5.3
H.33. Version 3.5.2
H.34. Version 3.5.1
H.35. Version 3.5.0
H.36. Version 3.2.1.1
H.37. Version 3.2.1
H.38. Version 3.2.0
H.39. Version 3.1.1
H.40. Version 3.1.0
H.41. Version 3.0.1
H.42. Version 3.0.0
H.43. Version 2.5.0
H.44. Version 2.4.1
H.45. Version 2.4.0
H.46. Version 2.3.0
H.47. Version 2.2.0
H.48. Version 2.1.3
H.49. Version 2.1.2
H.50. Version 2.1.1
H.51. Version 2.1.0