Debian Policy Manual Release 4.6.0.1 The Debian Policy Mailing List Aug 18, 2021 CONTENTS 1 About this manual 3 1.1 Scope ................................................... 3 1.2 New versions of this document ...................................... 4 1.3 Authors and Maintainers ......................................... 4 1.3.1 Early history ........................................... 4 1.3.2 Current process ......................................... 4 1.3.3 Improvements .......................................... 5 1.4 Related documents ............................................ 5 1.5 Definitions ................................................ 5 1.6 Translations ................................................ 6 2 The Debian Archive 7 2.1 The Debian Free Software Guidelines .................................. 7 2.2 Archive areas ............................................... 8 2.2.1 The main archive area ...................................... 8 2.2.2 The contrib archive area ..................................... 8 2.2.3 The non-free archive area .................................... 9 2.3 Copyright considerations ......................................... 9 2.4 Sections .................................................. 10 2.5 Priorities ................................................. 10 3 Binary packages 13 3.1 The package name ............................................ 13 3.1.1 Packages with potentially offensive content ........................... 13 3.2 The version of a package ......................................... 14 3.2.1 Version numbers based on dates ................................. 14 3.2.2 Uniqueness of version numbers ................................. 14 3.3 The maintainer of a package ....................................... 15 3.4 The description of a package ....................................... 15 3.4.1 The single line synopsis ..................................... 16 3.4.2 The extended description .................................... 16 3.5 Dependencies ............................................... 16 3.6 Virtual packages ............................................. 16 3.7 Base system ................................................ 17 3.8 Essential packages ............................................ 17 3.9 Maintainer Scripts ............................................ 17 3.9.1 Prompting in maintainer scripts ................................. 18 4 Source packages 19 4.1 Standards conformance .......................................... 19 i 4.2 Package relationships ........................................... 19 4.3 Changes to the upstream sources ..................................... 20 4.4 Debian changelog: debian/changelog ............................... 20 4.5 Copyright: debian/copyright ................................... 22 4.6 Error trapping in makefiles ........................................ 22 4.7 Time Stamps ............................................... 22 4.8 Restrictions on objects in source packages ................................ 22 4.9 Main building script: debian/rules ................................. 22 4.9.1 debian/rules and DEB_BUILD_OPTIONS ........................ 25 4.9.2 debian/rules and Rules-Requires-Root ...................... 26 4.10 Variable substitutions: debian/substvars ............................. 27 4.11 Upstream source location: debian/watch .............................. 27 4.12 Generated files list: debian/files .................................. 28 4.13 Embedded code copies .......................................... 28 4.14 Source package handling: debian/README.source ........................ 28 4.15 Reproducibility .............................................. 29 4.16 Missing sources: debian/missing-sources ........................... 29 4.17 Vendor-specific patch series ....................................... 29 5 Control files and their fields 31 5.1 Syntax of control files ........................................... 31 5.2 Source package control files – debian/control ........................... 32 5.3 Binary package control files – DEBIAN/control ........................... 33 5.4 Debian source control files – .dsc .................................... 34 5.5 Debian changes files – .changes .................................... 34 5.6 List of fields ............................................... 35 5.6.1 Source ............................................. 35 5.6.2 Maintainer ......................................... 35 5.6.3 Uploaders .......................................... 36 5.6.4 Changed-By ......................................... 36 5.6.5 Section ............................................ 36 5.6.6 Priority ........................................... 36 5.6.7 Package ............................................ 36 5.6.8 Architecture ........................................ 36 5.6.9 Essential .......................................... 37 5.6.10 Package interrelationship fields: Depends, Pre-Depends, Recommends, Suggests, Breaks, Conflicts, Provides, Replaces, Enhances ............... 37 5.6.11 Standards-Version .................................... 37 5.6.12 Version ............................................ 38 5.6.12.1 Epochs should be used sparingly ............................ 39 5.6.13 Description ......................................... 39 5.6.14 Distribution ........................................ 40 5.6.15 Date .............................................. 40 5.6.16 Format ............................................. 40 5.6.17 Urgency ............................................ 40 5.6.18 Changes ............................................ 41 5.6.19 Binary ............................................. 41 5.6.20 Installed-Size ...................................... 41 5.6.21 Files ............................................. 41 5.6.22 Closes ............................................. 42 5.6.23 Homepage ........................................... 42 5.6.24 Checksums-Sha1 and Checksums-Sha256 ....................... 42 5.6.25 DM-Upload-Allowed .................................... 43 5.6.26 Version Control System (VCS) fields .............................. 43 ii 5.6.27 Package-List ........................................ 44 5.6.28 Package-Type ........................................ 44 5.6.29 Dgit .............................................. 44 5.6.30 Testsuite .......................................... 44 5.6.31 Rules-Requires-Root .................................. 45 5.6.31.1 Remarks ........................................ 45 5.6.31.2 Definition of the keywords ............................... 45 5.6.31.3 Provided keywords ................................... 46 5.7 User-defined fields ............................................ 46 5.8 Obsolete fields .............................................. 46 5.8.1 DM-Upload-Allowed .................................... 47 6 Package maintainer scripts and installation procedure 49 6.1 Introduction to package maintainer scripts ................................ 49 6.2 Maintainer scripts idempotency ...................................... 50 6.3 Controlling terminal for maintainer scripts ................................ 50 6.4 Exit status ................................................. 50 6.5 Summary of ways maintainer scripts are called .............................. 50 6.6 Details of unpack phase of installation or upgrade ............................ 52 6.7 Details of configuration .......................................... 55 6.8 Details of removal and/or configuration purging ............................. 55 7 Declaring relationships between packages 57 7.1 Syntax of relationship fields ........................................ 57 7.2 Binary Dependencies - Depends, Recommends, Suggests, Enhances, Pre-Depends .... 59 7.3 Packages which break other packages - Breaks ............................. 60 7.4 Conflicting binary packages - Conflicts ............................... 61 7.5 Virtual packages - Provides ...................................... 62 7.6 Overwriting files and replacing packages - Replaces ......................... 63 7.6.1 Overwriting files in other packages ............................... 63 7.6.2 Replacing whole packages, forcing their removal ........................ 64 7.7 Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Depends-Arch, Build-Conflicts, Build-Conflicts-Indep, Build- Conflicts-Arch ........................................... 64 7.8 Additional source packages used to build the binary - Built-Using ................. 65 8 Shared libraries 67 8.1 Run-time shared libraries ......................................... 68 8.1.1 ldconfig ........................................... 69 8.2 Shared library support files ........................................ 69 8.3 Static libraries .............................................. 69 8.4 Development files ............................................. 70 8.5 Dependencies between the packages of the same library ......................... 70 8.6 Dependencies between the library and other packages .......................... 70 8.6.1 Generating dependencies on shared libraries .......................... 71 8.6.2 Shared library ABI changes ................................... 72 8.6.3 The symbols system ...................................... 73 8.6.3.1 The symbols files present on the system ....................... 73 8.6.3.2 The symbols File Format .............................. 73 8.6.3.3 Providing a symbols file ............................... 75 8.6.4 The shlibs system