Debian New Maintainers' Guide
Total Page:16
File Type:pdf, Size:1020Kb
Debian New Maintainers’ Guide Josip Rodin and Osamu Aoki Debian New Maintainers’ Guide ii Copyright © 1998-2002 Josip Rodin Copyright © 2005-2015 Osamu Aoki Copyright © 2010 Craig Small Copyright © 2010 Raphaël Hertzog This document may be used under the terms of the GNU General Public License version 2 or higher. This document was made using these two documents as examples: • Making a Debian Package (AKA the Debmake Manual), copyright © 1997 Jaldhar Vyas. • The New-Maintainer’s Debian Packaging Howto, copyright © 1997 Will Lowe. Debian New Maintainers’ Guide iii COLLABORATORS TITLE : Debian New Maintainers’ Guide ACTION NAME DATE SIGNATURE WRITTEN BY Josip Rodin and December 24, 2020 Osamu Aoki REVISION HISTORY NUMBER DATE DESCRIPTION NAME Debian New Maintainers’ Guide iv Contents 1 Getting started The Right Way 1 1.1 Social dynamics of Debian .............................................. 1 1.2 Programs needed for development .......................................... 3 1.3 Documentation needed for development ....................................... 4 1.4 Where to ask for help ................................................. 4 2 First steps 6 2.1 Debian package building workflow .......................................... 6 2.2 Choose your program ................................................. 7 2.3 Get the program, and try it out ............................................ 9 2.4 Simple build systems ................................................. 10 2.5 Popular portable build systems ............................................ 10 2.6 Package name and version .............................................. 11 2.7 Setting up dh_make ................................................. 11 2.8 Initial non-native Debian package .......................................... 12 3 Modifying the source 13 3.1 Setting up quilt .................................................... 13 3.2 Fixing upstream bugs ................................................. 13 3.3 Installation of files to their destination ........................................ 14 3.4 Differing libraries ................................................... 16 4 Required files under the debian directory 17 4.1 control ....................................................... 17 4.2 copyright ..................................................... 21 4.3 changelog ..................................................... 22 4.4 rules ........................................................ 23 4.4.1 Targets of the rules file .......................................... 23 4.4.2 Default rules file .............................................. 24 4.4.3 Customization of rules file ......................................... 26 Debian New Maintainers’ Guide v 5 Other files under the debian directory 29 5.1 README.Debian .................................................. 29 5.2 compat ........................................................ 30 5.3 conffiles ..................................................... 30 5.4 package.cron.* .................................................. 30 5.5 dirs ......................................................... 31 5.6 package.doc-base ................................................ 31 5.7 docs ......................................................... 31 5.8 emacsen-* ..................................................... 31 5.9 package.examples ................................................ 32 5.10 package.init and package.default ..................................... 32 5.11 install ....................................................... 32 5.12 package.info ................................................... 32 5.13 package.links ................................................... 33 5.14 {package.,source/}lintian-overrides ................................. 33 5.15 manpage.* ..................................................... 33 5.15.1 manpage.1.ex ............................................... 33 5.15.2 manpage.sgml.ex ............................................ 34 5.15.3 manpage.xml.ex ............................................. 34 5.16 package.manpages ................................................ 34 5.17 NEWS ......................................................... 34 5.18 {pre,post}{inst,rm} ............................................. 35 5.19 package.symbols ................................................. 35 5.20 TODO ......................................................... 35 5.21 watch ........................................................ 35 5.22 source/format .................................................. 36 5.23 source/local-options ............................................ 36 5.24 source/options ................................................. 36 5.25 patches/* ..................................................... 37 6 Building the package 38 6.1 Complete (re)build .................................................. 38 6.2 Autobuilder ...................................................... 39 6.3 debuild command ................................................... 40 6.4 pbuilder package ................................................. 40 6.5 git-buildpackage command and similar ....................................... 42 6.6 Quick rebuild ..................................................... 42 6.7 Command hierarchy .................................................. 43 Debian New Maintainers’ Guide vi 7 Checking the package for errors 44 7.1 Suspicious changes .................................................. 44 7.2 Verifying a package’s installation ........................................... 44 7.3 Verifying a package’s maintainer scripts ....................................... 44 7.4 Using lintian ................................................... 45 7.5 The debc command .................................................. 46 7.6 The debdiff command ................................................ 46 7.7 The interdiff command ................................................ 46 7.8 The mc command ................................................... 46 8 Updating the package 47 8.1 New Debian revision ................................................. 47 8.2 Inspection of the new upstream release ........................................ 48 8.3 New upstream release ................................................. 48 8.4 Updating the packaging style ............................................. 49 8.5 UTF-8 conversion ................................................... 50 8.6 Reminders for updating packages ........................................... 50 9 Uploading the package 51 9.1 Uploading to the Debian archive ........................................... 51 9.2 Including orig.tar.gz for upload ........................................ 52 9.3 Skipped uploads .................................................... 52 A Advanced packaging 53 A.1 Shared libraries .................................................... 53 A.2 Managing debian/package.symbols ...................................... 54 A.3 Multiarch ....................................................... 55 A.4 Building a shared library package .......................................... 56 A.5 Native Debian package ................................................ 57 Debian New Maintainers’ Guide 1 / 57 Chapter 1 Getting started The Right Way This document tries to describe the building of a Debian package to ordinary Debian users and prospective developers. It uses fairly non-technical language, and it’s well covered with working examples. 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). The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Main- tainers (https://www.debian.org/doc/devel-manuals#debmake-doc) . Please use this new tutorial as the primary tutorial document. This document is made available for the Debian Buster release since this offers many translations. This document will be dropped in the following releases since contents are getting outdated. 1 One of the things that makes Debian such a top-notch distribution is its package system. While there is a vast quantity of software already in the Debian format, sometimes you need to install software that isn’t. You may be wondering how you can make your own packages; and perhaps you think it is a very difficult task. Well, if you are a real novice on Linux, it is hard, but if you were a rookie, you wouldn’t be reading this document now :-) You do need to know a little about Unix programming but you certainly don’t need to be a wizard. 2 One thing is certain, though: to properly create and maintain Debian packages takes many hours. Make no mistake, for our system to work the maintainers need to be both technically competent and diligent. If you need some help with packaging, please read Section 1.4. Newer versions of this document should always be available online at http://www.debian.org/doc/maint-guide/ and in the maint-guide package. The translations may be available in packages such as maint-guide-es. Please note that this documentation may be slightly outdated. Since this is a tutorial, I choose to explain each detailed step for some important topics. Some of them may look irrelevant to you. Please be patient. I have also intentionally skipped some corner cases and provided only pointers to keep this document simple. 1.1 Social dynamics of Debian Here are some observations of Debian’s social dynamics, presented