* dpkg --get-selections and --set-selections added.
* New dpkg --force-not-root flag.
* Don't replace directory with another package's file. (Bug#4202.)
* All manpages now installed compressed.
* Copyright file moved to /usr/doc/dpkg/copyright.
* Standards-Version updated (0.2.1.1).
-- Ian Jackson <ian@chiark.chu.cam.ac.uk> Sat, 24 Aug 1996 19:09:30 +0100
+dpkg (1.3.9) unstable; urgency=low (high for new source format)
+
+ * dpkg --get-selections and --set-selections added.
+ * New dpkg --force-not-root flag.
+
+ * Don't replace directory with another package's file. (Bug#4202.)
+
+ * All manpages now installed compressed.
+ * Copyright file moved to /usr/doc/dpkg/copyright.
+ * Standards-Version updated (0.2.1.1).
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Sat, 24 Aug 1996 19:09:30 +0100
+
dpkg (1.3.8) unstable; urgency=low (high for new source format)
* dpkg-buildpackage -sa, -si options work correctly.
Section: base
Priority: required
Maintainer: Ian Jackson <ian@chiark.chu.cam.ac.uk>
-Standards-Version: 0.1
+Standards-Version: 0.2.1.1
Package: dpkg
Architecture: any
datadir=$(DIR)/debian/tmp/var/lib/dpkg \
etcdir=$(DIR)/debian/tmp/etc \
install
- cp debian/copyright debian/tmp/usr/doc/copyright/dpkg
- cp TODO debian/tmp/usr/doc/dpkg/WISHLIST
+ find debian/tmp/usr/man -type f | xargs gzip -9v
gzip -9v debian/tmp/usr/doc/dpkg/changelog.*
+ cp debian/copyright debian/tmp/usr/doc/dpkg/copyright
+ cp TODO debian/tmp/usr/doc/dpkg/WISHLIST
touch debian/tmp/var/lib/dpkg/{status,available}
dpkg-shlibdeps -dPre-Depends main/dpkg dselect/dselect
dpkg-gencontrol
+debian-manuals (0.2.1.1) unstable;
+
+ * Can't overwrite directories in one package with files in another.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Sat, 24 Aug 1996 18:44:54 +0100
+
debian-manuals (0.2.1.0) unstable;
* Policy says when and how to include original source in upload.
-<!entity manuals-version "0.2.0.0">
-<!entity dpkg-version "1.3.7">
+<!entity manuals-version "0.2.1.1">
+<!entity dpkg-version "1.3.9">
+++ /dev/null
-L12 policy.sgml
-(DEBIANDOC
-(BOOK
-L14
-(TITLEPAG
-(TITLE
--Debian policy manual
-L15
-)TITLE
-(AUTHOR
-(NAME
--Ian Jackson
-)NAME
-(EMAIL
--ijackson@gnu.ai.mit.edu
-)EMAIL
-L16
-)AUTHOR
-(VERSION
--version 0.2.0.0 (dpkg 1.3.7),
-(DATE
-)DATE
--\n
-L18
-)VERSION
-(ABSTRACT
-L19
--This manual describes the policy requirements which must be satisfied\nfor a package to be included in the Debian distribution. This\nincludes details of the permissions and ownerships of files in\npackages and other technical requirements as well as information like\nthe upload procedure.
-L24
-)ABSTRACT
-L26
-(COPYRIGHT
-(COPYRIGHTSUMMARY
--Copyright \|©\|1996 Ian Jackson.
-L27
-)COPYRIGHTSUMMARY
-(P
-L28
--\nThis manual is free software; you may redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation; either version 2, or (at your option) any\nlater version.
-L33
-)P
-(P
-L34
--\nThis is distributed in the hope that it will be useful, but\n
-(EM
--without any warranty
-)EM
--; without even the implied warranty of\nmerchantability or fitness for a particular purpose. See the GNU\nGeneral Public License for more details.
-L39
-)P
-(P
-L40
--\nYou should have received a copy of the GNU General Public License with\nyour Debian GNU/Linux system, in
-(TT
--/usr/doc/copyright/GPL
-)TT
--, or\nwith the
-(PRGN
--dpkg
-)PRGN
-- source package as the file
-(TT
--COPYING
-)TT
--. If\nnot, write to the Free Software Foundation, Inc., 675 Mass Ave,\nCambridge, MA 02139, USA.\n
-L47
-)P
-)COPYRIGHT
-)TITLEPAG
-ADETAIL TOKEN SECT
-(TOC
-)TOC
-AID CDATA scope
-L49
-(CHAPT
-(HEADING
--Introduction and scope of this manual
-L50
-)HEADING
-(P
-L51
--\nThis manual describes the criteria that a Debian-format package must\nsatisfy to be included in the Debian distribution.
-L54
-)P
-(P
-L55
--\nMuch of this information will be useful even when building a package\nwhich is to be distributed in some other way or is for local use.
-L58
-)P
-(P
-L59
--\nThis manual does
-(EM
--not
-)EM
-- describe the technical mechanisms involved\nin package creation, installation and removal. This information can\nbe found in the
-(PRGN
--dpkg
-)PRGN
-- programmers' manual and the
-(PRGN
--dpkg
-)PRGN
-- system\nadministrators' manual.
-L64
-)P
-(P
-L65
--\nThis document assumes familiarity with these other two manuals.\nUnfortunately the system administrators' manual does not exist yet.
-L68
-)P
-(P
-L69
--\nThe Debian version of the FSF's GNU
-(PRGN
--hello
-)PRGN
-- program is provided\nas an example for people wishing to create Debian packages.
-L72
-)P
-(P
-L73
--\n
-(EM
--Note that this document is still a draft!
-)EM
--\n
-L76
-)P
-)CHAPT
-AID CDATA pkgcopyright
-(CHAPT
-(HEADING
--Package copyright
-L77
-)HEADING
-(P
-L78
--\nPlease study the copyright of your submission
-(EM
--carefully
-)EM
-- and\nunderstand it before proceeding. If you have doubts or questions,\nplease ask.
-L82
-)P
-(P
-L83
--\nThe aims of the policy detailed below are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L86
-(ITEM
-L87
-(P
--That any user be able to rebuild any package in the official Debian\ndistribution from the original source plus our patches.
-L89
-)P
-)ITEM
-(ITEM
-L90
-(P
--That we make available in our packaging formats as much software as we\ncan.
-L92
-)P
-)ITEM
-(ITEM
-L93
-(P
--That it be easy for people to make CDROMs of our distribution without\nviolating copyrights.
-L95
-)P
-)ITEM
-)LIST
-L96
-)P
-(P
-L97
--\nAll packages in the Debian distribution proper must be freely useable,\nmodifiable and redistributable in both source and binary form. It\nmust be possible for anyone to distribute and use modified source code\nand their own own compiled binaries, at least when they do so as part\nof a Debian distribution.
-L103
-)P
-(P
-L104
--\nPackages whose copyright permission notices (or patent problems) do\nnot allow distribution and copying for profit, without restriction on\nthe amount charged, or where distribution is restricted according to\nthe medium used, or where the distributor must ask any kind of special\npermission of the authors, or with other onerous conditions, may only\nbe placed in the semi-supported non-free section of the Debian FTP\narchives. This is important so that CDROM manufacturers can\ndistribute Debian without having to check the copyright of each\npackage individually, simply by leaving out the contents of the\nnon-free area; CDROM distributors are encouraged, though, to check the\ncopyrights on programs in non-free individually and include as many as\nthey can.
-L117
-)P
-(P
-L118
--\nPackages whose copyright permission notices (or patent problems) allow\nonly distribution of compiled binaries (and thus of which only\nbinaries are available), or where the source code which may be\ndistributed is not the complete source code required to compile the\nprogram (ie, the program cannot be compiled using only packages in the\nmain Debian distribution), or which depend for their use on non-free\nor contrib packages, or allow free use only for a trial period\n(shareware), or are demonstration programs lacking vital functionality\n(crippleware), or are only installer-packages which require the user\nto supply a separate file to be installed, or which fail to meet some\nother policy requirements, may only be placed in the semi-supported\ncontrib section of the Debian FTP archives (unless they need to be in\nnon-free - see above).
-L132
-)P
-(P
-L133
--\nPrograms whose authors encourage the user to make donations are fine\nfor the main distribution, provided that the authors do not claim that\nnot donating is immoral, unethical, illegal or something similar;\notherwise they must go in contrib (or non-free, if even distribution\nis restricted by such statements).
-L139
-)P
-(P
-L140
--\nPackages whose copyright permission notices (or patent problems) do\nnot allow redistribution even of only binaries, and where no special\npermission has been obtained, cannot placed on the Debian FTP site and\nits mirrors at all.
-L145
-)P
-(P
-L146
--\nNote that under international copyright law
-(FOOTNOTE
-(P
--This applies in\nthe United States, too.
-)P
-)FOOTNOTE
--
-(EM
--no
-)EM
-- distribution or modification\nof a work is allowed without an explicit notice saying so. Therefore\na program without a copyright notice
-(EM
--is
-)EM
-- copyrighted and you may\nnot do anything to it without risking being sued! Likewise if a\nprogram has a copyright notice but no statement saying what is\npermitted then nothing is permitted.
-L154
-)P
-(P
-L155
--\nMany authors are unaware of the problems that restrictive copyrights\n(or lack of copyright notices) can cause for the users of their\nsupposedly-free software. It is often worthwhile contacting such\nauthors diplomatically to ask them to modify their terms generally, or\nspecially for Debian. However, this is a politically difficult thing\nto do and you should ask for advice on
-(PRGN
--debian-devel
-)PRGN
-- first.
-L162
-)P
-(P
-L163
--\nWhen in doubt, send mail to
-(EMAIL
--debian-devel@lists.debian.org
-)EMAIL
--. Be\nprepared to provide us with the copyright statement. Software covered\nby the GPL, public domain software and BSD-like copyrights are safe;\nbe wary of the phrases `commercial use prohibited' and `distribution\nrestricted'.
-L169
-)P
-(P
-L170
--\nEvery package submission
-(EM
--must
-)EM
-- be accompanied by verbatim copy of\nits copyright (with the exceptions of public domain packages and those\ncovered by the UCB BSD licence or the GNU GPL or LGPL; in these cases\nsimply indicate which is appropriate). This information must be\nincluded in a file installed by the binary package - see
-AID CDATA copyrightfile
-(REF
-)REF
-L176
--.\n
-L178
-)P
-)CHAPT
-AID CDATA binarypkg
-(CHAPT
-(HEADING
--Contents of the binary package\n
-L180
-)HEADING
-AID IMPLIED
-(SECT
-(HEADING
--Control file requirements\n
-L182
-)HEADING
-AID IMPLIED
-(SECT1
-(HEADING
-(TT
--Maintainer
-)TT
-- information
-L183
-)HEADING
-(P
-L184
--\nAll packages must have a
-(TT
--Maintainer
-)TT
-- field with the correct name\nand a working email address for the Debian maintainer of the package.\nIf one person maintains several packages they should try to avoid\nhaving different forms of their name and address in different\n
-(TT
--Maintainer
-)TT
-- fields.\n
-L191
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Dependencies and virtual packages
-L192
-)HEADING
-(P
-L193
--\nAdd a dependency for any shared libraries required by\ndynamically-linked executable binaries in your package. Almost every\npackage containing compiled C code should therefore include a\n
-(TT
--Depends
-)TT
-- field which mentions the shared C library required for\nthe program to run. For ELF binaries linked against
-(TT
--libc.so.5
-)TT
--\nthe relevant package name is
-(TT
--libc5
-)TT
--.
-L200
-)P
-(P
-L201
--\nAll packages must use virtual package names where appropriate, and\narrange to create new ones if necessary. They must not use virtual\npackage names (except privately, amongst a cooperating group of\npackages) unless they have been agreed upon and appear in the list of\nvirtual package names.
-L207
-)P
-(P
-L208
--\nThe latest version of the authoritative list of virtual package names\ncan be found on
-(FTPSITE
--ftp.debian.org
-)FTPSITE
-- in\n
-(FTPPATH
--/debian/doc/package-developer/virtual-package-names-list.text
-)FTPPATH
--\nor your local mirror. The procedure for updating it is described at\nthe top of the file.\n
-L215
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-L216
-)HEADING
-(P
-L217
--\nDecide whether your package can go in
-(TT
--non-free
-)TT
--,
-(TT
--contrib
-)TT
-- or\nthe main distribution - see
-AID CDATA pkgcopyright
-(REF
-)REF
--, and put\nan appropriate value for the distribution in the\n
-(TT
--debian/changelog
-)TT
-- file.
-L222
-)P
-(P
-L223
--\nThe
-(TT
--Priority
-)TT
-- and
-(TT
--Section
-)TT
-- control file fields give\ninformation for classifying the package in
-(PRGN
--dselect
-)PRGN
-- and say\nwhich directory to place it in the FTP archive.
-L227
-)P
-(P
-L228
--\nThey are ultimately the responsibility of the distribution\nmaintainers; however, you should suggest values for them in your\n
-(TT
--.changes
-)TT
-- information when you upload a package. You do this by\nincluding appropriate information in the
-(TT
--debian/control
-)TT
-- file\nbefore building the packages.
-L234
-)P
-(P
-L235
--\nFor a list of the currently in-use sections, please see the FTP\narchive. Packages in the non-free and contrib areas should have\nsection
-(TT
--non-free
-)TT
-- and
-(TT
--contrib
-)TT
--, respectively.\n
-L240
-)P
-AID IMPLIED
-(SECT2
-(HEADING
-(TT
--Priority
-)TT
-- values
-L241
-)HEADING
-(P
-L242
--\n
-ACOMPACT IMPLIED
-(TAGLIST
-L244
-(TAG
-(TT
--required
-)TT
-L245
-)TAG
-(ITEM
-L246
-(P
-(TT
--required
-)TT
-- packages are necessary for the proper functioning of the\nsystem. You must not remove these packages or your system may become\ntotally broken and you may probably not even be able to use\n
-(PRGN
--dpkg
-)PRGN
-- to put things back. Systems with only the
-(TT
--required
-)TT
--\npackages are probably unuseable, but they do have enough functionality\nto allow the sysadmin to boot and install more software.\n
-L253
-)P
-)ITEM
-(TAG
-(TT
--important
-)TT
-L254
-)TAG
-(ITEM
-L255
-(P
--Important programs, including those which one would expect to find on\nany Unix-like system. If the expectation is that an experienced Unix\nperson who found it missing would go `What the F*!@\|<\|+ is going on,\nwhere is
-(PRGN
--foo
-)PRGN
--', it should be in
-(TT
--important
-)TT
--. This is an\nimportant criterion because we are trying to produce, amongst other\nthings, a free Unix. Other packages without which the system will not\nrun well or be useable should also be here. This does
-(EM
--not
-)EM
--\ninclude Emacs or X11 or TeX or any other large applications. The\n
-(TT
--important
-)TT
-- packages are just a bare minimum of commonly-expected\nand necessary tools.\n
-L266
-)P
-)ITEM
-(TAG
-(TT
--standard
-)TT
-L267
-)TAG
-(ITEM
-L268
-(P
--These packages provide a reasonably small but not too limited\ncharacter-mode system. This is what will install by default if the\nuser doesn't select anything else. It doesn't include many large\napplications, but it does include Emacs (this is more of a piece of\ninfrastructure than an application) and a reasonable subset of TeX and\nLaTeX (if this is possible without X).\n
-L275
-)P
-)ITEM
-(TAG
-(TT
--optional
-)TT
-(FOOTNOTE
-(P
--In a sense everything is optional that\nisn't required, but that's not what is meant here.
-)P
-)FOOTNOTE
-L277
-)TAG
-(ITEM
-L278
-(P
--This is all the software that you might reasonably want to install if\nyou didn't know what it was or don't have specialised requirements.\nThis is a much larger system and includes X11, a full TeX\ndistribution, and lots of applications.\n
-L283
-)P
-)ITEM
-(TAG
-(TT
--extra
-)TT
-L284
-)TAG
-(ITEM
-L285
-(P
--This contains packages that conflict with others with higher\npriorities, or are only likely to be useful if you already know what\nthey are or have specialised requirements.\n
-L289
-)P
-)ITEM
-)TAGLIST
-L290
-)P
-(P
-L291
--\nPriority values are not case-sensitive.\n
-L294
-)P
-)SECT2
-AID IMPLIED
-(SECT2
-(HEADING
--Base packages
-L295
-)HEADING
-(P
-L296
--\nSome packages have
-(TT
--Section: base
-)TT
-- and are in the
-(TT
--base
-)TT
--\nsubdirectory on the FTP archives. These are the packages that are\nsupplied on the base disks. They are the minimum sensible set for\ninstalling new packages (perhaps via a network).
-L301
-)P
-(P
-L302
--\nMost of these packages should have
-(TT
--Priority: required
-)TT
-- or at least\n
-(TT
--Priority: important
-)TT
--.\n
-L306
-)P
-)SECT2
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--The
-(TT
--Essential
-)TT
-- flag
-L307
-)HEADING
-(P
-L308
--\nThe
-(TT
--Essential: yes
-)TT
-- control file field should not be used unless\nremoving a package really will completely hose the system; nor should\nit be used for a shared library package - the dependencies will\nprevent its premature removal, and we need to be able to remove it\nwhen it has been superseded.\n
-L315
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Including
-(TT
--Priority
-)TT
-- and
-(TT
--Section
-)TT
-- in the
-(TT
--.deb
-)TT
--\ncontrol file
-L317
-)HEADING
-(P
-L318
--\nIf a user installs a package which is not part of the standard\ndistribution, or without downloading and updating from a new\n
-(PRGN
--Packages
-)PRGN
-- file, the information about the priority and section\nof a package will be absent, and the
-(PRGN
--dselect
-)PRGN
-- package listing\nwill have the package listed under `unclassified'. In order to\nimprove this it is permissible to use the
-(TT
---is
-)TT
--,
-(TT
---isp
-)TT
-- or\n
-(TT
---ip
-)TT
-- option to
-(PRGN
--dpkg-gencontrol
-)PRGN
--, so that the
-(TT
--Section
-)TT
--\nand/or
-(TT
--Priority
-)TT
-- is copied into the actual control information in\nthe
-(TT
--.deb
-)TT
-- file. However, if you do this you should make sure you\nkeep the information up to date so that users are not shown\nconflicting information.\n\n
-L332
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Formatting of the
-(TT
--Description
-)TT
-- control file field
-L333
-)HEADING
-(P
-L334
--\nEvery Debian package should have an extended description.
-L336
-)P
-(P
-L337
--\nThe description should be written so that it tells the user what they\nneed to know to decide whether to install the package. This\ndescription should not just be copied from the blurb for the program.\nInstructions for configuring or using the package should not be\nincluded - that is what installation scripts, manpages, Info files and\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
-)TT
-- are for. Copyright statements and other\nadministrivia should not be included - that is what\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
-- is for.
-L346
-)P
-(P
-L347
--\nIf you wish to include a list in your extended with entries which are\na line or more each you must indent each entry by one space to make\nsure that it doesn't get wordwrapped. The start of each list entry\nshould be marked with an asterisk, followed by a single space. You\nmust wrap the list entries yourself to 75 columns, and should start\ncontinuation lines indented by three spaces so that they line up with\nthe start of the text on the first line of each list entry.
-L355
-)P
-(P
-L356
--\nSee the programmers' manual for further requirements and pitfalls.\n
-L359
-)P
-)SECT1
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Locations of files
-L360
-)HEADING
-(P
-L361
--\nThe location of all installed files and directories must comply fully\nwith the Linux File System Standard (FSSTND). The latest version of\nthis document can be found alongside this manual or on\n
-(FTPSITE
--tsx-11.mit.edu
-)FTPSITE
-- in\n
-(FTPPATH
--/pub/linux/docs/linux-standards/fsstnd/
-)FTPPATH
--. Specific questions\nabout following the standard may be asked on
-(PRGN
--debian-devel
-)PRGN
--, or\nreferred to Daniel Quinlan, the FSSTND coordinator, at\n
-(EMAIL
--quinlan@yggdrasil.com
-)EMAIL
--.
-L370
-)P
-(P
-L372
-)P
-AID IMPLIED
-(SECT1
-(HEADING
--Manpages
-L373
-)HEADING
-(P
-L374
--\nYou must install manpages in
-(PRGN
--nroff
-)PRGN
-- source form, in appropriate\nplaces under
-(TT
--/usr/man
-)TT
--. You should only use sections 1 to 9\n(see the FSSTND for more details). You must
-(EM
--not
-)EM
-- install a\npreformatted `cat page'.
-L379
-)P
-(P
-L380
--\nIf no manual page is available for a particular program, utility or\nfunction and this is reported as a bug on debian-bugs, a symbolic link\nfrom the requested manual page to the
-ANAME CDATA undocumented
-ASECTION CDATA 7
-(MANREF
-)MANREF
-L384
-- manual page should be provided. This symbolic link can be\ncreated from
-(TT
--debian/rules
-)TT
-- like this:\n
-(EXAMPLE
-L387
--ln -s ../man7/undocumented.7 \\\n debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9]
-L389
-)EXAMPLE
--\nThis manpage claims that the lack of a manpage has been reported as a\nbug, so you may only do this if it really has (you can report it\nyourself, if you like). Do not close the bug report until a proper\nmanpage is available.
-L394
-)P
-(P
-L395
--\nYou may forward a complaint about a missing manpage to the upstream\nauthors, and mark the bug as forwarded in the Debian bug tracking\nsystem. Even though the GNU Project do not in general consider the\nlack of a manpage to be a bug, we do - if they tell you that they\ndon't consider it a bug you should leave the bug in our bug tracking\nsystem open anyway.
-L402
-)P
-(P
-L403
--\nManpages should be installed compressed using
-(TT
--gzip -9
-)TT
--.
-L405
-)P
-(P
-L406
--\nIf one manpage needs to be accesssible via several names it is better\nto use a symbolic link than the
-(TT
--.so
-)TT
-- feature, but there is no need\nto fiddle with the relevant parts of the upstream source to change\nfrom
-(TT
--.so
-)TT
-- to symlinks - don't do it unless it's easy. Do not\ncreate hard links in the manual page directories, and do not put\nabsolute filenames in
-(TT
--.so
-)TT
-- directives. The filename in a\n
-(TT
--.so
-)TT
-- in a manpage should be relative to the base of the manpage\ntree (usually
-(TT
--/usr/man
-)TT
--).\n
-L416
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Info documents
-L417
-)HEADING
-(P
-L418
--\nInfo documents should be installed in
-(TT
--/usr/info
-)TT
--. They should\nbe compressed with
-(TT
--gzip -9
-)TT
--.
-L421
-)P
-(P
-L422
--\nYour package must call
-(PRGN
--install-info
-)PRGN
-- to update the Info
-(TT
--dir
-)TT
--\nfile, in its post-installation script:\n
-(EXAMPLE
-L426
--install-info --quiet --section Development Development \\\n /usr/info/foobar.info
-L428
-)EXAMPLE
-L429
-)P
-(P
-L430
--\nIt is a good idea to specify a section for the location of your\nprogram; this is done with the
-(TT
----section
-)TT
-- switch. To determine\nwhich section to use, you should use look at
-(TT
--/usr/info/dir
-)TT
-- on\nyour system and choose the most relevant (or create a new section if\nnone of the current sections are relevant). Note that the\n
-(TT
----section
-)TT
-- flag takes two arguments; the first is a regular\nexpression to match (case-insensitively) against an existing section,\nthe second is used when creating a new one.
-L439
-)P
-(P
-L440
--\nYou must remove the entries in the pre-removal script:\n
-(EXAMPLE
-L443
--install-info --quiet --remove /usr/info/foobar.info
-L444
-)EXAMPLE
-L445
-)P
-(P
-L446
--\nIf
-(PRGN
--install-info
-)PRGN
-- cannot find a description entry in the Info file\nyou will have to supply one. See
-ANAME CDATA install-info
-ASECTION CDATA 8
-(MANREF
-)MANREF
--\nfor details.\n
-L451
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Additional documentation
-L452
-)HEADING
-(P
-L453
--\nAny additional documentation that comes with the package can be\ninstalled at the discretion of the package maintainer. Text\ndocumentation should be installed in a directory\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
-)TT
-(FOOTNOTE
-(P
--Where
-(VAR
--package
-)VAR
-- is the\nname of the package.
-)P
-)FOOTNOTE
-- and compressed with
-(TT
--gzip -9
-)TT
--\nunless it is small.
-L460
-)P
-(P
-L461
--\nIf a package comes with large amounts of documentation which many\nusers of the package will not require you should create a separate\nbinary package to contain it, so that it does not take up disk space\non the machines of users who do not need or want it installed.
-L466
-)P
-(P
-L467
--\nIt is often a good idea to put text information files (
-(TT
--README
-)TT
--s,\nchangelogs, and so forth) that come with the source package in\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
-)TT
-- in the binary package. However, don't\ninstall the instructions for building and installing the package, of\ncourse!\n
-L474
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Preferred documentation formats
-L475
-)HEADING
-(P
-L476
--\nThe unification of Debian documentation is being carried out via HTML.
-L478
-)P
-(P
-L479
--\nIf your package comes with extensive documentation in a markup format\nthat can be converted to various other formats you should if possible\nship HTML versions in the binary package, in the directory\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
-)TT
-- or its subdirectories.
-L484
-)P
-(P
-L485
--\nOther formats such as PostScript may be provided at your option.\n
-L488
-)P
-AID IMPLIED
-(SECT2
-(HEADING
--Examples
-L489
-)HEADING
-(P
-L490
--\nAny examples (configurations, source files, whatever), should be\ninstalled in a directory
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/examples
-)TT
--.\nThese files should not be referenced by any program - they're there\nfor the benefit of the system administrator and users, as\ndocumentation only.\n
-L497
-)P
-)SECT2
-)SECT1
-AID CDATA instchangelog
-(SECT1
-(HEADING
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/changelog.Debian.gz
-)TT
-L498
-)HEADING
-(P
-L499
--\nThis installed file must contain a copy of the
-(TT
--debian/changelog
-)TT
--\nfile from your Debian source tree.
-L502
-)P
-(P
-L503
--\nIt should be installed compressed using
-(TT
--gzip -9
-)TT
--, as it will\nbecome large with time even if it starts out small.
-L506
-)P
-(P
-L507
--\nIf the package has only one changelog which is used both as the Debian\nchangelog and the upstream one because there is no separate upstream\nmaintainer then the changelog should usually be installed as\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/changelog.gz
-)TT
-- instead.\n
-L513
-)P
-)SECT1
-AID CDATA copyrightfile
-(SECT1
-(HEADING
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
-L514
-)HEADING
-(P
-L515
--\nThis file must contain details of the authorship and copyright of the\npackage. It must say where the upstream sources (if any) were\nobtained, and explain briefly what modifications were made in the\nDebian version of the package compared to the upstream one. It must\nname the original authors of the package and the Debian maintainer(s)\nwho were involved with its creation.
-L522
-)P
-(P
-L523
--\nIt must contain the full text of the copyright notice and any\nacknowledgements for the program and the licence terms under which the\nprogram is distributed. If the package is distributed under the GNU\nGeneral Public Licence, the GNU Library General Public Licence, the\nRegents of the University of California at Berkeley (BSD) licence or\nLarry Wall's Artistic Licence please say so instead of including a\ncopy of the licence. The files
-(TT
--BSD
-)TT
--,
-(TT
--GPL
-)TT
--,
-(TT
--LGPL
-)TT
-- and\n
-(TT
--Artistic
-)TT
-- are be available in
-(TT
--/usr/doc/copyright
-)TT
-- for you\nto refer to.
-L533
-)P
-(P
-L534
--\nThe copyright file should not be compressed unless it is very large.
-L536
-)P
-(P
-L537
--\nDo not use the copyright file as a general
-(TT
--README
-)TT
-- file. If your\npackage has such a file it should be installed in\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/README
-)TT
-- or
-(TT
--README.Debian
-)TT
-- or some\nother appropriate place.\n
-L543
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Symbolic links
-L544
-)HEADING
-(P
-L545
--\nMost symbolic links should be relative, not absolute. Absolute links,\nin general, cause problems when a file system is not mounted where it\n"normally" resides (for example, when mounted via NFS).
-L549
-)P
-(P
-L550
--\nIn particular, symlinks from one part of
-(TT
--/usr
-)TT
-- to another\nshould be relative.
-L553
-)P
-(P
-L554
--\nIn certain cases, however, relative links may cause more problems.\nFor example, links into
-(TT
--/etc
-)TT
-- and
-(TT
--/var
-)TT
-- should be\nabsolute.
-L558
-)P
-(P
-L559
--\nNote that when creating a relative link using
-(PRGN
--ln
-)PRGN
-- it is not\nnecessary for the target of the link to exist relative to the working\ndirectory you're running
-(PRGN
--ln
-)PRGN
-- from; nor is it necessary to change\ndirectory to the directory where the link is to be made. Simply\ninclude the string that should appear as the target of the link (this\nwill be a pathname relative to the directory in which the link\nresides) as the first argument to
-(PRGN
--ln
-)PRGN
--.
-L567
-)P
-(P
-L568
--\nFor example, in your
-(PRGN
--Makefile
-)PRGN
-- or
-(TT
--debian/rules
-)TT
--, do things\nlike:\n
-(EXAMPLE
-L572
--ln -fs gcc $(prefix)/bin/cc\nln -fs gcc debian/tmp/usr/bin/cc\nln -fs ../sbin/sendmail $(prefix)/bin/runq\nln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
-L576
-)EXAMPLE
--\n
-L578
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Logfiles
-L579
-)HEADING
-(P
-L580
--\nLogfiles should usually be named\n
-(TT
--/var/log/
-(VAR
--package
-)VAR
--.log
-)TT
--. If you have many logfiles,\nor need a separate directory for permissions reasons\n(
-(TT
--/var/log
-)TT
-- is writeable only by
-(TT
--root
-)TT
--), you should usually\ncreate a directory named
-(TT
--/var/log/
-(VAR
--package
-)VAR
-)TT
--.
-L586
-)P
-(P
-L587
--\nMake sure that any logfiles are rotated occasionally using so that\nthey don't grow indefinitely; the best way to do this is to use\n
-(PRGN
--savelog
-)PRGN
-- program in an
-(TT
--/etc/cron.daily
-)TT
--,\n
-(TT
--/etc/cron.weekly
-)TT
-- or
-(TT
--/etc/cron.monthly
-)TT
-- script.
-L592
-)P
-(P
-L593
--\nMake sure that any logfiles are removed when the package is purged\n(but not when it is only removed), by checking the argument to the\npostrm script (see the programmer's manual for details).\n
-L598
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(TT
--/usr/local
-)TT
-- - for the use of the system administrator
-L599
-)HEADING
-(P
-L600
--\nAs mandated by the FSSTND no package should place any files in\n
-(TT
--/usr/local
-)TT
--, either by putting them in the filesystem archive to\nbe unpacked by
-(PRGN
--dpkg
-)PRGN
-- or by manipulating them in their maintainer\nscripts.
-L605
-)P
-(P
-L606
--\nEvery package that searches a number of directories or files for\nsomething (for example, looking for shared libraries in
-(TT
--/lib
-)TT
-- or\n
-(TT
--/usr/lib
-)TT
--) should search an appropriate directory in\n
-(TT
--/usr/local
-)TT
-- too.
-L611
-)P
-(P
-L612
--\nIn order that the system administrator may know where to place\nadditional files a package should create an empty directory in the\nappropriate place in
-(TT
--/usr/local
-)TT
-- by supplying it in the\nfilesystem archive for unpacking by
-(PRGN
--dpkg
-)PRGN
--. The\n
-(TT
--/usr/local
-)TT
-- directory itself and all the subdirectories created\nby the package should have permissions 2775 (group-writeable and\nset-group-id) and be owned by
-(TT
--root.staff
-)TT
--.
-L620
-)P
-(P
-L621
--\nIn the future it will be possible to tell
-(PRGN
--dpkg
-)PRGN
-- not to unpack\nfiles matching certain patterns, so that system administrators who do\nnot wish these directories in
-(TT
--/usr/local
-)TT
-- do not need to have\nthem.\n
-L627
-)P
-)SECT1
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Permissions and ownerships
-L628
-)HEADING
-(P
-L629
--\nThe rules in this section are guidelines for general use. If\nnecessary you may deviate from the details below. However, if you do\nso you must make sure that what is done is secure and you must try to\nbe as consistent as possible with the rest of the system. You should\nprobably also discuss it on
-(PRGN
--debian-devel
-)PRGN
-- first.
-L635
-)P
-(P
-L636
--\nFiles should be owned by
-(TT
--root.root
-)TT
--, and made writeable only by\nthe owner and universally readable (and executable, if appropriate).
-L639
-)P
-(P
-L640
--\nDirectories should be mode 755 or (for group-writability) mode 2775.\nThe ownership of the directory should be consistent with its mode -\nif a directory is mode 2775, it should be owned by the group that\nneeds write access to it.
-L645
-)P
-(P
-L646
--\nSetuid and setgid executables should be mode 4755 or 2755\nrespectively, and owned by the appropriate user or group. They should\nnot be made unreadable (modes like 4711 or 2711 or even 4111); doing\nso achieves no extra security, because anyone can find the binary in\nthe freely available Debian package - it is merely inconvenient. For\nthe same reason you should not restrict read or execute permissions on\nnon-set-id executables.
-L654
-)P
-(P
-L655
--\nSome setuid programs need to be restricted to particular sets of\nusers, using file permissions. In this case they should be owned by\nthe uid to which they are set-id, and by the group which should be\nallowed to execute them. They should have mode 4754; there is no\npoint in making them unreadable to those users who must not be allowed\nto execute them.
-L662
-)P
-(P
-L663
--\nDo not arrange that the system administrator can only reconfigure the\npackage to correspond to their local security policy by changing the\npermissions on a binary. Ordinary files installed by
-(PRGN
--dpkg
-)PRGN
-- (as\nopposed to conffiles and other similar objects) have their permissions\nreset to the distributed permissions when the package is reinstalled.\nInstead you should consider (for example) creating a group for people\nallowed to use the program(s) and making any setuid executables\nexecutable only by that group.
-L672
-)P
-(P
-L673
--\nShared libraries should be installed executable.\n
-L676
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Configuration files
-L677
-)HEADING
-(P
-L678
--\nAny configuration files created or used by your package should reside\nin
-(TT
--/etc
-)TT
--. If there are several you should consider creating a\nsubdirectory named after your package.
-L682
-)P
-(P
-L683
--\nIt is almost certain that any file in
-(TT
--/etc
-)TT
-- that is in your\npackage's filesystem archive should be listed in
-(PRGN
--dpkg
-)PRGN
--'s\n
-(TT
--conffiles
-)TT
-- control area file. (See the
-(PRGN
--dpkg
-)PRGN
-- programmers'\nmanual).\n
-L689
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Maintainer scripts
-L690
-)HEADING
-(P
-L691
--\nThe package installation scripts should avoid producing output which\nit is unnecessary for the user to see and should rely on
-(PRGN
--dpkg
-)PRGN
-- to\nstave off boredom on the part of a user installing many packages.\nThis means, amongst other things, using the
-(TT
----quiet
-)TT
-- option on\n
-(PRGN
--install-info
-)PRGN
--.
-L697
-)P
-(P
-L698
--\nPackages should try to minimise the amount of prompting they need to\ndo, and they should ensure that the user will only every be asked each\nquestion once. This means that packages should try to use appropriate\nshared configuration files (such as
-(TT
--/etc/papersize
-)TT
-- and\n
-(TT
--/etc/news/server
-)TT
--, rather than each prompting for their own\nlist of required pieces of information.
-L705
-)P
-(P
-L706
--\nIt also means that an upgrade should not ask the same questions again,\nunless the user has used
-(TT
--dpkg --purge
-)TT
-- to remove the package's\nconfiguration. The answers to configuration questions should be\nstored in an appropriate place in
-(TT
--/etc
-)TT
-- so that the user can\nmodify them, and how this has been done should be documented.
-L712
-)P
-(P
-L713
--\nIf a package has a vitally important piece of information to pass to\nthe user (such as "don't run me as I am, you must edit the following\nconfiguration files first or you risk your system emitting\nbadly-formatted messages"), it should display this in the\n
-(PRGN
--postinst
-)PRGN
-- script and prompt the user to hit return to\nacknowledge the message. Copyright messages do not count as vitally\nimportant (they belong in
-(TT
--/usr/doc/copyright
-)TT
--); neither do\ninstructions on how to use a program (these should be in on line\ndocumentation, where all the users can see them).
-L723
-)P
-(P
-L724
--\nAny necessary prompting should almost always be confined to the\npost-installation script, and should be protected with a conditional\nso that unnecssary prompting doesn't happen if a package's\ninstallation fails and the
-(PRGN
--postinst
-)PRGN
-- is called with\n
-(TT
--abort-upgrade
-)TT
--,
-(TT
--abort-remove
-)TT
-- or
-(TT
--abort-deconfigure
-)TT
--.
-L730
-)P
-(P
-L731
--\nErrors which occur during the execution of an installation script\n
-(EM
--must
-)EM
-- be checked and the installation
-(EM
--must not
-)EM
-- continue after\nan error.
-L735
-)P
-(P
-L736
--\nThe section below on scripts in general applies to package maintainer\nscripts too.\n
-L740
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Scripts in general
-L741
-)HEADING
-(P
-L742
--\nAll command scripts, including the package maintainer scripts inside\nthe package and used by
-(PRGN
--dpkg
-)PRGN
--, should have a
-(TT
--#!
-)TT
-- line naming\nthe shell to be used to interpret them.
-L746
-)P
-(P
-L747
--\nIn the case of Perl scripts this should be
-(TT
--#!/usr/bin/perl
-)TT
--.
-L749
-)P
-(P
-L750
--\nShell scripts (
-(PRGN
--sh
-)PRGN
-- and
-(PRGN
--bash
-)PRGN
--) should almost certainly\nstart with
-(TT
--set -e
-)TT
-- so that errors are detected. Every script\n
-(EM
--must
-)EM
-- use
-(TT
--set -e
-)TT
-- or check the exit status of
-(EM
--every
-)EM
--\ncommand.
-L755
-)P
-(P
-L756
--\nPerl scripts should check for errors when making any system calls,\nincluding
-(TT
--open
-)TT
--,
-(TT
--print
-)TT
--,
-(TT
--close
-)TT
--,
-(TT
--rename
-)TT
-- and\n
-(TT
--system
-)TT
--.
-L760
-)P
-(P
-L761
--\n
-(PRGN
--csh
-)PRGN
-- and
-(PRGN
--tcsh
-)PRGN
-- should be avoided as scripting languages. See\nCsh Programming Considered Harmful, one of the
-(TT
--comp.unix.*
-)TT
-- FAQs.\nIf an upstream package comes with
-(PRGN
--csh
-)PRGN
-- scripts then you must make\nsure that they start with
-(TT
--#!/bin/csh
-)TT
-- and make your package\ndepend on
-(PRGN
--csh
-)PRGN
--.
-L767
-)P
-(P
-L769
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Compilation options
-L770
-)HEADING
-(P
-L771
--\nGenerally the following compilation parameters should be used:\n
-(EXAMPLE
-L774
--CC = gcc\nCFLAGS = -O2 -g -Wall # sane warning options vary between programs\nLDFLAGS = # none\ninstall -s # (or use strip on the files in debian/tmp)
-L778
-)EXAMPLE
-L779
-)P
-(P
-L780
--\nNote that all installed binaries should be stripped, either by using\nthe
-(TT
---s
-)TT
-- flag to
-(PRGN
--install
-)PRGN
--, or by calling
-(PRGN
--strip
-)PRGN
-- on the\nbinaries after they have been copied into
-(TT
--debian/tmp
-)TT
-- but\nbefore the tree is made into a package.
-L785
-)P
-(P
-L786
--\nMake sure that you do not link with
-(TT
---g
-)TT
--, as this makes a.out\ncompilers produce huge statically linked binaries. The
-(TT
---g
-)TT
-- flag\nis useful on compilation so that you have available a full set of\ndebugging symbols in your built source tree, in case anyone should\nfile a bug report involving (for example) a core dump.
-L792
-)P
-(P
-L793
--\nThe
-(TT
---N
-)TT
-- flag should not be used. On a.out systems it may have\nbeen useful for some very small binaries, but for ELF it has no good\neffect.
-L797
-)P
-(P
-L798
--\nIt is up to the package maintainer to decide what compilation options\nare best for the package. Certain binaries (such as\ncomputationally-intensive programs) may function better with certain\nflags (
-(TT
---O3
-)TT
--, for example); feel free to use them. Please use good\njudgment here. Don't use flags for the sake of it; only use them if\nthere is good reason to do so. Feel free to override the upstream\nauthor's ideas about which compilation options are best - they are\noften inappropriate for our environment.
-L807
-)P
-(P
-L808
--\nPlease make sure that you use only released versions of shared\nlibraries to build your packages; otherwise other users will not be\nable to run your binaries properly. Producing source packages that\ndepend on unreleased compilers is also usually a bad idea.\n
-L814
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Shared library packages
-L815
-)HEADING
-(P
-L816
--\nPackages involving shared libraries should be split up into several\nbinary packages.
-L819
-)P
-(P
-L820
--\nFor a straightforward library which has a development environment and\na runtime kit including just shared libraries you need to create two\npackages:
-(TT
-(VAR
--libraryname
-)VAR
-(VAR
--soname
-)VAR
-)TT
-(FOOTNOTE
-(P
-(VAR
--soname
-)VAR
-- is\nthe shared object name of the shared library - it's the thing that has\nto match exactly between building an executable and running it for the\ndynamic linker to be able run the program. Usually the
-(VAR
--soname
-)VAR
--\nis the major number of the library.
-)P
-)FOOTNOTE
-- and\n
-(TT
-(VAR
--libraryname
-)VAR
-(VAR
--soname
-)VAR
---dev
-)TT
--.
-L829
-)P
-(P
-L830
--\nIf you prefer only to support one development version time you may\nname the development package
-(TT
-(VAR
--libraryname
-)VAR
---dev
-)TT
--; otherwise you\nmay wish to use
-(PRGN
--dpkg
-)PRGN
--'s conflicts mechanism to ensure that the\nuser only installs one development version at a time (after all,\ndifferent development versions are likely to have the same header\nfiles in them, causing a filename clash if both are installed).\nTypically the development version will also need an exact version\ndependency on the runtime library, to make sure that compilation and\nlinking happens correctly.
-L840
-)P
-(P
-L841
--\nPackages which use the shared library should have a dependency on the\nname of the shared library package,\n
-(TT
-(VAR
--libraryname
-)VAR
-(VAR
--soname
-)VAR
-)TT
--. When the
-(VAR
--soname
-)VAR
-- changes you\ncan have both versions of the library installed while moving from the\nold library to the new.
-L847
-)P
-(P
-L848
--\nIf your package has some run-time support programs which use the\nshared library you must
-(EM
--not
-)EM
-- put them in the shared library\npackage. If you do that then you won't be able to install several\nversions of the shared library without getting filename clashes.\nInstead, either create a third package for the runtime binaries (this\npackage might typically be named
-(TT
-(VAR
--libraryname
-)VAR
---runtime
-)TT
-- - note\nthe absence of the
-(VAR
--soname
-)VAR
-- in the package name) or if the\ndevelopment package is small include them in there.
-L857
-)P
-(P
-L858
--\nIf you have several shared libraries built from the same source tree\nyou can lump them all togther into a single shared library package,\nprovided that you change all their
-(VAR
--soname
-)VAR
--s at once (so that you\ndon't get filename clashes if you try to install different versions of\nthe combined shared libraries package).
-L864
-)P
-(P
-L865
--\nFollow the directions in the
-(PRGN
--dpkg
-)PRGN
-- programmers' manual for\nputting the shared library in its package, and make sure you include a\n
-(TT
--shlibs
-)TT
-- control area file with details of the dependencies for\npackages which use the library.\n
-L871
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Application configuration files, dotfiles and
-(TT
--/etc/skel
-)TT
-L872
-)HEADING
-(P
-L873
--\nFiles in
-(TT
--/etc/skel
-)TT
-- will automatically be copied into new user\naccounts by
-(PRGN
--adduser
-)PRGN
--. They should not be referenced there by\nany program.
-L877
-)P
-(P
-L878
--\nTherefore, if a program needs a dotfile to exist in advance in\n
-(TT
--$HOME
-)TT
-- to work sensibly that dotfile should be installed in\n
-(TT
--/etc/skel
-)TT
-- (and listed in conffiles, if it is not generated and\nmodified dynamically by the package's installation scripts).
-L883
-)P
-(P
-L884
--\nHowever, programs that require dotfiles in order to operate sensibly\n(dotfiles that they do not create themselves automatically, that is)\nare a bad thing, and programs should be configured by the Debian\ndefault installation as close to normal as possible.
-L889
-)P
-(P
-L890
--\nTherefore, if a program in a Debian package needs to be configured in\nsome way in order to operate sensibly that configuration should be\ndone in a site-wide global configuration file elsewhere in\n
-(TT
--/etc
-)TT
--. Only if the program doesn't support a site-wide default\nconfiguration and the package maintainer doesn't have time to add it\nshould a default per-user file be placed in
-(TT
--/etc/skel
-)TT
--.
-L897
-)P
-(P
-L898
--\n
-(TT
--/etc/skel
-)TT
-- should be as empty as we can make it. This is\nparticularly true because there is no easy mechanism for ensuring that\nthe appropriate dotfiles are copied into the accounts of existing\nusers when a package is installed.
-L903
-)P
-(P
-L904
--\nIdeally the sysadmin should ideally not have to do any configuration\nother than that done (semi-)automatically by the postinst script.\n
-L908
-)P
-)SECT
-AID CDATA mail
-(SECT
-(HEADING
--Mail processing on Debian systems
-L909
-)HEADING
-(P
-L910
--\nDebian packages which process electronic mail, whether\nmail-user-agents (MUAs) or mail-transport-agents (MTAs),
-(EM
--must
-)EM
--\nmake sure that they are compatible with the configuration decisions\nbelow. Failure to do this may result in lost mail, broken
-(TT
--From:
-)TT
--\nlines, and other serious brain damage!
-L916
-)P
-(P
-L917
--\nThe mail spool is
-(TT
--/var/spool/mail
-)TT
-- and the interface to send a\nmail message is
-(TT
--/usr/sbin/sendmail
-)TT
-- (as per the FSSTND). The\nmail spool is part of the base system and not part of the MTA package.
-L921
-)P
-(P
-L922
--\nMailboxes are locked using the
-(TT
-(VAR
--username
-)VAR
--.lock
-)TT
-- lockfile\nconvention, rather than
-(PRGN
--fcntl
-)PRGN
--,
-(PRGN
--flock
-)PRGN
-- or
-(PRGN
--lockf
-)PRGN
--.
-L925
-)P
-(P
-L926
--\nMailboxes are generally 660
-(TT
-(VAR
--user
-)VAR
--.mail
-)TT
-- unless the user has\nchosen otherwise. A MUA may remove a mailbox (unless it has\nnonstandard permissions) in which case the MTA or another MUA must\nrecreate it if needed. Mailboxes must be writeable by group mail.
-L931
-)P
-(P
-L932
--\nThe mail spool is 2775
-(TT
--mail.mail
-)TT
--, and MUA's need to be setgid\nmail to do the locking mentioned above (and obviously need to avoid\naccessing other users' mailboxes using this privilege).
-L936
-)P
-(P
-L937
--\n
-(TT
--/etc/aliases
-)TT
-- is the source file for the system mail aliases\n(e.g. postmaster, usenet, etc.) - it is the one which the sysadmin\nand postinst scripts may edit. After
-(TT
--/etc/aliases
-)TT
-- is edited\nthe program or human editing it must call
-(PRGN
--newaliases
-)PRGN
--. All MTA\npackages should come with a
-(PRGN
--newaliases
-)PRGN
-- program, even if it does\nnothing, but older MTA packages do not do this so programs should not\nfail if
-(PRGN
--newaliases
-)PRGN
-- cannot be found.
-L945
-)P
-(P
-L946
--\nThe convention of writing
-(TT
--forward to
-(VAR
--address
-)VAR
-)TT
-- in the mailbox\nitself is not supported. Use a
-(TT
--.forward
-)TT
-- file instead.
-L949
-)P
-(P
-L950
--\nThe location for the
-(PRGN
--rmail
-)PRGN
-- program used by UUCP for incoming\nmail is
-(TT
--/usr/sbin/rmail
-)TT
--, as per the FSSTND. Likewise,\n
-(PRGN
--rsmtp
-)PRGN
--, for receiving batch-SMTP-over-UUCP, is in\n
-(TT
--/usr/sbin/rsmtp
-)TT
-- if it is supported.
-L955
-)P
-(P
-L956
--\nIf you need to know what name to use (for example) on outgoing news\nand mail messages which are generated locally, you should use the file\n
-(TT
--/etc/mailname
-)TT
--. It will contain the portion after the username\nand
-(TT
--@
-)TT
-- (at) sign for email addresses of users on the machine\n(followed by a newline).
-L962
-)P
-(P
-L963
--\nA package should check for the existence of this file. If it exists\nit should use it without comment.
-(FOOTNOTE
-(P
--An MTA's prompting\nconfiguration script may wish to prompt the user even if it finds this\nfile exists.
-)P
-)FOOTNOTE
-- If it does not exist it should prompt the user\nfor the value and store it in
-(TT
--/etc/mailname
-)TT
-- as well as using it\nin the package's configuration. The prompt should make it clear that\nthe name will not just be used by that package. E.g., in this\nsituation the INN package says:\n
-(EXAMPLE
-L973
--Please enter the `mail name' of your system. This is the hostname\nportion of the address to be shown on outgoing news and mail messages.\nThe default is
-(VAR
--syshostname
-)VAR
--, your system's host name.\nMail name [`
-(VAR
--syshostname
-)VAR
--']:
-L977
-)EXAMPLE
--\nwhere
-(VAR
--syshostname
-)VAR
-- is the output of
-(TT
--hostname -fqdn
-)TT
--.\n\n
-L981
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Packages which can use the X shared libraries
-L982
-)HEADING
-(P
-L983
--\nSome programs can be configured with or without support for X Windows.\nTypically these binaries produced when configured for X will need the\nX shared libraries to run.
-L987
-)P
-(P
-L988
--\nSuch programs should be configured
-(EM
--with
-)EM
-- X support, and should\ndeclare a dependency on
-(TT
--elf-x11r6lib
-)TT
-- (for the X11R6 libraries).\nUsers who wish to use the program can install just the relatively\nsmall
-(TT
--xlib
-)TT
-- package, and do not need to install the whole of X.
-L993
-)P
-(P
-L994
--\nDo not create two versions (one with X support and one without) of\nyour package.\n\n
-L999
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Games
-L1000
-)HEADING
-(P
-L1001
--\nThe permissions on /var/lib/games are 755
-(TT
--root.root
-)TT
--.
-L1003
-)P
-(P
-L1004
--\nEach game decides on its own security policy.
-L1006
-)P
-(P
-L1007
--\nGames which require protected, privileged access to high-score files,\nsavegames, \|&\|c, must be made set-
-(EM
--group
-)EM
---id (mode 2755) and\nowned by
-(TT
--root.games
-)TT
--, and use files and directories with\nappropriate permissions (770
-(TT
--root.games
-)TT
--, for example). They must\n
-(EM
--not
-)EM
-- be made set-
-(EM
--user
-)EM
---id, as this causes security\nproblems.
-(FOOTNOTE
-(P
--If an attacker can subvert any set-user-id game\nthey can overwrite the executable of any other, causing other players\nof these cames to run a trojan. With a set-group-id game the attacker\nonly gets access to less important game data, and if they can get at\nthe other players' accounts at all it will take considerably more\neffort.
-)P
-)FOOTNOTE
-L1019
-)P
-(P
-L1020
--\nSome packages, for example some fortune cookie programs, are\nconfigured by the upstream authors to install with their data files or\nother static information made unreadable so that they can only be\naccessed through set-id programs provided. Do not do this in a Debian\npackage: anyone can download the
-(TT
--.deb
-)TT
-- file and read the data from\nit, so there is no point making the files unreadable. Not making the\nfiles unreadable also means that you don't have to make so many\nprograms set-id, which reduces the risk of a security hole.\n
-L1030
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Allocating package-specific users and groups
-L1031
-)HEADING
-(P
-L1032
--\nIf you need to create a new user or group for your package there are\ntwo possibilities. Firstly, you may need to make some files in the\nbinary package be owned by this user or group, or you may need to\ncompile the user or group id (rather than just the name) into the\nbinary (though this latter should be avoided if possible). In this\ncase you need a statically allocated id.
-L1039
-)P
-(P
-L1040
--\nYou must ask for a user or group id from the base system maintainer,\nand must not release the package until you have been allocated one.\nOnce you have been allocated one you must make the package depend\non a version of the base system with the id present in\n
-(TT
--/etc/passwd
-)TT
-- or
-(TT
--/etc/group
-)TT
--, or alternatively arrange\nfor your package to create the user or group itself with the correct\nid (using
-(TT
--adduser
-)TT
--) in its pre- or post-installation script (the\nlatter is to be preferred if it is possible).
-L1049
-)P
-(P
-L1050
--\nOn the other hand, the program may able to determine the uid or gid\nfrom the group name at runtime, so that a dynamic id can be used. In\nthis case you must choose an appropriate user or group name,\ndiscussing this on
-(PRGN
--debian-devel
-)PRGN
-- and checking with the base system\nmaintainer that it is unique and that they do not wish you to use a\nstatically allocated id instead. When this has been checked you must\narrange for your package to create the user or group if necessary\nusing
-(PRGN
--adduser
-)PRGN
-- in the pre- or post-installation script (again, the\nlatter is to be preferred if it is possible).
-L1060
-)P
-(P
-L1061
--\nNote that changing the numeric value of an id associated with a name\nis very difficult, and involves searching the filesystem for all\nappropriate files. You need to think carefully whether a static or\ndynamic id is required, since changing your mind later will cause\nproblems.\n
-L1068
-)P
-)SECT
-)CHAPT
-AID CDATA sourcepkg
-(CHAPT
-(HEADING
--Source package\n
-L1070
-)HEADING
-AID IMPLIED
-(SECT
-(HEADING
--Releases of packages by other than the usual Debian maintainer
-L1071
-)HEADING
-(P
-L1072
--\nUnder certain circumstances it is necessary for someone other than the\nusual package maintainer to make a release of a package. For example,\na porter for another architecture may have to make some small changes\nto the source package and does not wish to wait with uploading their\nrelease until the main maintainer has incorporated the patch, or a\nserious security problem may have come to light requiring immediate\nattention.
-L1080
-)P
-(P
-L1081
--\nMaintainers other than the usual package maintainer should make as few\nchanges to the package as possible, and they should always send a\nunified context diff (
-(TT
--diff -u
-)TT
--) detailing their changes to the bug\ntracking system properly flagged with the correct package so that the\nusual maintainer is kept aware of the situation.
-L1087
-)P
-(P
-L1088
--\nWhen someone other than the usual maintainer releases a package they\nshould add a new component to the
-(VAR
--debian-revision
-)VAR
-- component of\nthe version number - that is, the portion after the (last) hyphen.\nThis extra component will start at
-(TT
--1
-)TT
--. This is to avoid\n`stealing' one of the usual maintainer's version numbers, possibly\ndisrupting their work. If there is no
-(VAR
--debian-revision
-)VAR
-- component\nin the version number then one should be created, starting at
-(TT
--1
-)TT
--.
-L1096
-)P
-(P
-L1097
--\nIf it is absolutely necessary for someone other than the usual\nmaintainer to make a release based on a new upstream version then the\nperson making the release should start with the
-(VAR
--debian-revision
-)VAR
--\nvalue
-(TT
--0.1
-)TT
--. The usual maintainer of a package should start their\n
-(VAR
--debian-revision
-)VAR
-- numbering at
-(TT
--1
-)TT
--.\n\n
-L1105
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Standards conformance and
-(TT
--Standards-Version
-)TT
-L1106
-)HEADING
-(P
-L1107
--\nYou should specify the most recent version of the packaging standards\nwith which your package complies in the source package's\n
-(TT
--Standards-Version
-)TT
-- field.
-L1111
-)P
-(P
-L1112
--\nThis value will be used to file bug reports automatically if your\npackage becomes too much out of date.
-L1115
-)P
-(P
-L1116
--\nThe value corresponds to a version of the Debian manuals, as can be\nfound on the title page or page headers and footers (depending on the\nformat). The value for this version of the manuals and packaging\nstandards is
-(TT
--0.2.0.0
-)TT
--.
-L1121
-)P
-(P
-L1122
--\nThe version number has four components - major and minor number and\nmajor and minor patchlevel. When the standards change in a way that\nrequires every package to change the major number will be changed.\nSignificant changes that will require work in many packages will be\nsignaled by a change to the minor number. The major patchlevel will\nbe changed for any change to the meaning of the standards, however\nsmall; the minor patchlevel will be changed when only cosmetic,\ntypographical or other edits which do not change the meaning are made.
-L1131
-)P
-(P
-L1132
--\nYou should regularly, and especially if your package has become out of\ndate, install the most recent version of dpkg and read\n
-(TT
--/usr/doc/dpkg/changelog-manuals
-)TT
-- to see which changes, if any,\nare relevant. If any are relevant you should look up the relevant\nsection in the policy or programmers' manuals and update your package.\nWhen your package complies with the new standards you may update the\n
-(TT
--Standards-Version
-)TT
-- source package field and release it.\n\n
-L1142
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Documentation and the
-(TT
--changelog
-)TT
-L1143
-)HEADING
-(P
-L1144
--\nDocument your changes and updates to the source package properly in\nthe
-(TT
--debian/changelog
-)TT
-- file.
-L1147
-)P
-(P
-L1148
--\nA copy of the file which will be installed in\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
-- should be in\n
-(TT
--debian/copyright
-)TT
--.
-L1152
-)P
-(P
-L1153
--\nIn non-experimental packages you may only use a format for\n
-(TT
--debian/changelog
-)TT
-- which is supported by the most recent released\nversion of
-(PRGN
--dpkg
-)PRGN
--. If your format is not supported and there is\ngeneral support for it you should contact the
-(PRGN
--dpkg
-)PRGN
-- maintainer\nto have the parser script for your format included in the
-(PRGN
--dpkg
-)PRGN
--\npackage.
-(FOOTNOTE
-(P
--You will need to agree that the parser and its\nmanpage may be distributed under the GNU GPL, just as the rest of\n
-(PRGN
--dpkg
-)PRGN
-- is.
-)P
-)FOOTNOTE
--\n
-L1163
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Changes to the upstream sources
-L1164
-)HEADING
-(P
-L1165
--\nIf you need to edit a
-(PRGN
--Makefile
-)PRGN
-- where GNU-style
-(PRGN
--configure
-)PRGN
--\nscripts are used, you should edit the
-(TT
--.in
-)TT
-- files rather than\nediting the
-(PRGN
--Makefile
-)PRGN
-- directly. This allows the user to\nreconfigure the package if necessary. You should
-(EM
--not
-)EM
-- configure\nthe package and edit the generated
-(PRGN
--Makefile
-)PRGN
--! This makes it\nimpossible for someone else to later reconfigure the package.
-L1172
-)P
-(P
-L1173
--\nIf changes to the source code are made that are generally applicable\nplease try to get them included in the upstream version of the package\nby supplying the upstream authors with the changes in whatever form\nthey prefer.
-L1178
-)P
-(P
-L1179
--\nIf you need to configure the package differently for Debian or for\nLinux, and the upstream source doesn't provide a way to configure it\nthe way you need to, please add such configuration facilities (for\nexample, a new
-(PRGN
--autoconf
-)PRGN
-- test or
-(TT
--#define
-)TT
--) and send the\npatch to the upstream authors, with the default set to the way they\noriginally had it. You can then easily override the default in your\n
-(TT
--debian/rules
-)TT
-- or wherever is appropriate.\n
-L1188
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Error trapping in makefiles
-L1189
-)HEADING
-(P
-L1190
--\nWhen
-(PRGN
--make
-)PRGN
-- invokes a command in a makefile (including your\npackage's upstream makefiles and the
-(TT
--debian/rules
-)TT
--) it does so\nusing
-(TT
--sh
-)TT
--. This means that
-(TT
--sh
-)TT
--'s usual bad error handling\nproperties apply: if you include a miniature script as one of the\ncommands in your makefile you'll find that if you don't do anything\nabout it then errors are not detected and
-(PRGN
--make
-)PRGN
-- will blithely\ncontinue after problems.
-L1198
-)P
-(P
-L1199
--\nEvery time you put more than one shell command (this includes using a\nloop) in a makefile command you
-(EM
--must
-)EM
-- make sure that errors are\ntrapped. For simple compound commands, such as changing directory and\nthen running a program, using
-(TT
--\|&\|\|&\|
-)TT
-- rather than semicolon as\na command separator is sufficient. For more complex commands\nincluding most loops and conditionals you must include a separate\n
-(TT
--set -e
-)TT
-- command at the start of every makefile command that's\nactually one of these miniature shellscripts.\n
-L1209
-)P
-)SECT
-)CHAPT
-AID CDATA developer
-(CHAPT
-(HEADING
--How to become a Debian developer\n
-L1211
-)HEADING
-AID IMPLIED
-(SECT
-(HEADING
--Before you start work
-L1212
-)HEADING
-(P
-L1213
--\nSo, you've read all the documentation, you understand what everything\nin the
-(PRGN
--hello
-)PRGN
-- example package is for, and you're about to\nDebianise your favourite package. How do you actually become a Debian\ndeveloper so that your work can be incorporated into the Project?
-L1218
-)P
-(P
-L1219
--\nFirstly, subscribe to
-(PRGN
--debian-devel
-)PRGN
-- if you haven't already.\nSend the word
-(TT
--subscribe
-)TT
-- in the
-(EM
--Subject
-)EM
-- of a mail to\n
-(EMAIL
--debian-devel-REQUEST@lists.debian.org
-)EMAIL
--. In case of problems\ncontact the list administrator, Anders Chrigstrom
-(EMAIL
--ac@netg.se
-)EMAIL
--.
-L1224
-)P
-(P
-L1225
--\nYou should to subscribe and lurk for a bit before doing any coding,\nand you should post about your intentions to work on something to\navoid duplicated effort.
-L1229
-)P
-(P
-L1230
--\nIf you do not have a PGP key yet generate one. You should probably\nread the PGP manual, as it has much important information which is\ncritical to its security. Many more security failures are due to\nhuman error than to software failure or high-powered spy techniques.
-L1235
-)P
-(P
-L1236
--\nIf you live in a country where use of cryptography even for signing is\nforbidden then please contact us so we can make special arrangements.\nThis does not apply in France, where I believe only encryption and not\nsigning is forbidden.\n
-L1242
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--When you have a package to upload
-L1243
-)HEADING
-(P
-L1244
--\nWhen you have your package ready to be uploaded you must send a\nmessage to the project leader, Bruce Perens
-(EMAIL
--bruce@pixar.com
-)EMAIL
--,\nthe administrator of
-(TT
--master.debian.org
-)TT
--, Simon Shapiro\n
-(EMAIL
--shimon@i-connect.net
-)EMAIL
--, the mailing list administrator, Anders\nChrigstrom
-(EMAIL
--ac@netg.se
-)EMAIL
-- and the
-(PRGN
--dpkg
-)PRGN
-- maintainer, Ian\nJackson
-(EMAIL
--ijackson@gnu.ai.mit.edu
-)EMAIL
--.
-L1251
-)P
-(P
-L1252
--\nThe message should say what you've done and who you are, and should\nask for an account on
-(PRGN
--master
-)PRGN
-- and to be subscribed to\n
-(PRGN
--debian-private
-)PRGN
-- (the developers-only mailing list). It should\ncontain your PGP key (extracted using
-(TT
--pgp -kxa
-)TT
--) for the database\nof keys which is shipped with
-(PRGN
--dpkg
-)PRGN
--.\n\nWhen you have your personal account on
-(PRGN
--master
-)PRGN
-- log in and\ntransfer the files to\n
-(TT
--/home/Debian/ftp/private/project/Incoming
-)TT
--. You cannot upload\nto
-(PRGN
--Incoming
-)PRGN
-- on
-(PRGN
--master
-)PRGN
-- using anonymous FTP.
-L1263
-)P
-(P
-L1264
--\nYou can also upload files to
-(PRGN
--Incoming
-)PRGN
-- via a
-(PRGN
--cron
-)PRGN
---driven\nupload queue in Europe on
-(FTPSITE
--chiark.chu.cam.ac.uk
-)FTPSITE
--. For details\nconnect to
-(PRGN
--chiark
-)PRGN
-- using anonymous FTP and read\n
-(FTPPATH
--/pub/debian/private/project/README.how-to-upload
-)FTPPATH
--.\n
-L1270
-)P
-)SECT
-AID CDATA changesfiles
-(SECT
-(HEADING
--Upload handling -
-(TT
--.changes
-)TT
-- files
-L1271
-)HEADING
-(P
-L1272
--\nWhen a package is uploaded to the Debian FTP archive, it must be\naccompanied by a
-(TT
--.changes
-)TT
-- file which gives directions for its\nhandling. This is usually generated by
-(PRGN
--dpkg-genchanges
-)PRGN
--.
-L1276
-)P
-(P
-L1277
--\nThis file is a control file with the following fields:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1280
-(ITEM
-(P
-(TT
--Format
-)TT
-L1281
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Date
-)TT
-L1282
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Source
-)TT
-L1283
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Binary
-)TT
-L1284
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Architecture
-)TT
-L1285
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Version
-)TT
-L1286
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Distribution
-)TT
-L1287
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Urgency
-)TT
-L1288
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Maintainer
-)TT
-L1289
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Description
-)TT
-L1290
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Changes
-)TT
-L1291
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Files
-)TT
-L1292
-)P
-)ITEM
-)LIST
-L1293
-)P
-(P
-L1294
--\nAll of them are mandatory for a Debian upload. See the list of\ncontrol fields in the
-(PRGN
--dpkg
-)PRGN
-- programmers' manual for the contents\nof these fields.\n\n
-L1300
-)P
-)SECT
-)CHAPT
-AID CDATA mailinglists
-(CHAPT
-(HEADING
--The Debian mailing lists
-L1301
-)HEADING
-(P
-L1302
--\nThe mailing list server is at
-(TT
--lists.debian.org
-)TT
--. Mail\n
-(TT
--debian-
-(VAR
--foo
-)VAR
---REQUEST@lists.debian.org
-)TT
-(FOOTNOTE
-(P
--where\n
-(TT
--debian-
-(VAR
--foo
-)VAR
-)TT
-- is the name of the list
-)P
-)FOOTNOTE
-- with the word\n
-(TT
--subscribe
-)TT
-- in the Subject to subscribe or
-(TT
--unsubscribe
-)TT
-- to\nunsubscribe.
-L1308
-)P
-(P
-L1309
--\nWhen replying to messages on the mailing list, please do not send a\ncarbon copy (
-(TT
--CC
-)TT
-- - this does not mean `courtesy copy') to the\noriginal poster. Anyone who posts to a mailing list should read it to\nsee the responses.
-L1314
-)P
-(P
-L1315
--\nAs ever on the net, please trim down the quoting of articles you're\nreplying to.\n\n
-L1320
-)P
-)CHAPT
-AID CDATA conversion
-(CHAPT
-(HEADING
--Conversion procedure from old source packages
-L1321
-)HEADING
-(P
-L1322
--\nThis is a brief summary of the procedure for converting a\npre-2.0.0.0-format source package into the new format.
-L1325
-)P
-(P
-L1326
--\nYou are strongly advised to download and examine the
-(PRGN
--hello
-)PRGN
--\npackage, and to read the section in the
-(PRGN
--dpkg
-)PRGN
-- programmers'\nmanual describing the source packaging tools. More detail about the\nexact functionality of these tools is available in
-ANAME CDATA dpkg-source
-ASECTION CDATA 1
-(MANREF
-)MANREF
-L1331
--.
-L1332
-)P
-(P
-L1333
--\n
-ACOMPACT IMPLIED
-(LIST
-L1336
-(ITEM
-L1337
-(P
--Download the original source code from wherever it can be found and do\nany rearrangement required to make it look like the original tree of\nthe Debian source. Put it in\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--upstream-version
-)VAR
--.orig/
-)TT
-- or\n
-(TT
-(VAR
--package
-)VAR
--_
-(VAR
--upstream-version
-)VAR
--.orig.tar.gz
-)TT
--.\n
-L1343
-)P
-)ITEM
-(ITEM
-L1344
-(P
--Rename all files
-(TT
--debian.*
-)TT
-- to
-(TT
--debian/*
-)TT
--. There may be some\nexceptions to this, but this is a good start.\n
-L1347
-)P
-)ITEM
-(ITEM
-L1348
-(P
--Edit the
-(TT
--debian/changelog
-)TT
-- - create or rename it if necessary.\nAdd a new revision to the top with the appropriate details, and a\nlocal variables entry to the bottom to set Emacs to the right mode:\n
-(EXAMPLE
-L1352
--Local variables:\nmode: debian-changelog\nEnd:
-L1355
-)EXAMPLE
--\n
-L1357
-)P
-)ITEM
-(ITEM
-L1358
-(P
--Edit/create
-(TT
--debian/control
-)TT
--:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1360
-(ITEM
-L1361
-(P
--Remove the
-(TT
--Version
-)TT
-- field. If it is generated unusually (not\nequal to the source version) you must use the -v option to\ndpkg-gencontrol (see below).
-(TT
--Section
-)TT
--,
-(TT
--Priority
-)TT
--,\n
-(TT
--Maintainer
-)TT
-- go above the first blank line, most of the rest below.\n
-L1366
-)P
-)ITEM
-(ITEM
-L1367
-(P
--Reorder the fields and add a blank line at an appropriate point,\nseparating the source package fields from the binary package\nfields.\n
-L1371
-)P
-)ITEM
-(ITEM
-L1372
-(P
--Add the
-(TT
--Source
-)TT
-- field.\n
-L1374
-)P
-)ITEM
-(ITEM
-L1375
-(P
--Add the
-(TT
--Standards-Version
-)TT
-- field. The current value is\n
-(TT
--0.2.0.0
-)TT
--.\n
-L1378
-)P
-)ITEM
-(ITEM
-L1379
-(P
--Change the
-(TT
--Architecture
-)TT
-- field for each package to
-(TT
--any
-)TT
--,\n
-(TT
--all
-)TT
-- or whatever. If there isn't an
-(TT
--Architecture
-)TT
-- field add\none.\n
-L1383
-)P
-)ITEM
-(ITEM
-L1384
-(P
--If any other seddery or things used to happen to make the binary\ncontrol files use
-(PRGN
--dpkg-gencontrol
-)PRGN
--'s variable substitution\nfeatures to achieve the same effect. Use
-(TT
--debian/substvars
-)TT
-- if\nyou need to put unusally-generated information (apart from details of\n
-(TT
--.deb
-)TT
-- files) in the
-(TT
--.changes
-)TT
-- file too.
-L1389
-)P
-)ITEM
-)LIST
--\n
-L1391
-)P
-)ITEM
-(ITEM
-L1392
-(P
--Edit the
-(TT
--debian/rules
-)TT
--:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1394
-(ITEM
-L1395
-(P
--Remove the
-(PRGN
--source
-)PRGN
-- and
-(PRGN
--diff
-)PRGN
-- and any
-(PRGN
--changes
-)PRGN
-- and\n
-(PRGN
--dist
-)PRGN
-- targets. These things now happen in a package-independent\nway and are not done by
-(TT
--debian/rules
-)TT
--.
-L1398
-)P
-)ITEM
-(ITEM
-L1399
-(P
--Split the
-(PRGN
--binary
-)PRGN
-- target into
-(PRGN
--binary-arch
-)PRGN
-- and\n
-(PRGN
--binary-indep
-)PRGN
--; in many cases all of
-(PRGN
--binary
-)PRGN
-- should go into\n
-(PRGN
--binary-arch
-)PRGN
--. Create the
-(PRGN
--binary
-)PRGN
-- target and the unused of\nthe two other
-(PRGN
--binary-*
-)PRGN
-- targets if there is one - you can copy\nthe ones from the
-(PRGN
--hello
-)PRGN
-- package.
-L1404
-)P
-)ITEM
-(ITEM
-L1405
-(P
--Change the
-(PRGN
--binary
-)PRGN
-- target to use
-(PRGN
--dpkg-gencontrol
-)PRGN
-- to make\nthe package control file(s). Move it to after all the files have been\ninstalled but just before the last
-(PRGN
--chown
-)PRGN
-- and
-(PRGN
--chmod
-)PRGN
-- in\nthe target.
-L1409
-)P
-)ITEM
-(ITEM
-L1410
-(P
--Change occurrences of
-(TT
--debian-tmp
-)TT
-- to
-(TT
--debian/tmp
-)TT
--.
-L1411
-)P
-)ITEM
-(ITEM
-L1412
-(P
--Change occurrences of
-(TT
--debian.{post,pre}{inst,rm}
-)TT
-- to\n
-(TT
--debian/*
-)TT
--.
-L1414
-)P
-)ITEM
-(ITEM
-L1415
-(P
--Remove the version number setting at the top, if there is one.
-L1416
-)P
-)ITEM
-(ITEM
-L1417
-(P
--Ensure that the package's Debian-specific and upstream changelogs are\ninstalled.
-L1419
-)P
-)ITEM
-)LIST
--\n
-L1421
-)P
-)ITEM
-(ITEM
-L1422
-(P
--Check that the
-(TT
--debian/README
-)TT
-- is really the copyright file, and\nif so rename it to
-(TT
--debian/copyright
-)TT
-- and edit\n
-(TT
--debian/rules
-)TT
-- to cope with this and to change the installation\nof the copyright file from
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
--\ninstead of
-(TT
--/usr/doc/copyright/
-(VAR
--package
-)VAR
-)TT
--. If it isn't then\nfind
-(TT
--debian/copyright
-)TT
-- and decide what to do with the\n
-(TT
--README
-)TT
--.\n
-L1430
-)P
-)ITEM
-(ITEM
-L1431
-(P
--Check for various other anachronisms and problems:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1433
-(ITEM
-L1434
-(P
--Remove any
-(TT
--Package_Revision
-)TT
--,
-(TT
--Package-Revision
-)TT
-- or\n
-(TT
--Revision
-)TT
-- fields.
-L1436
-)P
-)ITEM
-(ITEM
-L1437
-(P
--Rename
-(TT
--Optional
-)TT
-- to
-(TT
--Suggests
-)TT
--,
-(TT
--Recommended
-)TT
-- to\n
-(TT
--Recommends
-)TT
--.
-L1439
-)P
-)ITEM
-(ITEM
-L1440
-(P
--Change
-(TT
--/usr/doc/examples/
-(VAR
--package
-)VAR
-)TT
-- to\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/examples
-)TT
--.
-L1442
-)P
-)ITEM
-(ITEM
-L1443
-(P
--Make sure that manpages are installed compressed.
-L1444
-)P
-)ITEM
-(ITEM
-L1445
-(P
--Check that the description has an extended description, is\nwell-formatted and meaningful and helpful to people wanting to know\nwhether to install a package.
-L1448
-)P
-)ITEM
-)LIST
--\n
-L1450
-)P
-)ITEM
-(ITEM
-L1451
-(P
--Look everything over.\n
-L1453
-)P
-)ITEM
-(ITEM
-L1454
-(P
--Do a test build using
-(TT
--dpkg-buildpackage -ur -uc -r
-(VAR
--whatever
-)VAR
-)TT
--.\nCheck the permissions and locations of files in the resulting package\nby eyeballing the output of
-(TT
--dpkg-deb --contents
-)TT
--, and check that\nthe source build happened OK. Test install the binary package(s) and\ntest extract the source package(s).\n
-L1460
-)P
-)ITEM
-(ITEM
-L1461
-(P
--Sign the release: either re-run
-(PRGN
--dpkg-buildpackage
-)PRGN
-- (this will\nrebuild the package entirely), or PGP-sign the
-(TT
--.dsc
-)TT
--, rebuild the\n
-(TT
--.changes
-)TT
-- using
-(PRGN
--dpkg-genchanges
-)PRGN
--, and then PGP-sign the\n
-(TT
--.changes
-)TT
--.\n
-L1466
-)P
-)ITEM
-)LIST
--\n
-L1468
-)P
-)CHAPT
-)BOOK
-)DEBIANDOC
-C
+++ /dev/null
-L12 policy.sgml
-(DEBIANDOC
-(BOOK
-L14
-(TITLEPAG
-(TITLE
--Debian policy manual
-L15
-)TITLE
-(AUTHOR
-(NAME
--Ian Jackson
-)NAME
-(EMAIL
--ijackson@gnu.ai.mit.edu
-)EMAIL
-L16
-)AUTHOR
-(VERSION
--version 0.2.0.0 (dpkg 1.3.7),
-(DATE
-)DATE
--\n
-L18
-)VERSION
-(ABSTRACT
-L19
--This manual describes the policy requirements which must be satisfied\nfor a package to be included in the Debian distribution. This\nincludes details of the permissions and ownerships of files in\npackages and other technical requirements as well as information like\nthe upload procedure.
-L24
-)ABSTRACT
-L26
-(COPYRIGHT
-(COPYRIGHTSUMMARY
--Copyright \|©\|1996 Ian Jackson.
-L27
-)COPYRIGHTSUMMARY
-(P
-L28
--\nThis manual is free software; you may redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation; either version 2, or (at your option) any\nlater version.
-L33
-)P
-(P
-L34
--\nThis is distributed in the hope that it will be useful, but\n
-(EM
--without any warranty
-)EM
--; without even the implied warranty of\nmerchantability or fitness for a particular purpose. See the GNU\nGeneral Public License for more details.
-L39
-)P
-(P
-L40
--\nYou should have received a copy of the GNU General Public License with\nyour Debian GNU/Linux system, in
-(TT
--/usr/doc/copyright/GPL
-)TT
--, or\nwith the
-(PRGN
--dpkg
-)PRGN
-- source package as the file
-(TT
--COPYING
-)TT
--. If\nnot, write to the Free Software Foundation, Inc., 675 Mass Ave,\nCambridge, MA 02139, USA.\n
-L47
-)P
-)COPYRIGHT
-)TITLEPAG
-L47 policy.sgml
-ADETAIL TOKEN SECT
-(TOC
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-scope
-ACHAPT CDATA 1
-ASECT IMPLIED
-AHNAME CDATA chapter 1
-(TOCENTRY
-L49 policy.sgml
--Introduction and scope of this manual
-L50
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-pkgcopyright
-ACHAPT CDATA 2
-ASECT IMPLIED
-AHNAME CDATA chapter 2
-(TOCENTRY
-L76 policy.sgml
--Package copyright
-L77
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-binarypkg
-ACHAPT CDATA 3
-ASECT IMPLIED
-AHNAME CDATA chapter 3
-(TOCENTRY
-L178 policy.sgml
--Contents of the binary package\n
-L180
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1
-AHNAME CDATA section 3.1
-(TOCENTRY
-L180 policy.sgml
--Control file requirements\n
-L182
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.1
-AHNAME CDATA subsection 3.1.1
-(TOCENTRY
-L182 policy.sgml
-(TT
--Maintainer
-)TT
-- information
-L183
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.2
-AHNAME CDATA subsection 3.1.2
-(TOCENTRY
-L191 policy.sgml
--Dependencies and virtual packages
-L192
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.3
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.3
-AHNAME CDATA subsection 3.1.3
-(TOCENTRY
-L215 policy.sgml
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-L216
-)TOCENTRY
-ALEVEL CDATA SECT2
-ASRID CDATA s3.1.3.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.3.1
-AHNAME CDATA subsubsection 3.1.3.1
-(TOCENTRY
-L240 policy.sgml
-(TT
--Priority
-)TT
-- values
-L241
-)TOCENTRY
-ALEVEL CDATA SECT2
-ASRID CDATA s3.1.3.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.3.2
-AHNAME CDATA subsubsection 3.1.3.2
-(TOCENTRY
-L294 policy.sgml
--Base packages
-L295
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.4
-AHNAME CDATA subsection 3.1.4
-(TOCENTRY
-L306 policy.sgml
--The
-(TT
--Essential
-)TT
-- flag
-L307
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.5
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.5
-AHNAME CDATA subsection 3.1.5
-(TOCENTRY
-L315 policy.sgml
--Including
-(TT
--Priority
-)TT
-- and
-(TT
--Section
-)TT
-- in the
-(TT
--.deb
-)TT
--\ncontrol file
-L317
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.6
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.6
-AHNAME CDATA subsection 3.1.6
-(TOCENTRY
-L332 policy.sgml
--Formatting of the
-(TT
--Description
-)TT
-- control file field
-L333
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2
-AHNAME CDATA section 3.2
-(TOCENTRY
-L359 policy.sgml
--Locations of files
-L360
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.1
-AHNAME CDATA subsection 3.2.1
-(TOCENTRY
-L372 policy.sgml
--Manpages
-L373
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.2
-AHNAME CDATA subsection 3.2.2
-(TOCENTRY
-L416 policy.sgml
--Info documents
-L417
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.3
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.3
-AHNAME CDATA subsection 3.2.3
-(TOCENTRY
-L451 policy.sgml
--Additional documentation
-L452
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.4
-AHNAME CDATA subsection 3.2.4
-(TOCENTRY
-L474 policy.sgml
--Preferred documentation formats
-L475
-)TOCENTRY
-ALEVEL CDATA SECT2
-ASRID CDATA s3.2.4.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.4.1
-AHNAME CDATA subsubsection 3.2.4.1
-(TOCENTRY
-L488 policy.sgml
--Examples
-L489
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-instchangelog
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.5
-AHNAME CDATA subsection 3.2.5
-(TOCENTRY
-L497 policy.sgml
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/changelog.Debian.gz
-)TT
-L498
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-copyrightfile
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.6
-AHNAME CDATA subsection 3.2.6
-(TOCENTRY
-L513 policy.sgml
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
-L514
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.7
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.7
-AHNAME CDATA subsection 3.2.7
-(TOCENTRY
-L543 policy.sgml
--Symbolic links
-L544
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.8
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.8
-AHNAME CDATA subsection 3.2.8
-(TOCENTRY
-L578 policy.sgml
--Logfiles
-L579
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.9
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.9
-AHNAME CDATA subsection 3.2.9
-(TOCENTRY
-L598 policy.sgml
-(TT
--/usr/local
-)TT
-- - for the use of the system administrator
-L599
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.3
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .3
-AHNAME CDATA section 3.3
-(TOCENTRY
-L627 policy.sgml
--Permissions and ownerships
-L628
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .4
-AHNAME CDATA section 3.4
-(TOCENTRY
-L676 policy.sgml
--Configuration files
-L677
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.5
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .5
-AHNAME CDATA section 3.5
-(TOCENTRY
-L689 policy.sgml
--Maintainer scripts
-L690
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.6
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .6
-AHNAME CDATA section 3.6
-(TOCENTRY
-L740 policy.sgml
--Scripts in general
-L741
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.7
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .7
-AHNAME CDATA section 3.7
-(TOCENTRY
-L769 policy.sgml
--Compilation options
-L770
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.8
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .8
-AHNAME CDATA section 3.8
-(TOCENTRY
-L814 policy.sgml
--Shared library packages
-L815
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.9
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .9
-AHNAME CDATA section 3.9
-(TOCENTRY
-L871 policy.sgml
--Application configuration files, dotfiles and
-(TT
--/etc/skel
-)TT
-L872
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-mail
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .10
-AHNAME CDATA section 3.10
-(TOCENTRY
-L908 policy.sgml
--Mail processing on Debian systems
-L909
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.11
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .11
-AHNAME CDATA section 3.11
-(TOCENTRY
-L981 policy.sgml
--Packages which can use the X shared libraries
-L982
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.12
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .12
-AHNAME CDATA section 3.12
-(TOCENTRY
-L999 policy.sgml
--Games
-L1000
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.13
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .13
-AHNAME CDATA section 3.13
-(TOCENTRY
-L1030 policy.sgml
--Allocating package-specific users and groups
-L1031
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-sourcepkg
-ACHAPT CDATA 4
-ASECT IMPLIED
-AHNAME CDATA chapter 4
-(TOCENTRY
-L1068 policy.sgml
--Source package\n
-L1070
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s4.1
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1
-AHNAME CDATA section 4.1
-(TOCENTRY
-L1070 policy.sgml
--Releases of packages by other than the usual Debian maintainer
-L1071
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s4.2
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2
-AHNAME CDATA section 4.2
-(TOCENTRY
-L1105 policy.sgml
--Standards conformance and
-(TT
--Standards-Version
-)TT
-L1106
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s4.3
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .3
-AHNAME CDATA section 4.3
-(TOCENTRY
-L1142 policy.sgml
--Documentation and the
-(TT
--changelog
-)TT
-L1143
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s4.4
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .4
-AHNAME CDATA section 4.4
-(TOCENTRY
-L1163 policy.sgml
--Changes to the upstream sources
-L1164
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s4.5
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .5
-AHNAME CDATA section 4.5
-(TOCENTRY
-L1188 policy.sgml
--Error trapping in makefiles
-L1189
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-developer
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(TOCENTRY
-L1209 policy.sgml
--How to become a Debian developer\n
-L1211
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s5.1
-ACHAPT CDATA 5
-ACSRID CDATA ch-developer
-ASECT CDATA .1
-AHNAME CDATA section 5.1
-(TOCENTRY
-L1211 policy.sgml
--Before you start work
-L1212
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s5.2
-ACHAPT CDATA 5
-ACSRID CDATA ch-developer
-ASECT CDATA .2
-AHNAME CDATA section 5.2
-(TOCENTRY
-L1242 policy.sgml
--When you have a package to upload
-L1243
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-changesfiles
-ACHAPT CDATA 5
-ACSRID CDATA ch-developer
-ASECT CDATA .3
-AHNAME CDATA section 5.3
-(TOCENTRY
-L1270 policy.sgml
--Upload handling -
-(TT
--.changes
-)TT
-- files
-L1271
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-mailinglists
-ACHAPT CDATA 6
-ASECT IMPLIED
-AHNAME CDATA chapter 6
-(TOCENTRY
-L1300 policy.sgml
--The Debian mailing lists
-L1301
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-conversion
-ACHAPT CDATA 7
-ASECT IMPLIED
-AHNAME CDATA chapter 7
-(TOCENTRY
-L1320 policy.sgml
--Conversion procedure from old source packages
-L1321
-)TOCENTRY
-)TOC
-L47 policy.sgml
-AID CDATA scope
-L49
-ASRID CDATA ch-scope
-ACHAPT CDATA 1
-ASECT IMPLIED
-AHNAME CDATA chapter 1
-(CHAPT
-(HEADING
--Introduction and scope of this manual
-L50
-)HEADING
-(P
-L51
--\nThis manual describes the criteria that a Debian-format package must\nsatisfy to be included in the Debian distribution.
-L54
-)P
-(P
-L55
--\nMuch of this information will be useful even when building a package\nwhich is to be distributed in some other way or is for local use.
-L58
-)P
-(P
-L59
--\nThis manual does
-(EM
--not
-)EM
-- describe the technical mechanisms involved\nin package creation, installation and removal. This information can\nbe found in the
-(PRGN
--dpkg
-)PRGN
-- programmers' manual and the
-(PRGN
--dpkg
-)PRGN
-- system\nadministrators' manual.
-L64
-)P
-(P
-L65
--\nThis document assumes familiarity with these other two manuals.\nUnfortunately the system administrators' manual does not exist yet.
-L68
-)P
-(P
-L69
--\nThe Debian version of the FSF's GNU
-(PRGN
--hello
-)PRGN
-- program is provided\nas an example for people wishing to create Debian packages.
-L72
-)P
-(P
-L73
--\n
-(EM
--Note that this document is still a draft!
-)EM
--\n
-L76
-)P
-)CHAPT
-AID CDATA pkgcopyright
-ASRID CDATA ch-pkgcopyright
-ACHAPT CDATA 2
-ASECT IMPLIED
-AHNAME CDATA chapter 2
-(CHAPT
-(HEADING
--Package copyright
-L77
-)HEADING
-(P
-L78
--\nPlease study the copyright of your submission
-(EM
--carefully
-)EM
-- and\nunderstand it before proceeding. If you have doubts or questions,\nplease ask.
-L82
-)P
-(P
-L83
--\nThe aims of the policy detailed below are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L86
-(ITEM
-L87
-(P
--That any user be able to rebuild any package in the official Debian\ndistribution from the original source plus our patches.
-L89
-)P
-)ITEM
-(ITEM
-L90
-(P
--That we make available in our packaging formats as much software as we\ncan.
-L92
-)P
-)ITEM
-(ITEM
-L93
-(P
--That it be easy for people to make CDROMs of our distribution without\nviolating copyrights.
-L95
-)P
-)ITEM
-)LIST
-L96
-)P
-(P
-L97
--\nAll packages in the Debian distribution proper must be freely useable,\nmodifiable and redistributable in both source and binary form. It\nmust be possible for anyone to distribute and use modified source code\nand their own own compiled binaries, at least when they do so as part\nof a Debian distribution.
-L103
-)P
-(P
-L104
--\nPackages whose copyright permission notices (or patent problems) do\nnot allow distribution and copying for profit, without restriction on\nthe amount charged, or where distribution is restricted according to\nthe medium used, or where the distributor must ask any kind of special\npermission of the authors, or with other onerous conditions, may only\nbe placed in the semi-supported non-free section of the Debian FTP\narchives. This is important so that CDROM manufacturers can\ndistribute Debian without having to check the copyright of each\npackage individually, simply by leaving out the contents of the\nnon-free area; CDROM distributors are encouraged, though, to check the\ncopyrights on programs in non-free individually and include as many as\nthey can.
-L117
-)P
-(P
-L118
--\nPackages whose copyright permission notices (or patent problems) allow\nonly distribution of compiled binaries (and thus of which only\nbinaries are available), or where the source code which may be\ndistributed is not the complete source code required to compile the\nprogram (ie, the program cannot be compiled using only packages in the\nmain Debian distribution), or which depend for their use on non-free\nor contrib packages, or allow free use only for a trial period\n(shareware), or are demonstration programs lacking vital functionality\n(crippleware), or are only installer-packages which require the user\nto supply a separate file to be installed, or which fail to meet some\nother policy requirements, may only be placed in the semi-supported\ncontrib section of the Debian FTP archives (unless they need to be in\nnon-free - see above).
-L132
-)P
-(P
-L133
--\nPrograms whose authors encourage the user to make donations are fine\nfor the main distribution, provided that the authors do not claim that\nnot donating is immoral, unethical, illegal or something similar;\notherwise they must go in contrib (or non-free, if even distribution\nis restricted by such statements).
-L139
-)P
-(P
-L140
--\nPackages whose copyright permission notices (or patent problems) do\nnot allow redistribution even of only binaries, and where no special\npermission has been obtained, cannot placed on the Debian FTP site and\nits mirrors at all.
-L145
-)P
-(P
-L146
--\nNote that under international copyright law
-(FOOTNOTE
-(P
--This applies in\nthe United States, too.
-)P
-)FOOTNOTE
--
-(EM
--no
-)EM
-- distribution or modification\nof a work is allowed without an explicit notice saying so. Therefore\na program without a copyright notice
-(EM
--is
-)EM
-- copyrighted and you may\nnot do anything to it without risking being sued! Likewise if a\nprogram has a copyright notice but no statement saying what is\npermitted then nothing is permitted.
-L154
-)P
-(P
-L155
--\nMany authors are unaware of the problems that restrictive copyrights\n(or lack of copyright notices) can cause for the users of their\nsupposedly-free software. It is often worthwhile contacting such\nauthors diplomatically to ask them to modify their terms generally, or\nspecially for Debian. However, this is a politically difficult thing\nto do and you should ask for advice on
-(PRGN
--debian-devel
-)PRGN
-- first.
-L162
-)P
-(P
-L163
--\nWhen in doubt, send mail to
-(EMAIL
--debian-devel@lists.debian.org
-)EMAIL
--. Be\nprepared to provide us with the copyright statement. Software covered\nby the GPL, public domain software and BSD-like copyrights are safe;\nbe wary of the phrases `commercial use prohibited' and `distribution\nrestricted'.
-L169
-)P
-(P
-L170
--\nEvery package submission
-(EM
--must
-)EM
-- be accompanied by verbatim copy of\nits copyright (with the exceptions of public domain packages and those\ncovered by the UCB BSD licence or the GNU GPL or LGPL; in these cases\nsimply indicate which is appropriate). This information must be\nincluded in a file installed by the binary package - see
-AID CDATA copyrightfile
-ALEVEL CDATA SECT1
-ASRID CDATA s-copyrightfile
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.6
-AHNAME CDATA subsection 3.2.6
-(REF
-L513 policy.sgml
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
-L514
-)REF
-L176
--.\n
-L178
-)P
-)CHAPT
-AID CDATA binarypkg
-ASRID CDATA ch-binarypkg
-ACHAPT CDATA 3
-ASECT IMPLIED
-AHNAME CDATA chapter 3
-(CHAPT
-(HEADING
--Contents of the binary package\n
-L180
-)HEADING
-AID IMPLIED
-ASRID CDATA s3.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1
-AHNAME CDATA section 3.1
-(SECT
-(HEADING
--Control file requirements\n
-L182
-)HEADING
-AID IMPLIED
-ASRID CDATA s3.1.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.1
-AHNAME CDATA subsection 3.1.1
-(SECT1
-(HEADING
-(TT
--Maintainer
-)TT
-- information
-L183
-)HEADING
-(P
-L184
--\nAll packages must have a
-(TT
--Maintainer
-)TT
-- field with the correct name\nand a working email address for the Debian maintainer of the package.\nIf one person maintains several packages they should try to avoid\nhaving different forms of their name and address in different\n
-(TT
--Maintainer
-)TT
-- fields.\n
-L191
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.2
-AHNAME CDATA subsection 3.1.2
-(SECT1
-(HEADING
--Dependencies and virtual packages
-L192
-)HEADING
-(P
-L193
--\nAdd a dependency for any shared libraries required by\ndynamically-linked executable binaries in your package. Almost every\npackage containing compiled C code should therefore include a\n
-(TT
--Depends
-)TT
-- field which mentions the shared C library required for\nthe program to run. For ELF binaries linked against
-(TT
--libc.so.5
-)TT
--\nthe relevant package name is
-(TT
--libc5
-)TT
--.
-L200
-)P
-(P
-L201
--\nAll packages must use virtual package names where appropriate, and\narrange to create new ones if necessary. They must not use virtual\npackage names (except privately, amongst a cooperating group of\npackages) unless they have been agreed upon and appear in the list of\nvirtual package names.
-L207
-)P
-(P
-L208
--\nThe latest version of the authoritative list of virtual package names\ncan be found on
-(FTPSITE
--ftp.debian.org
-)FTPSITE
-- in\n
-(FTPPATH
--/debian/doc/package-developer/virtual-package-names-list.text
-)FTPPATH
--\nor your local mirror. The procedure for updating it is described at\nthe top of the file.\n
-L215
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.3
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.3
-AHNAME CDATA subsection 3.1.3
-(SECT1
-(HEADING
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-L216
-)HEADING
-(P
-L217
--\nDecide whether your package can go in
-(TT
--non-free
-)TT
--,
-(TT
--contrib
-)TT
-- or\nthe main distribution - see
-AID CDATA pkgcopyright
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-pkgcopyright
-ACHAPT CDATA 2
-ASECT IMPLIED
-AHNAME CDATA chapter 2
-(REF
-L76 policy.sgml
--Package copyright
-L77
-)REF
--, and put\nan appropriate value for the distribution in the\n
-(TT
--debian/changelog
-)TT
-- file.
-L222
-)P
-(P
-L223
--\nThe
-(TT
--Priority
-)TT
-- and
-(TT
--Section
-)TT
-- control file fields give\ninformation for classifying the package in
-(PRGN
--dselect
-)PRGN
-- and say\nwhich directory to place it in the FTP archive.
-L227
-)P
-(P
-L228
--\nThey are ultimately the responsibility of the distribution\nmaintainers; however, you should suggest values for them in your\n
-(TT
--.changes
-)TT
-- information when you upload a package. You do this by\nincluding appropriate information in the
-(TT
--debian/control
-)TT
-- file\nbefore building the packages.
-L234
-)P
-(P
-L235
--\nFor a list of the currently in-use sections, please see the FTP\narchive. Packages in the non-free and contrib areas should have\nsection
-(TT
--non-free
-)TT
-- and
-(TT
--contrib
-)TT
--, respectively.\n
-L240
-)P
-AID IMPLIED
-ASRID CDATA s3.1.3.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.3.1
-AHNAME CDATA subsubsection 3.1.3.1
-(SECT2
-(HEADING
-(TT
--Priority
-)TT
-- values
-L241
-)HEADING
-(P
-L242
--\n
-ACOMPACT IMPLIED
-(TAGLIST
-L244
-(TAG
-(TT
--required
-)TT
-L245
-)TAG
-(ITEM
-L246
-(P
-(TT
--required
-)TT
-- packages are necessary for the proper functioning of the\nsystem. You must not remove these packages or your system may become\ntotally broken and you may probably not even be able to use\n
-(PRGN
--dpkg
-)PRGN
-- to put things back. Systems with only the
-(TT
--required
-)TT
--\npackages are probably unuseable, but they do have enough functionality\nto allow the sysadmin to boot and install more software.\n
-L253
-)P
-)ITEM
-(TAG
-(TT
--important
-)TT
-L254
-)TAG
-(ITEM
-L255
-(P
--Important programs, including those which one would expect to find on\nany Unix-like system. If the expectation is that an experienced Unix\nperson who found it missing would go `What the F*!@\|<\|+ is going on,\nwhere is
-(PRGN
--foo
-)PRGN
--', it should be in
-(TT
--important
-)TT
--. This is an\nimportant criterion because we are trying to produce, amongst other\nthings, a free Unix. Other packages without which the system will not\nrun well or be useable should also be here. This does
-(EM
--not
-)EM
--\ninclude Emacs or X11 or TeX or any other large applications. The\n
-(TT
--important
-)TT
-- packages are just a bare minimum of commonly-expected\nand necessary tools.\n
-L266
-)P
-)ITEM
-(TAG
-(TT
--standard
-)TT
-L267
-)TAG
-(ITEM
-L268
-(P
--These packages provide a reasonably small but not too limited\ncharacter-mode system. This is what will install by default if the\nuser doesn't select anything else. It doesn't include many large\napplications, but it does include Emacs (this is more of a piece of\ninfrastructure than an application) and a reasonable subset of TeX and\nLaTeX (if this is possible without X).\n
-L275
-)P
-)ITEM
-(TAG
-(TT
--optional
-)TT
-(FOOTNOTE
-(P
--In a sense everything is optional that\nisn't required, but that's not what is meant here.
-)P
-)FOOTNOTE
-L277
-)TAG
-(ITEM
-L278
-(P
--This is all the software that you might reasonably want to install if\nyou didn't know what it was or don't have specialised requirements.\nThis is a much larger system and includes X11, a full TeX\ndistribution, and lots of applications.\n
-L283
-)P
-)ITEM
-(TAG
-(TT
--extra
-)TT
-L284
-)TAG
-(ITEM
-L285
-(P
--This contains packages that conflict with others with higher\npriorities, or are only likely to be useful if you already know what\nthey are or have specialised requirements.\n
-L289
-)P
-)ITEM
-)TAGLIST
-L290
-)P
-(P
-L291
--\nPriority values are not case-sensitive.\n
-L294
-)P
-)SECT2
-AID IMPLIED
-ASRID CDATA s3.1.3.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.3.2
-AHNAME CDATA subsubsection 3.1.3.2
-(SECT2
-(HEADING
--Base packages
-L295
-)HEADING
-(P
-L296
--\nSome packages have
-(TT
--Section: base
-)TT
-- and are in the
-(TT
--base
-)TT
--\nsubdirectory on the FTP archives. These are the packages that are\nsupplied on the base disks. They are the minimum sensible set for\ninstalling new packages (perhaps via a network).
-L301
-)P
-(P
-L302
--\nMost of these packages should have
-(TT
--Priority: required
-)TT
-- or at least\n
-(TT
--Priority: important
-)TT
--.\n
-L306
-)P
-)SECT2
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.4
-AHNAME CDATA subsection 3.1.4
-(SECT1
-(HEADING
--The
-(TT
--Essential
-)TT
-- flag
-L307
-)HEADING
-(P
-L308
--\nThe
-(TT
--Essential: yes
-)TT
-- control file field should not be used unless\nremoving a package really will completely hose the system; nor should\nit be used for a shared library package - the dependencies will\nprevent its premature removal, and we need to be able to remove it\nwhen it has been superseded.\n
-L315
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.5
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.5
-AHNAME CDATA subsection 3.1.5
-(SECT1
-(HEADING
--Including
-(TT
--Priority
-)TT
-- and
-(TT
--Section
-)TT
-- in the
-(TT
--.deb
-)TT
--\ncontrol file
-L317
-)HEADING
-(P
-L318
--\nIf a user installs a package which is not part of the standard\ndistribution, or without downloading and updating from a new\n
-(PRGN
--Packages
-)PRGN
-- file, the information about the priority and section\nof a package will be absent, and the
-(PRGN
--dselect
-)PRGN
-- package listing\nwill have the package listed under `unclassified'. In order to\nimprove this it is permissible to use the
-(TT
---is
-)TT
--,
-(TT
---isp
-)TT
-- or\n
-(TT
---ip
-)TT
-- option to
-(PRGN
--dpkg-gencontrol
-)PRGN
--, so that the
-(TT
--Section
-)TT
--\nand/or
-(TT
--Priority
-)TT
-- is copied into the actual control information in\nthe
-(TT
--.deb
-)TT
-- file. However, if you do this you should make sure you\nkeep the information up to date so that users are not shown\nconflicting information.\n\n
-L332
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.6
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1.6
-AHNAME CDATA subsection 3.1.6
-(SECT1
-(HEADING
--Formatting of the
-(TT
--Description
-)TT
-- control file field
-L333
-)HEADING
-(P
-L334
--\nEvery Debian package should have an extended description.
-L336
-)P
-(P
-L337
--\nThe description should be written so that it tells the user what they\nneed to know to decide whether to install the package. This\ndescription should not just be copied from the blurb for the program.\nInstructions for configuring or using the package should not be\nincluded - that is what installation scripts, manpages, Info files and\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
-)TT
-- are for. Copyright statements and other\nadministrivia should not be included - that is what\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
-- is for.
-L346
-)P
-(P
-L347
--\nIf you wish to include a list in your extended with entries which are\na line or more each you must indent each entry by one space to make\nsure that it doesn't get wordwrapped. The start of each list entry\nshould be marked with an asterisk, followed by a single space. You\nmust wrap the list entries yourself to 75 columns, and should start\ncontinuation lines indented by three spaces so that they line up with\nthe start of the text on the first line of each list entry.
-L355
-)P
-(P
-L356
--\nSee the programmers' manual for further requirements and pitfalls.\n
-L359
-)P
-)SECT1
-)SECT
-AID IMPLIED
-ASRID CDATA s3.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2
-AHNAME CDATA section 3.2
-(SECT
-(HEADING
--Locations of files
-L360
-)HEADING
-(P
-L361
--\nThe location of all installed files and directories must comply fully\nwith the Linux File System Standard (FSSTND). The latest version of\nthis document can be found alongside this manual or on\n
-(FTPSITE
--tsx-11.mit.edu
-)FTPSITE
-- in\n
-(FTPPATH
--/pub/linux/docs/linux-standards/fsstnd/
-)FTPPATH
--. Specific questions\nabout following the standard may be asked on
-(PRGN
--debian-devel
-)PRGN
--, or\nreferred to Daniel Quinlan, the FSSTND coordinator, at\n
-(EMAIL
--quinlan@yggdrasil.com
-)EMAIL
--.
-L370
-)P
-(P
-L372
-)P
-AID IMPLIED
-ASRID CDATA s3.2.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.1
-AHNAME CDATA subsection 3.2.1
-(SECT1
-(HEADING
--Manpages
-L373
-)HEADING
-(P
-L374
--\nYou must install manpages in
-(PRGN
--nroff
-)PRGN
-- source form, in appropriate\nplaces under
-(TT
--/usr/man
-)TT
--. You should only use sections 1 to 9\n(see the FSSTND for more details). You must
-(EM
--not
-)EM
-- install a\npreformatted `cat page'.
-L379
-)P
-(P
-L380
--\nIf no manual page is available for a particular program, utility or\nfunction and this is reported as a bug on debian-bugs, a symbolic link\nfrom the requested manual page to the
-ANAME CDATA undocumented
-ASECTION CDATA 7
-(MANREF
-)MANREF
-L384
-- manual page should be provided. This symbolic link can be\ncreated from
-(TT
--debian/rules
-)TT
-- like this:\n
-(EXAMPLE
-L387
--ln -s ../man7/undocumented.7 \\\n debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9]
-L389
-)EXAMPLE
--\nThis manpage claims that the lack of a manpage has been reported as a\nbug, so you may only do this if it really has (you can report it\nyourself, if you like). Do not close the bug report until a proper\nmanpage is available.
-L394
-)P
-(P
-L395
--\nYou may forward a complaint about a missing manpage to the upstream\nauthors, and mark the bug as forwarded in the Debian bug tracking\nsystem. Even though the GNU Project do not in general consider the\nlack of a manpage to be a bug, we do - if they tell you that they\ndon't consider it a bug you should leave the bug in our bug tracking\nsystem open anyway.
-L402
-)P
-(P
-L403
--\nManpages should be installed compressed using
-(TT
--gzip -9
-)TT
--.
-L405
-)P
-(P
-L406
--\nIf one manpage needs to be accesssible via several names it is better\nto use a symbolic link than the
-(TT
--.so
-)TT
-- feature, but there is no need\nto fiddle with the relevant parts of the upstream source to change\nfrom
-(TT
--.so
-)TT
-- to symlinks - don't do it unless it's easy. Do not\ncreate hard links in the manual page directories, and do not put\nabsolute filenames in
-(TT
--.so
-)TT
-- directives. The filename in a\n
-(TT
--.so
-)TT
-- in a manpage should be relative to the base of the manpage\ntree (usually
-(TT
--/usr/man
-)TT
--).\n
-L416
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.2
-AHNAME CDATA subsection 3.2.2
-(SECT1
-(HEADING
--Info documents
-L417
-)HEADING
-(P
-L418
--\nInfo documents should be installed in
-(TT
--/usr/info
-)TT
--. They should\nbe compressed with
-(TT
--gzip -9
-)TT
--.
-L421
-)P
-(P
-L422
--\nYour package must call
-(PRGN
--install-info
-)PRGN
-- to update the Info
-(TT
--dir
-)TT
--\nfile, in its post-installation script:\n
-(EXAMPLE
-L426
--install-info --quiet --section Development Development \\\n /usr/info/foobar.info
-L428
-)EXAMPLE
-L429
-)P
-(P
-L430
--\nIt is a good idea to specify a section for the location of your\nprogram; this is done with the
-(TT
----section
-)TT
-- switch. To determine\nwhich section to use, you should use look at
-(TT
--/usr/info/dir
-)TT
-- on\nyour system and choose the most relevant (or create a new section if\nnone of the current sections are relevant). Note that the\n
-(TT
----section
-)TT
-- flag takes two arguments; the first is a regular\nexpression to match (case-insensitively) against an existing section,\nthe second is used when creating a new one.
-L439
-)P
-(P
-L440
--\nYou must remove the entries in the pre-removal script:\n
-(EXAMPLE
-L443
--install-info --quiet --remove /usr/info/foobar.info
-L444
-)EXAMPLE
-L445
-)P
-(P
-L446
--\nIf
-(PRGN
--install-info
-)PRGN
-- cannot find a description entry in the Info file\nyou will have to supply one. See
-ANAME CDATA install-info
-ASECTION CDATA 8
-(MANREF
-)MANREF
--\nfor details.\n
-L451
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.3
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.3
-AHNAME CDATA subsection 3.2.3
-(SECT1
-(HEADING
--Additional documentation
-L452
-)HEADING
-(P
-L453
--\nAny additional documentation that comes with the package can be\ninstalled at the discretion of the package maintainer. Text\ndocumentation should be installed in a directory\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
-)TT
-(FOOTNOTE
-(P
--Where
-(VAR
--package
-)VAR
-- is the\nname of the package.
-)P
-)FOOTNOTE
-- and compressed with
-(TT
--gzip -9
-)TT
--\nunless it is small.
-L460
-)P
-(P
-L461
--\nIf a package comes with large amounts of documentation which many\nusers of the package will not require you should create a separate\nbinary package to contain it, so that it does not take up disk space\non the machines of users who do not need or want it installed.
-L466
-)P
-(P
-L467
--\nIt is often a good idea to put text information files (
-(TT
--README
-)TT
--s,\nchangelogs, and so forth) that come with the source package in\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
-)TT
-- in the binary package. However, don't\ninstall the instructions for building and installing the package, of\ncourse!\n
-L474
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.4
-AHNAME CDATA subsection 3.2.4
-(SECT1
-(HEADING
--Preferred documentation formats
-L475
-)HEADING
-(P
-L476
--\nThe unification of Debian documentation is being carried out via HTML.
-L478
-)P
-(P
-L479
--\nIf your package comes with extensive documentation in a markup format\nthat can be converted to various other formats you should if possible\nship HTML versions in the binary package, in the directory\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
-)TT
-- or its subdirectories.
-L484
-)P
-(P
-L485
--\nOther formats such as PostScript may be provided at your option.\n
-L488
-)P
-AID IMPLIED
-ASRID CDATA s3.2.4.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.4.1
-AHNAME CDATA subsubsection 3.2.4.1
-(SECT2
-(HEADING
--Examples
-L489
-)HEADING
-(P
-L490
--\nAny examples (configurations, source files, whatever), should be\ninstalled in a directory
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/examples
-)TT
--.\nThese files should not be referenced by any program - they're there\nfor the benefit of the system administrator and users, as\ndocumentation only.\n
-L497
-)P
-)SECT2
-)SECT1
-AID CDATA instchangelog
-ASRID CDATA s-instchangelog
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.5
-AHNAME CDATA subsection 3.2.5
-(SECT1
-(HEADING
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/changelog.Debian.gz
-)TT
-L498
-)HEADING
-(P
-L499
--\nThis installed file must contain a copy of the
-(TT
--debian/changelog
-)TT
--\nfile from your Debian source tree.
-L502
-)P
-(P
-L503
--\nIt should be installed compressed using
-(TT
--gzip -9
-)TT
--, as it will\nbecome large with time even if it starts out small.
-L506
-)P
-(P
-L507
--\nIf the package has only one changelog which is used both as the Debian\nchangelog and the upstream one because there is no separate upstream\nmaintainer then the changelog should usually be installed as\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/changelog.gz
-)TT
-- instead.\n
-L513
-)P
-)SECT1
-AID CDATA copyrightfile
-ASRID CDATA s-copyrightfile
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.6
-AHNAME CDATA subsection 3.2.6
-(SECT1
-(HEADING
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
-L514
-)HEADING
-(P
-L515
--\nThis file must contain details of the authorship and copyright of the\npackage. It must say where the upstream sources (if any) were\nobtained, and explain briefly what modifications were made in the\nDebian version of the package compared to the upstream one. It must\nname the original authors of the package and the Debian maintainer(s)\nwho were involved with its creation.
-L522
-)P
-(P
-L523
--\nIt must contain the full text of the copyright notice and any\nacknowledgements for the program and the licence terms under which the\nprogram is distributed. If the package is distributed under the GNU\nGeneral Public Licence, the GNU Library General Public Licence, the\nRegents of the University of California at Berkeley (BSD) licence or\nLarry Wall's Artistic Licence please say so instead of including a\ncopy of the licence. The files
-(TT
--BSD
-)TT
--,
-(TT
--GPL
-)TT
--,
-(TT
--LGPL
-)TT
-- and\n
-(TT
--Artistic
-)TT
-- are be available in
-(TT
--/usr/doc/copyright
-)TT
-- for you\nto refer to.
-L533
-)P
-(P
-L534
--\nThe copyright file should not be compressed unless it is very large.
-L536
-)P
-(P
-L537
--\nDo not use the copyright file as a general
-(TT
--README
-)TT
-- file. If your\npackage has such a file it should be installed in\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/README
-)TT
-- or
-(TT
--README.Debian
-)TT
-- or some\nother appropriate place.\n
-L543
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.7
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.7
-AHNAME CDATA subsection 3.2.7
-(SECT1
-(HEADING
--Symbolic links
-L544
-)HEADING
-(P
-L545
--\nMost symbolic links should be relative, not absolute. Absolute links,\nin general, cause problems when a file system is not mounted where it\n"normally" resides (for example, when mounted via NFS).
-L549
-)P
-(P
-L550
--\nIn particular, symlinks from one part of
-(TT
--/usr
-)TT
-- to another\nshould be relative.
-L553
-)P
-(P
-L554
--\nIn certain cases, however, relative links may cause more problems.\nFor example, links into
-(TT
--/etc
-)TT
-- and
-(TT
--/var
-)TT
-- should be\nabsolute.
-L558
-)P
-(P
-L559
--\nNote that when creating a relative link using
-(PRGN
--ln
-)PRGN
-- it is not\nnecessary for the target of the link to exist relative to the working\ndirectory you're running
-(PRGN
--ln
-)PRGN
-- from; nor is it necessary to change\ndirectory to the directory where the link is to be made. Simply\ninclude the string that should appear as the target of the link (this\nwill be a pathname relative to the directory in which the link\nresides) as the first argument to
-(PRGN
--ln
-)PRGN
--.
-L567
-)P
-(P
-L568
--\nFor example, in your
-(PRGN
--Makefile
-)PRGN
-- or
-(TT
--debian/rules
-)TT
--, do things\nlike:\n
-(EXAMPLE
-L572
--ln -fs gcc $(prefix)/bin/cc\nln -fs gcc debian/tmp/usr/bin/cc\nln -fs ../sbin/sendmail $(prefix)/bin/runq\nln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
-L576
-)EXAMPLE
--\n
-L578
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.8
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.8
-AHNAME CDATA subsection 3.2.8
-(SECT1
-(HEADING
--Logfiles
-L579
-)HEADING
-(P
-L580
--\nLogfiles should usually be named\n
-(TT
--/var/log/
-(VAR
--package
-)VAR
--.log
-)TT
--. If you have many logfiles,\nor need a separate directory for permissions reasons\n(
-(TT
--/var/log
-)TT
-- is writeable only by
-(TT
--root
-)TT
--), you should usually\ncreate a directory named
-(TT
--/var/log/
-(VAR
--package
-)VAR
-)TT
--.
-L586
-)P
-(P
-L587
--\nMake sure that any logfiles are rotated occasionally using so that\nthey don't grow indefinitely; the best way to do this is to use\n
-(PRGN
--savelog
-)PRGN
-- program in an
-(TT
--/etc/cron.daily
-)TT
--,\n
-(TT
--/etc/cron.weekly
-)TT
-- or
-(TT
--/etc/cron.monthly
-)TT
-- script.
-L592
-)P
-(P
-L593
--\nMake sure that any logfiles are removed when the package is purged\n(but not when it is only removed), by checking the argument to the\npostrm script (see the programmer's manual for details).\n
-L598
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.9
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2.9
-AHNAME CDATA subsection 3.2.9
-(SECT1
-(HEADING
-(TT
--/usr/local
-)TT
-- - for the use of the system administrator
-L599
-)HEADING
-(P
-L600
--\nAs mandated by the FSSTND no package should place any files in\n
-(TT
--/usr/local
-)TT
--, either by putting them in the filesystem archive to\nbe unpacked by
-(PRGN
--dpkg
-)PRGN
-- or by manipulating them in their maintainer\nscripts.
-L605
-)P
-(P
-L606
--\nEvery package that searches a number of directories or files for\nsomething (for example, looking for shared libraries in
-(TT
--/lib
-)TT
-- or\n
-(TT
--/usr/lib
-)TT
--) should search an appropriate directory in\n
-(TT
--/usr/local
-)TT
-- too.
-L611
-)P
-(P
-L612
--\nIn order that the system administrator may know where to place\nadditional files a package should create an empty directory in the\nappropriate place in
-(TT
--/usr/local
-)TT
-- by supplying it in the\nfilesystem archive for unpacking by
-(PRGN
--dpkg
-)PRGN
--. The\n
-(TT
--/usr/local
-)TT
-- directory itself and all the subdirectories created\nby the package should have permissions 2775 (group-writeable and\nset-group-id) and be owned by
-(TT
--root.staff
-)TT
--.
-L620
-)P
-(P
-L621
--\nIn the future it will be possible to tell
-(PRGN
--dpkg
-)PRGN
-- not to unpack\nfiles matching certain patterns, so that system administrators who do\nnot wish these directories in
-(TT
--/usr/local
-)TT
-- do not need to have\nthem.\n
-L627
-)P
-)SECT1
-)SECT
-AID IMPLIED
-ASRID CDATA s3.3
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .3
-AHNAME CDATA section 3.3
-(SECT
-(HEADING
--Permissions and ownerships
-L628
-)HEADING
-(P
-L629
--\nThe rules in this section are guidelines for general use. If\nnecessary you may deviate from the details below. However, if you do\nso you must make sure that what is done is secure and you must try to\nbe as consistent as possible with the rest of the system. You should\nprobably also discuss it on
-(PRGN
--debian-devel
-)PRGN
-- first.
-L635
-)P
-(P
-L636
--\nFiles should be owned by
-(TT
--root.root
-)TT
--, and made writeable only by\nthe owner and universally readable (and executable, if appropriate).
-L639
-)P
-(P
-L640
--\nDirectories should be mode 755 or (for group-writability) mode 2775.\nThe ownership of the directory should be consistent with its mode -\nif a directory is mode 2775, it should be owned by the group that\nneeds write access to it.
-L645
-)P
-(P
-L646
--\nSetuid and setgid executables should be mode 4755 or 2755\nrespectively, and owned by the appropriate user or group. They should\nnot be made unreadable (modes like 4711 or 2711 or even 4111); doing\nso achieves no extra security, because anyone can find the binary in\nthe freely available Debian package - it is merely inconvenient. For\nthe same reason you should not restrict read or execute permissions on\nnon-set-id executables.
-L654
-)P
-(P
-L655
--\nSome setuid programs need to be restricted to particular sets of\nusers, using file permissions. In this case they should be owned by\nthe uid to which they are set-id, and by the group which should be\nallowed to execute them. They should have mode 4754; there is no\npoint in making them unreadable to those users who must not be allowed\nto execute them.
-L662
-)P
-(P
-L663
--\nDo not arrange that the system administrator can only reconfigure the\npackage to correspond to their local security policy by changing the\npermissions on a binary. Ordinary files installed by
-(PRGN
--dpkg
-)PRGN
-- (as\nopposed to conffiles and other similar objects) have their permissions\nreset to the distributed permissions when the package is reinstalled.\nInstead you should consider (for example) creating a group for people\nallowed to use the program(s) and making any setuid executables\nexecutable only by that group.
-L672
-)P
-(P
-L673
--\nShared libraries should be installed executable.\n
-L676
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .4
-AHNAME CDATA section 3.4
-(SECT
-(HEADING
--Configuration files
-L677
-)HEADING
-(P
-L678
--\nAny configuration files created or used by your package should reside\nin
-(TT
--/etc
-)TT
--. If there are several you should consider creating a\nsubdirectory named after your package.
-L682
-)P
-(P
-L683
--\nIt is almost certain that any file in
-(TT
--/etc
-)TT
-- that is in your\npackage's filesystem archive should be listed in
-(PRGN
--dpkg
-)PRGN
--'s\n
-(TT
--conffiles
-)TT
-- control area file. (See the
-(PRGN
--dpkg
-)PRGN
-- programmers'\nmanual).\n
-L689
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.5
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .5
-AHNAME CDATA section 3.5
-(SECT
-(HEADING
--Maintainer scripts
-L690
-)HEADING
-(P
-L691
--\nThe package installation scripts should avoid producing output which\nit is unnecessary for the user to see and should rely on
-(PRGN
--dpkg
-)PRGN
-- to\nstave off boredom on the part of a user installing many packages.\nThis means, amongst other things, using the
-(TT
----quiet
-)TT
-- option on\n
-(PRGN
--install-info
-)PRGN
--.
-L697
-)P
-(P
-L698
--\nPackages should try to minimise the amount of prompting they need to\ndo, and they should ensure that the user will only every be asked each\nquestion once. This means that packages should try to use appropriate\nshared configuration files (such as
-(TT
--/etc/papersize
-)TT
-- and\n
-(TT
--/etc/news/server
-)TT
--, rather than each prompting for their own\nlist of required pieces of information.
-L705
-)P
-(P
-L706
--\nIt also means that an upgrade should not ask the same questions again,\nunless the user has used
-(TT
--dpkg --purge
-)TT
-- to remove the package's\nconfiguration. The answers to configuration questions should be\nstored in an appropriate place in
-(TT
--/etc
-)TT
-- so that the user can\nmodify them, and how this has been done should be documented.
-L712
-)P
-(P
-L713
--\nIf a package has a vitally important piece of information to pass to\nthe user (such as "don't run me as I am, you must edit the following\nconfiguration files first or you risk your system emitting\nbadly-formatted messages"), it should display this in the\n
-(PRGN
--postinst
-)PRGN
-- script and prompt the user to hit return to\nacknowledge the message. Copyright messages do not count as vitally\nimportant (they belong in
-(TT
--/usr/doc/copyright
-)TT
--); neither do\ninstructions on how to use a program (these should be in on line\ndocumentation, where all the users can see them).
-L723
-)P
-(P
-L724
--\nAny necessary prompting should almost always be confined to the\npost-installation script, and should be protected with a conditional\nso that unnecssary prompting doesn't happen if a package's\ninstallation fails and the
-(PRGN
--postinst
-)PRGN
-- is called with\n
-(TT
--abort-upgrade
-)TT
--,
-(TT
--abort-remove
-)TT
-- or
-(TT
--abort-deconfigure
-)TT
--.
-L730
-)P
-(P
-L731
--\nErrors which occur during the execution of an installation script\n
-(EM
--must
-)EM
-- be checked and the installation
-(EM
--must not
-)EM
-- continue after\nan error.
-L735
-)P
-(P
-L736
--\nThe section below on scripts in general applies to package maintainer\nscripts too.\n
-L740
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.6
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .6
-AHNAME CDATA section 3.6
-(SECT
-(HEADING
--Scripts in general
-L741
-)HEADING
-(P
-L742
--\nAll command scripts, including the package maintainer scripts inside\nthe package and used by
-(PRGN
--dpkg
-)PRGN
--, should have a
-(TT
--#!
-)TT
-- line naming\nthe shell to be used to interpret them.
-L746
-)P
-(P
-L747
--\nIn the case of Perl scripts this should be
-(TT
--#!/usr/bin/perl
-)TT
--.
-L749
-)P
-(P
-L750
--\nShell scripts (
-(PRGN
--sh
-)PRGN
-- and
-(PRGN
--bash
-)PRGN
--) should almost certainly\nstart with
-(TT
--set -e
-)TT
-- so that errors are detected. Every script\n
-(EM
--must
-)EM
-- use
-(TT
--set -e
-)TT
-- or check the exit status of
-(EM
--every
-)EM
--\ncommand.
-L755
-)P
-(P
-L756
--\nPerl scripts should check for errors when making any system calls,\nincluding
-(TT
--open
-)TT
--,
-(TT
--print
-)TT
--,
-(TT
--close
-)TT
--,
-(TT
--rename
-)TT
-- and\n
-(TT
--system
-)TT
--.
-L760
-)P
-(P
-L761
--\n
-(PRGN
--csh
-)PRGN
-- and
-(PRGN
--tcsh
-)PRGN
-- should be avoided as scripting languages. See\nCsh Programming Considered Harmful, one of the
-(TT
--comp.unix.*
-)TT
-- FAQs.\nIf an upstream package comes with
-(PRGN
--csh
-)PRGN
-- scripts then you must make\nsure that they start with
-(TT
--#!/bin/csh
-)TT
-- and make your package\ndepend on
-(PRGN
--csh
-)PRGN
--.
-L767
-)P
-(P
-L769
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.7
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .7
-AHNAME CDATA section 3.7
-(SECT
-(HEADING
--Compilation options
-L770
-)HEADING
-(P
-L771
--\nGenerally the following compilation parameters should be used:\n
-(EXAMPLE
-L774
--CC = gcc\nCFLAGS = -O2 -g -Wall # sane warning options vary between programs\nLDFLAGS = # none\ninstall -s # (or use strip on the files in debian/tmp)
-L778
-)EXAMPLE
-L779
-)P
-(P
-L780
--\nNote that all installed binaries should be stripped, either by using\nthe
-(TT
---s
-)TT
-- flag to
-(PRGN
--install
-)PRGN
--, or by calling
-(PRGN
--strip
-)PRGN
-- on the\nbinaries after they have been copied into
-(TT
--debian/tmp
-)TT
-- but\nbefore the tree is made into a package.
-L785
-)P
-(P
-L786
--\nMake sure that you do not link with
-(TT
---g
-)TT
--, as this makes a.out\ncompilers produce huge statically linked binaries. The
-(TT
---g
-)TT
-- flag\nis useful on compilation so that you have available a full set of\ndebugging symbols in your built source tree, in case anyone should\nfile a bug report involving (for example) a core dump.
-L792
-)P
-(P
-L793
--\nThe
-(TT
---N
-)TT
-- flag should not be used. On a.out systems it may have\nbeen useful for some very small binaries, but for ELF it has no good\neffect.
-L797
-)P
-(P
-L798
--\nIt is up to the package maintainer to decide what compilation options\nare best for the package. Certain binaries (such as\ncomputationally-intensive programs) may function better with certain\nflags (
-(TT
---O3
-)TT
--, for example); feel free to use them. Please use good\njudgment here. Don't use flags for the sake of it; only use them if\nthere is good reason to do so. Feel free to override the upstream\nauthor's ideas about which compilation options are best - they are\noften inappropriate for our environment.
-L807
-)P
-(P
-L808
--\nPlease make sure that you use only released versions of shared\nlibraries to build your packages; otherwise other users will not be\nable to run your binaries properly. Producing source packages that\ndepend on unreleased compilers is also usually a bad idea.\n
-L814
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.8
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .8
-AHNAME CDATA section 3.8
-(SECT
-(HEADING
--Shared library packages
-L815
-)HEADING
-(P
-L816
--\nPackages involving shared libraries should be split up into several\nbinary packages.
-L819
-)P
-(P
-L820
--\nFor a straightforward library which has a development environment and\na runtime kit including just shared libraries you need to create two\npackages:
-(TT
-(VAR
--libraryname
-)VAR
-(VAR
--soname
-)VAR
-)TT
-(FOOTNOTE
-(P
-(VAR
--soname
-)VAR
-- is\nthe shared object name of the shared library - it's the thing that has\nto match exactly between building an executable and running it for the\ndynamic linker to be able run the program. Usually the
-(VAR
--soname
-)VAR
--\nis the major number of the library.
-)P
-)FOOTNOTE
-- and\n
-(TT
-(VAR
--libraryname
-)VAR
-(VAR
--soname
-)VAR
---dev
-)TT
--.
-L829
-)P
-(P
-L830
--\nIf you prefer only to support one development version time you may\nname the development package
-(TT
-(VAR
--libraryname
-)VAR
---dev
-)TT
--; otherwise you\nmay wish to use
-(PRGN
--dpkg
-)PRGN
--'s conflicts mechanism to ensure that the\nuser only installs one development version at a time (after all,\ndifferent development versions are likely to have the same header\nfiles in them, causing a filename clash if both are installed).\nTypically the development version will also need an exact version\ndependency on the runtime library, to make sure that compilation and\nlinking happens correctly.
-L840
-)P
-(P
-L841
--\nPackages which use the shared library should have a dependency on the\nname of the shared library package,\n
-(TT
-(VAR
--libraryname
-)VAR
-(VAR
--soname
-)VAR
-)TT
--. When the
-(VAR
--soname
-)VAR
-- changes you\ncan have both versions of the library installed while moving from the\nold library to the new.
-L847
-)P
-(P
-L848
--\nIf your package has some run-time support programs which use the\nshared library you must
-(EM
--not
-)EM
-- put them in the shared library\npackage. If you do that then you won't be able to install several\nversions of the shared library without getting filename clashes.\nInstead, either create a third package for the runtime binaries (this\npackage might typically be named
-(TT
-(VAR
--libraryname
-)VAR
---runtime
-)TT
-- - note\nthe absence of the
-(VAR
--soname
-)VAR
-- in the package name) or if the\ndevelopment package is small include them in there.
-L857
-)P
-(P
-L858
--\nIf you have several shared libraries built from the same source tree\nyou can lump them all togther into a single shared library package,\nprovided that you change all their
-(VAR
--soname
-)VAR
--s at once (so that you\ndon't get filename clashes if you try to install different versions of\nthe combined shared libraries package).
-L864
-)P
-(P
-L865
--\nFollow the directions in the
-(PRGN
--dpkg
-)PRGN
-- programmers' manual for\nputting the shared library in its package, and make sure you include a\n
-(TT
--shlibs
-)TT
-- control area file with details of the dependencies for\npackages which use the library.\n
-L871
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.9
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .9
-AHNAME CDATA section 3.9
-(SECT
-(HEADING
--Application configuration files, dotfiles and
-(TT
--/etc/skel
-)TT
-L872
-)HEADING
-(P
-L873
--\nFiles in
-(TT
--/etc/skel
-)TT
-- will automatically be copied into new user\naccounts by
-(PRGN
--adduser
-)PRGN
--. They should not be referenced there by\nany program.
-L877
-)P
-(P
-L878
--\nTherefore, if a program needs a dotfile to exist in advance in\n
-(TT
--$HOME
-)TT
-- to work sensibly that dotfile should be installed in\n
-(TT
--/etc/skel
-)TT
-- (and listed in conffiles, if it is not generated and\nmodified dynamically by the package's installation scripts).
-L883
-)P
-(P
-L884
--\nHowever, programs that require dotfiles in order to operate sensibly\n(dotfiles that they do not create themselves automatically, that is)\nare a bad thing, and programs should be configured by the Debian\ndefault installation as close to normal as possible.
-L889
-)P
-(P
-L890
--\nTherefore, if a program in a Debian package needs to be configured in\nsome way in order to operate sensibly that configuration should be\ndone in a site-wide global configuration file elsewhere in\n
-(TT
--/etc
-)TT
--. Only if the program doesn't support a site-wide default\nconfiguration and the package maintainer doesn't have time to add it\nshould a default per-user file be placed in
-(TT
--/etc/skel
-)TT
--.
-L897
-)P
-(P
-L898
--\n
-(TT
--/etc/skel
-)TT
-- should be as empty as we can make it. This is\nparticularly true because there is no easy mechanism for ensuring that\nthe appropriate dotfiles are copied into the accounts of existing\nusers when a package is installed.
-L903
-)P
-(P
-L904
--\nIdeally the sysadmin should ideally not have to do any configuration\nother than that done (semi-)automatically by the postinst script.\n
-L908
-)P
-)SECT
-AID CDATA mail
-ASRID CDATA s-mail
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .10
-AHNAME CDATA section 3.10
-(SECT
-(HEADING
--Mail processing on Debian systems
-L909
-)HEADING
-(P
-L910
--\nDebian packages which process electronic mail, whether\nmail-user-agents (MUAs) or mail-transport-agents (MTAs),
-(EM
--must
-)EM
--\nmake sure that they are compatible with the configuration decisions\nbelow. Failure to do this may result in lost mail, broken
-(TT
--From:
-)TT
--\nlines, and other serious brain damage!
-L916
-)P
-(P
-L917
--\nThe mail spool is
-(TT
--/var/spool/mail
-)TT
-- and the interface to send a\nmail message is
-(TT
--/usr/sbin/sendmail
-)TT
-- (as per the FSSTND). The\nmail spool is part of the base system and not part of the MTA package.
-L921
-)P
-(P
-L922
--\nMailboxes are locked using the
-(TT
-(VAR
--username
-)VAR
--.lock
-)TT
-- lockfile\nconvention, rather than
-(PRGN
--fcntl
-)PRGN
--,
-(PRGN
--flock
-)PRGN
-- or
-(PRGN
--lockf
-)PRGN
--.
-L925
-)P
-(P
-L926
--\nMailboxes are generally 660
-(TT
-(VAR
--user
-)VAR
--.mail
-)TT
-- unless the user has\nchosen otherwise. A MUA may remove a mailbox (unless it has\nnonstandard permissions) in which case the MTA or another MUA must\nrecreate it if needed. Mailboxes must be writeable by group mail.
-L931
-)P
-(P
-L932
--\nThe mail spool is 2775
-(TT
--mail.mail
-)TT
--, and MUA's need to be setgid\nmail to do the locking mentioned above (and obviously need to avoid\naccessing other users' mailboxes using this privilege).
-L936
-)P
-(P
-L937
--\n
-(TT
--/etc/aliases
-)TT
-- is the source file for the system mail aliases\n(e.g. postmaster, usenet, etc.) - it is the one which the sysadmin\nand postinst scripts may edit. After
-(TT
--/etc/aliases
-)TT
-- is edited\nthe program or human editing it must call
-(PRGN
--newaliases
-)PRGN
--. All MTA\npackages should come with a
-(PRGN
--newaliases
-)PRGN
-- program, even if it does\nnothing, but older MTA packages do not do this so programs should not\nfail if
-(PRGN
--newaliases
-)PRGN
-- cannot be found.
-L945
-)P
-(P
-L946
--\nThe convention of writing
-(TT
--forward to
-(VAR
--address
-)VAR
-)TT
-- in the mailbox\nitself is not supported. Use a
-(TT
--.forward
-)TT
-- file instead.
-L949
-)P
-(P
-L950
--\nThe location for the
-(PRGN
--rmail
-)PRGN
-- program used by UUCP for incoming\nmail is
-(TT
--/usr/sbin/rmail
-)TT
--, as per the FSSTND. Likewise,\n
-(PRGN
--rsmtp
-)PRGN
--, for receiving batch-SMTP-over-UUCP, is in\n
-(TT
--/usr/sbin/rsmtp
-)TT
-- if it is supported.
-L955
-)P
-(P
-L956
--\nIf you need to know what name to use (for example) on outgoing news\nand mail messages which are generated locally, you should use the file\n
-(TT
--/etc/mailname
-)TT
--. It will contain the portion after the username\nand
-(TT
--@
-)TT
-- (at) sign for email addresses of users on the machine\n(followed by a newline).
-L962
-)P
-(P
-L963
--\nA package should check for the existence of this file. If it exists\nit should use it without comment.
-(FOOTNOTE
-(P
--An MTA's prompting\nconfiguration script may wish to prompt the user even if it finds this\nfile exists.
-)P
-)FOOTNOTE
-- If it does not exist it should prompt the user\nfor the value and store it in
-(TT
--/etc/mailname
-)TT
-- as well as using it\nin the package's configuration. The prompt should make it clear that\nthe name will not just be used by that package. E.g., in this\nsituation the INN package says:\n
-(EXAMPLE
-L973
--Please enter the `mail name' of your system. This is the hostname\nportion of the address to be shown on outgoing news and mail messages.\nThe default is
-(VAR
--syshostname
-)VAR
--, your system's host name.\nMail name [`
-(VAR
--syshostname
-)VAR
--']:
-L977
-)EXAMPLE
--\nwhere
-(VAR
--syshostname
-)VAR
-- is the output of
-(TT
--hostname -fqdn
-)TT
--.\n\n
-L981
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.11
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .11
-AHNAME CDATA section 3.11
-(SECT
-(HEADING
--Packages which can use the X shared libraries
-L982
-)HEADING
-(P
-L983
--\nSome programs can be configured with or without support for X Windows.\nTypically these binaries produced when configured for X will need the\nX shared libraries to run.
-L987
-)P
-(P
-L988
--\nSuch programs should be configured
-(EM
--with
-)EM
-- X support, and should\ndeclare a dependency on
-(TT
--elf-x11r6lib
-)TT
-- (for the X11R6 libraries).\nUsers who wish to use the program can install just the relatively\nsmall
-(TT
--xlib
-)TT
-- package, and do not need to install the whole of X.
-L993
-)P
-(P
-L994
--\nDo not create two versions (one with X support and one without) of\nyour package.\n\n
-L999
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.12
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .12
-AHNAME CDATA section 3.12
-(SECT
-(HEADING
--Games
-L1000
-)HEADING
-(P
-L1001
--\nThe permissions on /var/lib/games are 755
-(TT
--root.root
-)TT
--.
-L1003
-)P
-(P
-L1004
--\nEach game decides on its own security policy.
-L1006
-)P
-(P
-L1007
--\nGames which require protected, privileged access to high-score files,\nsavegames, \|&\|c, must be made set-
-(EM
--group
-)EM
---id (mode 2755) and\nowned by
-(TT
--root.games
-)TT
--, and use files and directories with\nappropriate permissions (770
-(TT
--root.games
-)TT
--, for example). They must\n
-(EM
--not
-)EM
-- be made set-
-(EM
--user
-)EM
---id, as this causes security\nproblems.
-(FOOTNOTE
-(P
--If an attacker can subvert any set-user-id game\nthey can overwrite the executable of any other, causing other players\nof these cames to run a trojan. With a set-group-id game the attacker\nonly gets access to less important game data, and if they can get at\nthe other players' accounts at all it will take considerably more\neffort.
-)P
-)FOOTNOTE
-L1019
-)P
-(P
-L1020
--\nSome packages, for example some fortune cookie programs, are\nconfigured by the upstream authors to install with their data files or\nother static information made unreadable so that they can only be\naccessed through set-id programs provided. Do not do this in a Debian\npackage: anyone can download the
-(TT
--.deb
-)TT
-- file and read the data from\nit, so there is no point making the files unreadable. Not making the\nfiles unreadable also means that you don't have to make so many\nprograms set-id, which reduces the risk of a security hole.\n
-L1030
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.13
-ACHAPT CDATA 3
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .13
-AHNAME CDATA section 3.13
-(SECT
-(HEADING
--Allocating package-specific users and groups
-L1031
-)HEADING
-(P
-L1032
--\nIf you need to create a new user or group for your package there are\ntwo possibilities. Firstly, you may need to make some files in the\nbinary package be owned by this user or group, or you may need to\ncompile the user or group id (rather than just the name) into the\nbinary (though this latter should be avoided if possible). In this\ncase you need a statically allocated id.
-L1039
-)P
-(P
-L1040
--\nYou must ask for a user or group id from the base system maintainer,\nand must not release the package until you have been allocated one.\nOnce you have been allocated one you must make the package depend\non a version of the base system with the id present in\n
-(TT
--/etc/passwd
-)TT
-- or
-(TT
--/etc/group
-)TT
--, or alternatively arrange\nfor your package to create the user or group itself with the correct\nid (using
-(TT
--adduser
-)TT
--) in its pre- or post-installation script (the\nlatter is to be preferred if it is possible).
-L1049
-)P
-(P
-L1050
--\nOn the other hand, the program may able to determine the uid or gid\nfrom the group name at runtime, so that a dynamic id can be used. In\nthis case you must choose an appropriate user or group name,\ndiscussing this on
-(PRGN
--debian-devel
-)PRGN
-- and checking with the base system\nmaintainer that it is unique and that they do not wish you to use a\nstatically allocated id instead. When this has been checked you must\narrange for your package to create the user or group if necessary\nusing
-(PRGN
--adduser
-)PRGN
-- in the pre- or post-installation script (again, the\nlatter is to be preferred if it is possible).
-L1060
-)P
-(P
-L1061
--\nNote that changing the numeric value of an id associated with a name\nis very difficult, and involves searching the filesystem for all\nappropriate files. You need to think carefully whether a static or\ndynamic id is required, since changing your mind later will cause\nproblems.\n
-L1068
-)P
-)SECT
-)CHAPT
-AID CDATA sourcepkg
-ASRID CDATA ch-sourcepkg
-ACHAPT CDATA 4
-ASECT IMPLIED
-AHNAME CDATA chapter 4
-(CHAPT
-(HEADING
--Source package\n
-L1070
-)HEADING
-AID IMPLIED
-ASRID CDATA s4.1
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1
-AHNAME CDATA section 4.1
-(SECT
-(HEADING
--Releases of packages by other than the usual Debian maintainer
-L1071
-)HEADING
-(P
-L1072
--\nUnder certain circumstances it is necessary for someone other than the\nusual package maintainer to make a release of a package. For example,\na porter for another architecture may have to make some small changes\nto the source package and does not wish to wait with uploading their\nrelease until the main maintainer has incorporated the patch, or a\nserious security problem may have come to light requiring immediate\nattention.
-L1080
-)P
-(P
-L1081
--\nMaintainers other than the usual package maintainer should make as few\nchanges to the package as possible, and they should always send a\nunified context diff (
-(TT
--diff -u
-)TT
--) detailing their changes to the bug\ntracking system properly flagged with the correct package so that the\nusual maintainer is kept aware of the situation.
-L1087
-)P
-(P
-L1088
--\nWhen someone other than the usual maintainer releases a package they\nshould add a new component to the
-(VAR
--debian-revision
-)VAR
-- component of\nthe version number - that is, the portion after the (last) hyphen.\nThis extra component will start at
-(TT
--1
-)TT
--. This is to avoid\n`stealing' one of the usual maintainer's version numbers, possibly\ndisrupting their work. If there is no
-(VAR
--debian-revision
-)VAR
-- component\nin the version number then one should be created, starting at
-(TT
--1
-)TT
--.
-L1096
-)P
-(P
-L1097
--\nIf it is absolutely necessary for someone other than the usual\nmaintainer to make a release based on a new upstream version then the\nperson making the release should start with the
-(VAR
--debian-revision
-)VAR
--\nvalue
-(TT
--0.1
-)TT
--. The usual maintainer of a package should start their\n
-(VAR
--debian-revision
-)VAR
-- numbering at
-(TT
--1
-)TT
--.\n\n
-L1105
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s4.2
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2
-AHNAME CDATA section 4.2
-(SECT
-(HEADING
--Standards conformance and
-(TT
--Standards-Version
-)TT
-L1106
-)HEADING
-(P
-L1107
--\nYou should specify the most recent version of the packaging standards\nwith which your package complies in the source package's\n
-(TT
--Standards-Version
-)TT
-- field.
-L1111
-)P
-(P
-L1112
--\nThis value will be used to file bug reports automatically if your\npackage becomes too much out of date.
-L1115
-)P
-(P
-L1116
--\nThe value corresponds to a version of the Debian manuals, as can be\nfound on the title page or page headers and footers (depending on the\nformat). The value for this version of the manuals and packaging\nstandards is
-(TT
--0.2.0.0
-)TT
--.
-L1121
-)P
-(P
-L1122
--\nThe version number has four components - major and minor number and\nmajor and minor patchlevel. When the standards change in a way that\nrequires every package to change the major number will be changed.\nSignificant changes that will require work in many packages will be\nsignaled by a change to the minor number. The major patchlevel will\nbe changed for any change to the meaning of the standards, however\nsmall; the minor patchlevel will be changed when only cosmetic,\ntypographical or other edits which do not change the meaning are made.
-L1131
-)P
-(P
-L1132
--\nYou should regularly, and especially if your package has become out of\ndate, install the most recent version of dpkg and read\n
-(TT
--/usr/doc/dpkg/changelog-manuals
-)TT
-- to see which changes, if any,\nare relevant. If any are relevant you should look up the relevant\nsection in the policy or programmers' manuals and update your package.\nWhen your package complies with the new standards you may update the\n
-(TT
--Standards-Version
-)TT
-- source package field and release it.\n\n
-L1142
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s4.3
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .3
-AHNAME CDATA section 4.3
-(SECT
-(HEADING
--Documentation and the
-(TT
--changelog
-)TT
-L1143
-)HEADING
-(P
-L1144
--\nDocument your changes and updates to the source package properly in\nthe
-(TT
--debian/changelog
-)TT
-- file.
-L1147
-)P
-(P
-L1148
--\nA copy of the file which will be installed in\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
-- should be in\n
-(TT
--debian/copyright
-)TT
--.
-L1152
-)P
-(P
-L1153
--\nIn non-experimental packages you may only use a format for\n
-(TT
--debian/changelog
-)TT
-- which is supported by the most recent released\nversion of
-(PRGN
--dpkg
-)PRGN
--. If your format is not supported and there is\ngeneral support for it you should contact the
-(PRGN
--dpkg
-)PRGN
-- maintainer\nto have the parser script for your format included in the
-(PRGN
--dpkg
-)PRGN
--\npackage.
-(FOOTNOTE
-(P
--You will need to agree that the parser and its\nmanpage may be distributed under the GNU GPL, just as the rest of\n
-(PRGN
--dpkg
-)PRGN
-- is.
-)P
-)FOOTNOTE
--\n
-L1163
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s4.4
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .4
-AHNAME CDATA section 4.4
-(SECT
-(HEADING
--Changes to the upstream sources
-L1164
-)HEADING
-(P
-L1165
--\nIf you need to edit a
-(PRGN
--Makefile
-)PRGN
-- where GNU-style
-(PRGN
--configure
-)PRGN
--\nscripts are used, you should edit the
-(TT
--.in
-)TT
-- files rather than\nediting the
-(PRGN
--Makefile
-)PRGN
-- directly. This allows the user to\nreconfigure the package if necessary. You should
-(EM
--not
-)EM
-- configure\nthe package and edit the generated
-(PRGN
--Makefile
-)PRGN
--! This makes it\nimpossible for someone else to later reconfigure the package.
-L1172
-)P
-(P
-L1173
--\nIf changes to the source code are made that are generally applicable\nplease try to get them included in the upstream version of the package\nby supplying the upstream authors with the changes in whatever form\nthey prefer.
-L1178
-)P
-(P
-L1179
--\nIf you need to configure the package differently for Debian or for\nLinux, and the upstream source doesn't provide a way to configure it\nthe way you need to, please add such configuration facilities (for\nexample, a new
-(PRGN
--autoconf
-)PRGN
-- test or
-(TT
--#define
-)TT
--) and send the\npatch to the upstream authors, with the default set to the way they\noriginally had it. You can then easily override the default in your\n
-(TT
--debian/rules
-)TT
-- or wherever is appropriate.\n
-L1188
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s4.5
-ACHAPT CDATA 4
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .5
-AHNAME CDATA section 4.5
-(SECT
-(HEADING
--Error trapping in makefiles
-L1189
-)HEADING
-(P
-L1190
--\nWhen
-(PRGN
--make
-)PRGN
-- invokes a command in a makefile (including your\npackage's upstream makefiles and the
-(TT
--debian/rules
-)TT
--) it does so\nusing
-(TT
--sh
-)TT
--. This means that
-(TT
--sh
-)TT
--'s usual bad error handling\nproperties apply: if you include a miniature script as one of the\ncommands in your makefile you'll find that if you don't do anything\nabout it then errors are not detected and
-(PRGN
--make
-)PRGN
-- will blithely\ncontinue after problems.
-L1198
-)P
-(P
-L1199
--\nEvery time you put more than one shell command (this includes using a\nloop) in a makefile command you
-(EM
--must
-)EM
-- make sure that errors are\ntrapped. For simple compound commands, such as changing directory and\nthen running a program, using
-(TT
--\|&\|\|&\|
-)TT
-- rather than semicolon as\na command separator is sufficient. For more complex commands\nincluding most loops and conditionals you must include a separate\n
-(TT
--set -e
-)TT
-- command at the start of every makefile command that's\nactually one of these miniature shellscripts.\n
-L1209
-)P
-)SECT
-)CHAPT
-AID CDATA developer
-ASRID CDATA ch-developer
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(CHAPT
-(HEADING
--How to become a Debian developer\n
-L1211
-)HEADING
-AID IMPLIED
-ASRID CDATA s5.1
-ACHAPT CDATA 5
-ACSRID CDATA ch-developer
-ASECT CDATA .1
-AHNAME CDATA section 5.1
-(SECT
-(HEADING
--Before you start work
-L1212
-)HEADING
-(P
-L1213
--\nSo, you've read all the documentation, you understand what everything\nin the
-(PRGN
--hello
-)PRGN
-- example package is for, and you're about to\nDebianise your favourite package. How do you actually become a Debian\ndeveloper so that your work can be incorporated into the Project?
-L1218
-)P
-(P
-L1219
--\nFirstly, subscribe to
-(PRGN
--debian-devel
-)PRGN
-- if you haven't already.\nSend the word
-(TT
--subscribe
-)TT
-- in the
-(EM
--Subject
-)EM
-- of a mail to\n
-(EMAIL
--debian-devel-REQUEST@lists.debian.org
-)EMAIL
--. In case of problems\ncontact the list administrator, Anders Chrigstrom
-(EMAIL
--ac@netg.se
-)EMAIL
--.
-L1224
-)P
-(P
-L1225
--\nYou should to subscribe and lurk for a bit before doing any coding,\nand you should post about your intentions to work on something to\navoid duplicated effort.
-L1229
-)P
-(P
-L1230
--\nIf you do not have a PGP key yet generate one. You should probably\nread the PGP manual, as it has much important information which is\ncritical to its security. Many more security failures are due to\nhuman error than to software failure or high-powered spy techniques.
-L1235
-)P
-(P
-L1236
--\nIf you live in a country where use of cryptography even for signing is\nforbidden then please contact us so we can make special arrangements.\nThis does not apply in France, where I believe only encryption and not\nsigning is forbidden.\n
-L1242
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s5.2
-ACHAPT CDATA 5
-ACSRID CDATA ch-developer
-ASECT CDATA .2
-AHNAME CDATA section 5.2
-(SECT
-(HEADING
--When you have a package to upload
-L1243
-)HEADING
-(P
-L1244
--\nWhen you have your package ready to be uploaded you must send a\nmessage to the project leader, Bruce Perens
-(EMAIL
--bruce@pixar.com
-)EMAIL
--,\nthe administrator of
-(TT
--master.debian.org
-)TT
--, Simon Shapiro\n
-(EMAIL
--shimon@i-connect.net
-)EMAIL
--, the mailing list administrator, Anders\nChrigstrom
-(EMAIL
--ac@netg.se
-)EMAIL
-- and the
-(PRGN
--dpkg
-)PRGN
-- maintainer, Ian\nJackson
-(EMAIL
--ijackson@gnu.ai.mit.edu
-)EMAIL
--.
-L1251
-)P
-(P
-L1252
--\nThe message should say what you've done and who you are, and should\nask for an account on
-(PRGN
--master
-)PRGN
-- and to be subscribed to\n
-(PRGN
--debian-private
-)PRGN
-- (the developers-only mailing list). It should\ncontain your PGP key (extracted using
-(TT
--pgp -kxa
-)TT
--) for the database\nof keys which is shipped with
-(PRGN
--dpkg
-)PRGN
--.\n\nWhen you have your personal account on
-(PRGN
--master
-)PRGN
-- log in and\ntransfer the files to\n
-(TT
--/home/Debian/ftp/private/project/Incoming
-)TT
--. You cannot upload\nto
-(PRGN
--Incoming
-)PRGN
-- on
-(PRGN
--master
-)PRGN
-- using anonymous FTP.
-L1263
-)P
-(P
-L1264
--\nYou can also upload files to
-(PRGN
--Incoming
-)PRGN
-- via a
-(PRGN
--cron
-)PRGN
---driven\nupload queue in Europe on
-(FTPSITE
--chiark.chu.cam.ac.uk
-)FTPSITE
--. For details\nconnect to
-(PRGN
--chiark
-)PRGN
-- using anonymous FTP and read\n
-(FTPPATH
--/pub/debian/private/project/README.how-to-upload
-)FTPPATH
--.\n
-L1270
-)P
-)SECT
-AID CDATA changesfiles
-ASRID CDATA s-changesfiles
-ACHAPT CDATA 5
-ACSRID CDATA ch-developer
-ASECT CDATA .3
-AHNAME CDATA section 5.3
-(SECT
-(HEADING
--Upload handling -
-(TT
--.changes
-)TT
-- files
-L1271
-)HEADING
-(P
-L1272
--\nWhen a package is uploaded to the Debian FTP archive, it must be\naccompanied by a
-(TT
--.changes
-)TT
-- file which gives directions for its\nhandling. This is usually generated by
-(PRGN
--dpkg-genchanges
-)PRGN
--.
-L1276
-)P
-(P
-L1277
--\nThis file is a control file with the following fields:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1280
-(ITEM
-(P
-(TT
--Format
-)TT
-L1281
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Date
-)TT
-L1282
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Source
-)TT
-L1283
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Binary
-)TT
-L1284
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Architecture
-)TT
-L1285
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Version
-)TT
-L1286
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Distribution
-)TT
-L1287
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Urgency
-)TT
-L1288
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Maintainer
-)TT
-L1289
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Description
-)TT
-L1290
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Changes
-)TT
-L1291
-)P
-)ITEM
-(ITEM
-(P
-(TT
--Files
-)TT
-L1292
-)P
-)ITEM
-)LIST
-L1293
-)P
-(P
-L1294
--\nAll of them are mandatory for a Debian upload. See the list of\ncontrol fields in the
-(PRGN
--dpkg
-)PRGN
-- programmers' manual for the contents\nof these fields.\n\n
-L1300
-)P
-)SECT
-)CHAPT
-AID CDATA mailinglists
-ASRID CDATA ch-mailinglists
-ACHAPT CDATA 6
-ASECT IMPLIED
-AHNAME CDATA chapter 6
-(CHAPT
-(HEADING
--The Debian mailing lists
-L1301
-)HEADING
-(P
-L1302
--\nThe mailing list server is at
-(TT
--lists.debian.org
-)TT
--. Mail\n
-(TT
--debian-
-(VAR
--foo
-)VAR
---REQUEST@lists.debian.org
-)TT
-(FOOTNOTE
-(P
--where\n
-(TT
--debian-
-(VAR
--foo
-)VAR
-)TT
-- is the name of the list
-)P
-)FOOTNOTE
-- with the word\n
-(TT
--subscribe
-)TT
-- in the Subject to subscribe or
-(TT
--unsubscribe
-)TT
-- to\nunsubscribe.
-L1308
-)P
-(P
-L1309
--\nWhen replying to messages on the mailing list, please do not send a\ncarbon copy (
-(TT
--CC
-)TT
-- - this does not mean `courtesy copy') to the\noriginal poster. Anyone who posts to a mailing list should read it to\nsee the responses.
-L1314
-)P
-(P
-L1315
--\nAs ever on the net, please trim down the quoting of articles you're\nreplying to.\n\n
-L1320
-)P
-)CHAPT
-AID CDATA conversion
-ASRID CDATA ch-conversion
-ACHAPT CDATA 7
-ASECT IMPLIED
-AHNAME CDATA chapter 7
-(CHAPT
-(HEADING
--Conversion procedure from old source packages
-L1321
-)HEADING
-(P
-L1322
--\nThis is a brief summary of the procedure for converting a\npre-2.0.0.0-format source package into the new format.
-L1325
-)P
-(P
-L1326
--\nYou are strongly advised to download and examine the
-(PRGN
--hello
-)PRGN
--\npackage, and to read the section in the
-(PRGN
--dpkg
-)PRGN
-- programmers'\nmanual describing the source packaging tools. More detail about the\nexact functionality of these tools is available in
-ANAME CDATA dpkg-source
-ASECTION CDATA 1
-(MANREF
-)MANREF
-L1331
--.
-L1332
-)P
-(P
-L1333
--\n
-ACOMPACT IMPLIED
-(LIST
-L1336
-(ITEM
-L1337
-(P
--Download the original source code from wherever it can be found and do\nany rearrangement required to make it look like the original tree of\nthe Debian source. Put it in\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--upstream-version
-)VAR
--.orig/
-)TT
-- or\n
-(TT
-(VAR
--package
-)VAR
--_
-(VAR
--upstream-version
-)VAR
--.orig.tar.gz
-)TT
--.\n
-L1343
-)P
-)ITEM
-(ITEM
-L1344
-(P
--Rename all files
-(TT
--debian.*
-)TT
-- to
-(TT
--debian/*
-)TT
--. There may be some\nexceptions to this, but this is a good start.\n
-L1347
-)P
-)ITEM
-(ITEM
-L1348
-(P
--Edit the
-(TT
--debian/changelog
-)TT
-- - create or rename it if necessary.\nAdd a new revision to the top with the appropriate details, and a\nlocal variables entry to the bottom to set Emacs to the right mode:\n
-(EXAMPLE
-L1352
--Local variables:\nmode: debian-changelog\nEnd:
-L1355
-)EXAMPLE
--\n
-L1357
-)P
-)ITEM
-(ITEM
-L1358
-(P
--Edit/create
-(TT
--debian/control
-)TT
--:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1360
-(ITEM
-L1361
-(P
--Remove the
-(TT
--Version
-)TT
-- field. If it is generated unusually (not\nequal to the source version) you must use the -v option to\ndpkg-gencontrol (see below).
-(TT
--Section
-)TT
--,
-(TT
--Priority
-)TT
--,\n
-(TT
--Maintainer
-)TT
-- go above the first blank line, most of the rest below.\n
-L1366
-)P
-)ITEM
-(ITEM
-L1367
-(P
--Reorder the fields and add a blank line at an appropriate point,\nseparating the source package fields from the binary package\nfields.\n
-L1371
-)P
-)ITEM
-(ITEM
-L1372
-(P
--Add the
-(TT
--Source
-)TT
-- field.\n
-L1374
-)P
-)ITEM
-(ITEM
-L1375
-(P
--Add the
-(TT
--Standards-Version
-)TT
-- field. The current value is\n
-(TT
--0.2.0.0
-)TT
--.\n
-L1378
-)P
-)ITEM
-(ITEM
-L1379
-(P
--Change the
-(TT
--Architecture
-)TT
-- field for each package to
-(TT
--any
-)TT
--,\n
-(TT
--all
-)TT
-- or whatever. If there isn't an
-(TT
--Architecture
-)TT
-- field add\none.\n
-L1383
-)P
-)ITEM
-(ITEM
-L1384
-(P
--If any other seddery or things used to happen to make the binary\ncontrol files use
-(PRGN
--dpkg-gencontrol
-)PRGN
--'s variable substitution\nfeatures to achieve the same effect. Use
-(TT
--debian/substvars
-)TT
-- if\nyou need to put unusally-generated information (apart from details of\n
-(TT
--.deb
-)TT
-- files) in the
-(TT
--.changes
-)TT
-- file too.
-L1389
-)P
-)ITEM
-)LIST
--\n
-L1391
-)P
-)ITEM
-(ITEM
-L1392
-(P
--Edit the
-(TT
--debian/rules
-)TT
--:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1394
-(ITEM
-L1395
-(P
--Remove the
-(PRGN
--source
-)PRGN
-- and
-(PRGN
--diff
-)PRGN
-- and any
-(PRGN
--changes
-)PRGN
-- and\n
-(PRGN
--dist
-)PRGN
-- targets. These things now happen in a package-independent\nway and are not done by
-(TT
--debian/rules
-)TT
--.
-L1398
-)P
-)ITEM
-(ITEM
-L1399
-(P
--Split the
-(PRGN
--binary
-)PRGN
-- target into
-(PRGN
--binary-arch
-)PRGN
-- and\n
-(PRGN
--binary-indep
-)PRGN
--; in many cases all of
-(PRGN
--binary
-)PRGN
-- should go into\n
-(PRGN
--binary-arch
-)PRGN
--. Create the
-(PRGN
--binary
-)PRGN
-- target and the unused of\nthe two other
-(PRGN
--binary-*
-)PRGN
-- targets if there is one - you can copy\nthe ones from the
-(PRGN
--hello
-)PRGN
-- package.
-L1404
-)P
-)ITEM
-(ITEM
-L1405
-(P
--Change the
-(PRGN
--binary
-)PRGN
-- target to use
-(PRGN
--dpkg-gencontrol
-)PRGN
-- to make\nthe package control file(s). Move it to after all the files have been\ninstalled but just before the last
-(PRGN
--chown
-)PRGN
-- and
-(PRGN
--chmod
-)PRGN
-- in\nthe target.
-L1409
-)P
-)ITEM
-(ITEM
-L1410
-(P
--Change occurrences of
-(TT
--debian-tmp
-)TT
-- to
-(TT
--debian/tmp
-)TT
--.
-L1411
-)P
-)ITEM
-(ITEM
-L1412
-(P
--Change occurrences of
-(TT
--debian.{post,pre}{inst,rm}
-)TT
-- to\n
-(TT
--debian/*
-)TT
--.
-L1414
-)P
-)ITEM
-(ITEM
-L1415
-(P
--Remove the version number setting at the top, if there is one.
-L1416
-)P
-)ITEM
-(ITEM
-L1417
-(P
--Ensure that the package's Debian-specific and upstream changelogs are\ninstalled.
-L1419
-)P
-)ITEM
-)LIST
--\n
-L1421
-)P
-)ITEM
-(ITEM
-L1422
-(P
--Check that the
-(TT
--debian/README
-)TT
-- is really the copyright file, and\nif so rename it to
-(TT
--debian/copyright
-)TT
-- and edit\n
-(TT
--debian/rules
-)TT
-- to cope with this and to change the installation\nof the copyright file from
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/copyright
-)TT
--\ninstead of
-(TT
--/usr/doc/copyright/
-(VAR
--package
-)VAR
-)TT
--. If it isn't then\nfind
-(TT
--debian/copyright
-)TT
-- and decide what to do with the\n
-(TT
--README
-)TT
--.\n
-L1430
-)P
-)ITEM
-(ITEM
-L1431
-(P
--Check for various other anachronisms and problems:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1433
-(ITEM
-L1434
-(P
--Remove any
-(TT
--Package_Revision
-)TT
--,
-(TT
--Package-Revision
-)TT
-- or\n
-(TT
--Revision
-)TT
-- fields.
-L1436
-)P
-)ITEM
-(ITEM
-L1437
-(P
--Rename
-(TT
--Optional
-)TT
-- to
-(TT
--Suggests
-)TT
--,
-(TT
--Recommended
-)TT
-- to\n
-(TT
--Recommends
-)TT
--.
-L1439
-)P
-)ITEM
-(ITEM
-L1440
-(P
--Change
-(TT
--/usr/doc/examples/
-(VAR
--package
-)VAR
-)TT
-- to\n
-(TT
--/usr/doc/
-(VAR
--package
-)VAR
--/examples
-)TT
--.
-L1442
-)P
-)ITEM
-(ITEM
-L1443
-(P
--Make sure that manpages are installed compressed.
-L1444
-)P
-)ITEM
-(ITEM
-L1445
-(P
--Check that the description has an extended description, is\nwell-formatted and meaningful and helpful to people wanting to know\nwhether to install a package.
-L1448
-)P
-)ITEM
-)LIST
--\n
-L1450
-)P
-)ITEM
-(ITEM
-L1451
-(P
--Look everything over.\n
-L1453
-)P
-)ITEM
-(ITEM
-L1454
-(P
--Do a test build using
-(TT
--dpkg-buildpackage -ur -uc -r
-(VAR
--whatever
-)VAR
-)TT
--.\nCheck the permissions and locations of files in the resulting package\nby eyeballing the output of
-(TT
--dpkg-deb --contents
-)TT
--, and check that\nthe source build happened OK. Test install the binary package(s) and\ntest extract the source package(s).\n
-L1460
-)P
-)ITEM
-(ITEM
-L1461
-(P
--Sign the release: either re-run
-(PRGN
--dpkg-buildpackage
-)PRGN
-- (this will\nrebuild the package entirely), or PGP-sign the
-(TT
--.dsc
-)TT
--, rebuild the\n
-(TT
--.changes
-)TT
-- using
-(PRGN
--dpkg-genchanges
-)PRGN
--, and then PGP-sign the\n
-(TT
--.changes
-)TT
--.\n
-L1466
-)P
-)ITEM
-)LIST
--\n
-L1468
-)P
-)CHAPT
-)BOOK
-)DEBIANDOC
-C
+++ /dev/null
-L13 programmer.sgml
-(DEBIANDOC
-(BOOK
-L15
-(TITLEPAG
-(TITLE
-(PRGN
--dpkg
-)PRGN
-- programmers' manual
-L16
-)TITLE
-(AUTHOR
-(NAME
--Ian Jackson
-)NAME
-(EMAIL
--ijackson@gnu.ai.mit.edu
-)EMAIL
-L17
-)AUTHOR
-(VERSION
--version 0.2.0.0 (dpkg 1.3.7),
-(DATE
-)DATE
--\n
-L19
-)VERSION
-(ABSTRACT
-L20
--This manual describes the technical aspects of creating Debian binary\nand source packages. It also documents the interface between\n
-(PRGN
--dselect
-)PRGN
-- and its access method scripts. It does not deal with\nthe Debian Project policy requirements, and it assumes familiarity\nwith
-(PRGN
--dpkg
-)PRGN
--'s functions from the system administrator's\nperspective.\n
-L27
-)ABSTRACT
-(COPYRIGHT
-(COPYRIGHTSUMMARY
--Copyright \|©\|1996 Ian Jackson.
-L28
-)COPYRIGHTSUMMARY
-(P
-L29
--\nThis manual is free software; you may redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation; either version 2, or (at your option) any\nlater version.
-L34
-)P
-(P
-L35
--\nThis is distributed in the hope that it will be useful, but\n
-(EM
--without any warranty
-)EM
--; without even the implied warranty of\nmerchantability or fitness for a particular purpose. See the GNU\nGeneral Public License for more details.
-L40
-)P
-(P
-L41
--\nYou should have received a copy of the GNU General Public License with\nyour Debian GNU/Linux system, in
-(TT
--/usr/doc/copyright/GPL
-)TT
--, or\nwith the
-(PRGN
--dpkg
-)PRGN
-- source package as the file
-(TT
--COPYING
-)TT
--. If\nnot, write to the Free Software Foundation, Inc., 675 Mass Ave,\nCambridge, MA 02139, USA.\n
-L48
-)P
-)COPYRIGHT
-)TITLEPAG
-ADETAIL TOKEN SECT
-(TOC
-)TOC
-AID CDATA scope
-L67
-(CHAPT
-(HEADING
--Introduction and scope of this manual
-L68
-)HEADING
-(P
-L69
--\n
-(PRGN
--dpkg
-)PRGN
-- is a suite of programs for creating binary package files\nand installing and removing them on Unix systems.
-(FOOTNOTE
-(P
-(PRGN
--dpkg
-)PRGN
--\nis targetted primarily at Debian GNU/Linux, but may work on or be\nported to other systems.
-)P
-)FOOTNOTE
-L74
-)P
-(P
-L75
--\nThe binary packages are designed for the management of installed\nexecutable programs (usually compiled binaries) and their associated\ndata, though source code examples and documentation are provided as\npart of some packages.
-L80
-)P
-(P
-L81
--\nThis manual describes the technical aspects of creating Debian binary\npackages (
-(TT
--.deb
-)TT
-- files). It documents the behaviour of the\npackage management programs
-(PRGN
--dpkg
-)PRGN
--,
-(PRGN
--dselect
-)PRGN
-- et al. and and the\nway they interact with packages.
-L86
-)P
-(P
-L87
--\nIt also documents the interaction between
-(PRGN
--dselect
-)PRGN
--'s core and the\naccess method scripts it uses to actually install the selected\npackages, and describes how to create a new access method.
-L91
-)P
-(P
-L92
--\nThis manual does not go into detail about the options and usage of the\npackage building and installation tools. It should therefore be read\nin conjuction with those programs' manpages.
-L96
-)P
-(P
-L97
--\nThe utility programs which are provided with
-(PRGN
--dpkg
-)PRGN
-- for managing\nvarious system configuration and similar issues, such as\n
-(PRGN
--update-rc.d
-)PRGN
-- and
-(PRGN
--install-info
-)PRGN
--, are not described in\ndetail here - please see their manpages.
-L102
-)P
-(P
-L103
--\nIt does
-(EM
--not
-)EM
-- describe the policy requirements imposed on Debian\npackages, such as the permissions on files and directories,\ndocumentation requirements, upload procedure, and so on. You should\nsee the Debian packaging policy manual for these details. (Many of\nthem will probably turn out to be helpful even if you don't plan to\nupload your package and make it available as part of the\ndistribution.)
-L111
-)P
-(P
-L112
--\nIt is assumed that the reader is reasonably familiar with the\n
-(PRGN
--dpkg
-)PRGN
-- System Administrators' manual. Unfortunately this manual\ndoes not yet exist.
-L116
-)P
-(P
-L117
--\nThe Debian version of the FSF's GNU hello program is provided as an\nexample for people wishing to create Debian packages.
-L120
-)P
-(P
-L121
--\n
-(EM
--Note that this document is still a draft!
-)EM
--\n
-L124
-)P
-)CHAPT
-AID CDATA binarypkg
-(CHAPT
-(HEADING
--Binary packages
-L125
-)HEADING
-(P
-L126
--\nThe binary package has two main sections. The first part consists of\nvarious control information files and scripts used by
-(PRGN
--dpkg
-)PRGN
-- when\ninstalling and removing. See
-AID CDATA controlarea
-(REF
-)REF
--.
-L130
-)P
-(P
-L131
--\nThe second part is an archive (currently a
-(PRGN
--tar
-)PRGN
-- archive)\ncontaining files and directories to be installed.
-L134
-)P
-(P
-L135
--\nIn the future binary packages may also contain other components, such\nas checksums and digital signatures.\n\n
-L140
-)P
-AID CDATA bincreating
-(SECT
-(HEADING
--Creating package files -
-(PRGN
--dpkg-deb
-)PRGN
-L141
-)HEADING
-(P
-L142
--\nAll manipulation of binary package files is done by
-(PRGN
--dpkg-deb
-)PRGN
--;\nit's the only program that has knowledge of the format.\n(
-(PRGN
--dpkg-deb
-)PRGN
-- may be invoked by calling
-(PRGN
--dpkg
-)PRGN
--, as
-(PRGN
--dpkg
-)PRGN
-- will\nspot that the options requested are appropriate to
-(PRGN
--dpkg-deb
-)PRGN
-- and\ninvoke that instead with the same arguments.)
-L148
-)P
-(P
-L149
--\nIn order to create a binary package you must make a directory tree\nwhich contains all the files and directories you want to have in the\nfilesystem data part of the package. In Debian-format source packages\nthis directory is usually
-(TT
--debian/tmp
-)TT
--, relative to the top of\nthe package's source tree.
-L155
-)P
-(P
-L156
--\nThey should have the locations (relative to the root of the directory\ntree you're constructing) ownerships and permissions which you want\nthem to have on the system when they are installed.
-L160
-)P
-(P
-L161
--\nWith current versions of
-(PRGN
--dpkg
-)PRGN
-- the uid/username and gid/groupname\nmappings for the users and groups being used should be the same on the\nsystem where the package is built and the one where it is installed.
-L165
-)P
-(P
-L166
--\nYou need to add one special directory to the root of the miniature\nfilesystem tree you're creating:
-(PRGN
--DEBIAN
-)PRGN
--. It should contain the\ncontrol information files, notably the binary package control file\n(see
-AID CDATA controlfile
-(REF
-)REF
--).
-L171
-)P
-(P
-L172
--\nThe
-(PRGN
--DEBIAN
-)PRGN
-- directory will not appear in the filesystem archive of\nthe package, and so won't be installed by
-(PRGN
--dpkg
-)PRGN
-- when the package\nis installed.
-L176
-)P
-(P
-L177
--\nWhen you've prepared the package, you should invoke:\n
-(EXAMPLE
-L180
--dpkg --build
-(VAR
--directory
-)VAR
-L181
-)EXAMPLE
-L182
-)P
-(P
-L183
--\nThis will build the package in
-(TT
-(VAR
--directory
-)VAR
--.deb
-)TT
--.\n(
-(PRGN
--dpkg
-)PRGN
-- knows that
-(TT
----build
-)TT
-- is a
-(PRGN
--dpkg-deb
-)PRGN
-- option, so it\ninvokes
-(PRGN
--dpkg-deb
-)PRGN
-- with the same arguments to build the package.)
-L187
-)P
-(P
-L188
--\nSee the manpage
-ANAME CDATA dpkg-deb
-ASECTION CDATA 8
-(MANREF
-)MANREF
-- for details of how\nto examine the contents of this newly-created file. You may find the\noutput of following commands enlightening:\n
-(EXAMPLE
-L193
--dpkg-deb --info
-(VAR
--filename
-)VAR
--.deb\ndpkg-deb --contents
-(VAR
--filename
-)VAR
--.deb
-L195
-)EXAMPLE
--\n
-L197
-)P
-)SECT
-AID CDATA controlarea
-(SECT
-(HEADING
--Package control information files
-L198
-)HEADING
-(P
-L199
--\nThe control information portion of a binary package is a collection of\nfiles with names known to
-(PRGN
--dpkg
-)PRGN
--. It will treat the contents of\nthese files specially - some of them contain information used by\n
-(PRGN
--dpkg
-)PRGN
-- when installing or removing the package; others are scripts\nwhich the package maintainer wants
-(PRGN
--dpkg
-)PRGN
-- to run.
-L205
-)P
-(P
-L206
--\nIt is possible to put other files in the package control area, but\nthis is not generally a good idea (though they will largely be\nignored).
-L210
-)P
-(P
-L211
--\nHere is a brief list of the control info files supported by
-(PRGN
--dpkg
-)PRGN
--\nand a summary of what they're used for.
-L214
-)P
-(P
-L215
--\n
-ACOMPACT IMPLIED
-(TAGLIST
-L217
-(TAG
-(TT
--control
-)TT
-L218
-)TAG
-(ITEM
-L220
-(P
--This is the key description file used by
-(PRGN
--dpkg
-)PRGN
--. It specifies the\npackage's name and version, gives its description for the user, states\nits relationships with other packages, and so forth.\nSee
-AID CDATA controlfile
-(REF
-)REF
--.
-L224
-)P
-(P
-L225
--\nIt is usually generated automatically from information in the source\npackage by the
-(PRGN
--dpkg-gencontrol
-)PRGN
-- program, and with assistance\nfrom
-(PRGN
--dpkg-shlibdeps
-)PRGN
--. See
-AID CDATA sourcetools
-(REF
-)REF
--.\n
-L230
-)P
-)ITEM
-(TAG
-(TT
--postinst
-)TT
--,
-(TT
--preinst
-)TT
--,
-(TT
--postrm
-)TT
--,
-(TT
--prerm
-)TT
-L231
-)TAG
-(ITEM
-L233
-(P
--These are exectuable files (usually scripts) which
-(PRGN
--dpkg
-)PRGN
-- runs\nduring installation, upgrade and removal of packages. They allow the\npackage to deal with matters which are particular to that package or\nrequire more complicated processing than that provided by
-(PRGN
--dpkg
-)PRGN
--.\nDetails of when and how they are called are in\n
-AID CDATA maintainerscripts
-(REF
-)REF
--.
-L239
-)P
-(P
-L240
--\nIt is very important to make these scripts itempotent.
-(FOOTNOTE
-(P
--That\nmeans that if it runs successfully or fails and then you call it again\nit doesn't bomb out, but just ensures that everything is the way it\nought to be.
-)P
-)FOOTNOTE
-- This is so that if an error occurs, the user\ninterrupts
-(PRGN
--dpkg
-)PRGN
-- or some other unforeseen circumstance happens you\ndon't leave the user with a badly-broken package.
-L247
-)P
-(P
-L248
--\nThe maintainer scripts are guaranteed to run with a controlling\nterminal and can interact with the user. If they need to prompt for\npasswords, do full-screen interaction or something similar you should\ndo these things to and from
-(TT
--/dev/tty
-)TT
--, since
-(PRGN
--dpkg
-)PRGN
-- will at\nsome point redirect scripts' standard input and output so that it can\nlog the installation process. Likewise, because these scripts may be\nexecuted with standard output redirected into a pipe for logging\npurposes, Perl scripts should set unbuffered output by setting\n
-(TT
--$|=1
-)TT
-- so that the output is printed immediately rather than being\nbuffered.
-L259
-)P
-(P
-L260
--\nEach script should return a zero exit status for success, or a nonzero\none for failure.\n
-L264
-)P
-)ITEM
-(TAG
-(TT
--conffiles
-)TT
-L265
-)TAG
-(ITEM
-L267
-(P
--This file contains a list of configuration files which are to be\nhandled automatically by
-(PRGN
--dpkg
-)PRGN
-- (see
-AID CDATA conffiles
-(REF
-)REF
--). Note\nthat not necessarily every configuration file should be listed here.\n
-L271
-)P
-)ITEM
-(TAG
-(TT
--shlibs
-)TT
-L272
-)TAG
-(ITEM
-L274
-(P
--This file contains a list of the shared libraries supplied by the\npackage, with dependency details for each. This is used by\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- when it determines what dependencies are\nrequired in a package control file.
-L278
-)P
-(P
-L279
--\nEach line is of the form:\n
-(EXAMPLE
-L282
-(VAR
--library-name
-)VAR
--
-(VAR
--version-or-soname
-)VAR
--
-(VAR
--dependencies ...
-)VAR
-L283
-)EXAMPLE
-L284
-)P
-(P
-L285
--\n
-(VAR
--library-name
-)VAR
-- is the name of the shared library, for example\n
-(TT
--libc5
-)TT
--.
-L288
-)P
-(P
-L289
--\n
-(VAR
--version-or-soname
-)VAR
-- is the soname of the library - ie, the thing\nthat must exactly match for the library to be recognised by\n
-(PRGN
--ld.so
-)PRGN
--. Usually this is major version number of the library.
-L293
-)P
-(P
-L294
--\n
-(VAR
--dependencies
-)VAR
-- has the same syntax as a dependency field in a\nbinary package control file. It should give details of which\npackage(s) are required to satisfy a binary built against the version\nof the library contained in the package. See
-AID CDATA depsyntax
-(REF
-)REF
--.
-L299
-)P
-(P
-L300
--\nFor example, if the package
-(TT
--foo
-)TT
-- contains
-(TT
--libfoo.so.1.2.3
-)TT
--,\nwhere the soname of the library is
-(TT
--libfoo.so.1
-)TT
--, and the first\nversion of the package which contained a minor number of at least\n
-(TT
--2.3
-)TT
-- was
-(VAR
--1.2.3-1
-)VAR
--, then the package's
-(VAR
--shlibs
-)VAR
-- could\nsay:\n
-(EXAMPLE
-L307
--libfoo 1\011foo (>= 1.2.3-1)
-L308
-)EXAMPLE
-L309
-)P
-(P
-L310
--\nThe version-specific dependency is to avoid warnings from
-(PRGN
--ld.so
-)PRGN
--\nabout using older shared libraries with newer binaries.\n
-L314
-)P
-)ITEM
-)TAGLIST
--\n
-L316
-)P
-)SECT
-AID CDATA controlfile
-(SECT
-(HEADING
--The main control information file:
-(TT
--control
-)TT
-L317
-)HEADING
-(P
-L318
--\nThe most important control information file used by
-(PRGN
--dpkg
-)PRGN
-- when it\ninstalls a package is
-(TT
--control
-)TT
--. It contains all the package's\n`vital statistics'.
-L322
-)P
-(P
-L323
--\nThe binary package control files of packages built from Debian sources\nare made by a special tool,
-(PRGN
--dpkg-gencontrol
-)PRGN
--, which reads\n
-(TT
--debian/control
-)TT
-- and
-(TT
--debian/changelog
-)TT
-- to find the\ninformation it needs. See
-AID CDATA sourcepkg
-(REF
-)REF
-- for more details.
-L328
-)P
-(P
-L329
--\nThe fields in binary package control files are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L333
-(ITEM
-(P
-AID CDATA f-Package
-(QREF
-(TT
--Package
-)TT
-)QREF
-- (mandatory)
-L334
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA versions
-(QREF
-(TT
--Version
-)TT
-)QREF
-- (mandatory)\n
-L336
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Architecture
-(QREF
-(TT
--Architecture
-)TT
-)QREF
--\n(mandatory)
-(FOOTNOTE
-(P
--This field should appear in all packages, though\n
-(PRGN
--dpkg
-)PRGN
-- doesn't require it yet so that old packages can still be\ninstalled.
-)P
-)FOOTNOTE
--\n
-L341
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA relationships
-(QREF
-(TT
--Depends
-)TT
--,
-(TT
--Provides
-)TT
-- et al.
-)QREF
-L342
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Essential
-(QREF
-(TT
--Essential
-)TT
-)QREF
-L343
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Maintainer
-(QREF
-(TT
--Maintainer
-)TT
-)QREF
-L344
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-classification
-(QREF
-(TT
--Section
-)TT
--,
-(TT
--Priority
-)TT
-)QREF
-L345
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Source
-(QREF
-(TT
--Source
-)TT
-)QREF
-L346
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA descriptions
-(QREF
-(TT
--Description
-)TT
-)QREF
-L347
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Installed-Size
-(QREF
-(TT
--Installed-Size
-)TT
-)QREF
--\n
-L349
-)P
-)ITEM
-)LIST
-L350
-)P
-(P
-L351
--\nA description of the syntax of control files and the purpose of these\nfields is available in
-AID CDATA controlfields
-(REF
-)REF
--.\n\n
-L356
-)P
-)SECT
-)CHAPT
-AID CDATA sourcepkg
-(CHAPT
-(HEADING
--Source packages
-L357
-)HEADING
-(P
-L358
--\nThe Debian binary packages in the distribution are generated from\nDebian sources, which are in a special format to assist the easy and\nautomatic building of binaries.\n
-L363
-)P
-AID CDATA sourcetools
-(SECT
-(HEADING
--Tools for processing source packages
-L364
-)HEADING
-(P
-L365
--\nVarious tools are provided for manipulating source packages; they pack\nand unpack sources and help build of binary packages and help manage\nthe distribution of new versions.
-L369
-)P
-(P
-L370
--\nThey are introduced and typical uses described here; see
-ANAME CDATA dpkg-source
-ASECTION CDATA 1
-(MANREF
-)MANREF
-L372
-- for full documentation about their\narguments and operation.
-L374
-)P
-(P
-L375
--\nFor examples of how to construct a Debian source package, and how to\nuse those utilities that are used by Debian source packages, please\nsee the
-(PRGN
--hello
-)PRGN
-- example package.\n
-L380
-)P
-AID IMPLIED
-(SECT1
-(HEADING
-(PRGN
--dpkg-source
-)PRGN
-- - packs and unpacks Debian source packages
-L381
-)HEADING
-(P
-L382
--\nThis program is frequently used by hand, and is also called from\npackage-independent automated building scripts such as\n
-(PRGN
--dpkg-buildpackage
-)PRGN
--.
-L386
-)P
-(P
-L387
--\nTo unpack a package it is typically invoked with\n
-(EXAMPLE
-L390
--dpkg-source -x
-(VAR
--.../path/to/filename
-)VAR
--.dsc
-L391
-)EXAMPLE
--\nwith the
-(TT
-(VAR
--filename
-)VAR
--.tar.gz
-)TT
-- and\n
-(TT
-(VAR
--filename
-)VAR
--.diff.gz
-)TT
-- (if applicable) in the same directory. It\nunpacks into
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
-)TT
--, and if applicable\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
--.orig
-)TT
--, in the current directory.
-L396
-)P
-(P
-L397
--\nTo create a packed source archive it is typically invoked:\n
-(EXAMPLE
-L400
--dpkg-source -b
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
-L401
-)EXAMPLE
--\nThis will create the
-(TT
--.dsc
-)TT
--,
-(TT
--.tar.gz
-)TT
-- and
-(TT
--.diff.gz
-)TT
-- (if\nappropriate) in the current directory.
-(PRGN
--dpkg-source
-)PRGN
-- does not\nclean the source tree first - this must be done separately if it is\nrequired.
-L406
-)P
-(P
-L407
--\nSee also
-AID CDATA sourcearchives
-(REF
-)REF
--.\n\n
-L411
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(PRGN
--dpkg-buildpackage
-)PRGN
-- - overall package-building control\nscript
-L413
-)HEADING
-(P
-L414
--\n
-(PRGN
--dpkg-buildpackage
-)PRGN
-- is a script which invokes
-(PRGN
--dpkg-source
-)PRGN
--,\nthe
-(TT
--debian/rules
-)TT
-- targets
-(PRGN
--clean
-)PRGN
--,
-(PRGN
--build
-)PRGN
-- and\n
-(PRGN
--binary
-)PRGN
--,
-(PRGN
--dpkg-genchanges
-)PRGN
-- and
-(PRGN
--pgp
-)PRGN
-- to build a signed\nsource and binary package upload.
-L419
-)P
-(P
-L420
--\nIt is usually invoked by hand from the top level of the built or\nunbuilt source directory. It may be invoked with no arguments; useful\narguments include:\n
-ACOMPACT TOKEN COMPACT
-(TAGLIST
-L425
-(TAG
-(TT
---uc
-)TT
--,
-(TT
---us
-)TT
-L426
-)TAG
-(ITEM
-(P
--Do not PGP-sign the
-(TT
--.changes
-)TT
-- file or the source package\n
-(TT
--.dsc
-)TT
-- file, respectively.\n
-L429
-)P
-)ITEM
-(TAG
-(TT
---p
-(VAR
--pgp-command
-)VAR
-)TT
-L430
-)TAG
-(ITEM
-(P
--Invoke
-(VAR
--pgp-command
-)VAR
-- instead of finding
-(TT
--pgp
-)TT
-- on the\n
-(PRGN
--PATH
-)PRGN
--.
-(VAR
--pgp-command
-)VAR
-- must behave just like
-(PRGN
--pgp
-)PRGN
--.\n
-L433
-)P
-)ITEM
-(TAG
-(TT
---r
-(VAR
--root-command
-)VAR
-)TT
-L434
-)TAG
-(ITEM
-(P
--When root privilege is required, invoke the command\n
-(VAR
--root-command
-)VAR
--.
-(VAR
--root-command
-)VAR
-- should invoke its first\nargument as a command, from the
-(PRGN
--PATH
-)PRGN
-- if necessary, and pass its\nsecond and subsequent arguments to the command it calls. If no\n
-(VAR
--root-command
-)VAR
-- is supplied then
-(VAR
--dpkg-buildpackage
-)VAR
-- will take\nno special action to gain root privilege, so that for most packages it\nwill have to be invoked as root to start with.\n
-L442
-)P
-)ITEM
-(TAG
-(TT
---b
-)TT
--,
-(TT
---B
-)TT
-L443
-)TAG
-(ITEM
-(P
--Two types of binary-only build and upload - see
-ANAME CDATA dpkg-source
-ASECTION CDATA 1
-(MANREF
-)MANREF
-L444
--.
-L445
-)P
-)ITEM
-)TAGLIST
--\n\n
-L448
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(PRGN
--dpkg-gencontrol
-)PRGN
-- - generates binary package control files
-L449
-)HEADING
-(P
-L450
--\nThis program is usually called from
-(TT
--debian/rules
-)TT
-- (see
-AID CDATA sourcetree
-(REF
-)REF
-L452
--) in the top level of the source tree.
-L453
-)P
-(P
-L454
--\nThis is usually done just before the files and directories in the\ntemporary directory tree where the package is being built have their\npermissions and ownerships set and the package is constructed using\n
-(PRGN
--dpkg-deb
-)PRGN
-(FOOTNOTE
-(P
--This is so that the control file which is\nproduced has the right permissions
-)P
-)FOOTNOTE
--.
-L460
-)P
-(P
-L461
--\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- must be called after all the files which are to\ngo into the package have been placed in the temporary build directory,\nso that its calculation of the installed size of a package is correct.
-L465
-)P
-(P
-L466
--\nIt is also necessary for
-(PRGN
--dpkg-gencontrol
-)PRGN
-- to be run after\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- so that the variable substitutions created by\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- in
-(TT
--debian/substvars
-)TT
-- are available.
-L470
-)P
-(P
-L471
--\nFor a package which generates only one binary package, and which\nbuilds it in
-(TT
--debian/tmp
-)TT
-- relative to the top of the source\npackage, it is usually sufficient to call:\n
-(EXAMPLE
-L476
--dpkg-gencontrol
-L477
-)EXAMPLE
-L478
-)P
-(P
-L479
--\nSources which build several binaries will typically need something\nlike:\n
-(EXAMPLE
-L483
--dpkg-gencontrol -Pdebian/tmp-
-(VAR
--pkg
-)VAR
-- -p
-(VAR
--package
-)VAR
-L484
-)EXAMPLE
--\nThe
-(TT
---P
-)TT
-- tells
-(PRGN
--dpkg-gencontrol
-)PRGN
-- that the package is being\nbuilt in a non-default directory, and the
-(TT
---p
-)TT
-- tells it which\npackage's control file should be generated.
-L488
-)P
-(P
-L489
--\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- also adds information to the list of files in\n
-(TT
--debian/files
-)TT
--, for the benefit of (for example) a future\ninvocation of
-(PRGN
--dpkg-genchanges
-)PRGN
--.\n\n
-L495
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- - calculates shared library dependencies
-L496
-)HEADING
-(P
-L497
--\nThis program is usually called from
-(TT
--debian/rules
-)TT
-- just before\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- (see
-AID CDATA sourcetree
-(REF
-)REF
--), in the top level\nof the source tree.
-L501
-)P
-(P
-L502
--\nIts arguments are executables
-(FOOTNOTE
-(P
--They may be specified either\nin the locations in the source tree where they are created or in the\nlocations in the temporary build tree where they are installed prior\nto binary package creation.
-)P
-)FOOTNOTE
-- for which shared library\ndependencies should be included in the binary package's control file.
-L508
-)P
-(P
-L509
--\nIf some of the executable(s) shared libraries should only warrant a\n
-(TT
--Recommends
-)TT
-- or
-(TT
--Suggests
-)TT
--, or if some warrant a\n
-(TT
--Pre-Depends
-)TT
--, this can be achieved by using the\n
-(TT
---d
-(VAR
--dependency-field
-)VAR
-)TT
-- option before those executable(s).\n(Each
-(TT
---d
-)TT
-- option takes effect until the next
-(TT
---d
-)TT
--.)
-L515
-)P
-(P
-L516
--\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- does not directly cause the output control file\nto be modified. Instead by default it adds to the\n
-(TT
--debian/substvars
-)TT
-- file variable settings like\n
-(TT
--shlibs:Depends
-)TT
--. These variable settings must be referenced in\ndependency fields in the appropriate per-binary-package sections of\nthe source control file.
-L523
-)P
-(P
-L524
--\nFor example, the
-(PRGN
--procps
-)PRGN
-- package generates two kinds of\nbinaries, simple C binaries like
-(PRGN
--ps
-)PRGN
-- which require a\npredependency and full-screen ncurses binaries like
-(PRGN
--top
-)PRGN
-- which\nrequire only a recommendation. It can say in its
-(TT
--debian/rules
-)TT
--:\n
-(EXAMPLE
-L530
--dpkg-shlibdeps -dPre-Depends ps -dRecommends top
-L531
-)EXAMPLE
--\nand then in its main control file
-(TT
--debian/control
-)TT
--:\n
-(EXAMPLE
-L534
-(VAR
--...
-)VAR
--\nPackage: procps\nPre-Depends: ${shlibs:Pre-Depends}\nRecommends: ${shlibs:Recommends}\n
-(VAR
--...
-)VAR
-L539
-)EXAMPLE
-L540
-)P
-(P
-L541
--\nSources which produce several binary packages with different shared\nlibrary dependency requirements can use the
-(TT
---p
-(VAR
--varnameprefix
-)VAR
-)TT
--\noption to override the default
-(TT
--shlib:
-)TT
-- prefix (one invocation of\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- per setting of this option). They can thus\nproduce several sets of dependency variables, each of the form\n
-(TT
-(VAR
--varnameprefix
-)VAR
--:
-(VAR
--dependencyfield
-)VAR
-)TT
--, which can be referred\nto in the appropriate parts of the binary package control files.\n\n
-L551
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(PRGN
--dpkg-distaddfile
-)PRGN
-- - adds a file to
-(TT
--debian/files
-)TT
-L552
-)HEADING
-(P
-L553
--\nSome packages' uploads need to include files other than the source and\nbinary package files.
-L556
-)P
-(P
-L557
--\n
-(PRGN
--dpkg-distaddfile
-)PRGN
-- adds a file to the
-(TT
--debian/files
-)TT
-- file so\nthat it will be included in the
-(TT
--.changes
-)TT
-- file when\n
-(PRGN
--dpkg-genchanges
-)PRGN
-- is run.
-L561
-)P
-(P
-L562
--\nIt is usually invoked from the
-(PRGN
--binary
-)PRGN
-- target of\n
-(TT
--debian/rules
-)TT
--:\n
-(EXAMPLE
-L566
--dpkg-distaddfile
-(VAR
--filename
-)VAR
--
-(VAR
--section
-)VAR
--
-(VAR
--priority
-)VAR
-L567
-)EXAMPLE
--\nThe
-(VAR
--filename
-)VAR
-- is relative to the directory where\n
-(PRGN
--dpkg-genchanges
-)PRGN
-- will expect to find it - this is usually the\ndirectory above the top level of the source tree. The\n
-(TT
--debian/rules
-)TT
-- target should put the file there just before or\njust after calling
-(PRGN
--dpkg-distaddfile
-)PRGN
--.
-L573
-)P
-(P
-L574
--\nThe
-(VAR
--section
-)VAR
-- and
-(VAR
--priority
-)VAR
-- are passed unchanged into the\nresulting
-(TT
--.changes
-)TT
-- file. See
-AID CDATA f-classification
-(REF
-)REF
--.\n\n
-L579
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(PRGN
--dpkg-genchanges
-)PRGN
-- - generates a
-(TT
--.changes
-)TT
-- upload\ncontrol file
-L581
-)HEADING
-(P
-L582
--\nThis program is usually called by package-independent automatic\nbuilding scripts such as
-(PRGN
--dpkg-buildpackage
-)PRGN
--, but it may also be\ncalled by hand.
-L586
-)P
-(P
-L587
--\nIt is usually called in the top level of a built source tree, and when\ninvoked with no arguments will print out a straightforward\n
-(TT
--.changes
-)TT
-- file based on the information in the source package's\nchangelog and control file and the binary and source packages which\nshould have been built.\n\n
-L595
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(PRGN
--dpkg-parsechangelog
-)PRGN
-- - produces parsed representation of\na changelog
-L597
-)HEADING
-(P
-L598
--\nThis program is used internally by
-(PRGN
--dpkg-source
-)PRGN
-- et al. It may\nalso occasionally be useful in
-(TT
--debian/rules
-)TT
-- and elsewhere. It\nparses a changelog,
-(TT
--debian/changelog
-)TT
-- by default, and prints a\ncontrol-file format representation of the information in it to\nstandard output.\n
-L605
-)P
-)SECT1
-)SECT
-AID CDATA sourcetree
-(SECT
-(HEADING
--The Debianised source tree
-L606
-)HEADING
-(P
-L607
--\nThe source archive scheme described later is intended to allow a\nDebianised source tree with some associated control information to be\nreproduced and transported easily. The Debianised source tree is a\nversion of the original program with certain files added for the\nbenefit of the Debianisation process, and with any other changes\nrequired made to the rest of the source code and installation scripts.
-L614
-)P
-(P
-L615
--\nThe extra files created for Debian are in the subdirectory
-(TT
--debian
-)TT
--\nof the top level of the Debianised source tree. They are described\nbelow.\n
-L620
-)P
-AID IMPLIED
-(SECT1
-(HEADING
-(TT
--debian/rules
-)TT
-- - the main building script
-L621
-)HEADING
-(P
-L622
--\nThis file is an executable makefile, and contains the package-specific\nrecipies for compiling the package and building binary package(s) out\nof the source.
-L626
-)P
-(P
-L627
--\nIt must start with the line
-(TT
--#!/usr/bin/make -f
-)TT
--, so that it\ncan be invoked by saying its name rather than invoking
-(PRGN
--make
-)PRGN
--\nexplicitly.
-L631
-)P
-(P
-L632
--\nThe targets which are required to be present are:\n\n
-ACOMPACT IMPLIED
-(TAGLIST
-L636
-(TAG
-(TT
--build
-)TT
-)TAG
-L637
-(ITEM
-L639
-(P
--This should perform all non-interactive configuration and compilation\nof the package. If a package has an interactive pre-build\nconfiguration routine, the Debianised source package should be built\nafter this has taken place, so that it can be built without rerunning\nthe configuration.
-L644
-)P
-(P
-L645
--\nFor some packages, notably ones where the same source tree is compiled\nin different ways to produce two binary packages, the
-(PRGN
--build
-)PRGN
--\ntarget does not make much sense. For these packages it is good enough\nto provide two (or more) targets (
-(TT
--build-a
-)TT
-- and
-(TT
--build-b
-)TT
-- or\nwhatever) for each of the ways of building the package, and a\n
-(PRGN
--build
-)PRGN
-- target that does nothing. The
-(PRGN
--binary
-)PRGN
-- target will have\nto build the package in each of the possible ways and make the binary\npackage out of each.
-L654
-)P
-(P
-L655
--\nThe
-(PRGN
--build
-)PRGN
-- target must not do anything that might require root\nprivilege.
-L658
-)P
-(P
-L659
--\nThe
-(PRGN
--build
-)PRGN
-- target may need to run
-(PRGN
--clean
-)PRGN
-- first - see below.
-L661
-)P
-(P
-L662
--\nWhen a package has a configuration routine that takes a long time, or\nwhen the makefiles are poorly designed, or when
-(PRGN
--build
-)PRGN
-- needs to\nrun
-(PRGN
--clean
-)PRGN
-- first, it is a good idea to
-(TT
--touch build
-)TT
-- when the\nbuild process is complete. This will ensure that if
-(TT
--debian/rules\nbuild
-)TT
-- is run again it will not rebuild the whole program.\n
-L669
-)P
-)ITEM
-(TAG
-(TT
--binary
-)TT
--,
-(TT
--binary-arch
-)TT
--,
-(TT
--binary-indep
-)TT
-L670
-)TAG
-(ITEM
-L672
-(P
--The
-(PRGN
--binary
-)PRGN
-- target should be all that is necessary for the user\nto build the binary package. It is split into two parts:\n
-(PRGN
--binary-arch
-)PRGN
-- builds the packages' output files which are\nspecific to a particular architecture, and
-(PRGN
--binary-indep
-)PRGN
--\nbuilds those which are not.
-L677
-)P
-(P
-L678
--\n
-(PRGN
--binary
-)PRGN
-- should usually be a target with no commands which simply\ndepends on
-(PRGN
--binary-arch
-)PRGN
-- and
-(PRGN
--binary-indep
-)PRGN
--.
-L681
-)P
-(P
-L682
--\nBoth
-(PRGN
--binary-*
-)PRGN
-- targets should depend on the
-(PRGN
--build
-)PRGN
-- target,\nabove, so that the package is built if it has not been already. It\nshould then create the relevant binary package(s), using\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- to make their control files and
-(PRGN
--dpkg-deb
-)PRGN
--\nto build them and place them in the parent of the top level directory.
-L688
-)P
-(P
-L689
--\nIf one of the
-(PRGN
--binary-*
-)PRGN
-- targets has nothing to do (this will be\nalways be the case if the source generates only a single binary\npackage, whether architecture-dependent or not) it
-(EM
--must
-)EM
-- still\nexist, but should always succeed.
-L694
-)P
-(P
-L695
--\n
-AID CDATA binarypkg
-(REF
-)REF
-- describes how to construct binary packages.
-L697
-)P
-(P
-L698
--\nThe
-(PRGN
--binary
-)PRGN
-- targets must be invoked as root.\n
-L701
-)P
-)ITEM
-(TAG
-(TT
--clean
-)TT
-)TAG
-L702
-(ITEM
-L704
-(P
--This should undo any effects that the
-(PRGN
--build
-)PRGN
-- and
-(PRGN
--binary
-)PRGN
--\ntargets may have had, except that it should leave alone any output\nfiles created in the parent directory by a run of
-(PRGN
--binary
-)PRGN
--.
-L707
-)P
-(P
-L708
--\nIf a
-(PRGN
--build
-)PRGN
-- file is touched at the end of the
-(PRGN
--build
-)PRGN
-- target,\nas suggested above, it must be removed as the first thing that\n
-(PRGN
--clean
-)PRGN
-- does, so that running
-(PRGN
--build
-)PRGN
-- again after an interrupted\n
-(PRGN
--clean
-)PRGN
-- doesn't think that everything is already done.
-L713
-)P
-(P
-L714
--\nThe
-(PRGN
--clean
-)PRGN
-- target must be invoked as root if
-(PRGN
--binary
-)PRGN
-- has\nbeen invoked since the last
-(PRGN
--clean
-)PRGN
--, or if
-(PRGN
--build
-)PRGN
-- has been\ninvoked as root (since
-(PRGN
--build
-)PRGN
-- may create directories, for\nexample).\n
-L720
-)P
-)ITEM
-(TAG
-(TT
--get-orig-source
-)TT
-)TAG
-L721
-(ITEM
-L723
-(P
--This target fetches the most recent version of the original source\npackage from a canonical archive site (via FTP or WWW, for example),\ndoes any necessary rearrangement to turn it into the original source\ntarfile format described below, and leaves it in the current directory.
-L727
-)P
-(P
-L728
--\nThis target may be invoked in any directory, and should take care to\nclean up any temporary files it may have left.
-L731
-)P
-(P
-L732
--\nThis target is optional, but providing it if possible is a good idea.\n
-L735
-)P
-)ITEM
-)TAGLIST
--\n\nThe
-(PRGN
--build
-)PRGN
--,
-(PRGN
--binary
-)PRGN
-- and
-(PRGN
--clean
-)PRGN
-- targets must be\ninvoked with a current directory of the package's top-level\ndirectory.\n
-L741
-)P
-(P
-L742
--\nAdditional targets may exist in
-(TT
--debian/rules
-)TT
--, either as\npublished or undocumented interfaces or for the package's internal\nuse.\n\n
-L748
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(TT
--debian/control
-)TT
-L749
-)HEADING
-(P
-L750
--\nThis file contains version-independent details about the source\npackage and about the binary packages it creates.
-L753
-)P
-(P
-L754
--\nIt is a series of sets of control fields, each syntactically similar\nto a binary package control file. The sets are separated by one or\nmore blank lines. The first set is information about the source\npackage in general; each subsequent set describes one binary package\nthat the source tree builds.
-L760
-)P
-(P
-L761
--\nThe syntax and semantics of the fields are described below in\n
-AID CDATA controlfields
-(REF
-)REF
--.
-L764
-)P
-(P
-L765
--\nThe general (binary-package-independent) fields are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L768
-(ITEM
-(P
-AID CDATA f-Source
-(QREF
-(TT
--Source
-)TT
-)QREF
-- (mandatory)
-L769
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Maintainer
-(QREF
-(TT
--Maintainer
-)TT
-)QREF
-L770
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-classification
-(QREF
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-)QREF
--\n(classification, mandatory)
-L772
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Standards-Version
-(QREF
-(TT
--Standards-Version
-)TT
-)QREF
-L773
-)P
-)ITEM
-)LIST
-L774
-)P
-(P
-L775
--\nThe per-binary-package fields are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L778
-(ITEM
-(P
-AID CDATA f-Package
-(QREF
-(TT
--Package
-)TT
-)QREF
-- (mandatory)
-L779
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Architecture
-(QREF
-(TT
--Architecture
-)TT
-)QREF
-- (mandatory)
-L780
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA descriptions
-(QREF
-(TT
--Description
-)TT
-)QREF
-L781
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-classification
-(QREF
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-)QREF
-- (classification)
-L782
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Essential
-(QREF
-(TT
--Essential
-)TT
-)QREF
-L783
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA relationships
-(QREF
-(TT
--Depends
-)TT
-- et al.
-)QREF
-- (package interrelationships)
-L784
-)P
-)ITEM
-)LIST
-L785
-)P
-(P
-L786
--\nThese fields are used by
-(PRGN
--dpkg-gencontrol
-)PRGN
-- to generate control\nfiles for binary packages (see below), by
-(PRGN
--dpkg-genchanges
-)PRGN
-- to\ngenerate the
-(TT
--.changes
-)TT
-- file to accompany the upload, and by\n
-(PRGN
--dpkg-source
-)PRGN
-- when it creates the
-(TT
--.dsc
-)TT
-- source control file as\npart of a source archive.
-L792
-)P
-(P
-L793
--\nThe fields here may contain variable references - their values will be\nsubstituted by
-(PRGN
--dpkg-gencontrol
-)PRGN
--,
-(PRGN
--dpkg-genchanges
-)PRGN
-- or\n
-(PRGN
--dpkg-source
-)PRGN
-- when they generate output control files. See
-AID CDATA srcsubstvars
-(REF
-)REF
-L797
-- for details.
-L798
-)P
-(P
-L800
-)P
-AID IMPLIED
-(SECT2
-(HEADING
--User-defined fields
-L801
-)HEADING
-(P
-L802
--\nAdditional user-defined fields may be added to the source package\ncontrol file. Such fields will be ignored, and not copied to (for\nexample) binary or source package control files or upload control\nfiles.
-L807
-)P
-(P
-L808
--\nIf you wish to add additional unsupported fields to these output files\nyou should use the mechanism described here.
-L811
-)P
-(P
-L812
--\nFields in the main source control information file with names starting\n
-(TT
--X
-)TT
--, followed by one or more of the letters
-(TT
--BCS
-)TT
-- and a hyphen\n
-(TT
---
-)TT
--, will be copied to the output files. Only the part of the\nfield name after the hyphen will be used in the output file. Where\nthe letter
-(TT
--B
-)TT
-- is used the field will appear in binary package\ncontrol files, where the letter
-(TT
--S
-)TT
-- is used in source package\ncontrol files and where
-(TT
--C
-)TT
-- is used in upload control\n(
-(TT
--.changes
-)TT
--) files.
-L821
-)P
-(P
-L822
--\nFor example, if the main source information control file contains the\nfield\n
-(EXAMPLE
-L826
--XBS-Comment: I stand between the candle and the star.
-L827
-)EXAMPLE
--\nthen the binary and source package control files will contain the\nfield\n
-(EXAMPLE
-L831
--Comment: I stand between the candle and the star.
-L832
-)EXAMPLE
--\n
-L834
-)P
-)SECT2
-)SECT1
-AID CDATA dpkgchangelog
-(SECT1
-(HEADING
-(TT
--debian/changelog
-)TT
-L835
-)HEADING
-(P
-L836
--\nThis file records the changes to the Debian-specific parts of the\npackage
-(FOOTNOTE
-(P
--Though there is nothing stopping an author who is\nalso the Debian maintainer from using it for all their changes, it\nwill have to be renamed if the Debian and upstream maintainers become\ndifferent people.
-)P
-)FOOTNOTE
--.
-L842
-)P
-(P
-L843
--\nIt has a special format which allows the package building tools to\ndiscover which version of the package is being built and find out\nother release-specific information.
-L847
-)P
-(P
-L848
--\nThat format is a series of entries like this:\n
-(EXAMPLE
-L851
-(VAR
--package
-)VAR
-- (
-(VAR
--version
-)VAR
--)
-(VAR
--distribution(s)
-)VAR
--; urgency=
-(VAR
--urgency
-)VAR
--\n\n *
-(VAR
--change details
-)VAR
--\n
-(VAR
--more change details
-)VAR
--\n *
-(VAR
--even more change details
-)VAR
--\n\n --
-(VAR
--maintainer name and email address
-)VAR
--
-(VAR
--date
-)VAR
-L858
-)EXAMPLE
-L859
-)P
-(P
-L860
--\n
-(VAR
--package
-)VAR
-- and
-(VAR
--version
-)VAR
-- are the source package name and\nversion number.
-(VAR
--distribution(s)
-)VAR
-- lists the distributions where\nthis version should be installed when it is uploaded - it is copied to\nthe
-(TT
--Distribution
-)TT
-- field in the
-(TT
--.changes
-)TT
-- file. See
-AID CDATA f-Distribution
-(REF
-)REF
-L865
--.
-L866
-)P
-(P
-L867
--\n
-(VAR
--urgency
-)VAR
-- is the value for the
-(TT
--Urgency
-)TT
-- field in the\n
-(TT
--.changes
-)TT
-- file for the upload. See
-AID CDATA f-Urgency
-(REF
-)REF
--. It is\nnot possible to specify an urgency containing commas; commas are used\nto separate
-(TT
-(VAR
--keyword
-)VAR
--=
-(VAR
--value
-)VAR
-)TT
-- settings in the
-(PRGN
--dpkg
-)PRGN
--\nchangelog format (though there is currently only one useful\n
-(VAR
--keyword
-)VAR
--,
-(TT
--urgency
-)TT
--).
-L874
-)P
-(P
-L875
--\nThe change details may in fact be any series of lines starting with at\nleast two spaces, but conventionally each change starts with an\nasterisk and a separating space and continuation lines are indented so\nas to bring them in line with the start of the text above. Blank\nlines may be used here to separate groups of changes, if desired.
-L881
-)P
-(P
-L882
--\nThe maintainer name and email address should
-(EM
--not
-)EM
-- necessarily be\nthose of the usual package maintainer. They should be the details of\nthe person doing
-(EM
--this
-)EM
-- version. The information here will be\ncopied to the
-(TT
--.changes
-)TT
-- file, and then later used to send an\nacknowledgement when the upload has been installed.
-L888
-)P
-(P
-L889
--\nThe
-(VAR
--date
-)VAR
-- should be in RFC822 format; it should include the\ntimezone specified numerically, with the timezone name or abbreviation\noptionally present as a comment.
-L893
-)P
-(P
-L894
--\nThe first `title' line with the package name should start at the left\nhand margin; the `trailer' line with the maintainer and date details\nshould be preceded by exactly one space. The maintainer details and\nthe date must be separated by exactly two spaces.
-L899
-)P
-(P
-L900
--\nAn Emacs mode for editing this format is available: it is called\n
-(TT
--debian-changelog-mode
-)TT
--. You can have this mode selected\nautomatically when you edit a Debian changelog by adding a local\nvariables clause to the end of the changelog.\n
-L906
-)P
-AID IMPLIED
-(SECT2
-(HEADING
--Defining alternative changelog formats
-L907
-)HEADING
-(P
-L908
--\nIt is possible to use a different format to the standard one, by\nproviding a parser for the format you wish to use.
-L911
-)P
-(P
-L912
--\nIn order to have
-(TT
--dpkg-parsechangelog
-)TT
-- run your parser, you must\ninclude a line within the last 40 lines of your file matching the Perl\nregular expression:\n
-(EXAMPLE
-L917
--\\schangelog-format:\\s+([0-9a-z]+)\\W
-L918
-)EXAMPLE
--\nThe part in parentheses should be the name of the format.
-L920
-)P
-(P
-L921
--\nIf such a line exists then
-(TT
--dpkg-parsechangelog
-)TT
-- will look for the\nparser as
-(TT
--/usr/lib/dpkg/parsechangelog/
-(VAR
--format-name
-)VAR
-)TT
-- or\n
-(TT
--/usr/local/lib/dpkg/parsechangelog/
-(VAR
--format-name
-)VAR
-)TT
--; it is an\nerror for it not to find it, or for it not to be an executable\nprogram. The default changelog format is
-(TT
--dpkg
-)TT
--, and a parser for\nit is provided with the
-(TT
--dpkg
-)TT
-- package.
-L928
-)P
-(P
-L929
--\nThe parser will be invoked with the changelog open on standard input\nat the start of the file. It should read the file (it may seek if it\nwishes) to determine the information required and return the parsed\ninformation to standard output in the form of a series of control\nfields in the standard format. By default it should return\ninformation about only the most recent version in the changelog; it\nshould accept a
-(TT
---v
-(VAR
--version
-)VAR
-)TT
-- option to return changes\ninformation from all versions present
-(EM
--strictly after
-)EM
--\n
-(VAR
--version
-)VAR
--, and it should then be an error for
-(VAR
--version
-)VAR
-- not to\nbe present in the changelog.
-L940
-)P
-(P
-L941
--\nThe fields are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L944
-(ITEM
-(P
-AID CDATA f-Source
-(QREF
-(TT
--Source
-)TT
-)QREF
-L945
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA versions
-(QREF
-(TT
--Version
-)TT
-)QREF
-- (mandatory)
-L946
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Distribution
-(QREF
-(TT
--Distribution
-)TT
-)QREF
-- (mandatory)
-L947
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Urgency
-(QREF
-(TT
--Urgency
-)TT
-)QREF
-- (mandatory)
-L948
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Maintainer
-(QREF
-(TT
--Maintainer
-)TT
-)QREF
-- (mandatory)
-L949
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Date
-(QREF
-(TT
--Date
-)TT
-)QREF
-L950
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Changes
-(QREF
-(TT
--Changes
-)TT
-)QREF
-- (mandatory)
-L951
-)P
-)ITEM
-)LIST
-L952
-)P
-(P
-L953
--\nIf several versions are being returned (due to the use of
-(TT
---v
-)TT
--),\nthe urgency value should be of the highest urgency code listed at the\nstart of any of the versions requested followed by the concatenated\n(space-separated) comments from all the versions requested; the\nmaintainer, version, distribution and date should always be from the\nmost recent version.
-L960
-)P
-(P
-L961
--\nFor the format of the
-(TT
--Changes
-)TT
-- field see
-AID CDATA f-Changes
-(REF
-)REF
--.
-L963
-)P
-(P
-L964
--\nIf the changelog format which is being parsed always or almost always\nleaves a blank line between individual change notes these blank lines\nshould be stripped out, so as to make the resulting output compact.
-L968
-)P
-(P
-L969
--\nIf the changelog format does not contain date or package name\ninformation this information should be omitted from the output. The\nparser should not attempt to synthesise it or find it from other\nsources.
-L974
-)P
-(P
-L975
--\nIf the changelog does not have the expected format the parser should\nexit with a nonzero exit status, rather than trying to muddle through\nand possibly generating incorrect output.
-L979
-)P
-(P
-L980
--\nA changelog parser may not interact with the user at all.\n
-L983
-)P
-)SECT2
-)SECT1
-AID CDATA srcsubstvars
-(SECT1
-(HEADING
-(TT
--debian/substvars
-)TT
-- and variable substitutions
-L984
-)HEADING
-(P
-L985
--\nWhen
-(PRGN
--dpkg-gencontrol
-)PRGN
--,
-(PRGN
--dpkg-genchanges
-)PRGN
-- and\n
-(PRGN
--dpkg-source
-)PRGN
-- generate control files they do variable\nsubstitutions on their output just before writing it. Variable\nsubstitutions have the form
-(TT
--${
-(VAR
--variable-name
-)VAR
--}
-)TT
--. The optional\nfile
-(TT
--debian/substvars
-)TT
-- contains variable substitutions to be\nused; variables can also be set directly from
-(TT
--debian/rules
-)TT
--\nusing the
-(TT
---V
-)TT
-- option to the source packaging commands, and certain\npredefined variables are available.
-L994
-)P
-(P
-L995
--\nThe file may be a static part of the source archive, or generated and\nmodified dynamically by
-(TT
--debian/rules
-)TT
-- targets. In the latter\ncase it must be removed by the
-(PRGN
--clean
-)PRGN
-- target.
-L999
-)P
-(P
-L1000
--\nSee
-ANAME CDATA dpkg-source
-ASECTION CDATA 1
-(MANREF
-)MANREF
-- for full details about source\nvariable substitutions, including the format of\n
-(TT
--debian/substvars
-)TT
--.\n
-L1005
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(TT
--debian/files
-)TT
-L1006
-)HEADING
-(P
-L1007
--\nThis file is not a permanent part of the source tree; it is used while\nbuilding packages to record which files are being generated.\n
-(PRGN
--dpkg-genchanges
-)PRGN
-- uses it when it generates a
-(TT
--.changes
-)TT
-- file.
-L1011
-)P
-(P
-L1012
--\nIt should not exist in a shipped source package, and so it (and any\nbackup files or temporary files such as\n
-(TT
--files.new
-)TT
-(FOOTNOTE
-(P
-(TT
--files.new
-)TT
-- is used as a temporary file by\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- and
-(PRGN
--dpkg-distaddfile
-)PRGN
-- - they write a new\nversion of
-(TT
--files
-)TT
-- here before renaming it, to avoid leaving a\ncorrupted copy if an error occurs
-)P
-)FOOTNOTE
--) should be removed by the\n
-(PRGN
--clean
-)PRGN
-- target. It may also be wise to ensure a fresh start by\nemptying or removing it at the start of the
-(PRGN
--binary
-)PRGN
-- target.
-L1021
-)P
-(P
-L1022
--\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- adds an entry to this file for the
-(TT
--.deb
-)TT
--\nfile that will be created by
-(PRGN
--dpkg-deb
-)PRGN
-- from the control file\nthat it generates, so for most packages all that needs to be done with\nthis file is to delete it in
-(PRGN
--clean
-)PRGN
--.
-L1027
-)P
-(P
-L1028
--\nIf a package upload includes files besides the source package and any\nbinary packages whose control files were made with\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- then they should be placed in the parent of the\npackage's top-level directory and
-(PRGN
--dpkg-distaddfile
-)PRGN
-- should be\ncalled to add the file to the list in
-(TT
--debian/files
-)TT
--.\n
-L1035
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
-(TT
--debian/tmp
-)TT
-L1036
-)HEADING
-(P
-L1037
--\nThis is the canonical temporary location for the construction of\nbinary packages by the
-(PRGN
--binary
-)PRGN
-- target. The directory
-(TT
--tmp
-)TT
--\nserves as the root of the filesystem tree as it is being constructed\n(for example, by using the package's upstream makefiles install\ntargets and redirecting the output there), and it also contains the\n
-(TT
--DEBIAN
-)TT
-- subdirectory. See
-AID CDATA bincreating
-(REF
-)REF
--.
-L1044
-)P
-(P
-L1045
--\nIf several binary packages are generated from the same source tree it\nis usual to use several
-(TT
--debian/tmp
-(VAR
--something
-)VAR
-)TT
-- directories,\nfor example
-(TT
--tmp-a
-)TT
-- or
-(TT
--tmp-doc
-)TT
--.
-L1049
-)P
-(P
-L1050
--\nWhatever
-(TT
--tmp
-)TT
-- directories are created and used by
-(PRGN
--binary
-)PRGN
--\nmust of course be removed by the
-(PRGN
--clean
-)PRGN
-- target.\n\n
-L1055
-)P
-)SECT1
-)SECT
-AID CDATA sourcearchives
-(SECT
-(HEADING
--Source packages as archives
-L1056
-)HEADING
-(P
-L1057
--\nAs it exists on the FTP site, a Debian source package consists of\nthree related files. You must have the right versions of all three to\nbe able to use them.
-L1061
-)P
-(P
-L1062
--\n
-ACOMPACT IMPLIED
-(TAGLIST
-L1064
-(TAG
--Debian source control file -
-(TT
--.dsc
-)TT
-)TAG
-L1065
-(ITEM
-L1067
-(P
--This file contains a series of fields, identified and separated just\nlike the fields in the control file of a binary package. The fields\nare listed below; their syntax is described above, in\n
-AID CDATA controlfields
-(REF
-)REF
--.\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1072
-(ITEM
-(P
-AID CDATA f-Source
-(QREF
-(TT
--Source
-)TT
-)QREF
-L1073
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA versions
-(QREF
-(TT
--Version
-)TT
-)QREF
-L1074
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Maintainer
-(QREF
-(TT
--Maintainer
-)TT
-)QREF
-L1075
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Binary
-(QREF
-(TT
--Binary
-)TT
-)QREF
-L1076
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Architecture
-(QREF
-(TT
--Architecture
-)TT
-)QREF
-L1077
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Standards-Version
-(QREF
-(TT
--Standards-Version
-)TT
-)QREF
-L1078
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Files
-(QREF
-(TT
--Files
-)TT
-)QREF
-L1079
-)P
-)ITEM
-)LIST
-L1080
-)P
-(P
-L1081
--\nThe source package control file is generated by
-(PRGN
--dpkg-source
-)PRGN
--\nwhen it builds the source archive, from other files in the source\npackage, described above. When unpacking it is checked against the\nfiles and directories in the other parts of the source package, as\ndescribed below.\n
-L1088
-)P
-)ITEM
-(TAG
--Original source archive -
-(TT
-(VAR
--package
-)VAR
--_
-(VAR
--upstream-version
-)VAR
--.orig.tar.gz
-)TT
-)TAG
-L1089
-(ITEM
-L1091
-(P
--This is a compressed (with
-(TT
--gzip -9
-)TT
--)
-(PRGN
--tar
-)PRGN
-- file containing\nthe source code from the upstream authors of the program. The tarfile\nunpacks into a directory\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--upstream-version
-)VAR
--.orig
-)TT
--, and does not contain\nfiles anywhere other than in there or in its subdirectories.\n
-L1097
-)P
-)ITEM
-(TAG
--Debianisation diff -
-(TT
-(VAR
--package
-)VAR
--_
-(VAR
--version-revision
-)VAR
--.diff.gz
-)TT
-)TAG
-L1098
-(ITEM
-L1100
-(P
--This is a unified context diff (
-(TT
--diff -u
-)TT
--) giving the changes which\nare required to turn the original source into the Debian source.\nThese changes may only include editing and creating plain files. The\npermissions of files, the targets of symbolic links and the\ncharacteristics of special files or pipes may not be changed and no\nfiles may be removed or renamed.
-L1106
-)P
-(P
-L1107
--\nAll the directories in the diff must exist, except the
-(TT
--debian
-)TT
--\nsubdirectory of the top of the source tree, which will be created by\n
-(PRGN
--dpkg-source
-)PRGN
-- if necessary when unpacking.
-L1111
-)P
-(P
-L1112
--\nThe
-(PRGN
--dpkg-source
-)PRGN
-- program will automatically make the\n
-(TT
--debian/rules
-)TT
-- file executable (see below).\n
-L1116
-)P
-)ITEM
-)TAGLIST
-L1117
-)P
-(P
-L1118
--\nIf there is no original source code - for example, if the package is\nspecially prepared for Debian or the Debian maintainer is the same as\nthe upstream maintainer - the format is slightly different: then there\nis no diff, and the tarfile is named\n
-(TT
-(VAR
--package
-)VAR
--_
-(VAR
--version
-)VAR
--.tar.gz
-)TT
-- and contains a directory\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
-)TT
--.\n
-L1126
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Unpacking a Debian source package without
-(PRGN
--dpkg-source
-)PRGN
-L1127
-)HEADING
-(P
-L1128
--\n
-(TT
--dpkg-source -x
-)TT
-- is the recommended way to unpack a Debian source\npackage. However, if it is not available it is possible to unpack a\nDebian source archive as follows:\n\n
-ACOMPACT TOKEN COMPACT
-(ENUMLIST
-L1134
-(ITEM
-(P
--Untar the tarfile, which will create a
-(TT
--.orig
-)TT
-- directory.
-L1135
-)P
-)ITEM
-(ITEM
-(P
--Rename the
-(TT
--.orig
-)TT
-- directory to\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
-)TT
--.
-L1137
-)P
-)ITEM
-(ITEM
-(P
--Create the subdirectory
-(TT
--debian
-)TT
-- at the top of the source\ntree.
-L1139
-)P
-)ITEM
-(ITEM
-(P
--Apply the diff using
-(TT
--patch -p0
-)TT
--.
-L1140
-)P
-)ITEM
-(ITEM
-(P
--Untar the tarfile again if you want a copy of the original\nsource code alongside the Debianised version.
-L1142
-)P
-)ITEM
-)ENUMLIST
-L1143
-)P
-(P
-L1144
--\nIt is not possible to generate a valid Debian source archive without\nusing
-(PRGN
--dpkg-source
-)PRGN
--. In particular, attempting to use\n
-(PRGN
--diff
-)PRGN
-- directly to generate the
-(TT
--.diff.gz
-)TT
-- file will not work.\n
-L1149
-)P
-AID IMPLIED
-(SECT1
-(HEADING
--Restrictions on objects in source packages
-L1150
-)HEADING
-(P
-L1151
--\nThe source package may not contain any device special files, sockets\nor setuid or setgid files.
-(FOOTNOTE
-(P
--Setgid directories are\nallowed.
-)P
-)FOOTNOTE
-L1155
-)P
-(P
-L1156
--\nThe source packaging tools manage the changes between the original and\nDebianised source using
-(PRGN
--diff
-)PRGN
-- and
-(PRGN
--patch
-)PRGN
--. Turning the\noriginal source tree as included in the
-(TT
--.orig.tar.gz
-)TT
-- into the\ndebianised source must not involve any changes which cannot be handled\nby these tools. Problematic changes which cause
-(PRGN
--dpkg-source
-)PRGN
-- to\nhalt with an error when building the source package are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1164
-(ITEM
-(P
--Adding or removing symbolic links, sockets or pipes.
-L1165
-)P
-)ITEM
-(ITEM
-(P
--Changing the targets of symbolic links.
-L1166
-)P
-)ITEM
-(ITEM
-(P
--Creating directories, other than
-(TT
--debian
-)TT
--.
-L1167
-)P
-)ITEM
-(ITEM
-(P
--Changes to the contents of binary files.
-L1168
-)P
-)ITEM
-)LIST
--\nChanges which cause
-(PRGN
--dpkg-source
-)PRGN
-- to print a warning but continue\nanyway are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1172
-(ITEM
-(P
--Removing files, directories or symlinks.
-(FOOTNOTE
-(P
--Renaming a\nfile is not treated specially - it is seen as the removal of the old\nfile (which generates a warning, but is otherwise ignored), and the\ncreation of the new one.
-)P
-)FOOTNOTE
-L1176
-)P
-)ITEM
-)LIST
--\nChanges which are not represented, but which are not detected by\n
-(PRGN
--dpkg-source
-)PRGN
--, are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1180
-(ITEM
-(P
--Changing the permissions of files (other than\n
-(TT
--debian/rules
-)TT
--) and directories.
-L1182
-)P
-)ITEM
-)LIST
-L1183
-)P
-(P
-L1184
--\nThe
-(TT
--debian
-)TT
-- directory and
-(TT
--debian/rules
-)TT
-- are handled\nspecially by
-(PRGN
--dpkg-source
-)PRGN
-- - before applying the changes it will\ncreate the
-(TT
--debian
-)TT
-- directory, and afterwards it will make\n
-(TT
--debian/rules
-)TT
-- world-exectuable.\n
-L1190
-)P
-)SECT1
-)SECT
-)CHAPT
-AID CDATA controlfields
-(CHAPT
-(HEADING
--Control files and their fields
-L1191
-)HEADING
-(P
-L1192
--\nMany of the tools in the
-(PRGN
--dpkg
-)PRGN
-- suite manipulate data in a common\nformat, known as control files. Binary and source packages have\ncontrol data as do the
-(TT
--.changes
-)TT
-- files which control the\ninstallation of uploaded files, and
-(PRGN
--dpkg
-)PRGN
--'s internal databases\nare in a similar format.\n
-L1199
-)P
-AID IMPLIED
-(SECT
-(HEADING
--Syntax of control files
-L1200
-)HEADING
-(P
-L1201
--\nA file consists of one or more paragraphs of fields. The paragraphs\nare separated by blank lines. Some control files only allow one\nparagraph; others allow several, in which case each paragraph often\nrefers to a different package.
-L1206
-)P
-(P
-L1207
--\nEach paragraph is a series of fields and values; each field consists\nof a name, followed by a colon and the value. It ends at the end of\nthe line. Horizontal whitespace (spaces and tabs) may occur before or\nafter the value and is ignored there; it is conventional to put a\nsingle space after the colon.
-L1213
-)P
-(P
-L1214
--\nSome fields' values may span several lines; in this case each\ncontinuation line
-(EM
--must
-)EM
-- start with a space or tab. Any trailing\nspaces or tabs at the end of individual lines of a field value are\nignored.
-L1219
-)P
-(P
-L1220
--\nExcept where otherwise stated only a single line of data is allowed\nand whitespace is not significant in a field body. Whitespace may\nnever appear inside names (of packages, architectures, files or\nanything else), version numbers or in between the characters of\nmulti-character version relationships.
-L1226
-)P
-(P
-L1227
--\nField names are not case-sensitive, but it is usual to capitalise the\nfields using mixed case as shown below.
-L1230
-)P
-(P
-L1231
--\nBlank lines, or lines consisting only of spaces and tabs, are not\nallowed within field values or between fields - that would mean a new\nparagraph.
-L1235
-)P
-(P
-L1236
--\nIt is important to note that there are several fields which are\noptional as far as
-(PRGN
--dpkg
-)PRGN
-- and the related tools are concerned,\nbut which must appear in every Debian package, or whose omission may\ncause problems. When writing the control files for Debian packages\nyou
-(EM
--must
-)EM
-- read the Debian policy manual in conjuction with the\ndetails below and the list of fields for the particular file.\n
-L1244
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--List of fields\n
-L1246
-)HEADING
-AID CDATA f-Package
-(SECT1
-(HEADING
-(TT
--Package
-)TT
-L1247
-)HEADING
-(P
-L1248
--\nThe name of the binary package. Package names consist of the\nalphanumerics and
-(TT
--+
-)TT
--
-(TT
---
-)TT
--
-(TT
--.
-)TT
-- (plus, minus and full\nstop).
-(FOOTNOTE
-(P
--The characters
-(TT
--@
-)TT
--
-(TT
--:
-)TT
--
-(TT
--=
-)TT
--
-(TT
--%
-)TT
--
-(TT
--_
-)TT
-- (at,\ncolon, equals, percent and underscore) used to be legal and are still\naccepted when found in a package file, but may not be used in new\npackages
-)P
-)FOOTNOTE
-L1255
-)P
-(P
-L1256
--\nThey must be at least two characters and must start with an\nalphanumeric. In current versions of dpkg they are sort of\ncase-sensitive
-(FOOTNOTE
-(P
--This is a bug.
-)P
-)FOOTNOTE
--; use lowercase\npackage names unless the package you're building (or referring to, in\nother fields) is already using uppercase.\n
-L1263
-)P
-)SECT1
-AID CDATA f-Version
-(SECT1
-(HEADING
-(TT
--Version
-)TT
-L1264
-)HEADING
-(P
-L1265
--\nThis lists the source or binary package's version number - see
-AID CDATA versions
-(REF
-)REF
-L1267
--.\n
-L1269
-)P
-)SECT1
-AID CDATA f-Architecture
-(SECT1
-(HEADING
-(TT
--Architecture
-)TT
-L1270
-)HEADING
-(P
-L1271
--\nThis is the architecture string; it is a single word for the CPU\narchitecture.
-L1274
-)P
-(P
-L1275
--\n
-(PRGN
--dpkg
-)PRGN
-- will check the declared architecture of a binary package\nagainst its own compiled-in value before it installs it.
-L1278
-)P
-(P
-L1279
--\nThe special value
-(TT
--all
-)TT
-- indicates that the package is\narchitecture-independent.
-L1282
-)P
-(P
-L1283
--\nIn the main
-(TT
--debian/control
-)TT
-- file in the source package, or in\nthe source package control file
-(TT
--.dsc
-)TT
--, a list of architectures\n(separated by spaces) is also allowed, as is the special value\n
-(TT
--any
-)TT
--. A list indicates that the source will build an\narchitecture-dependent package, and will only work correctly on the\nlisted architectures.
-(TT
--any
-)TT
-- indicates that though the source\npackage isn't dependent on any particular architecture and should\ncompile fine on any one, the binary package(s) produced are not\narchitecture-independent but will instead be specific to whatever the\ncurrent build architecture is.
-L1294
-)P
-(P
-L1295
--\nIn a
-(TT
--.changes
-)TT
-- file the
-(TT
--Architecture
-)TT
-- field lists the\narchitecture(s) of the package(s) currently being uploaded. This will\nbe a list; if the source for the package is being uploaded too the\nspecial entry
-(TT
--source
-)TT
-- is also present.
-L1300
-)P
-(P
-L1301
--\nThe current build architecture can be determined using
-(TT
--dpkg\n--print-architecture
-)TT
--.
-(FOOTNOTE
-(P
--This actually invokes\n
-(EXAMPLE
-L1305
--gcc --print-libgcc-file-name
-L1306
-)EXAMPLE
--\nand parses and decomposes the output and looks the CPU type from the\nGCC configuration in a table in
-(PRGN
--dpkg
-)PRGN
--. This is so that it will\nwork if you're cross-compiling.
-L1310
-)P
-)FOOTNOTE
--\nThis value is automatically used by
-(PRGN
--dpkg-gencontrol
-)PRGN
-- when\nbuilding the control file for a binary package for which the source\ncontrol information doesn't specify architecture
-(TT
--all
-)TT
--.
-L1314
-)P
-(P
-L1315
--\nThere is a separate option,
-(TT
----print-installation-architecture
-)TT
--,\nfor finding out what architecture
-(PRGN
--dpkg
-)PRGN
-- is willing to install.\nThis information is also in the output of
-(TT
--dpkg --version
-)TT
--.\n
-L1320
-)P
-)SECT1
-AID CDATA f-Maintainer
-(SECT1
-(HEADING
-(TT
--Maintainer
-)TT
-L1321
-)HEADING
-(P
-L1322
--\nThe package maintainer's name and email address. The name should come\nfirst, then the email address inside angle brackets
-(TT
--\|<\|\|>\|
-)TT
-- (in\nRFC822 format).
-L1326
-)P
-(P
-L1327
--\nIf the maintainer's name contains a full stop then the whole field\nwill not work directly as an email address due to a misfeature in the\nsyntax specified in RFC822; a program using this field as an address\nmust check for this and correct the problem if necessary (for example\nby putting the name in round brackets and moving it to the end, and\nbringing the email address forward).
-L1334
-)P
-(P
-L1335
--\nIn a
-(TT
--.changes
-)TT
-- file or parsed changelog data this contains the\nname and email address of the person responsible for the particular\nversion in question - this may not be the package's usual maintainer.
-L1339
-)P
-(P
-L1340
--\nThis field is usually optional in as far as the
-(PRGN
--dpkg
-)PRGN
-- are\nconcerned, but its absence when building packages usually generates a\nwarning.\n
-L1345
-)P
-)SECT1
-AID CDATA f-Source
-(SECT1
-(HEADING
-(TT
--Source
-)TT
-L1346
-)HEADING
-(P
-L1347
--\nThis field identifies the source package name.
-L1349
-)P
-(P
-L1350
--\nIn a main source control information or a
-(TT
--.changes
-)TT
-- or
-(TT
--.dsc
-)TT
--\nfile or parsed changelog data this may contain only the name of the\nsource package.
-L1354
-)P
-(P
-L1355
--\nIn the control file of a binary package (or in a
-(TT
--Packages
-)TT
-- file)\nit may be followed by a version number in parentheses.
-(FOOTNOTE
-(P
--It is\nusual to leave a space after the package name if a version number is\nspecified.
-)P
-)FOOTNOTE
-- This version number may be omitted (and is, by\n
-(PRGN
--dpkg-gencontrol
-)PRGN
--) if it has the same value as the
-(TT
--Version
-)TT
--\nfield of the binary package in question. The field itself may be\nomitted from a binary package control file when the source package has\nthe same name and version as the binary package.\n
-L1365
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Package interrelationship fields:\n
-(TT
--Depends
-)TT
--,
-(TT
--Pre-Depends
-)TT
--,
-(TT
--Recommends
-)TT
--\n
-(TT
--Suggests
-)TT
--,
-(TT
--Conflicts
-)TT
--,
-(TT
--Provides
-)TT
--,
-(TT
--Replaces
-)TT
-L1368
-)HEADING
-(P
-L1369
--\nThese fields describe the package's relationships with other packages.\nTheir syntax and semantics are described in
-AID CDATA relationships
-(REF
-)REF
--.\n
-L1373
-)P
-)SECT1
-AID CDATA f-Description
-(SECT1
-(HEADING
-(TT
--Description
-)TT
-L1374
-)HEADING
-(P
-L1375
--\nIn a binary package
-(TT
--Packages
-)TT
-- file or main source control file\nthis field contains a description of the binary package, in a special\nformat. See
-AID CDATA descriptions
-(REF
-)REF
-- for details.
-L1379
-)P
-(P
-L1380
--\nIn a
-(TT
--.changes
-)TT
-- file it contains a summary of the descriptions for\nthe packages being uploaded. The part of the field before the first\nnewline is empty; thereafter each line has the name of a binary\npackage and the summary description line from that binary package.\nEach line is indented by one space.\n
-L1387
-)P
-)SECT1
-AID CDATA f-Essential
-(SECT1
-(HEADING
-(TT
--Essential
-)TT
-L1388
-)HEADING
-(P
-L1389
--\nThis is a boolean field which may occur only in the control file of a\nbinary package (or in the
-(TT
--Packages
-)TT
-- file) or in a per-package\nfields paragraph of a main source control data file.
-L1393
-)P
-(P
-L1394
--\nIf set to
-(TT
--yes
-)TT
-- then
-(PRGN
--dpkg
-)PRGN
-- and
-(PRGN
--dselect
-)PRGN
-- will refuse to\nremove the package (though it can be upgraded and/or replaced). The\nother possible value is
-(TT
--no
-)TT
--, which is the same as not having the\nfield at all.\n
-L1400
-)P
-)SECT1
-AID CDATA f-classification
-(SECT1
-(HEADING
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-L1401
-)HEADING
-(P
-L1402
--\nThese two fields classify the package. The
-(TT
--Priority
-)TT
-- represents\nhow important that it is that the user have it installed; the\n
-(TT
--Section
-)TT
-- represents an application area into which the package has\nbeen classified.
-L1407
-)P
-(P
-L1408
--\nWhen they appear in the
-(TT
--debian/control
-)TT
-- file these fields give\nvalues for the section and priority subfields of the
-(TT
--Files
-)TT
-- field\nof the
-(TT
--.changes
-)TT
-- file, and give defaults for the section and\npriority of the binary packages.
-L1413
-)P
-(P
-L1414
--\nThe section and priority are represented, though not as separate\nfields, in the information for each file in the
-AID CDATA f-Files
-(QREF
-L1417
-(TT
--Files
-)TT
-)QREF
-- field of a
-(TT
--.changes
-)TT
-- file. The\nsection value in a
-(TT
--.changes
-)TT
-- file is used to decide where to\ninstall a package in the FTP archive.
-L1420
-)P
-(P
-L1421
--\nThese fields are not used by by
-(PRGN
--dpkg
-)PRGN
-- proper, but by\n
-(PRGN
--dselect
-)PRGN
-- when it sorts packages and selects defaults. See the\nDebian policy manual for the priorities in use and the criteria for\nselecting the priority for a Debian package, and look at the Debian\nFTP archive for a list of currently in-use priorities.
-L1427
-)P
-(P
-L1428
--\nThese fields may appear in binary package control files, in which case\nthey provide a default value in case the
-(TT
--Packages
-)TT
-- files are\nmissing the information.
-(PRGN
--dpkg
-)PRGN
-- and
-(PRGN
--dselect
-)PRGN
-- will only use\nthe value from a
-(TT
--.deb
-)TT
-- file if they have no other information; a\nvalue listed in a
-(TT
--Packages
-)TT
-- file will always take precedence. By\ndefault
-(PRGN
--dpkg-genchanges
-)PRGN
-- does not include the section and\npriority in the control file of a binary package - use the
-(TT
---isp
-)TT
--,\n
-(TT
---is
-)TT
-- or
-(TT
---ip
-)TT
-- options to achieve this effect.\n
-L1438
-)P
-)SECT1
-AID CDATA f-Binary
-(SECT1
-(HEADING
-(TT
--Binary
-)TT
-L1439
-)HEADING
-(P
-L1440
--\nThis field is a list of binary packages.
-L1442
-)P
-(P
-L1443
--\nWhen it appears in the
-(TT
--.dsc
-)TT
-- file it is the list of binary\npackages which a source package can produce. It does not necessarily\nproduce all of these binary packages for every architecture. The\nsource control file doesn't contain details of which architectures are\nappropriate for which of the binary packages.
-L1449
-)P
-(P
-L1450
--\nWhen it appears in a
-(TT
--.changes
-)TT
-- file it lists the names of the\nbinary packages actually being uploaded.
-L1453
-)P
-(P
-L1454
--\nThe syntax is a list of binary packages separated by\ncommas.
-(FOOTNOTE
-(P
--A space after each comma is conventional.
-)P
-)FOOTNOTE
--\nCurrently the packages must be separated using only spaces in the\n
-(TT
--.changes
-)TT
-- file.\n
-L1460
-)P
-)SECT1
-AID CDATA f-Installed-Size
-(SECT1
-(HEADING
-(TT
--Installed-Size
-)TT
-L1461
-)HEADING
-(P
-L1462
--\nThis field appears in the control files of binary packages, and in the\n
-(TT
--Packages
-)TT
-- files. It gives the total amount of disk space\nrequired to install the named package.
-L1466
-)P
-(P
-L1467
--\nThe disk space is represented in kilobytes as a simple decimal number.\n
-L1470
-)P
-)SECT1
-AID CDATA f-Files
-(SECT1
-(HEADING
-(TT
--Files
-)TT
-L1471
-)HEADING
-(P
-L1472
--\nThis field contains a list of files with information about each one.\nThe exact information and syntax varies with the context. In all\ncases the the part of the field contents on the same line as the field\nname is empty. The remainder of the field is one line per file, each\nline being indented by one space and containing a number of sub-fields\nseparated by spaces.
-L1479
-)P
-(P
-L1480
--\nIn the
-(TT
--.dsc
-)TT
-- (Debian source control) file each line contains the\nMD5 checksum, size and filename of the tarfile and (if applicable)\ndiff file which make up the remainder of the source\npackage.
-(FOOTNOTE
-(P
--That is, the parts which are not the\n
-(TT
--.dsc
-)TT
--.
-)P
-)FOOTNOTE
-- The exact forms of the filenames are described\nin
-AID CDATA sourcearchives
-(REF
-)REF
--.
-L1487
-)P
-(P
-L1488
--\nIn the
-(TT
--.changes
-)TT
-- file this contains one line per file being\nuploaded. Each line contains the MD5 checksum, size, section and\npriority and the filename. The section and priority are the values of\nthe corresponding fields in the main source control file - see
-AID CDATA f-classification
-(REF
-)REF
-L1493
--. If no section or priority is specified then\n
-(TT
---
-)TT
-- should be used, though section and priority values must be\nspecified for new packages to be installed properly.
-L1496
-)P
-(P
-L1497
--\nThe special value
-(TT
--byhand
-)TT
-- for the section in a
-(TT
--.changes
-)TT
-- file\nindicates that the file in question is not an ordinary package file\nand must by installed by hand by the distribution maintainers. If the\nsection is
-(TT
--byhand
-)TT
-- the priority should be
-(TT
---
-)TT
--.
-L1502
-)P
-(P
-L1503
--\nIf a new Debian revision of a package is being shipped and no new\noriginal source archive is being distributed the
-(TT
--.dsc
-)TT
-- must still\ncontain the
-(TT
--Files
-)TT
-- field entry for the original source archive\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--upstream-version
-)VAR
--.orig.tar.gz
-)TT
--, but the\n
-(TT
--.changes
-)TT
-- file should leave it out. In this case the original\nsource archive on the distribution site must match exactly,\nbyte-for-byte, the original source archive which was used to generate\nthe
-(TT
--.dsc
-)TT
-- file and diff which are being uploaded.\n\n
-L1514
-)P
-)SECT1
-AID CDATA f-Standards-Version
-(SECT1
-(HEADING
-(TT
--Standards-Version
-)TT
-L1515
-)HEADING
-(P
-L1516
--\nThe most recent version of the standards (the
-(PRGN
--dpkg
-)PRGN
-- programmers'\nand policy manuals and associated texts) with which the package\ncomplies. This is updated manually when editing the source package to\nconform to newer standards; it can sometimes be used to tell when a\npackage needs attention.
-L1522
-)P
-(P
-L1523
--\nIts format is the same as that of a version number except that no\nepoch or Debian revision is allowed - see
-AID CDATA versions
-(REF
-)REF
--.\n\n
-L1528
-)P
-)SECT1
-AID CDATA f-Distribution
-(SECT1
-(HEADING
-(TT
--Distribution
-)TT
-L1529
-)HEADING
-(P
-L1530
--\nIn a
-(TT
--.changes
-)TT
-- file or parsed changelog output this contains the\n(space-separated) name(s) of the distribution(s) where this version of\nthe package should be or was installed. Distribution names follow the\nrules for package names. (See
-AID CDATA f-Package
-(REF
-)REF
--).
-L1535
-)P
-(P
-L1536
--\nCurrent distribution values are
-(TT
--stable
-)TT
--,
-(TT
--unstable
-)TT
--,\n
-(TT
--contrib
-)TT
--,
-(TT
--non-free
-)TT
-- and
-(TT
--experimental
-)TT
--.\n
-L1540
-)P
-)SECT1
-AID CDATA f-Urgency
-(SECT1
-(HEADING
-(TT
--Urgency
-)TT
-L1541
-)HEADING
-(P
-L1542
--\nThis is a description of how important it is to upgrade to this\nversion from previous ones. It consists of a single keyword usually\ntaking one of the values
-(TT
--LOW
-)TT
--,
-(TT
--MEDIUM
-)TT
-- or
-(TT
--HIGH
-)TT
--) followed\nby an optional commentary (separated by a space) which is usually in\nparentheses. For example:\n
-(EXAMPLE
-L1549
--Urgency: LOW (HIGH for diversions users)
-L1550
-)EXAMPLE
-L1551
-)P
-(P
-L1552
--\nThis field appears in the
-(TT
--.changes
-)TT
-- file and in parsed changelogs;\nits value appears as the value of the
-(TT
--urgency
-)TT
-- attribute in a\n
-(PRGN
--dpkg
-)PRGN
---style changelog (see
-AID CDATA dpkgchangelog
-(REF
-)REF
--).
-L1556
-)P
-(P
-L1557
--\nUrgency keywords are not case-sensitive.\n
-L1560
-)P
-)SECT1
-AID CDATA f-Date
-(SECT1
-(HEADING
-(TT
--Date
-)TT
-L1561
-)HEADING
-(P
-L1562
--\nIn
-(TT
--.changes
-)TT
-- files and parsed changelogs, this gives the date the\npackage was built or last edited.\n
-L1566
-)P
-)SECT1
-AID CDATA f-Format
-(SECT1
-(HEADING
-(TT
--Format
-)TT
-L1567
-)HEADING
-(P
-L1568
--\nThis field occurs in
-(TT
--.changes
-)TT
-- files, and specifies a format\nrevision for the file. The format described here is version
-(TT
--1.5
-)TT
--.\nThe syntax of the format value is the same as that of a package\nversion number except that no epoch or Debian revision is allowed -\nsee
-AID CDATA versions
-(REF
-)REF
--.\n
-L1575
-)P
-)SECT1
-AID CDATA f-Changes
-(SECT1
-(HEADING
-(TT
--Changes
-)TT
-L1576
-)HEADING
-(P
-L1577
--\nIn a
-(TT
--.changes
-)TT
-- file or parsed changelog this field contains the\nhuman-readable changes data, describing the differences between the\nlast version and the current one.
-L1581
-)P
-(P
-L1582
--\nThere should be nothing in this field before the first newline; all\nthe subsequent lines must be indented by at least one space; blank\nlines must be represented by a line consiting only of a space and a\nfull stop.
-L1587
-)P
-(P
-L1588
--\nEach version's change information should be preceded by a `title' line\ngiving at least the version, distribution(s) and urgency, in a\nhuman-readable way.
-L1592
-)P
-(P
-L1593
--\nIf data from several versions is being returned the entry for the most\nrecent version should be returned first, and entries should be\nseparated by the representation of a blank line (the `title' line may\nalso be followed by the representation of blank line).\n
-L1599
-)P
-)SECT1
-AID CDATA f-Filename
-(SECT1
-(HEADING
-(TT
--Filename
-)TT
-- and
-(TT
--MSDOS-Filename
-)TT
-L1600
-)HEADING
-(P
-L1601
--\nThese fields in
-(TT
--Packages
-)TT
-- files give the filename(s) of (the parts\nof) a package in the distribution directories, relative to the root of\nthe Debian hierarchy. If the package has been split into several\nparts the parts are all listed in order, separated by spaces.\n
-L1607
-)P
-)SECT1
-AID CDATA f-Size
-(SECT1
-(HEADING
-(TT
--Size
-)TT
-- and
-(TT
--MD5sum
-)TT
-L1608
-)HEADING
-(P
-L1609
--\nThese fields in
-(TT
--Packages
-)TT
-- files give the size (in bytes, expressed\nin decimal) and MD5 checksum of the file(s) which make(s) up a binary\npackage in the distribution. If the package is split into several\nparts the values for the parts are listed in order, separated by\nspaces.\n
-L1616
-)P
-)SECT1
-AID CDATA f-Status
-(SECT1
-(HEADING
-(TT
--Status
-)TT
-L1617
-)HEADING
-(P
-L1618
--\nThis field in
-(PRGN
--dpkg
-)PRGN
--'s status file records whether the user wants a\npackage installed, removed or left alone, whether it is broken\n(requiring reinstallation) or not and what its current state on the\nsystem is. Each of these pieces of information is a single word.\n
-L1624
-)P
-)SECT1
-AID CDATA f-Config-Version
-(SECT1
-(HEADING
-(TT
--Config-Version
-)TT
-L1625
-)HEADING
-(P
-L1626
--\nIf a package is not installed or not configured, this field in\n
-(PRGN
--dpkg
-)PRGN
--'s status file records the last version of the package which\nwas successfully configured.\n
-L1631
-)P
-)SECT1
-AID CDATA f-Conffiles
-(SECT1
-(HEADING
-(TT
--Conffiles
-)TT
-L1632
-)HEADING
-(P
-L1633
--\nThis field in
-(PRGN
--dpkg
-)PRGN
--'s status file contains information about the\nautomatically-managed configuration files held by a package. This\nfield should
-(EM
--not
-)EM
-- appear anywhere in a package!\n
-L1638
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Obsolete fields
-L1639
-)HEADING
-(P
-L1640
--\nThese are still recognised by
-(PRGN
--dpkg
-)PRGN
-- but should not appear anywhere\nany more.\n\n
-ACOMPACT TOKEN COMPACT
-(TAGLIST
-L1646
-(TAG
-(TT
--Revision
-)TT
-L1647
-)TAG
-(TAG
-(TT
--Package-Revision
-)TT
-L1648
-)TAG
-(TAG
-(TT
--Package_Revision
-)TT
-L1649
-)TAG
-(ITEM
-L1650
-(P
--The Debian revision part of the package version was at one point in a\nseparate control file field. This field went through several names.\n
-L1653
-)P
-)ITEM
-(TAG
-(TT
--Recommended
-)TT
-L1654
-)TAG
-(ITEM
-(P
--Old name for
-(TT
--Recommends
-)TT
--\n
-L1656
-)P
-)ITEM
-(TAG
-(TT
--Optional
-)TT
-L1657
-)TAG
-(ITEM
-(P
--Old name for
-(TT
--Suggests
-)TT
--.\n
-L1659
-)P
-)ITEM
-(TAG
-(TT
--Class
-)TT
-L1660
-)TAG
-(ITEM
-(P
--Old name for
-(TT
--Priority
-)TT
--.\n
-L1662
-)P
-)ITEM
-)TAGLIST
--\n
-L1664
-)P
-)SECT1
-)SECT
-)CHAPT
-AID CDATA versions
-(CHAPT
-(HEADING
--Version numbering
-L1665
-)HEADING
-(P
-L1666
--\nEvery package has a version number, in its
-(TT
--Version
-)TT
-- control file\nfield.
-L1669
-)P
-(P
-L1670
--\n
-(PRGN
--dpkg
-)PRGN
-- imposes an ordering on version numbers, so that it can tell\nwhether packages are being up- or downgraded and so that
-(PRGN
--dselect
-)PRGN
--\ncan tell whether a package it finds available is newer than the one\ninstalled on the system. The version number format has the most\nsignificant parts (as far as comparison is concerned) at the\nbeginning.
-L1677
-)P
-(P
-L1678
--\nThe version number format is:\n\|[\|
-(VAR
--epoch
-)VAR
-(TT
--:
-)TT
--\|]\|
-(VAR
--upstream-version
-)VAR
--\|[\|
-(TT
---
-)TT
-(VAR
--debian-revision
-)VAR
--\|]\|.
-L1681
-)P
-(P
-L1682
--\nThe three components here are:\n\n
-ACOMPACT IMPLIED
-(TAGLIST
-L1687
-(TAG
-(VAR
--epoch
-)VAR
-L1688
-)TAG
-(ITEM
-L1690
-(P
--This is a single unsigned integer, which should usually be small. It\nmay be omitted, in which case zero is assumed. If it is omitted then\nthe
-(VAR
--upstream-version
-)VAR
-- may not contain any colons.
-L1693
-)P
-(P
-L1694
--\nIt is provided to allow mistakes in the version numbers of older\nversions of a package, and also a package's previous version numbering\nschemes, to be left behind.
-L1698
-)P
-(P
-L1699
--\n
-(PRGN
--dpkg
-)PRGN
-- will not usually display the epoch unless it is essential\n(non-zero, or if the
-(VAR
--upstream-version
-)VAR
-- contains a colon);\n
-(PRGN
--dselect
-)PRGN
-- does not display epochs at all in the main part of the\npackage selection display.\n
-L1705
-)P
-)ITEM
-(TAG
-(VAR
--upstream-version
-)VAR
-L1706
-)TAG
-(ITEM
-L1708
-(P
--This is the main part of the version. It is usually version number of\nthe original (`upstream') package of which the
-(TT
--.deb
-)TT
-- file has been\nmade, if this is applicable. Usually this will be in the same format\nas that specified by the upstream author(s); however, it may need to\nbe reformatted to fit into
-(PRGN
--dpkg
-)PRGN
--'s format and comparison scheme.
-L1713
-)P
-(P
-L1714
--\nThe comparison behaviour of
-(PRGN
--dpkg
-)PRGN
-- with respect to the\n
-(VAR
--upstream-version
-)VAR
-- is described below. The
-(VAR
--upstream-version
-)VAR
--\nportion of the version number is mandatory.
-L1718
-)P
-(P
-L1719
--\nThe
-(VAR
--upstream-version
-)VAR
-- may contain only alphanumerics and the\ncharacters
-(TT
--+
-)TT
--
-(TT
--.
-)TT
--
-(TT
---
-)TT
--
-(TT
--:
-)TT
-- (full stop, plus, hyphen,\ncolon) and should start with a digit. If there is no\n
-(VAR
--debian-revision
-)VAR
-- then hyphens are not allowed; if there is no\n
-(VAR
--epoch
-)VAR
-- then colons are not allowed.\n
-L1726
-)P
-)ITEM
-(TAG
-(VAR
--debian-revision
-)VAR
-L1727
-)TAG
-(ITEM
-L1729
-(P
--This part of the version represents the version of the modifications\nthat were made to the package to make it a Debian binary package. It\nis in the same format as the
-(VAR
--upstream-version
-)VAR
-- and
-(PRGN
--dpkg
-)PRGN
--\ncompares it in the same way.
-L1733
-)P
-(P
-L1734
--\nIt is optional; if it isn't present then the
-(VAR
--upstream-version
-)VAR
--\nmay not contain a hyphen. This format represents the case where a\npiece of software was written specifically to be turned into a Debian\nbinary package, and so there is only one `debianization' of it and\ntherefore no revision indication is required.
-L1740
-)P
-(P
-L1741
--\nIt is conventional to restart the
-(VAR
--debian-revision
-)VAR
-- at
-(TT
--1
-)TT
-- each\ntime the
-(VAR
--upstream-version
-)VAR
-- is increased.
-L1744
-)P
-(P
-L1745
--\n
-(PRGN
--dpkg
-)PRGN
-- will break the
-(VAR
--upstream-version
-)VAR
-- and\n
-(VAR
--debian-revision
-)VAR
-- apart at the last hyphen in the string. The\nabsence of a
-(VAR
--debian-revision
-)VAR
-- compares earlier than the presence\nof one (but note that the
-(VAR
--debian-revision
-)VAR
-- is the least\nsignificant part of the version number).
-L1751
-)P
-(P
-L1752
--\nThe
-(VAR
--debian-revision
-)VAR
-- may contain only alphanumerics and the\ncharacters
-(TT
--+
-)TT
-- and
-(TT
--.
-)TT
-- (plus and full stop).\n
-L1756
-)P
-)ITEM
-)TAGLIST
--\n\nThe
-(VAR
--upstream-version
-)VAR
-- and
-(VAR
--debian-revision
-)VAR
-- parts are\ncompared by
-(PRGN
--dpkg
-)PRGN
-- using the same algorithm:
-L1760
-)P
-(P
-L1761
--\nThe strings are compared from left to right.
-L1763
-)P
-(P
-L1764
--\nFirst the initial part of each string consisting entirely of non-digit\ncharacters is determined. These two parts (one of which may be empty)\nare compared lexically. If a difference is found it is returned. The\nlexical comparison is a comparison of ASCII values modified so that\nall the letters sort earlier than all the non-letters.
-L1770
-)P
-(P
-L1771
--\nThen the initial part of the remainder of each string which consists\nentirely of digit characters is determined. The numerical values of\nthese two parts are compared, and any difference found is returned as\nthe result of the comparison. For these purposes an empty string\n(which can only occur at the end of one or both version strings being\ncompared) counts as zero.
-L1778
-)P
-(P
-L1779
--\nThese two steps are repeated (chopping initial non-digit strings and\ninitial digit strings off from the start) until a difference is found\nor both strings are exhausted.
-L1783
-)P
-(P
-L1784
--\nNote that the purpose of epochs is to allow us to leave behind\nmistakes in version numbering, and to cope with situations where the\nversion numbering changes. It is
-(EM
--not
-)EM
-- there to cope with version\nnumbers containing strings of letters which
-(PRGN
--dpkg
-)PRGN
-- cannot interpret\n(such as
-(TT
--ALPHA
-)TT
-- or
-(TT
--pre-
-)TT
--), or with silly orderings (the author\nof this manual has heard of a package whose versions went
-(TT
--1.1
-)TT
--,\n
-(TT
--1.2
-)TT
--,
-(TT
--1.3
-)TT
--,
-(TT
--1
-)TT
--,
-(TT
--2.1
-)TT
--,
-(TT
--2.2
-)TT
--,
-(TT
--2
-)TT
-- and so forth).
-L1792
-)P
-(P
-L1793
--\nIf an upstream package has problematic version numbers they should be\nconverted to a sane form for use in the
-(TT
--Version
-)TT
-- field.\n\n
-L1798
-)P
-)CHAPT
-AID CDATA maintainerscripts
-(CHAPT
-(HEADING
--Package maintainer scripts\nand installation procedure
-L1800
-)HEADING
-AID IMPLIED
-(SECT
-(HEADING
--Introduction to package maintainer scripts
-L1801
-)HEADING
-(P
-L1802
--\nIt is possible supply scripts as part of a package which
-(PRGN
--dpkg
-)PRGN
--\nwill run for you when your package is installed, upgraded or removed.
-L1805
-)P
-(P
-L1806
--\nThese scripts should be the files
-(TT
--preinst
-)TT
--,
-(TT
--postinst
-)TT
--,\n
-(TT
--prerm
-)TT
-- and
-(TT
--postrm
-)TT
-- in the control area of the package. They\nmust be proper exectuable files; if they are scripts (which is\nrecommended) they must start with the usual
-(TT
--#!
-)TT
-- convention. They\nshould be readable and executable to anyone, and not world-writeable.
-L1812
-)P
-(P
-L1813
--\n
-(PRGN
--dpkg
-)PRGN
-- looks at the exit status from these scripts. It is\nimportant that they exit with a non-zero status if there is an error,\nso that
-(PRGN
--dpkg
-)PRGN
-- can stop its processing. For shell scripts this\nmeans that you
-(EM
--almost always
-)EM
-- need to use
-(TT
--set -e
-)TT
-- (this is\nusually true when writing shell scripts, in fact). It is also\nimportant, of course, that they don't exit with a non-zero status if\neverything went well.
-L1821
-)P
-(P
-L1822
--\nIt is necessary for the error recovery procedures that the scripts be\nidempotent: ie, invoking the same script several times in the same\nsituation should do no harm. If the first call failed, or aborted\nhalf way through for some reason, the second call should merely do the\nthings that were left undone the first time, if any, and exit with a\nsuccess status.
-L1829
-)P
-(P
-L1830
--\nWhen a package is upgraded a combination of the scripts from the old\nand new packages is called in amongst the other steps of the upgrade\nprocedure. If your scripts are going to be at all complicated you\nneed to be aware of this, and may need to check the arguments to your\nscripts.
-L1836
-)P
-(P
-L1837
--\nBroadly speaking the
-(PRGN
--preinst
-)PRGN
-- is called before (a particular\nversion of) a package is installed, and the
-(PRGN
--postinst
-)PRGN
-- afterwards;\nthe
-(PRGN
--prerm
-)PRGN
-- before (a version of) a package is removed and the\n
-(PRGN
--postrm
-)PRGN
-- afterwards.\n\n
-L1844
-)P
-)SECT
-AID CDATA mscriptsinstact
-(SECT
-(HEADING
--Summary of ways maintainer scripts are called
-L1845
-)HEADING
-(P
-L1846
--\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1848
-(ITEM
-(P
-(VAR
--new-preinst
-)VAR
--
-(TT
--install
-)TT
-L1849
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-preinst
-)VAR
--
-(TT
--install
-)TT
--
-(VAR
--old-version
-)VAR
-L1850
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-preinst
-)VAR
--
-(TT
--upgrade
-)TT
--
-(VAR
--old-version
-)VAR
-L1851
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--old-preinst
-)VAR
--
-(TT
--abort-upgrade
-)TT
--
-(VAR
--new-version
-)VAR
-L1852
-)P
-)ITEM
-)LIST
-L1853
-)P
-(P
-L1854
--\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1856
-(ITEM
-(P
-(VAR
--postinst
-)VAR
--
-(TT
--configure
-)TT
--
-(VAR
--most-recently-configured-version
-)VAR
-L1857
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--old-postinst
-)VAR
--
-(TT
--abort-upgrade
-)TT
--
-(VAR
--new version
-)VAR
-L1858
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--conflictor's-postinst
-)VAR
--
-(TT
--abort-remove
-)TT
--\n
-(TT
--in-favour
-)TT
--
-(VAR
--package
-)VAR
--
-(VAR
--new-version
-)VAR
-L1860
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--deconfigured's-postinst
-)VAR
--
-(TT
--abort-deconfigure
-)TT
--\n
-(TT
--in-favour
-)TT
--
-(VAR
--failed-install-package
-)VAR
--
-(VAR
--version
-)VAR
--\n
-(TT
--removing
-)TT
--
-(VAR
--conflicting-package
-)VAR
--
-(VAR
--version
-)VAR
-L1863
-)P
-)ITEM
-)LIST
-L1864
-)P
-(P
-L1865
--\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1867
-(ITEM
-(P
-(VAR
--prerm
-)VAR
--
-(TT
--remove
-)TT
-L1868
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--old-prerm
-)VAR
--
-(TT
--upgrade
-)TT
--
-(VAR
--new-version
-)VAR
-L1869
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-prerm
-)VAR
--
-(TT
--failed-upgrade
-)TT
--
-(VAR
--old-version
-)VAR
-L1870
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--conflictor's-prerm
-)VAR
--
-(TT
--remove
-)TT
--
-(TT
--in-favour
-)TT
--\n
-(VAR
--package
-)VAR
--
-(VAR
--new-version
-)VAR
-L1872
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--deconfigured's-prerm
-)VAR
--
-(TT
--deconfigure
-)TT
--\n
-(TT
--in-favour
-)TT
--
-(VAR
--package-being-installed
-)VAR
--
-(VAR
--version
-)VAR
--\n
-(TT
--removing
-)TT
--
-(VAR
--conflicting-package
-)VAR
--
-(VAR
--version
-)VAR
-L1875
-)P
-)ITEM
-)LIST
-L1876
-)P
-(P
-L1877
--\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1879
-(ITEM
-(P
-(VAR
--postrm
-)VAR
--
-(TT
--remove
-)TT
-L1880
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--postrm
-)VAR
--
-(TT
--purge
-)TT
-L1881
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--old-postrm
-)VAR
--
-(TT
--upgrade
-)TT
--
-(VAR
--new-version
-)VAR
-L1882
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-postrm
-)VAR
--
-(TT
--failed-upgrade
-)TT
--
-(VAR
--old-version
-)VAR
-L1883
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-postrm
-)VAR
--
-(TT
--abort-install
-)TT
-L1884
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-postrm
-)VAR
--
-(TT
--abort-install
-)TT
--
-(VAR
--old-version
-)VAR
-L1885
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-postrm
-)VAR
--
-(TT
--abort-upgrade
-)TT
--
-(VAR
--old-version
-)VAR
-L1886
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--disappearer's-postrm
-)VAR
--
-(TT
--disappear
-)TT
--
-(VAR
--overwriter
-)VAR
--
-(VAR
--new-version
-)VAR
-L1887
-)P
-)ITEM
-)LIST
--\n\n
-L1890
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Details of unpack phase of installation or upgrade
-L1891
-)HEADING
-(P
-L1892
--\nThe procedure on installation/upgrade/overwrite/disappear (ie, when\nrunning
-(TT
--dpkg --unpack
-)TT
--, or the unpack stage of
-(TT
--dpkg\n--install
-)TT
--) is as follows. In each case if an error occurs the\nactions in are general run backwards - this means that the maintainer\nscripts are run with different arguments in reverse order. These are\nthe `error unwind' calls listed below.\n\n
-ACOMPACT IMPLIED
-(ENUMLIST
-L1901
-(ITEM
-L1903
-(P
-ACOMPACT IMPLIED
-(ENUMLIST
-L1904
-(ITEM
-L1905
-(P
--If a version the package is already\ninstalled, call\n
-(EXAMPLE
-L1908
-(VAR
--old-prerm
-)VAR
-- upgrade
-(VAR
--new-version
-)VAR
-L1909
-)EXAMPLE
--\n
-L1911
-)P
-)ITEM
-(ITEM
-L1912
-(P
--If this gives an error (ie, a non-zero exit status), dpkg will\nattempt instead:\n
-(EXAMPLE
-L1915
-(VAR
--new-prerm
-)VAR
-- failed-upgrade
-(VAR
--old-version
-)VAR
-L1916
-)EXAMPLE
--\nError unwind, for both the above cases:\n
-(EXAMPLE
-L1919
-(VAR
--old-postinst
-)VAR
-- abort-upgrade
-(VAR
--new-version
-)VAR
-L1920
-)EXAMPLE
--\n
-L1922
-)P
-)ITEM
-)ENUMLIST
--\n
-L1924
-)P
-)ITEM
-(ITEM
-L1925
-(P
--If a `conflicting' package is being removed at the same time:\n
-ACOMPACT IMPLIED
-(ENUMLIST
-L1928
-(ITEM
-L1929
-(P
--If any packages depended on that conflicting package and\n
-(TT
----auto-deconfigure
-)TT
-- is specified, call, for each such package:\n
-(EXAMPLE
-L1932
-(VAR
--deconfigured's-prerm
-)VAR
-- deconfigure \\\n in-favour
-(VAR
--package-being-installed
-)VAR
--
-(VAR
--version
-)VAR
-- \\\n removing
-(VAR
--conflicting-package
-)VAR
--
-(VAR
--version
-)VAR
-L1935
-)EXAMPLE
--\nError unwind:\n
-(EXAMPLE
-L1938
-(VAR
--deconfigured's-postinst
-)VAR
-- abort-deconfigure \\\n in-favour
-(VAR
--package-being-installed-but-failed
-)VAR
--
-(VAR
--version
-)VAR
-- \\\n removing
-(VAR
--conflicting-package
-)VAR
--
-(VAR
--version
-)VAR
-L1941
-)EXAMPLE
--\nThe deconfigured packages are marked as requiring configuration, so\nthat if
-(TT
----install
-)TT
-- is used they will be configured again if\npossible.\n
-L1946
-)P
-)ITEM
-(ITEM
-L1947
-(P
--To prepare for removal of the conflicting package, call:\n
-(EXAMPLE
-L1949
-(VAR
--conflictor's-prerm
-)VAR
-- remove in-favour
-(VAR
--package
-)VAR
--
-(VAR
--new-version
-)VAR
-L1950
-)EXAMPLE
--\nError unwind:\n
-(EXAMPLE
-L1953
-(VAR
--conflictor's-postinst
-)VAR
-- abort-remove \\\n in-favour
-(VAR
--package
-)VAR
--
-(VAR
--new-version
-)VAR
-L1955
-)EXAMPLE
--\n
-L1957
-)P
-)ITEM
-)ENUMLIST
--\n
-L1959
-)P
-)ITEM
-(ITEM
-L1960
-(P
-ACOMPACT IMPLIED
-(ENUMLIST
-L1961
-(ITEM
-L1962
-(P
--If the package is being upgraded, call:\n
-(EXAMPLE
-L1964
-(VAR
--new-preinst
-)VAR
-- upgrade
-(VAR
--old-version
-)VAR
-L1965
-)EXAMPLE
--\n
-L1967
-)P
-)ITEM
-(ITEM
-L1968
-(P
--Otherwise, if the package had some configuration files from a previous\nversion installed (ie, it is in the `configuration files only' state):\n
-(EXAMPLE
-L1971
-(VAR
--new-preinst
-)VAR
-- install
-(VAR
--old-version
-)VAR
-L1972
-)EXAMPLE
--\n
-L1974
-)P
-)ITEM
-(ITEM
-L1975
-(P
--Otherwise (ie, the package was completely purged):\n
-(EXAMPLE
-L1977
-(VAR
--new-preinst
-)VAR
-- install
-L1978
-)EXAMPLE
--\nError unwind versions, respectively:\n
-(EXAMPLE
-L1981
-(VAR
--new-postrm
-)VAR
-- abort-upgrade
-(VAR
--old-version
-)VAR
--\n
-(VAR
--new-postrm
-)VAR
-- abort-install
-(VAR
--old-version
-)VAR
--\n
-(VAR
--new-postrm
-)VAR
-- abort-install
-L1984
-)EXAMPLE
--\n
-L1986
-)P
-)ITEM
-)ENUMLIST
--\n
-L1988
-)P
-)ITEM
-(ITEM
-L1989
-(P
--The new package's files are unpacked, overwriting any that may be on\nthe system already, for example any from the old version of the same\npackage or from another package (backups of the old files are left\naround, and if anything goes wrong dpkg will attempt to put them back\nas part of the error unwind).
-L1994
-)P
-(P
-L1995
--\nIt is an error for a package to contains files which are on the system\nin another package, unless
-(TT
--Replaces
-)TT
-- is used (see\n
-AID CDATA replaces
-(REF
-)REF
--). Currently the
-(TT
----force-overwrite
-)TT
-- flag is\nenabled, downgrading it to a warning, but this may not always be the\ncase.
-L2001
-)P
-(P
-L2002
--\nPackages which overwrite each other's files produce behaviour which\nthough deterministic is hard for the system administrator to\nunderstand. It can easily lead to `missing' programs if, for example,\na package is installed which overwrites a file from another package,\nand is then removed again.
-(FOOTNOTE
-(P
--Part of the problem is due to what\nis arguably a bug in
-(PRGN
--dpkg
-)PRGN
--.
-)P
-)FOOTNOTE
--\n
-L2010
-)P
-)ITEM
-(ITEM
-L2012
-(P
-ACOMPACT IMPLIED
-(ENUMLIST
-L2013
-(ITEM
-L2014
-(P
--If the package is being upgraded, call\n
-(EXAMPLE
-L2016
-(VAR
--old-postrm
-)VAR
-- upgrade
-(VAR
--new-version
-)VAR
-L2017
-)EXAMPLE
--\n
-L2019
-)P
-)ITEM
-(ITEM
-L2020
-(P
--If this fails,
-(PRGN
--dpkg
-)PRGN
-- will attempt:\n
-(EXAMPLE
-L2022
-(VAR
--new-postrm
-)VAR
-- failed-upgrade
-(VAR
--old-version
-)VAR
-L2023
-)EXAMPLE
--\nError unwind, for both cases:\n
-(EXAMPLE
-L2026
-(VAR
--old-preinst
-)VAR
-- abort-upgrade
-(VAR
--new-version
-)VAR
-L2027
-)EXAMPLE
--\n
-L2029
-)P
-)ITEM
-)ENUMLIST
--\n\nThis is the point of no return - if
-(PRGN
--dpkg
-)PRGN
-- gets this far, it won't\nback off past this point if an error occurs. This will leave the\npackage in a fairly bad state, which will require a successful\nreinstallation to clear up, but it's when
-(PRGN
--dpkg
-)PRGN
-- starts doing\nthings that are irreversible.\n
-L2037
-)P
-)ITEM
-(ITEM
-L2038
-(P
--Any files which were in the old version of the package but not in the\nnew are removed.\n
-L2041
-)P
-)ITEM
-(ITEM
-L2042
-(P
--The new file list replaces the old.\n
-L2044
-)P
-)ITEM
-(ITEM
-L2045
-(P
--The new maintainer scripts replace the old.\n
-L2047
-)P
-)ITEM
-(ITEM
-L2048
-(P
--Any packages all of whose files have been overwritten during the\ninstallation, and which aren't required for dependencies, are considered\nto have been removed. For each such package,\n\n
-ACOMPACT IMPLIED
-(ENUMLIST
-L2053
-(ITEM
-L2054
-(P
-(PRGN
--dpkg
-)PRGN
-- calls:\n
-(EXAMPLE
-L2056
-(VAR
--disappearer's-postrm
-)VAR
-- disappear \\\n
-(VAR
--overwriter
-)VAR
--
-(VAR
--overwriter-version
-)VAR
-L2058
-)EXAMPLE
--\n
-L2060
-)P
-)ITEM
-(ITEM
-L2061
-(P
--The package's maintainer scripts are removed.\n
-L2063
-)P
-)ITEM
-(ITEM
-L2064
-(P
--It is noted in the status database as being in a sane state, namely\nnot installed (any conffiles it may have are ignored, rather than\nbeing removed by
-(PRGN
--dpkg
-)PRGN
--). Note that disappearing packages do not\nhave their prerm called, because
-(PRGN
--dpkg
-)PRGN
-- doesn't know in advance\nthat the package is going to vanish.\n
-L2070
-)P
-)ITEM
-)ENUMLIST
--\n
-L2072
-)P
-)ITEM
-(ITEM
-L2073
-(P
--Any files in the package we're unpacking that are also listed in the\nfile lists of other packages are removed from those lists. (This will\nlobotomise the file list of the `conflicting' package if there is one.)\n
-L2077
-)P
-)ITEM
-(ITEM
-L2078
-(P
--The backup files made during installation, above, are deleted.\n
-L2080
-)P
-)ITEM
-(ITEM
-L2081
-(P
--The new package's status is now sane, and recorded as `unpacked'. Here\nis another point of no return - if the conflicting package's removal\nfails we do not unwind the rest of the installation; the conflicting\npackage is left in a half-removed limbo.\n
-L2086
-)P
-)ITEM
-(ITEM
-L2087
-(P
--If there was a conflicting package we go and do the removal actions\n(described below), starting with the removal of the conflicting\npackage's files (any that are also in the package being installed\nhave already been removed from the conflicting package's file list,\nand so do not get removed now).\n
-L2093
-)P
-)ITEM
-)ENUMLIST
--\n
-L2095
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Details of configuration
-L2096
-)HEADING
-(P
-L2097
--\nWhen we configure a package (this happens with
-(TT
--dpkg --install
-)TT
--, or\nwith
-(TT
----configure
-)TT
--), we first update the conffiles and then call:\n
-(EXAMPLE
-L2101
-(VAR
--postinst
-)VAR
-- configure
-(VAR
--most-recently-configured-version
-)VAR
-L2102
-)EXAMPLE
-L2103
-)P
-(P
-L2104
--\nNo attempt is made to unwind after errors during configuration.
-L2106
-)P
-(P
-L2107
--\nIf there is no most recently configured version
-(PRGN
--dpkg
-)PRGN
-- will pass a\nnull argument; older versions of dpkg may pass\n
-(TT
--\|<\|unknown\|>\|
-)TT
-- (including the angle brackets) in this case.\nEven older ones do not pass a second argument at all, under any\ncircumstances.\n
-L2114
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Details of removal and/or configuration purging
-L2115
-)HEADING
-(P
-L2116
--\n
-ACOMPACT IMPLIED
-(ENUMLIST
-L2118
-(ITEM
-L2119
-(P
-(EXAMPLE
-L2120
-(VAR
--prerm
-)VAR
-- remove
-L2121
-)EXAMPLE
--\n
-L2123
-)P
-)ITEM
-(ITEM
-L2124
-(P
--The package's files are removed (except conffiles).\n
-L2126
-)P
-)ITEM
-(ITEM
-L2127
-(P
-(EXAMPLE
-L2128
-(VAR
--postrm
-)VAR
-- remove
-L2129
-)EXAMPLE
--\n
-L2131
-)P
-)ITEM
-(ITEM
-L2132
-(P
--All the maintainer scripts except the postrm are removed.
-L2133
-)P
-(P
-L2134
--\nIf we aren't purging the package we stop here. Note that packages\nwhich have no postrm and no conffiles are automatically purged when\nremoved, as there is no difference except for the
-(PRGN
--dpkg
-)PRGN
-- status.\n
-L2139
-)P
-)ITEM
-(ITEM
-L2140
-(P
--The conffiles and any backup files (
-(TT
--~
-)TT
---files,
-(TT
--#*#
-)TT
-- files,\n
-(TT
--%
-)TT
---files,
-(TT
--.dpkg-{old,new,tmp}
-)TT
--, etc.) are removed.\n
-L2143
-)P
-)ITEM
-(ITEM
-L2144
-(P
-(EXAMPLE
-L2145
-(VAR
--postrm
-)VAR
-- purge
-L2146
-)EXAMPLE
--\n
-L2148
-)P
-)ITEM
-(ITEM
-L2149
-(P
--The package's file list is removed.\n
-L2151
-)P
-)ITEM
-)ENUMLIST
--\n\nNo attempt is made to unwind after errors during removal.\n\n
-L2156
-)P
-)SECT
-)CHAPT
-AID CDATA descriptions
-(CHAPT
-(HEADING
--Descriptions of packages - the\n
-(TT
--Description
-)TT
-- field
-L2158
-)HEADING
-(P
-L2159
--\nThe
-(TT
--Description
-)TT
-- control file field is used by
-(PRGN
--dselect
-)PRGN
-- when\nthe user is selecting which packages to install and by
-(PRGN
--dpkg
-)PRGN
--\nwhen it displays information about the status of packages and so\nforth. It is included on the FTP site in the
-(PRGN
--Packages
-)PRGN
-- files,\nand may also be used by the Debian WWW pages.
-L2165
-)P
-(P
-L2166
--\nThe description is intended to describe the program to a user who has\nnever met it before so that they know whether they want to install it.\nIt should also give information about the significant dependencies and\nconflicts between this package and others, so that the user knows why\nthese dependencies and conflicts have been declared.
-L2172
-)P
-(P
-L2173
--\nThe field's format is as follows:\n
-(EXAMPLE
-L2176
--Description:
-(VAR
--single line synopsis
-)VAR
--\n
-(VAR
--extended description over several lines
-)VAR
-L2178
-)EXAMPLE
-L2179
-)P
-(P
-L2180
--\nThe synopsis is often printed in lists of packages and so forth, and\nshould be as informative as possible. Every package should also have\nan extended description.
-L2184
-)P
-(P
-L2186
-)P
-AID IMPLIED
-(SECT
-(HEADING
--Types of formatting line in the extended description
-L2187
-)HEADING
-(P
-L2188
--\n
-ACOMPACT IMPLIED
-(LIST
-L2190
-(ITEM
-L2191
-(P
--Those starting with a single space are part of a paragraph.\nSuccessive lines of this form will be word-wrapped when displayed.\nThe leading space will usually be stripped off.\n
-L2195
-)P
-)ITEM
-(ITEM
-L2196
-(P
--Those starting with two or more spaces. These will be displayed\nverbatim. If the display cannot be panned horizontally the\ndisplaying program will linewrap them `hard' (ie, without taking\naccount of word breaks). If it can they will be allowed to trail\noff to the right. None, one or two initial spaces may be deleted,\nbut the number of spaces deleted from each line will be the same\n(so that you can have indenting work correctly, for example).\n
-L2204
-)P
-)ITEM
-(ITEM
-L2205
-(P
--Those containing a single space followed by a single full stop\ncharacter. These are rendered as blank lines. This is the
-(EM
--only
-)EM
--\nway to get a blank line - see below.\n
-L2209
-)P
-)ITEM
-(ITEM
-L2210
-(P
--Those containing a space, a full stop and some more characters. These\nare for future expansion. Do not use them.
-L2212
-)P
-)ITEM
-)LIST
--\n
-L2214
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Notes about writing descriptions
-L2215
-)HEADING
-(P
-L2216
--\n
-(EM
--Always
-)EM
-- start extended description lines with at least one\nwhitespace character. Fields in the control file and in the Packages\nfile are separated by field names starting in the first column, just\nas message header fields are in RFC822. Forgetting the whitespace\nwill cause
-(PRGN
--dpkg-deb
-)PRGN
-(FOOTNOTE
-(P
--Version 0.93.23 or\nlater.
-)P
-)FOOTNOTE
-- to produce a syntax error when trying to build the\npackage. If you force it to build anyway
-(PRGN
--dpkg
-)PRGN
-- will refuse to\ninstall the resulting mess.
-L2225
-)P
-(P
-L2226
--\n
-(EM
--Do not
-)EM
-- include any completely
-(EM
--empty
-)EM
-- lines. These separate\ndifferent records in the Packages file and different packages in the\n
-(TT
--debian/control
-)TT
-- file, and are forbidden in package control\nfiles. See the previous paragraph for what happens if you get this\nwrong.
-L2232
-)P
-(P
-L2233
--\nThe single line synopsis should be kept brief - certainly under 80\ncharacters.
-(PRGN
--dselect
-)PRGN
-- displays between 25 and 49 characters\nwithout panning if you're using an 80-column terminal, depending on\nwhat display options are in effect.
-L2238
-)P
-(P
-L2239
--\nDo not include the package name in the synopsis line. The display\nsoftware knows how to display this already, and you do not need to\nstate it. Remember that in many situations the user may only see\nthe synopsis line - make it as informative as you can.
-L2244
-)P
-(P
-L2245
--\nThe extended description should describe what the package does and\nhow it relates to the rest of the system (in terms of, for\nexample, which subsystem it is which part of).
-L2249
-)P
-(P
-L2250
--\nThe blurb that comes with a program in its announcements and/or\n
-(PRGN
--README
-)PRGN
-- files is rarely suitable for use in a description. It\nis usually aimed at people who are already in the community where the\npackage is used. The description field needs to make sense to anyone,\neven people who have no idea about any of the\nthings the package deals with.
-L2257
-)P
-(P
-L2258
--\nPut important information first, both in the synopis and extended\ndescription. Sometimes only the first part of the synopsis or of\nthe description will be displayed. You can assume that there will\nusually be a way to see the whole extended description.
-L2263
-)P
-(P
-L2264
--\nYou may include information about dependencies and so forth in the\nextended description, if you wish.
-L2267
-)P
-(P
-L2268
--\nDo not use tab characters. Their effect is not predictable.
-L2270
-)P
-(P
-L2271
--\nDo not try to linewrap the summary (the part on the same line as the\nfield name
-(TT
--Description
-)TT
--) into the extended description. This will\nnot work correctly when the full description is displayed, and makes\nno sense where only the summary is available.\n
-L2277
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Example description in control file for Smail
-L2278
-)HEADING
-(P
-L2279
--\n
-(EXAMPLE
-L2281
--Package: smail\nVersion: 3.1.29.1-13\nMaintainer: Ian Jackson \|<\|iwj10@cus.cam.ac.uk\|>\|\nRecommends: pine | mailx | elm | emacs | mail-user-agent\nSuggests: metamail\nDepends: cron, libc5\nConflicts: sendmail\nProvides: mail-transport-agent\nDescription: Electronic mail transport system.\n Smail is the recommended mail transport agent (MTA) for Debian.\n .\n An MTA is the innards of the mail system - it takes messages from\n user-friendly mailer programs and arranges for them to be delivered\n locally or passed on to other systems as required.\n .\n In order to make use of it you must have one or more user level\n mailreader programs such as elm, pine, mailx or Emacs (which has Rmail\n and VM as mailreaders) installed. If you wish to send messages other\n than just to other users of your system you must also have appropriate\n and VM as mailreaders) installed. If you wish to send messages other\n than just to other users of your system you must also have appropriate\n networking support, in the form of IP or UUCP.
-L2303
-)EXAMPLE
--\n
-L2305
-)P
-)SECT
-)CHAPT
-AID CDATA relationships
-(CHAPT
-(HEADING
--Declaring relationships between packages
-L2306
-)HEADING
-(P
-L2307
--\nPackages can declare in their control file that they have certain\nrelationships to other packages - for example, that they may not be\ninstalled at the same time as certain other packages, and/or that they\ndepend on the presence of others, or that they should overwrite files\nin certain other packages if present.
-L2313
-)P
-(P
-L2314
--\nThis is done using the
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
--,\n
-(TT
--Conflicts
-)TT
--,
-(TT
--Provides
-)TT
-- and
-(TT
--Replaces
-)TT
-- control file fields.
-L2317
-)P
-(P
-L2319
-)P
-AID CDATA depsyntax
-(SECT
-(HEADING
--Syntax of relationship fields
-L2320
-)HEADING
-(P
-L2321
--\nThese fields all have a uniform syntax. They are a list of package\nnames separated by commas.
-L2324
-)P
-(P
-L2325
--\nIn
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
-- and
-(TT
--Pre-Depends
-)TT
--\n(the fields which declare dependencies of the package in which they\noccur on other packages) these package names may also be lists of\nalternative package names, separated by vertical bar symbols
-(TT
--|
-)TT
--\n(pipe symbols).
-L2331
-)P
-(P
-L2332
--\nAll the fields except
-(TT
--Provides
-)TT
-- may restrict their applicability\nto particular versions of each named package. This is done in\nparentheses after each individual package name; the parentheses should\ncontain a relation from the list below followed by a version number,\nin the format described in
-AID CDATA versions
-(REF
-)REF
--.
-L2338
-)P
-(P
-L2339
--\nThe relations allowed are\n
-(TT
--\|<\|\|<\|
-)TT
--,\n
-(TT
--\|<\|=
-)TT
--,\n
-(TT
--=
-)TT
--,\n
-(TT
--\|>\|=
-)TT
-- and\n
-(TT
--\|>\|\|>\|
-)TT
--\nfor strictly earlier, earlier or equal, exactly equal, later or equal\nand strictly later, respectively. The forms
-(TT
--\|<\|
-)TT
-- and
-(TT
--\|>\|
-)TT
--\nwere used to mean earlier/later or equal, rather than strictly\nearlier/later, so they should not appear in new packages (though\n
-(PRGN
--dpkg
-)PRGN
-- still supports them).
-L2351
-)P
-(P
-L2352
--\nWhitespace may appear at any point in the version specification, and\nmust appear where it's necessary to disambiguate; it is not otherwise\nsignificant. For consistency and in case of future changes to\n
-(PRGN
--dpkg
-)PRGN
-- it is recommended that a single space be used after a\nversion relationship and before a version number; it is usual also to\nput a single space after each comma, on either side of each vertical\nbar, and before each open parenthesis.
-L2360
-)P
-(P
-L2361
--\nFor example:\n
-(EXAMPLE
-L2364
--Package: metamail\nVersion: 2.7-3\nDepends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
-L2367
-)EXAMPLE
--\n
-L2369
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Dependencies -
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
--,
-(TT
--Pre-Depends
-)TT
-L2370
-)HEADING
-(P
-L2371
--\nThese four fields are used to declare a dependency by one package on\nanother. They appear in the depending package's control file.
-L2374
-)P
-(P
-L2375
--\nAll but
-(TT
--Pre-Depends
-)TT
-- (discussed below) take effect
-(EM
--only
-)EM
-- when\na package is to be configured. They do not prevent a package being on\nthe system in an unconfigured state while its dependencies are\nunsatisfied, and it is possible to replace a package whose\ndependencies are satisfied and which is properly installed with a\ndifferent version whose dependencies are not and cannot be satisfied;\nwhen this is done the depending package will be left unconfigured\n(since attempts to configure it will give errors) and will not\nfunction properly.
-L2385
-)P
-(P
-L2386
--\nFor this reason packages in an installation run are usually all\nunpacked first and all configured later; this gives later versions of\npackages with dependencies on later versions of other packages the\nopportunity to have their dependencies satisfied.
-L2391
-)P
-(P
-L2392
--\nThus
-(TT
--Depends
-)TT
-- allows package maintainers to impose an order in\nwhich packages should be configured.\n\n
-ACOMPACT IMPLIED
-(TAGLIST
-L2397
-(TAG
-(TT
--Depends
-)TT
-L2398
-)TAG
-(ITEM
-L2400
-(P
--This declares an absolute dependency.
-L2401
-)P
-(P
-L2402
--\n
-(PRGN
--dpkg
-)PRGN
-- will not configure\npackages whose dependencies aren't satisfied. If it is asked to make\nan installation which would cause an installed package's dependencies\nto become unsatisfied it will complain
-(FOOTNOTE
-(P
--Current versions\n(1.2.4) of
-(PRGN
--dpkg
-)PRGN
-- have a bug in this area which will cause some of\nthese problems to be ignored.
-)P
-)FOOTNOTE
--, unless\n
-(TT
----auto-deconfigure
-)TT
-- is specified, in which case those packages\nwill be deconfigured before the installation proceeds.
-L2411
-)P
-(P
-L2412
--\n
-(PRGN
--dselect
-)PRGN
-- makes it hard for the user to select packages for\ninstallation, removal or upgrade in a way that would mean that\npackages'
-(PRGN
--Depends
-)PRGN
-- fields would be unsatisfied. The user can\noverride this if they wish, for example if they know that
-(PRGN
--dselect
-)PRGN
--\nhas an out-of-date view of the real package relationships.
-L2418
-)P
-(P
-L2419
--\nThe
-(TT
--Depends
-)TT
-- field should be used if the depended-on package is\nrequired for the depending package to provide a significant amount of\nfunctionality.\n
-L2424
-)P
-)ITEM
-(TAG
-(TT
--Recommends
-)TT
-L2425
-)TAG
-(ITEM
-L2426
-(P
--This declares a strong, but not absolute, dependency.
-L2427
-)P
-(P
-L2428
--\n
-(TT
--Recommends
-)TT
-- is ignored by
-(PRGN
--dpkg
-)PRGN
--, so that users using the\ncommand-line (who are presumed to know what they're doing) will not be\nimpeded.
-L2432
-)P
-(P
-L2433
--\nIt is treated by
-(PRGN
--dselect
-)PRGN
-- exactly as
-(TT
--Depends
-)TT
-- is; this makes\nit hard for the user to select things so as to leave
-(TT
--Recommends
-)TT
--\nfields unsatisfied, but they are able to do so by being persistent.
-L2437
-)P
-(P
-L2438
--\nThe
-(TT
--Recommends
-)TT
-- field should list packages that would be found\ntogether with this one in all but unusual installations.\n
-L2442
-)P
-)ITEM
-(TAG
-(TT
--Suggests
-)TT
-L2443
-)TAG
-(ITEM
-L2445
-(P
--This is used to declare that one package may be more useful with one\nor more others. Using this field tells the packaging system and the\nuser that the listed packages are be related to this one and can\nperhaps enhance its usefulness, but that installing this one without\nthem is perfectly reasonable.
-L2450
-)P
-(P
-L2451
--\n
-(PRGN
--dselect
-)PRGN
-- will offer suggsted packages to the system administrator\nwhen they select the suggesting package, but the default is not to\ninstall the suggested package.\n
-L2456
-)P
-)ITEM
-(TAG
-(TT
--Pre-Depends
-)TT
-L2457
-)TAG
-(ITEM
-L2459
-(P
--This field is like
-(TT
--Depends
-)TT
--, except that it also forces
-(PRGN
--dpkg
-)PRGN
--\nto complete installation of the packages named before even starting\nthe installation of the package which declares the predependency.
-L2462
-)P
-(P
-L2463
--\n
-(PRGN
--dselect
-)PRGN
-- checks for predependencies when it is doing an\ninstallation run, and will attempt to find the packages which are\nrequired to be installed first and do so in the right order.
-L2467
-)P
-(P
-L2468
--\nHowever, this process is slow (because it requires repeated\ninvocations of
-(PRGN
--dpkg
-)PRGN
--) and troublesome (because it requires\nguessing where to find the appropriate files).
-L2472
-)P
-(P
-L2473
--\nFor these reasons, and because this field imposes restrictions on the\norder in which packages may be unpacked (which can be difficult for\ninstallations from multipart media, for example),
-(TT
--Pre-Depends
-)TT
--\nshould be used sparingly, preferably only by packages whose premature\nupgrade or installation would hamper the ability of the system to\ncontinue with any upgrade that might be in progress.
-L2480
-)P
-(P
-L2481
--\nWhen the package declaring it is being configured, a\n
-(TT
--Pre-Dependency
-)TT
-- will be considered satisfied only if the depending\npackage has been correctly configured, just as if an ordinary\n
-(TT
--Depends
-)TT
-- had been used.
-L2486
-)P
-(P
-L2487
--\nHowever, when a package declaring a predependency is being unpacked\nthe predependency can be satisfied even if the depended-on package(s)\nare only unpacked or half-configured, provided that they have been\nconfigured correctly at some point in the past (and not removed or\npartially removed since). In this case both the previously-configured\nand currently unpacked or half-configured versions must satisfy any\nversion clause in the
-(TT
--Pre-Depends
-)TT
-- field.\n
-L2496
-)P
-)ITEM
-)TAGLIST
--\n
-L2498
-)P
-AID IMPLIED
-(SECT1
-(HEADING
--Dependencies on shared libraries
-L2499
-)HEADING
-(P
-L2500
--\nThe dependency fields listed above are used by packages which need\nshared libraries to declare dependencies on the appropriate packages.
-L2503
-)P
-(P
-L2504
--\nThese dependencies are usually determined automatically using\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- and inserted in the package control file using\nthe control file substitution variables mechanism; see
-AID CDATA srcsubstvars
-(REF
-)REF
-L2508
-- and
-AID CDATA sourcetools
-(REF
-)REF
--.\n
-L2510
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Deconfiguration due to removal during bulk installations
-L2511
-)HEADING
-(P
-L2512
--\nIf
-(PRGN
--dpkg
-)PRGN
-- would like to remove a package due to a conflict, as\ndescribed above, but this would violate a dependency of some other\npackage on the system,
-(PRGN
--dpkg
-)PRGN
-- will usually not remove the\nconflicting package and halt with an error.
-L2517
-)P
-(P
-L2518
--\nHowever, if the
-(TT
----auto-deconfigure
-)TT
-- (
-(TT
---B
-)TT
--) option is used\n
-(PRGN
--dpkg
-)PRGN
-- will automatically `deconfigure' the package with the\nproblematic dependency, so that the conflicting package can be removed\nand the package we're trying to install can be installed. If\n
-(PRGN
--dpkg
-)PRGN
-- is being asked to install packages (rather than just\nunpacking them) it will try to reconfigure the package when it has\nunpacked all its arguments, in the hope that one of the other packages\nit is installing will satisfy the problematic dependency.
-L2527
-)P
-(P
-L2528
--\n
-(PRGN
--dselect
-)PRGN
-- supplies this argument to
-(PRGN
--dpkg
-)PRGN
-- when it invokes it,\nso that bulk installations proceed smoothly.\n
-L2532
-)P
-)SECT1
-)SECT
-AID CDATA conflicts
-(SECT
-(HEADING
--Alternative packages -
-(TT
--Conflicts
-)TT
-- and
-(TT
--Replaces
-)TT
-L2533
-)HEADING
-(P
-L2534
--\nWhen one package declares a conflict with another
-(PRGN
--dpkg
-)PRGN
-- will\nrefuse to allow them to be installed on the system at the same time.
-L2537
-)P
-(P
-L2538
--\nIf one package is to be installed, the other must be removed first -\nif the package being installed is marked as replacing (
-AID CDATA replaces
-(REF
-)REF
-L2541
--) the one on the system, or the one on the system is\nmarked as deselected, or both packages are marked
-(TT
--Essential
-)TT
--, then\n
-(PRGN
--dpkg
-)PRGN
-- will automatically remove the package which is causing the\nconflict, otherwise it will halt the installation of the new package\nwith an error.
-L2546
-)P
-(P
-L2547
--\n
-(PRGN
--dselect
-)PRGN
-- makes it hard to select conflicting packages, though the\nuser can override this if they wish. If they do not override it then\n
-(PRGN
--dselect
-)PRGN
-- will select one of the packages for removal, and the user\nmust make sure it is the right one. In the future
-(PRGN
--dselect
-)PRGN
-- will\nlook for the presence of a
-(TT
--Replaces
-)TT
-- field to help decide which\npackage should be installed and which removed.
-L2554
-)P
-(P
-L2555
--\nA package will not cause a conflict merely because its configuration\nfiles are still installed; it must be at least half-installed.
-L2558
-)P
-(P
-L2559
--\nA special exception is made for packages which declare a conflict with\ntheir own package name, or with a virtual package which they provide\n(see below): this does not prevent their installation, and allows a\npackage to conflict with others providing a replacement for it. You\nuse this feature when you want the package in question to be the only\npackage providing something.
-L2566
-)P
-(P
-L2567
--\nA
-(TT
--Conflicts
-)TT
-- entry should almost never have an `earlier than'\nversion clause. This would prevent
-(PRGN
--dpkg
-)PRGN
-- from upgrading or\ninstalling the package which declared such a conflict until the\nupgrade or removal of the conflicted-with package had been completed.\nThis aspect of installation ordering is not handled by
-(PRGN
--dselect
-)PRGN
--,\nso that the use
-(TT
--Conflicts
-)TT
-- in this way is likely to cause problems\nfor `bulk run' upgrades and installations.
-L2575
-)P
-(P
-L2576
--\n
-L2578
-)P
-)SECT
-AID CDATA virtual
-(SECT
-(HEADING
--Virtual packages -
-(TT
--Provides
-)TT
-L2579
-)HEADING
-(P
-L2580
--\nAs well as the names of actual (`concrete') packages, the package\nrelationship fields
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
-- and\n
-(TT
--Conflicts
-)TT
-- may mention virtual packages.
-L2584
-)P
-(P
-L2585
--\nA virtual package is one which appears in the
-(TT
--Provides
-)TT
-- control\nfile field of another package. The effect is as if the package(s)\nwhich provide a particular virtual package name had been listed by\nname everywhere were the virtual package name appears.
-L2590
-)P
-(P
-L2591
--\nIf there are both a real and a virtual package of the same name then\nthe dependency may be satisfied (or the conflict caused) by either the\nreal package or any of the virtual packages which provide it. This is\nso that, for example, supposing we have\n
-(EXAMPLE
-L2597
--Package: vm\nDepends: emacs
-L2599
-)EXAMPLE
--\nand someone else releases an xemacs package they can say\n
-(EXAMPLE
-L2602
--Package: xemacs\nProvides: emacs
-L2604
-)EXAMPLE
--\nand all will work in the interim (until a purely virtual package name\nis decided on and the
-(TT
--emacs
-)TT
-- and
-(TT
--vm
-)TT
-- packages are changed to\nuse it).
-L2608
-)P
-(P
-L2609
--\nIf a dependency or a conflict has a version number attached then only\nreal packages will be considered to see whether the relationship is\nsatisfied (or the prohibition violated, for a conflict) - it is\nassumed that a real package which provides virtual package is not of\nthe `right' version. So, a
-(TT
--Provides
-)TT
-- field may not contain\nversion numbers, and the version number of the concrete package which\nprovides a particular virtual package will not be looked at when\nconsidering a dependency on or conflict with the virtual package name.
-L2618
-)P
-(P
-L2619
--\nIf you want to specify which of a set of real packages should be the\ndefault to satisfy a particular dependency on a virtual package, you\nshould list the real package as alternative before the virtual.
-L2623
-)P
-(P
-L2624
--\n
-L2626
-)P
-)SECT
-AID CDATA replaces
-(SECT
-(HEADING
-(TT
--Replaces
-)TT
-- - overwriting files and replacing packages
-L2627
-)HEADING
-(P
-L2628
--\nThe
-(TT
--Replaces
-)TT
-- control file field has two purposes, which come into\nplay in different situations.
-L2631
-)P
-(P
-L2632
--\nVirtual packages (
-AID CDATA virtual
-(REF
-)REF
--) are not considered when looking\nat a
-(TT
--Replaces
-)TT
-- field - the packages declared as being replaced\nmust be mentioned by their real names.\n
-L2637
-)P
-AID IMPLIED
-(SECT1
-(HEADING
--Overwriting files in other packages
-L2638
-)HEADING
-(P
-L2639
--\nFirstly, as mentioned before, it is usually an error for a package to\ncontains files which are on the system in another package, though\ncurrently the
-(TT
----force-overwrite
-)TT
-- flag is enabled by default,\ndowngrading the error to a warning,
-L2644
-)P
-(P
-L2645
--\nIf the overwriting package declares that it replaces the one\ncontaining the file being overwritten then
-(PRGN
--dpkg
-)PRGN
-- will proceed, and\nreplace the file from the old package with that from the new. The\nfile will no longer be listed as `owned' by the old package.
-L2650
-)P
-(P
-L2651
--\nIf a package is completely replaced in this way, so that
-(PRGN
--dpkg
-)PRGN
--\ndoes not know of any files it still contains, it is considered to have\ndisappeared. It will be marked as not wanted on the system (selected\nfor removal) and not installed. Any conffiles details noted in the\npackage will be ignored, as they will have been taken over by the\nreplacing package(s). The package's
-(PRGN
--postrm
-)PRGN
-- script will be run to\nallow the package to do any final cleanup required.\nSee
-AID CDATA mscriptsinstact
-(REF
-)REF
--.
-L2660
-)P
-(P
-L2661
--\nIn the future
-(PRGN
--dpkg
-)PRGN
-- will discard files which overwrite those from\nanother package which declares that it replaces the one being\ninstalled (so that you can install an older version of a package\nwithout problems).
-L2666
-)P
-(P
-L2667
--\nThis usage of
-(TT
--Replaces
-)TT
-- only takes effect when both packages are\nat least partially on the system at once, so that it can only happen\nif they do not conflict or if the conflict has been overridden.\n
-L2672
-)P
-)SECT1
-AID IMPLIED
-(SECT1
-(HEADING
--Replacing whole packages, forcing their removal
-L2673
-)HEADING
-(P
-L2674
--\nSecondly,
-(TT
--Replaces
-)TT
-- allows
-(PRGN
--dpkg
-)PRGN
-- and
-(PRGN
--dselect
-)PRGN
-- to resolve\nwhich package should be removed when a conflict - see\n
-AID CDATA conflicts
-(REF
-)REF
--. This usage only takes effect when the two\npackages
-(EM
--do
-)EM
-- conflict, so that the two effects do not interfere\nwith each other.
-L2680
-)P
-(P
-L2682
-)P
-)SECT1
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Defaults for satisfying dependencies - ordering
-L2683
-)HEADING
-(P
-L2684
--\nOrdering is significant in dependency fields.
-L2686
-)P
-(P
-L2687
--\nUsually dselect will suggest to the user that they select the package\nwith the most `fundamental' class (eg, it will prefer Base packages to\nOptional ones), or the one that they `most wanted' to select in some\nsense.
-L2692
-)P
-(P
-L2693
--\nIn the absence of other information
-(PRGN
--dselect
-)PRGN
-- will offer a\ndefault selection of the first named package in a list of\nalternatives.
-L2697
-)P
-(P
-L2698
--\nHowever, there is no way to specify the `order' of several packages\nwhich all provide the same thing, when that thing is listed as a\ndependency.
-L2702
-)P
-(P
-L2703
--\nTherefore a dependency on a virtual package should contain a concrete\npackage name as the first alternative, so that this is the default.
-L2706
-)P
-(P
-L2707
--\nFor example, consider the set of packages:\n\n
-(EXAMPLE
-L2711
--Package: glibcdoc\nRecommends: info-browser\n\nPackage: info\nProvides: info-browser\n\nPackage: emacs\nProvides: info-browser
-L2719
-)EXAMPLE
-L2720
-)P
-(P
-L2721
--\nIf
-(PRGN
--emacs
-)PRGN
-- and
-(PRGN
--info
-)PRGN
-- both have the same priority then\n
-(PRGN
--dselect
-)PRGN
--'s choice is essentially random. Better would be\n
-(EXAMPLE
-L2725
--Package: glibcdoc\nRecommends: info | info-browser
-L2727
-)EXAMPLE
--\nso that
-(PRGN
--dselect
-)PRGN
-- defaults to selecting the lightweight standalone\ninfo browser.\n\n\n
-L2733
-)P
-)SECT
-)CHAPT
-AID CDATA conffiles
-(CHAPT
-(HEADING
--Configuration file handling
-L2734
-)HEADING
-(P
-L2735
--\n
-(PRGN
--dpkg
-)PRGN
-- can do a certain amount of automatic handling of package\nconfiguration files.
-L2738
-)P
-(P
-L2739
--\nWhether this mechanism is appropriate depends on a number of factors,\nbut basically there are two approaches to any particular configuration\nfile.
-L2743
-)P
-(P
-L2744
--\nThe easy method is to ship a best-effort configuration in the package,\nand use
-(PRGN
--dpkg
-)PRGN
--'s conffile mechanism to handle updates. If the user\nis unlikely to want to edit the file, but you need them to be able to\nwithout losing their changes, and a new package with a changed version\nof the file is only released infrequently, this is a good approach.
-L2750
-)P
-(P
-L2751
--\nThe hard method is to build the configuration file from scratch in the\n
-(PRGN
--postinst
-)PRGN
-- script, and to take the responsibility for fixing any\nmistakes made in earlier versions of the package automatically. This\nwill be appropriate if the file is likely to need to be different on\neach system.\n
-L2758
-)P
-AID IMPLIED
-(SECT
-(HEADING
--Automatic handling of configuration files by
-(PRGN
--dpkg
-)PRGN
-L2759
-)HEADING
-(P
-L2760
--\nA package may contain a control area file called
-(TT
--conffiles
-)TT
--. This\nfile should be a list of filenames of configuration files needing\nautomatic handling, separated by newlines. The filenames should be\nabsolute pathnames, and the files referred to should actually exist in\nthe package.
-L2766
-)P
-(P
-L2767
--\nWhen a package is upgraded
-(PRGN
--dpkg
-)PRGN
-- will process the configuration\nfiles during the configuration stage, shortly before it runs the\npackage's
-(PRGN
--postinst
-)PRGN
-- script,
-L2771
-)P
-(P
-L2772
--\nFor each file it checks to see whether the version of the file\nincluded in the package is the same as the one that was included in\nthe last version of the package (the one that is being upgraded\nfrom); it also compares the version currently installed on the system\nwith the one shipped with the last version.
-L2778
-)P
-(P
-L2779
--\nIf neither the user nor the package maintainer has changed the file,\nit is left alone. If one or the other has changed their version, then\nthe changed version is preferred - ie, if the user edits their file,\nbut the package maintainer doesn't ship a different version, the\nuser's changes will stay, silently, but if the maintainer ships a new\nversion and the user hasn't edited it the new version will be\ninstalled (with an informative message). If both have changed their\nversion the user is prompted about the problem and must resolve the\ndifferences themselves.
-L2789
-)P
-(P
-L2790
--\nThe comparisons are done by calculating the MD5 message digests of the\nfiles, and storing the MD5 of the file as it was included in the most\nrecent version of the package.
-L2794
-)P
-(P
-L2795
--\nWhen a package is installed for the first time
-(PRGN
--dpkg
-)PRGN
-- will install\nthe file that comes with it, unless that would mean overwriting a file\nalready on the filesystem.
-L2799
-)P
-(P
-L2800
--\nHowever, note that
-(PRGN
--dpkg
-)PRGN
-- will
-(EM
--not
-)EM
-- replace a conffile that\nwas removed by the user (or by a script). This is necessary because\nwith some programs a missing file produces an effect hard or\nimpossible to achieve in another way, so that a missing file needs to\nbe kept that way if the user did it.
-L2806
-)P
-(P
-L2807
--\nNote that a package should
-(EM
--not
-)EM
-- modify a
-(PRGN
--dpkg
-)PRGN
---handled\nconffile in its maintainer scripts. Doing this will lead to\n
-(PRGN
--dpkg
-)PRGN
-- giving the user confusing and possibly dangerous options\nfor conffile update when the package is upgraded.\n
-L2813
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Fully-featured maintainer script configuration handling
-L2814
-)HEADING
-(P
-L2815
--\nFor files which contain site-specific information such as the hostname\nand networking details and so forth, it is better to create the file\nin the package's
-(PRGN
--postinst
-)PRGN
-- script.
-L2819
-)P
-(P
-L2820
--\nThis will typically involve examining the state of the rest of the\nsystem to determine values and other information, and may involve\nprompting the user for some information which can't be obtained some\nother way.
-L2825
-)P
-(P
-L2826
--\nWhen using this method there are a couple of important issues which\nshould be considered:
-L2829
-)P
-(P
-L2830
--\nIf you discover a bug in the program which generates the configuration\nfile, or if the format of the file changes from one version to the\nnext, you will have to arrange for the postinst script to do something\nsensible - usually this will mean editing the installed configuration\nfile to remove the problem or change the syntax. You will have to do\nthis very carefully, since the user may have changed the file, perhaps\nto fix the very problem that your script is trying to deal with - you\nwill have to detect these situations and deal with them correctly.
-L2839
-)P
-(P
-L2840
--\nIf you do go down this route it's probably a good idea to make the\nprogram that generates the configuration file(s) a separate program in\n
-(TT
--/usr/sbin
-)TT
--, by convention called
-(TT
-(VAR
--package
-)VAR
--config
-)TT
-- and\nthen run that if appropriate from the post-installation script. The\n
-(TT
-(VAR
--package
-)VAR
--config
-)TT
-- program should not unquestioningly overwrite\nan existing configuration - if its mode of operation is geared towards\nsetting up a package for the first time (rather than any arbitrary\nreconfiguration later) you should have it check whether the\nconfiguration already exists, and require a
-(TT
----force
-)TT
-- flag to\noverwrite it.\n\n\n
-L2854
-)P
-)SECT
-)CHAPT
-AID CDATA alternatives
-(CHAPT
-(HEADING
--Alternative versions of an interface -\n
-(PRGN
--update-alternatives
-)PRGN
-L2856
-)HEADING
-(P
-L2857
--\nWhen several packages all provide different versions of the same\nprogram or file it is useful to have the system select a default, but\nto allow the system administrator to change it and have their\ndecisions respected.
-L2862
-)P
-(P
-L2863
--\nFor example, there are several versions of the
-(PRGN
--vi
-)PRGN
-- editor, and\nthere is no reason to prevent all of them from being installed at\nonce, each under their own name (
-(PRGN
--nvi
-)PRGN
--,
-(PRGN
--vim
-)PRGN
-- or whatever).\nNevertheless it is desirable to have the name
-(TT
--vi
-)TT
-- refer to\nsomething, at least by default.
-L2869
-)P
-(P
-L2870
--\nIf all the packages involved cooperate, this can be done with\n
-(PRGN
--update-alternatives
-)PRGN
--.
-L2873
-)P
-(P
-L2874
--\nEach package provides its own version under its own name, and calls\n
-(PRGN
--update-alternatives
-)PRGN
-- in its postinst to register its version\n(and again in its prerm to deregister it).
-L2878
-)P
-(P
-L2879
--\nSee the manpage
-ANAME CDATA update-alternatives
-ASECTION CDATA 8
-(MANREF
-)MANREF
-- for\ndetails.
-L2882
-)P
-(P
-L2883
--\nIf
-(PRGN
--update-alternatives
-)PRGN
-- does not seem appropriate you may wish\nto consider using diversions instead.\n\n
-L2888
-)P
-)CHAPT
-AID CDATA diversions
-(CHAPT
-(HEADING
--Diversions - overriding a package's version of a file
-L2889
-)HEADING
-(P
-L2890
--\nIt is possible to have
-(PRGN
--dpkg
-)PRGN
-- not overwrite a file when it\nreinstalls the package it belongs to, and to have it put the file from\nthe package somewhere else instead.
-L2894
-)P
-(P
-L2895
--\nThis can be used locally to override a package's version of a file, or\nby one package to override another's version (or provide a wrapper for\nit).
-L2899
-)P
-(P
-L2900
--\nBefore deciding to use a diversion, read
-AID CDATA alternatives
-(REF
-)REF
-- to\nsee if you really want a diversion rather than several alternative\nversions of a program.
-L2904
-)P
-(P
-L2905
--\nThere is a diversion list, which is read by
-(PRGN
--dpkg
-)PRGN
--, and updated\nby a special program
-(PRGN
--dpkg-divert
-)PRGN
--. Please see
-ANAME CDATA dpkg-divert
-ASECTION CDATA 8
-(MANREF
-)MANREF
-L2908
-- for full details of its operation.
-L2909
-)P
-(P
-L2910
--\nWhen a package wishes to divert a file from another, it should call\n
-(PRGN
--dpkg-divert
-)PRGN
-- in its preinst to add the diversion and rename the\nexisting file. For example, supposing that a
-(PRGN
--smailwrapper
-)PRGN
--\npackage wishes to install a wrapper around
-(TT
--/usr/sbin/smail
-)TT
--:\n
-(EXAMPLE
-L2916
--if [ install = "$1" ]; then\n dpkg-divert --package smailwrapper --add --rename \\\n\011\011--divert /usr/sbin/smail.real /usr/sbin/smail\nfi
-L2920
-)EXAMPLE
--\nTesting
-(TT
--$1
-)TT
-- is necessary so that the script doesn't try to add the\ndiversion again when
-(PRGN
--smailwrapper
-)PRGN
-- is upgraded. The\n
-(TT
----package smailwrapper
-)TT
-- ensures that
-(PRGN
--smailwrapper
-)PRGN
--'s copy of\n
-(TT
--/usr/sbin/smail
-)TT
-- can bypass the diversion and get installed as\nthe true version.
-L2926
-)P
-(P
-L2927
--\nThe postrm has to do the reverse:\n
-(EXAMPLE
-L2930
--if [ remove = "$1" ]; then\n dpkg-divert --package smailwrapper --remove --rename \\\n --divert /usr/sbin/smail.real /usr/sbin/smail\nfi
-L2934
-)EXAMPLE
-L2935
-)P
-(P
-L2936
--\nDo not attempt to divert a file which is vitally important for the\nsystem's operation - when using
-(PRGN
--dpkg-divert
-)PRGN
-- there is a time,\nafter it has been diverted but before
-(PRGN
--dpkg
-)PRGN
-- has installed the\nnew version, when the file does not exist.\n\n
-L2943
-)P
-)CHAPT
-AID CDATA sharedlibs
-(CHAPT
-(HEADING
--Shared libraries
-L2944
-)HEADING
-(P
-L2945
--\nPackages containing shared libraries must be constructed with a little\ncare to make sure that the shared library is always available. This\nis especially important for packages whose shared libraries are\nvitally important, such as the libc.
-L2950
-)P
-(P
-L2951
--\nFirstly, your package should install the shared libraries under their\nnormal names. For example, the
-(PRGN
--libgdbm1
-)PRGN
-- package should install\n
-(TT
--libgdbm.so.1.7.3
-)TT
-- as
-(TT
--/usr/lib/libgdbm.so.1.7.3
-)TT
--. The\nfiles should not be renamed or relinked by any prerm or postrm\nscripts;
-(PRGN
--dpkg
-)PRGN
-- will take care of renaming things safely without\naffecting running programs, and attempts to interfere with this are\nlikely to lead to problems.
-L2959
-)P
-(P
-L2960
--\nSecondly, your package should include the symlink that
-(PRGN
--ldconfig
-)PRGN
--\nwould create for the shared libraries. For example, the
-(PRGN
--libgdbm1
-)PRGN
--\npackage should include a symlink from
-(TT
--/usr/lib/libgdbm.so.1
-)TT
--\nto
-(TT
--libgdbm.so.1.7.3
-)TT
--. This is needed so that
-(PRGN
--ld.so
-)PRGN
-- can find\nthe library in between the time
-(PRGN
--dpkg
-)PRGN
-- installs it and\n
-(PRGN
--ldconfig
-)PRGN
-- is run in the
-(PRGN
--postinst
-)PRGN
-- script. Futhermore, and
-(EM
--this\nis very important
-)EM
--, the symlink must be placed before the library it\npoints to in the
-(TT
--.deb
-)TT
-- file. Currently the way to ensure the\nordering is done properly is to create the symlink in the appropriate\n
-(TT
--debian/tmp/.../lib
-)TT
-- directory before installing the library\nwhen you build the package.
-L2972
-)P
-(P
-L2973
--\nIf you do the above your package does not need to call
-(PRGN
--ldconfig
-)PRGN
--\nin its maintainer scripts. It is especially important not to call\n
-(PRGN
--ldconfig
-)PRGN
-- in the postrm or preinst scripts in the case where the\npackage is being upgraded (see the programmer's manual), as\n
-(PRGN
--ldconfig
-)PRGN
-- will see the temporary names that
-(PRGN
--dpkg
-)PRGN
-- uses for the\nfiles while it is installing them and will make the shared library\nlinks point to them, just before
-(PRGN
--dpkg
-)PRGN
-- continues the installation\nand removes the links!\n\n\n
-L2985
-)P
-)CHAPT
-AID CDATA sysvinit
-(CHAPT
-(HEADING
--Configuration of
-(PRGN
--init
-)PRGN
-L2986
-)HEADING
-(P
-L2988
-)P
-AID IMPLIED
-(SECT
-(HEADING
--Introduction to the
-(TT
--init.d
-)TT
-- scheme
-L2989
-)HEADING
-(P
-L2990
--\nThe
-(TT
--/etc/init.d
-)TT
-- directory contains the scripts executed by\n
-(PRGN
--init
-)PRGN
-- when init state (or `runlevel') is changed (see
-ANAME CDATA init
-ASECTION CDATA 8
-(MANREF
-)MANREF
-L2993
--).
-L2994
-)P
-(P
-L2995
--\nThese scripts are be referenced by symbolic links in the\n
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
-- directories. When changing runlevels, init\nlooks in the directory
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
-- for the scripts it\nshould execute, where
-(VAR
--n
-)VAR
-- is the runlevel that is being changed\nto.
-L3001
-)P
-(P
-L3002
--\nThe names of the links all have the form
-(TT
--S
-(VAR
--mm
-)VAR
-(VAR
--script
-)VAR
-)TT
-- or\n
-(TT
--K
-(VAR
--mm
-)VAR
-(VAR
--script
-)VAR
-)TT
-- where
-(VAR
--mm
-)VAR
-- is a two-digit number and\n
-(VAR
--script
-)VAR
-- is the name of the script (this should be the same as the\nname of the actual script in
-(TT
--/etc/init.d
-)TT
--.\n\nWhen
-(PRGN
--init
-)PRGN
-- changes runlevel first the targets of the links whose\nnames starting with a
-(TT
--K
-)TT
-- are executed, each with the single\nargument
-(TT
--stop
-)TT
--, followed by the scripts prefixed with an
-(TT
--S
-)TT
--,\neach with the single argument
-(TT
--start
-)TT
--. The
-(TT
--K
-)TT
-- links are\nresponsible for killing services and the
-(TT
--S
-)TT
-- link for starting\nservices upon entering the runlevel.
-L3014
-)P
-(P
-L3015
--\nFor example, if we are changing from runlevel 2 to runlevel 3, init\nwill first execute all of the
-(TT
--K
-)TT
-- prefixed scripts it finds in\n
-(TT
--/etc/rc3.d
-)TT
--, and then all of the
-(TT
--S
-)TT
-- prefixed scripts. The\nlinks starting with
-(TT
--K
-)TT
-- will cause the referred-to file to be\nexecuted with an argument of
-(TT
--stop
-)TT
--, and the
-(TT
--S
-)TT
-- links with an\nargument of
-(TT
--start
-)TT
--.
-L3022
-)P
-(P
-L3023
--\nThe two-digit number
-(VAR
--mm
-)VAR
-- is used to decide which order to start\nand stop things in - low-numbered links have their scripts run first.\nFor example, the
-(TT
--K20
-)TT
-- scripts will be executed before the
-(TT
--K30
-)TT
--\nscripts. This is used when a certain service must be started before\nanother. For example, the name server
-(PRGN
--bind
-)PRGN
-- might need to be\nstarted before the news server
-(PRGN
--inn
-)PRGN
-- so that
-(PRGN
--inn
-)PRGN
-- can set\nup its access lists. In this case, the script that starts
-(PRGN
--bind
-)PRGN
--\nshould have a lower number than the script that starts
-(PRGN
--inn
-)PRGN
-- so\nthat it runs first:\n
-(EXAMPLE
-L3034
--/etc/rc2.d/S17bind\n/etc/rc2.d/S70inn
-L3036
-)EXAMPLE
--\n
-L3038
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Writing
-(TT
--init.d
-)TT
-- scripts
-L3039
-)HEADING
-(P
-L3040
--\nPackages can and should place scripts in
-(TT
--/etc/init.d
-)TT
-- to start\nor stop services at boot time or during a change of runlevel. These\nscripts should be named
-(TT
--/etc/init.d/
-(VAR
--package
-)VAR
-)TT
--, and they\nshould accept one argument, saying what to do:
-(TT
--start
-)TT
--, meaning to\nstarts the service, or
-(TT
--stop
-)TT
--, to stop the service. Optionally\nthey can support
-(TT
--reload
-)TT
-- which causes the configuration to be\nreloaded.
-L3048
-)P
-(P
-L3049
--\nThe
-(TT
--init.d
-)TT
-- scripts should ensure that they will behave sensibly\nif invoked with
-(TT
--start
-)TT
-- when the service is already running, or\nwith
-(TT
--stop
-)TT
-- when it isn't, and that they don't kill\nunfortunately-named user processes. The best way to achieve this is\nusually to use
-(PRGN
--start-stop-daemon
-)PRGN
--.
-L3055
-)P
-(P
-L3056
--\nThese scripts should not fail obscurely when the configuration files\nremain but the package has been removed, as the default in
-(PRGN
--dpkg
-)PRGN
--\nis to leave configuration files on the system after the package has\nbeen removed. Only when it is executed with the
-(TT
----purge
-)TT
-- option\nwill dpkg remove configuration files. Therefore, you should include a\n
-(TT
--test
-)TT
-- statement at the top of the script, like this:\n
-(EXAMPLE
-L3064
--test -f
-(VAR
--program-executed-later-in-script
-)VAR
-- || exit 0
-L3065
-)EXAMPLE
--\n
-L3067
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Managing the
-(TT
--rc
-(VAR
--n
-)VAR
--.d
-)TT
-- links -
-(PRGN
--update-rc.d
-)PRGN
-L3068
-)HEADING
-(P
-L3069
--\nA program is provided,
-(PRGN
--update-rc.d
-)PRGN
--, to make it easier for\npackage maintainers to arrange for the proper creation and removal of\n
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
-- symbolic links from their postinst and postrm\nscripts.
-L3074
-)P
-(P
-L3075
--\nYou should use this script to make changes to
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
--\nand
-(EM
--never
-)EM
-- include any
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
-- symbolic links in\nthe actual archive.
-L3079
-)P
-(P
-L3080
--\nBy default
-(PRGN
--update-rc.d
-)PRGN
-- will start services in each of the\nmulti-user state runlevels (2, 3, 4, and 5) and stop them in the halt\nrunlevel (0), the single-user runlevel (1) and the reboot runlevel\n(6). The system administrator will have the opportunity to customize\nrunlevels by simply adding, moving, or removing the symbolic links in\n
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
--.
-L3087
-)P
-(P
-L3088
--\nTo get the default behaviour for your package, put in your postinst\nscript\n
-(EXAMPLE
-L3092
--update-rc.d
-(VAR
--package
-)VAR
-- default \|>\|/dev/null
-L3093
-)EXAMPLE
--\nand in your postrm\n
-(EXAMPLE
-L3096
--if [ purge = "$1" ]; then\n update-rc.d
-(VAR
--package
-)VAR
-- remove \|>\|/dev/null\nfi
-L3099
-)EXAMPLE
-L3100
-)P
-(P
-L3101
--\nThis will use a default sequence number of 20. If it does not matter\nwhen or in which order the script is run, use this default. If it\ndoes, then you should talk to the maintainer of the
-(PRGN
--sysvinit
-)PRGN
--\npackage or post to
-(TT
--debian-devel
-)TT
--, and they will help you choose\na number.
-L3107
-)P
-(P
-L3108
--\nFor more information about using
-(TT
--update-rc.d
-)TT
--, please consult its\nmanpage
-ANAME CDATA update-rc.d
-ASECTION CDATA 8
-(MANREF
-)MANREF
--.\n
-L3112
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Boot-time initialisation -
-(TT
--rc.boot
-)TT
-L3113
-)HEADING
-(P
-L3114
--\nThere is another directory,
-(TT
--/etc/rc.boot
-)TT
--, which contains\nscripts which are run once per machine boot. This facility is\nprovided for initialisation of hardware devices, cleaning up of\nleftover files, and so forth.
-L3119
-)P
-(P
-L3120
--\nFor example, the
-(PRGN
--kbd
-)PRGN
-- package provides a script here for\ninitialising the keyboard layout and console font and mode.
-L3123
-)P
-(P
-L3124
--\nThe files in
-(TT
--/etc/rc.boot
-)TT
-- should
-(EM
--not
-)EM
-- be links into\n
-(TT
--/etc/init.d
-)TT
-- - they should be the scripts themselves.
-L3127
-)P
-(P
-L3128
--\n
-(TT
--rc.boot
-)TT
-- should
-(EM
--not
-)EM
-- be used for starting general-purpose\ndaemons and similar activities. This should be done using the\n
-(TT
--rc
-(VAR
--n
-)VAR
--.d
-)TT
-- scheme, above, so that the services can be started\nand stopped cleanly when the runlevel changes or the machine is to be\nshut down or rebooted.\n
-L3135
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Notes
-L3136
-)HEADING
-(P
-L3137
--\n
-(EM
--Do not
-)EM
-- include the
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d/*
-)TT
-- symbolic links in\nthe
-(TT
--.deb
-)TT
-- filesystem archive!
-(EM
--This will cause problems!
-)EM
--\nYou should create them with
-(PRGN
--update-rc.d
-)PRGN
--, as above.
-L3141
-)P
-(P
-L3142
--\n
-(EM
--Do not
-)EM
-- include the
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d/*
-)TT
-- symbolic links in\n
-(PRGN
--dpkg
-)PRGN
--'s conffiles list!
-(EM
--This will cause problems!
-)EM
--\n
-(EM
--Do
-)EM
--, however, include the
-(TT
--/etc/init.d
-)TT
-- scripts in conffiles.\n
-L3147
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Example
-L3148
-)HEADING
-(P
-L3149
--\nThe
-(PRGN
--bind
-)PRGN
-- DNS (nameserver) package wants to make sure that the\nnameserver is running in multiuser runlevels, and is properly shut\ndown with the system. It puts a script in
-(TT
--/etc/init.d
-)TT
--, naming\nthe script appropriately
-(TT
--bind
-)TT
--. As you can see, the script\ninterprets the argument
-(TT
--reload
-)TT
-- to send the nameserver a
-(TT
--HUP
-)TT
--\nsignal (causing it to reload its configuration); this way the user can\nsay
-(TT
--/etc/init.d/bind reload
-)TT
-- to reload the nameserver.
-L3157
-)P
-(P
-L3158
--\n
-(EXAMPLE
-L3160
--#!/bin/sh\n# Original version by Robert Leslie \|<\|rob@mars.org\|>\|, edited by iwj\ntest -x /usr/sbin/named || exit 0\ncase "$1" in\n start)\n test -f /etc/named.boot -a -f /var/named/boot.options || exit 0\n start-stop-daemon --start --verbose --exec /usr/sbin/named\n ;;\n stop)\n start-stop-daemon --stop --verbose \\\n --pidfile /var/run/named.pid --exec /usr/sbin/named\n ;;\n reload)\n start-stop-daemon --stop --signal 1 --verbose \\\n --pidfile /var/run/named.pid --exec /usr/sbin/named\n ;;\n *)\n echo "Usage: /etc/init.d/bind {start|stop|reload}" >&2\n exit 1\n ;;\nesac\nexit 0
-L3182
-)EXAMPLE
-L3183
-)P
-(P
-L3184
--\nAnother example on which to base your
-(TT
--/etc/init.d
-)TT
-- scripts is in\n
-(TT
--/etc/init.d/skeleton
-)TT
--.
-L3187
-)P
-(P
-L3188
--\nIf this package is happy with the default setup from\n
-(PRGN
--update-rc.d
-)PRGN
--, namely an ordering number of 20 and having named\nrunning in all runlevels, it can say in its postinst:\n
-(EXAMPLE
-L3193
--update-rc.d bind default >/dev/null
-L3194
-)EXAMPLE
--\nAnd in its postrm, to remove the links when the package is purged:\n
-(EXAMPLE
-L3197
--if [ purge = "$1" ]; then\n update-rc.d acct remove >/dev/null\nfi
-L3200
-)EXAMPLE
--\n\n\n
-L3204
-)P
-)SECT
-)CHAPT
-AID CDATA methif
-(CHAPT
-(HEADING
-(PRGN
--dselect
-)PRGN
--'s interface to its installation methods
-L3205
-)HEADING
-(P
-L3206
--\n
-(PRGN
--dselect
-)PRGN
-- calls scripts from its installation methods when it\nneeds to actually access data from the distribution. The core program\n
-(PRGN
--dselect
-)PRGN
-- itself just calls these scripts and provides the\npackage and access method selection interfaces. The installation\nmethods are responsible for invoking
-(PRGN
--dpkg
-)PRGN
-- as appropriate.
-L3212
-)P
-(P
-L3213
--\nEach installation method has three scripts:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L3216
-(ITEM
-(P
--Setup installation parameters.
-L3217
-)P
-)ITEM
-(ITEM
-(P
--Update list of available packages.
-L3218
-)P
-)ITEM
-(ITEM
-(P
--Install.
-L3219
-)P
-)ITEM
-)LIST
-L3220
-)P
-(P
-L3221
--\n
-(PRGN
--dselect
-)PRGN
-- searches for methods in
-(TT
--/usr/lib/dpkg/methods
-)TT
--\nand
-(TT
--/usr/local/lib/dpkg/methods
-)TT
--.\n
-L3225
-)P
-AID IMPLIED
-(SECT
-(HEADING
--Functions of the method scripts
-L3226
-)HEADING
-(P
-L3227
--\nThe setup script is run just after the user has chosen an installation\nmethod. It should prompt the user for parameters like the site to\nNFS-mount or FTP from, the directory to use, or the directory or\nfilesystem where the
-(TT
--.deb
-)TT
-- files can be found, or the tape or\nfloppy device to install from. It should store the responses under\n
-(TT
--/var/lib/dpkg/methods
-)TT
-- - see below. If no available\npackages list is available it should perhaps offer to scan the\navailable packages.
-L3236
-)P
-(P
-L3237
--\nThe update script should obtain a list of available packages if\npossible, and run
-(TT
--dpkg --update-avail
-)TT
--,
-(TT
--dpkg --merge-avail
-)TT
--\nand/or
-(TT
--dpkg --forget-old-unavail
-)TT
-- to load it into
-(PRGN
--dpkg
-)PRGN
-- and\n
-(PRGN
--dselect
-)PRGN
--'s database of available packages. If no packages list\nwas available and the user was offered and accepted the option of\nscanning the actual files available this scan should be done here,\nusing
-(TT
--dpkg --record-avail
-)TT
--.
-L3245
-)P
-(P
-L3246
--\nThe install script should feed all the available
-(TT
--.deb
-)TT
-- files to\n
-(TT
--dpkg --iGOEB
-)TT
-- (this is equivalent to
-(TT
--dpkg --install\n--refuse-downgrade --selected-only --skip-same-version\n--auto-deconfigure
-)TT
--). The
-(TT
---R
-)TT
-- (
-(TT
----recursive
-)TT
--) option for\ntraversing subdirectories may also be useful here).
-L3252
-)P
-(P
-L3253
--\nIf any of these scripts needs to display a message for the user, it\nshould wait for the user to hit `return' before exiting so that\ndselect doesn't immediately rewrite the screen.
-L3257
-)P
-(P
-L3258
--\nIf a method script succeeds (returns a zero exit status)\n
-(PRGN
--dselect
-)PRGN
-- will return immediately to the main menu, with the\n`next' option highlighted ready for the user to select it. If it\nfails
-(PRGN
--dselect
-)PRGN
-- will display a message and wait for the user to\nhit return.\n
-L3265
-)P
-)SECT
-AID IMPLIED
-(SECT
-(HEADING
--Location and arguments of the method scripts
-L3266
-)HEADING
-(P
-L3267
--\nA set of scripts (henceforth known as a group) may provide several\nmethods on the `main menu' with different behaviour. For example,\nthere might be a generic get-packages-by-FTP group which might provide\nmethods in the main menu for installation directly from one of the\nDebian mirror sites as well as for installation from a user-specified\nsite.
-L3274
-)P
-(P
-L3275
--\nEach group of methods implemented by the same set of scripts should\nhave a subdirectory
-(TT
--/usr/lib/dpkg/methods/
-(VAR
--group
-)VAR
-)TT
-- or\n
-(TT
--/usr/local/lib/dpkg/methods/
-(VAR
--group
-)VAR
-)TT
--, containing:\n
-ACOMPACT TOKEN COMPACT
-(TAGLIST
-L3280
-(TAG
-(TT
--names
-)TT
-L3281
-)TAG
-(ITEM
-(P
--a list of user-visible methods provided by these scripts.
-L3282
-)P
-)ITEM
-(TAG
-(TT
--setup
-)TT
-L3283
-)TAG
-(TAG
-(TT
--update
-)TT
-L3284
-)TAG
-(TAG
-(TT
--install
-)TT
-L3285
-)TAG
-(ITEM
-(P
--executable programs, the scripts themselves.
-L3286
-)P
-)ITEM
-(TAG
-(TT
--desc.
-(VAR
--option
-)VAR
-)TT
-L3287
-)TAG
-(ITEM
-(P
--description file.
-L3288
-)P
-)ITEM
-)TAGLIST
-L3289
-)P
-(P
-L3290
--\n
-(TT
--names
-)TT
-- will be formatted as a list of lines, each containing:\n
-(EXAMPLE
-L3293
-(VAR
--sequence
-)VAR
--
-(VAR
--method
-)VAR
--
-(VAR
--summary
-)VAR
-L3294
-)EXAMPLE
-L3295
-)P
-(P
-L3296
--\n
-(VAR
--sequence
-)VAR
-- is a two-digit number that will be used much like\n
-(TT
--rc.d
-)TT
-- prefixes to control the order in the main menu. If in doubt\nuse 50.
-L3300
-)P
-(P
-L3301
--\n
-(VAR
--method
-)VAR
-- is a name which is displayed by
-(PRGN
--dselect
-)PRGN
-- as the\nname of the method, and which will be passed to
-(TT
--setup
-)TT
--,\n
-(TT
--update
-)TT
-- and
-(TT
--unpack
-)TT
-- as their first argument.
-L3305
-)P
-(P
-L3306
--\n
-(VAR
--summary
-)VAR
-- is the brief description string for
-(PRGN
--dselect
-)PRGN
--'s menu.
-L3308
-)P
-(P
-L3309
--\nEach of the three scripts gets the same three arguments:
-(VAR
--vardir
-)VAR
--,\n
-(VAR
--group
-)VAR
-- and
-(VAR
--method
-)VAR
--.
-(VAR
--vardir
-)VAR
-- is the base directory for\nstoring
-(PRGN
--dpkg
-)PRGN
-- and
-(PRGN
--dselect
-)PRGN
--'s state, usually\n
-(TT
--/var/lib/dpkg
-)TT
--; this is passed in so that the
-(TT
----admindir
-)TT
--\noption to
-(PRGN
--dselect
-)PRGN
-- is honoured).
-L3315
-)P
-(P
-L3316
--\nEach option may have an extended description in\n
-(TT
--desc.
-(VAR
--option
-)VAR
-)TT
--. This should be formatted like the extended\ndescription part of a
-(TT
--Description
-)TT
-- field entry
-(EM
--shifted one\ncharacter to the left
-)EM
--.
-L3321
-)P
-(P
-L3322
--\n
-(TT
-(VAR
--vardir
-)VAR
--/methods
-)TT
-- will exist, and a method group may use a\n
-(TT
-(VAR
--vardir
-)VAR
--/methods/
-(VAR
--group
-)VAR
-)TT
-- directory to store its state.
-L3325
-)P
-(P
-L3326
--\nThe group name and method name must follow the rules for C identifiers.\n
-L3329
-)P
-)SECT
-)CHAPT
-)BOOK
-)DEBIANDOC
-C
+++ /dev/null
-L13 programmer.sgml
-(DEBIANDOC
-(BOOK
-L15
-(TITLEPAG
-(TITLE
-(PRGN
--dpkg
-)PRGN
-- programmers' manual
-L16
-)TITLE
-(AUTHOR
-(NAME
--Ian Jackson
-)NAME
-(EMAIL
--ijackson@gnu.ai.mit.edu
-)EMAIL
-L17
-)AUTHOR
-(VERSION
--version 0.2.0.0 (dpkg 1.3.7),
-(DATE
-)DATE
--\n
-L19
-)VERSION
-(ABSTRACT
-L20
--This manual describes the technical aspects of creating Debian binary\nand source packages. It also documents the interface between\n
-(PRGN
--dselect
-)PRGN
-- and its access method scripts. It does not deal with\nthe Debian Project policy requirements, and it assumes familiarity\nwith
-(PRGN
--dpkg
-)PRGN
--'s functions from the system administrator's\nperspective.\n
-L27
-)ABSTRACT
-(COPYRIGHT
-(COPYRIGHTSUMMARY
--Copyright \|©\|1996 Ian Jackson.
-L28
-)COPYRIGHTSUMMARY
-(P
-L29
--\nThis manual is free software; you may redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation; either version 2, or (at your option) any\nlater version.
-L34
-)P
-(P
-L35
--\nThis is distributed in the hope that it will be useful, but\n
-(EM
--without any warranty
-)EM
--; without even the implied warranty of\nmerchantability or fitness for a particular purpose. See the GNU\nGeneral Public License for more details.
-L40
-)P
-(P
-L41
--\nYou should have received a copy of the GNU General Public License with\nyour Debian GNU/Linux system, in
-(TT
--/usr/doc/copyright/GPL
-)TT
--, or\nwith the
-(PRGN
--dpkg
-)PRGN
-- source package as the file
-(TT
--COPYING
-)TT
--. If\nnot, write to the Free Software Foundation, Inc., 675 Mass Ave,\nCambridge, MA 02139, USA.\n
-L48
-)P
-)COPYRIGHT
-)TITLEPAG
-L48 programmer.sgml
-ADETAIL TOKEN SECT
-(TOC
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-scope
-ACHAPT CDATA 1
-ASECT IMPLIED
-AHNAME CDATA chapter 1
-(TOCENTRY
-L67 programmer.sgml
--Introduction and scope of this manual
-L68
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-binarypkg
-ACHAPT CDATA 2
-ASECT IMPLIED
-AHNAME CDATA chapter 2
-(TOCENTRY
-L124 programmer.sgml
--Binary packages
-L125
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-bincreating
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1
-AHNAME CDATA section 2.1
-(TOCENTRY
-L140 programmer.sgml
--Creating package files -
-(PRGN
--dpkg-deb
-)PRGN
-L141
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-controlarea
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2
-AHNAME CDATA section 2.2
-(TOCENTRY
-L197 programmer.sgml
--Package control information files
-L198
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-controlfile
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .3
-AHNAME CDATA section 2.3
-(TOCENTRY
-L316 programmer.sgml
--The main control information file:
-(TT
--control
-)TT
-L317
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-sourcepkg
-ACHAPT CDATA 3
-ASECT IMPLIED
-AHNAME CDATA chapter 3
-(TOCENTRY
-L356 programmer.sgml
--Source packages
-L357
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcetools
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1
-AHNAME CDATA section 3.1
-(TOCENTRY
-L363 programmer.sgml
--Tools for processing source packages
-L364
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.1
-AHNAME CDATA subsection 3.1.1
-(TOCENTRY
-L380 programmer.sgml
-(PRGN
--dpkg-source
-)PRGN
-- - packs and unpacks Debian source packages
-L381
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.2
-AHNAME CDATA subsection 3.1.2
-(TOCENTRY
-L411 programmer.sgml
-(PRGN
--dpkg-buildpackage
-)PRGN
-- - overall package-building control\nscript
-L413
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.3
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.3
-AHNAME CDATA subsection 3.1.3
-(TOCENTRY
-L448 programmer.sgml
-(PRGN
--dpkg-gencontrol
-)PRGN
-- - generates binary package control files
-L449
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.4
-AHNAME CDATA subsection 3.1.4
-(TOCENTRY
-L495 programmer.sgml
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- - calculates shared library dependencies
-L496
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.5
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.5
-AHNAME CDATA subsection 3.1.5
-(TOCENTRY
-L551 programmer.sgml
-(PRGN
--dpkg-distaddfile
-)PRGN
-- - adds a file to
-(TT
--debian/files
-)TT
-L552
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.6
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.6
-AHNAME CDATA subsection 3.1.6
-(TOCENTRY
-L579 programmer.sgml
-(PRGN
--dpkg-genchanges
-)PRGN
-- - generates a
-(TT
--.changes
-)TT
-- upload\ncontrol file
-L581
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.1.7
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.7
-AHNAME CDATA subsection 3.1.7
-(TOCENTRY
-L595 programmer.sgml
-(PRGN
--dpkg-parsechangelog
-)PRGN
-- - produces parsed representation of\na changelog
-L597
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcetree
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2
-AHNAME CDATA section 3.2
-(TOCENTRY
-L605 programmer.sgml
--The Debianised source tree
-L606
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.1
-AHNAME CDATA subsection 3.2.1
-(TOCENTRY
-L620 programmer.sgml
-(TT
--debian/rules
-)TT
-- - the main building script
-L621
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.2
-AHNAME CDATA subsection 3.2.2
-(TOCENTRY
-L748 programmer.sgml
-(TT
--debian/control
-)TT
-L749
-)TOCENTRY
-ALEVEL CDATA SECT2
-ASRID CDATA s3.2.2.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.2.1
-AHNAME CDATA subsubsection 3.2.2.1
-(TOCENTRY
-L800 programmer.sgml
--User-defined fields
-L801
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-dpkgchangelog
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.3
-AHNAME CDATA subsection 3.2.3
-(TOCENTRY
-L834 programmer.sgml
-(TT
--debian/changelog
-)TT
-L835
-)TOCENTRY
-ALEVEL CDATA SECT2
-ASRID CDATA s3.2.3.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.3.1
-AHNAME CDATA subsubsection 3.2.3.1
-(TOCENTRY
-L906 programmer.sgml
--Defining alternative changelog formats
-L907
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-srcsubstvars
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.4
-AHNAME CDATA subsection 3.2.4
-(TOCENTRY
-L983 programmer.sgml
-(TT
--debian/substvars
-)TT
-- and variable substitutions
-L984
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.5
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.5
-AHNAME CDATA subsection 3.2.5
-(TOCENTRY
-L1005 programmer.sgml
-(TT
--debian/files
-)TT
-L1006
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.2.6
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.6
-AHNAME CDATA subsection 3.2.6
-(TOCENTRY
-L1035 programmer.sgml
-(TT
--debian/tmp
-)TT
-L1036
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcearchives
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .3
-AHNAME CDATA section 3.3
-(TOCENTRY
-L1055 programmer.sgml
--Source packages as archives
-L1056
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s3.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .4
-AHNAME CDATA section 3.4
-(TOCENTRY
-L1126 programmer.sgml
--Unpacking a Debian source package without
-(PRGN
--dpkg-source
-)PRGN
-L1127
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s3.4.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .4.1
-AHNAME CDATA subsection 3.4.1
-(TOCENTRY
-L1149 programmer.sgml
--Restrictions on objects in source packages
-L1150
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-controlfields
-ACHAPT CDATA 4
-ASECT IMPLIED
-AHNAME CDATA chapter 4
-(TOCENTRY
-L1190 programmer.sgml
--Control files and their fields
-L1191
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s4.1
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .1
-AHNAME CDATA section 4.1
-(TOCENTRY
-L1199 programmer.sgml
--Syntax of control files
-L1200
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s4.2
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2
-AHNAME CDATA section 4.2
-(TOCENTRY
-L1244 programmer.sgml
--List of fields\n
-L1246
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Package
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.1
-AHNAME CDATA subsection 4.2.1
-(TOCENTRY
-L1246 programmer.sgml
-(TT
--Package
-)TT
-L1247
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Version
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.2
-AHNAME CDATA subsection 4.2.2
-(TOCENTRY
-L1263 programmer.sgml
-(TT
--Version
-)TT
-L1264
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Architecture
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.3
-AHNAME CDATA subsection 4.2.3
-(TOCENTRY
-L1269 programmer.sgml
-(TT
--Architecture
-)TT
-L1270
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Maintainer
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.4
-AHNAME CDATA subsection 4.2.4
-(TOCENTRY
-L1320 programmer.sgml
-(TT
--Maintainer
-)TT
-L1321
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Source
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.5
-AHNAME CDATA subsection 4.2.5
-(TOCENTRY
-L1345 programmer.sgml
-(TT
--Source
-)TT
-L1346
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s4.2.6
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.6
-AHNAME CDATA subsection 4.2.6
-(TOCENTRY
-L1365 programmer.sgml
--Package interrelationship fields:\n
-(TT
--Depends
-)TT
--,
-(TT
--Pre-Depends
-)TT
--,
-(TT
--Recommends
-)TT
--\n
-(TT
--Suggests
-)TT
--,
-(TT
--Conflicts
-)TT
--,
-(TT
--Provides
-)TT
--,
-(TT
--Replaces
-)TT
-L1368
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Description
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.7
-AHNAME CDATA subsection 4.2.7
-(TOCENTRY
-L1373 programmer.sgml
-(TT
--Description
-)TT
-L1374
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Essential
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.8
-AHNAME CDATA subsection 4.2.8
-(TOCENTRY
-L1387 programmer.sgml
-(TT
--Essential
-)TT
-L1388
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-classification
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.9
-AHNAME CDATA subsection 4.2.9
-(TOCENTRY
-L1400 programmer.sgml
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-L1401
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Binary
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.10
-AHNAME CDATA subsection 4.2.10
-(TOCENTRY
-L1438 programmer.sgml
-(TT
--Binary
-)TT
-L1439
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Installed-Size
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.11
-AHNAME CDATA subsection 4.2.11
-(TOCENTRY
-L1460 programmer.sgml
-(TT
--Installed-Size
-)TT
-L1461
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Files
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.12
-AHNAME CDATA subsection 4.2.12
-(TOCENTRY
-L1470 programmer.sgml
-(TT
--Files
-)TT
-L1471
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Standards-Version
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.13
-AHNAME CDATA subsection 4.2.13
-(TOCENTRY
-L1514 programmer.sgml
-(TT
--Standards-Version
-)TT
-L1515
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Distribution
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.14
-AHNAME CDATA subsection 4.2.14
-(TOCENTRY
-L1528 programmer.sgml
-(TT
--Distribution
-)TT
-L1529
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Urgency
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.15
-AHNAME CDATA subsection 4.2.15
-(TOCENTRY
-L1540 programmer.sgml
-(TT
--Urgency
-)TT
-L1541
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Date
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.16
-AHNAME CDATA subsection 4.2.16
-(TOCENTRY
-L1560 programmer.sgml
-(TT
--Date
-)TT
-L1561
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Format
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.17
-AHNAME CDATA subsection 4.2.17
-(TOCENTRY
-L1566 programmer.sgml
-(TT
--Format
-)TT
-L1567
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Changes
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.18
-AHNAME CDATA subsection 4.2.18
-(TOCENTRY
-L1575 programmer.sgml
-(TT
--Changes
-)TT
-L1576
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Filename
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.19
-AHNAME CDATA subsection 4.2.19
-(TOCENTRY
-L1599 programmer.sgml
-(TT
--Filename
-)TT
-- and
-(TT
--MSDOS-Filename
-)TT
-L1600
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Size
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.20
-AHNAME CDATA subsection 4.2.20
-(TOCENTRY
-L1607 programmer.sgml
-(TT
--Size
-)TT
-- and
-(TT
--MD5sum
-)TT
-L1608
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Status
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.21
-AHNAME CDATA subsection 4.2.21
-(TOCENTRY
-L1616 programmer.sgml
-(TT
--Status
-)TT
-L1617
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Config-Version
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.22
-AHNAME CDATA subsection 4.2.22
-(TOCENTRY
-L1624 programmer.sgml
-(TT
--Config-Version
-)TT
-L1625
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Conffiles
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.23
-AHNAME CDATA subsection 4.2.23
-(TOCENTRY
-L1631 programmer.sgml
-(TT
--Conffiles
-)TT
-L1632
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s4.2.24
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.24
-AHNAME CDATA subsection 4.2.24
-(TOCENTRY
-L1638 programmer.sgml
--Obsolete fields
-L1639
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(TOCENTRY
-L1664 programmer.sgml
--Version numbering
-L1665
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-maintainerscripts
-ACHAPT CDATA 6
-ASECT IMPLIED
-AHNAME CDATA chapter 6
-(TOCENTRY
-L1798 programmer.sgml
--Package maintainer scripts\nand installation procedure
-L1800
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s6.1
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .1
-AHNAME CDATA section 6.1
-(TOCENTRY
-L1800 programmer.sgml
--Introduction to package maintainer scripts
-L1801
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-mscriptsinstact
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .2
-AHNAME CDATA section 6.2
-(TOCENTRY
-L1844 programmer.sgml
--Summary of ways maintainer scripts are called
-L1845
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s6.3
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .3
-AHNAME CDATA section 6.3
-(TOCENTRY
-L1890 programmer.sgml
--Details of unpack phase of installation or upgrade
-L1891
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s6.4
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .4
-AHNAME CDATA section 6.4
-(TOCENTRY
-L2095 programmer.sgml
--Details of configuration
-L2096
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s6.5
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .5
-AHNAME CDATA section 6.5
-(TOCENTRY
-L2114 programmer.sgml
--Details of removal and/or configuration purging
-L2115
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-descriptions
-ACHAPT CDATA 7
-ASECT IMPLIED
-AHNAME CDATA chapter 7
-(TOCENTRY
-L2156 programmer.sgml
--Descriptions of packages - the\n
-(TT
--Description
-)TT
-- field
-L2158
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s7.1
-ACHAPT CDATA 7
-ACSRID CDATA ch-descriptions
-ASECT CDATA .1
-AHNAME CDATA section 7.1
-(TOCENTRY
-L2186 programmer.sgml
--Types of formatting line in the extended description
-L2187
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s7.2
-ACHAPT CDATA 7
-ACSRID CDATA ch-descriptions
-ASECT CDATA .2
-AHNAME CDATA section 7.2
-(TOCENTRY
-L2214 programmer.sgml
--Notes about writing descriptions
-L2215
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s7.3
-ACHAPT CDATA 7
-ACSRID CDATA ch-descriptions
-ASECT CDATA .3
-AHNAME CDATA section 7.3
-(TOCENTRY
-L2277 programmer.sgml
--Example description in control file for Smail
-L2278
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-relationships
-ACHAPT CDATA 8
-ASECT IMPLIED
-AHNAME CDATA chapter 8
-(TOCENTRY
-L2305 programmer.sgml
--Declaring relationships between packages
-L2306
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-depsyntax
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .1
-AHNAME CDATA section 8.1
-(TOCENTRY
-L2319 programmer.sgml
--Syntax of relationship fields
-L2320
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s8.2
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .2
-AHNAME CDATA section 8.2
-(TOCENTRY
-L2369 programmer.sgml
--Dependencies -
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
--,
-(TT
--Pre-Depends
-)TT
-L2370
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s8.2.1
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .2.1
-AHNAME CDATA subsection 8.2.1
-(TOCENTRY
-L2498 programmer.sgml
--Dependencies on shared libraries
-L2499
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s8.2.2
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .2.2
-AHNAME CDATA subsection 8.2.2
-(TOCENTRY
-L2510 programmer.sgml
--Deconfiguration due to removal during bulk installations
-L2511
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-conflicts
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .3
-AHNAME CDATA section 8.3
-(TOCENTRY
-L2532 programmer.sgml
--Alternative packages -
-(TT
--Conflicts
-)TT
-- and
-(TT
--Replaces
-)TT
-L2533
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-virtual
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .4
-AHNAME CDATA section 8.4
-(TOCENTRY
-L2578 programmer.sgml
--Virtual packages -
-(TT
--Provides
-)TT
-L2579
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s-replaces
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .5
-AHNAME CDATA section 8.5
-(TOCENTRY
-L2626 programmer.sgml
-(TT
--Replaces
-)TT
-- - overwriting files and replacing packages
-L2627
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s8.5.1
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .5.1
-AHNAME CDATA subsection 8.5.1
-(TOCENTRY
-L2637 programmer.sgml
--Overwriting files in other packages
-L2638
-)TOCENTRY
-ALEVEL CDATA SECT1
-ASRID CDATA s8.5.2
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .5.2
-AHNAME CDATA subsection 8.5.2
-(TOCENTRY
-L2672 programmer.sgml
--Replacing whole packages, forcing their removal
-L2673
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s8.6
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .6
-AHNAME CDATA section 8.6
-(TOCENTRY
-L2682 programmer.sgml
--Defaults for satisfying dependencies - ordering
-L2683
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-conffiles
-ACHAPT CDATA 9
-ASECT IMPLIED
-AHNAME CDATA chapter 9
-(TOCENTRY
-L2733 programmer.sgml
--Configuration file handling
-L2734
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s9.1
-ACHAPT CDATA 9
-ACSRID CDATA ch-conffiles
-ASECT CDATA .1
-AHNAME CDATA section 9.1
-(TOCENTRY
-L2758 programmer.sgml
--Automatic handling of configuration files by
-(PRGN
--dpkg
-)PRGN
-L2759
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s9.2
-ACHAPT CDATA 9
-ACSRID CDATA ch-conffiles
-ASECT CDATA .2
-AHNAME CDATA section 9.2
-(TOCENTRY
-L2813 programmer.sgml
--Fully-featured maintainer script configuration handling
-L2814
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-alternatives
-ACHAPT CDATA 10
-ASECT IMPLIED
-AHNAME CDATA chapter 10
-(TOCENTRY
-L2854 programmer.sgml
--Alternative versions of an interface -\n
-(PRGN
--update-alternatives
-)PRGN
-L2856
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-diversions
-ACHAPT CDATA 11
-ASECT IMPLIED
-AHNAME CDATA chapter 11
-(TOCENTRY
-L2888 programmer.sgml
--Diversions - overriding a package's version of a file
-L2889
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-sharedlibs
-ACHAPT CDATA 12
-ASECT IMPLIED
-AHNAME CDATA chapter 12
-(TOCENTRY
-L2943 programmer.sgml
--Shared libraries
-L2944
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-sysvinit
-ACHAPT CDATA 13
-ASECT IMPLIED
-AHNAME CDATA chapter 13
-(TOCENTRY
-L2985 programmer.sgml
--Configuration of
-(PRGN
--init
-)PRGN
-L2986
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s13.1
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .1
-AHNAME CDATA section 13.1
-(TOCENTRY
-L2988 programmer.sgml
--Introduction to the
-(TT
--init.d
-)TT
-- scheme
-L2989
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s13.2
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .2
-AHNAME CDATA section 13.2
-(TOCENTRY
-L3038 programmer.sgml
--Writing
-(TT
--init.d
-)TT
-- scripts
-L3039
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s13.3
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .3
-AHNAME CDATA section 13.3
-(TOCENTRY
-L3067 programmer.sgml
--Managing the
-(TT
--rc
-(VAR
--n
-)VAR
--.d
-)TT
-- links -
-(PRGN
--update-rc.d
-)PRGN
-L3068
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s13.4
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .4
-AHNAME CDATA section 13.4
-(TOCENTRY
-L3112 programmer.sgml
--Boot-time initialisation -
-(TT
--rc.boot
-)TT
-L3113
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s13.5
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .5
-AHNAME CDATA section 13.5
-(TOCENTRY
-L3135 programmer.sgml
--Notes
-L3136
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s13.6
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .6
-AHNAME CDATA section 13.6
-(TOCENTRY
-L3147 programmer.sgml
--Example
-L3148
-)TOCENTRY
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-methif
-ACHAPT CDATA 14
-ASECT IMPLIED
-AHNAME CDATA chapter 14
-(TOCENTRY
-L3204 programmer.sgml
-(PRGN
--dselect
-)PRGN
--'s interface to its installation methods
-L3205
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s14.1
-ACHAPT CDATA 14
-ACSRID CDATA ch-methif
-ASECT CDATA .1
-AHNAME CDATA section 14.1
-(TOCENTRY
-L3225 programmer.sgml
--Functions of the method scripts
-L3226
-)TOCENTRY
-ALEVEL CDATA SECT
-ASRID CDATA s14.2
-ACHAPT CDATA 14
-ACSRID CDATA ch-methif
-ASECT CDATA .2
-AHNAME CDATA section 14.2
-(TOCENTRY
-L3265 programmer.sgml
--Location and arguments of the method scripts
-L3266
-)TOCENTRY
-)TOC
-L48 programmer.sgml
-AID CDATA scope
-L67
-ASRID CDATA ch-scope
-ACHAPT CDATA 1
-ASECT IMPLIED
-AHNAME CDATA chapter 1
-(CHAPT
-(HEADING
--Introduction and scope of this manual
-L68
-)HEADING
-(P
-L69
--\n
-(PRGN
--dpkg
-)PRGN
-- is a suite of programs for creating binary package files\nand installing and removing them on Unix systems.
-(FOOTNOTE
-(P
-(PRGN
--dpkg
-)PRGN
--\nis targetted primarily at Debian GNU/Linux, but may work on or be\nported to other systems.
-)P
-)FOOTNOTE
-L74
-)P
-(P
-L75
--\nThe binary packages are designed for the management of installed\nexecutable programs (usually compiled binaries) and their associated\ndata, though source code examples and documentation are provided as\npart of some packages.
-L80
-)P
-(P
-L81
--\nThis manual describes the technical aspects of creating Debian binary\npackages (
-(TT
--.deb
-)TT
-- files). It documents the behaviour of the\npackage management programs
-(PRGN
--dpkg
-)PRGN
--,
-(PRGN
--dselect
-)PRGN
-- et al. and and the\nway they interact with packages.
-L86
-)P
-(P
-L87
--\nIt also documents the interaction between
-(PRGN
--dselect
-)PRGN
--'s core and the\naccess method scripts it uses to actually install the selected\npackages, and describes how to create a new access method.
-L91
-)P
-(P
-L92
--\nThis manual does not go into detail about the options and usage of the\npackage building and installation tools. It should therefore be read\nin conjuction with those programs' manpages.
-L96
-)P
-(P
-L97
--\nThe utility programs which are provided with
-(PRGN
--dpkg
-)PRGN
-- for managing\nvarious system configuration and similar issues, such as\n
-(PRGN
--update-rc.d
-)PRGN
-- and
-(PRGN
--install-info
-)PRGN
--, are not described in\ndetail here - please see their manpages.
-L102
-)P
-(P
-L103
--\nIt does
-(EM
--not
-)EM
-- describe the policy requirements imposed on Debian\npackages, such as the permissions on files and directories,\ndocumentation requirements, upload procedure, and so on. You should\nsee the Debian packaging policy manual for these details. (Many of\nthem will probably turn out to be helpful even if you don't plan to\nupload your package and make it available as part of the\ndistribution.)
-L111
-)P
-(P
-L112
--\nIt is assumed that the reader is reasonably familiar with the\n
-(PRGN
--dpkg
-)PRGN
-- System Administrators' manual. Unfortunately this manual\ndoes not yet exist.
-L116
-)P
-(P
-L117
--\nThe Debian version of the FSF's GNU hello program is provided as an\nexample for people wishing to create Debian packages.
-L120
-)P
-(P
-L121
--\n
-(EM
--Note that this document is still a draft!
-)EM
--\n
-L124
-)P
-)CHAPT
-AID CDATA binarypkg
-ASRID CDATA ch-binarypkg
-ACHAPT CDATA 2
-ASECT IMPLIED
-AHNAME CDATA chapter 2
-(CHAPT
-(HEADING
--Binary packages
-L125
-)HEADING
-(P
-L126
--\nThe binary package has two main sections. The first part consists of\nvarious control information files and scripts used by
-(PRGN
--dpkg
-)PRGN
-- when\ninstalling and removing. See
-AID CDATA controlarea
-ALEVEL CDATA SECT
-ASRID CDATA s-controlarea
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2
-AHNAME CDATA section 2.2
-(REF
-L197 programmer.sgml
--Package control information files
-L198
-)REF
--.
-L130
-)P
-(P
-L131
--\nThe second part is an archive (currently a
-(PRGN
--tar
-)PRGN
-- archive)\ncontaining files and directories to be installed.
-L134
-)P
-(P
-L135
--\nIn the future binary packages may also contain other components, such\nas checksums and digital signatures.\n\n
-L140
-)P
-AID CDATA bincreating
-ASRID CDATA s-bincreating
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1
-AHNAME CDATA section 2.1
-(SECT
-(HEADING
--Creating package files -
-(PRGN
--dpkg-deb
-)PRGN
-L141
-)HEADING
-(P
-L142
--\nAll manipulation of binary package files is done by
-(PRGN
--dpkg-deb
-)PRGN
--;\nit's the only program that has knowledge of the format.\n(
-(PRGN
--dpkg-deb
-)PRGN
-- may be invoked by calling
-(PRGN
--dpkg
-)PRGN
--, as
-(PRGN
--dpkg
-)PRGN
-- will\nspot that the options requested are appropriate to
-(PRGN
--dpkg-deb
-)PRGN
-- and\ninvoke that instead with the same arguments.)
-L148
-)P
-(P
-L149
--\nIn order to create a binary package you must make a directory tree\nwhich contains all the files and directories you want to have in the\nfilesystem data part of the package. In Debian-format source packages\nthis directory is usually
-(TT
--debian/tmp
-)TT
--, relative to the top of\nthe package's source tree.
-L155
-)P
-(P
-L156
--\nThey should have the locations (relative to the root of the directory\ntree you're constructing) ownerships and permissions which you want\nthem to have on the system when they are installed.
-L160
-)P
-(P
-L161
--\nWith current versions of
-(PRGN
--dpkg
-)PRGN
-- the uid/username and gid/groupname\nmappings for the users and groups being used should be the same on the\nsystem where the package is built and the one where it is installed.
-L165
-)P
-(P
-L166
--\nYou need to add one special directory to the root of the miniature\nfilesystem tree you're creating:
-(PRGN
--DEBIAN
-)PRGN
--. It should contain the\ncontrol information files, notably the binary package control file\n(see
-AID CDATA controlfile
-ALEVEL CDATA SECT
-ASRID CDATA s-controlfile
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .3
-AHNAME CDATA section 2.3
-(REF
-L316 programmer.sgml
--The main control information file:
-(TT
--control
-)TT
-L317
-)REF
--).
-L171
-)P
-(P
-L172
--\nThe
-(PRGN
--DEBIAN
-)PRGN
-- directory will not appear in the filesystem archive of\nthe package, and so won't be installed by
-(PRGN
--dpkg
-)PRGN
-- when the package\nis installed.
-L176
-)P
-(P
-L177
--\nWhen you've prepared the package, you should invoke:\n
-(EXAMPLE
-L180
--dpkg --build
-(VAR
--directory
-)VAR
-L181
-)EXAMPLE
-L182
-)P
-(P
-L183
--\nThis will build the package in
-(TT
-(VAR
--directory
-)VAR
--.deb
-)TT
--.\n(
-(PRGN
--dpkg
-)PRGN
-- knows that
-(TT
----build
-)TT
-- is a
-(PRGN
--dpkg-deb
-)PRGN
-- option, so it\ninvokes
-(PRGN
--dpkg-deb
-)PRGN
-- with the same arguments to build the package.)
-L187
-)P
-(P
-L188
--\nSee the manpage
-ANAME CDATA dpkg-deb
-ASECTION CDATA 8
-(MANREF
-)MANREF
-- for details of how\nto examine the contents of this newly-created file. You may find the\noutput of following commands enlightening:\n
-(EXAMPLE
-L193
--dpkg-deb --info
-(VAR
--filename
-)VAR
--.deb\ndpkg-deb --contents
-(VAR
--filename
-)VAR
--.deb
-L195
-)EXAMPLE
--\n
-L197
-)P
-)SECT
-AID CDATA controlarea
-ASRID CDATA s-controlarea
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .2
-AHNAME CDATA section 2.2
-(SECT
-(HEADING
--Package control information files
-L198
-)HEADING
-(P
-L199
--\nThe control information portion of a binary package is a collection of\nfiles with names known to
-(PRGN
--dpkg
-)PRGN
--. It will treat the contents of\nthese files specially - some of them contain information used by\n
-(PRGN
--dpkg
-)PRGN
-- when installing or removing the package; others are scripts\nwhich the package maintainer wants
-(PRGN
--dpkg
-)PRGN
-- to run.
-L205
-)P
-(P
-L206
--\nIt is possible to put other files in the package control area, but\nthis is not generally a good idea (though they will largely be\nignored).
-L210
-)P
-(P
-L211
--\nHere is a brief list of the control info files supported by
-(PRGN
--dpkg
-)PRGN
--\nand a summary of what they're used for.
-L214
-)P
-(P
-L215
--\n
-ACOMPACT IMPLIED
-(TAGLIST
-L217
-(TAG
-(TT
--control
-)TT
-L218
-)TAG
-(ITEM
-L220
-(P
--This is the key description file used by
-(PRGN
--dpkg
-)PRGN
--. It specifies the\npackage's name and version, gives its description for the user, states\nits relationships with other packages, and so forth.\nSee
-AID CDATA controlfile
-ALEVEL CDATA SECT
-ASRID CDATA s-controlfile
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .3
-AHNAME CDATA section 2.3
-(REF
-L316 programmer.sgml
--The main control information file:
-(TT
--control
-)TT
-L317
-)REF
--.
-L224
-)P
-(P
-L225
--\nIt is usually generated automatically from information in the source\npackage by the
-(PRGN
--dpkg-gencontrol
-)PRGN
-- program, and with assistance\nfrom
-(PRGN
--dpkg-shlibdeps
-)PRGN
--. See
-AID CDATA sourcetools
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcetools
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1
-AHNAME CDATA section 3.1
-(REF
-L363 programmer.sgml
--Tools for processing source packages
-L364
-)REF
--.\n
-L230
-)P
-)ITEM
-(TAG
-(TT
--postinst
-)TT
--,
-(TT
--preinst
-)TT
--,
-(TT
--postrm
-)TT
--,
-(TT
--prerm
-)TT
-L231
-)TAG
-(ITEM
-L233
-(P
--These are exectuable files (usually scripts) which
-(PRGN
--dpkg
-)PRGN
-- runs\nduring installation, upgrade and removal of packages. They allow the\npackage to deal with matters which are particular to that package or\nrequire more complicated processing than that provided by
-(PRGN
--dpkg
-)PRGN
--.\nDetails of when and how they are called are in\n
-AID CDATA maintainerscripts
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-maintainerscripts
-ACHAPT CDATA 6
-ASECT IMPLIED
-AHNAME CDATA chapter 6
-(REF
-L1798 programmer.sgml
--Package maintainer scripts\nand installation procedure
-L1800
-)REF
--.
-L239
-)P
-(P
-L240
--\nIt is very important to make these scripts itempotent.
-(FOOTNOTE
-(P
--That\nmeans that if it runs successfully or fails and then you call it again\nit doesn't bomb out, but just ensures that everything is the way it\nought to be.
-)P
-)FOOTNOTE
-- This is so that if an error occurs, the user\ninterrupts
-(PRGN
--dpkg
-)PRGN
-- or some other unforeseen circumstance happens you\ndon't leave the user with a badly-broken package.
-L247
-)P
-(P
-L248
--\nThe maintainer scripts are guaranteed to run with a controlling\nterminal and can interact with the user. If they need to prompt for\npasswords, do full-screen interaction or something similar you should\ndo these things to and from
-(TT
--/dev/tty
-)TT
--, since
-(PRGN
--dpkg
-)PRGN
-- will at\nsome point redirect scripts' standard input and output so that it can\nlog the installation process. Likewise, because these scripts may be\nexecuted with standard output redirected into a pipe for logging\npurposes, Perl scripts should set unbuffered output by setting\n
-(TT
--$|=1
-)TT
-- so that the output is printed immediately rather than being\nbuffered.
-L259
-)P
-(P
-L260
--\nEach script should return a zero exit status for success, or a nonzero\none for failure.\n
-L264
-)P
-)ITEM
-(TAG
-(TT
--conffiles
-)TT
-L265
-)TAG
-(ITEM
-L267
-(P
--This file contains a list of configuration files which are to be\nhandled automatically by
-(PRGN
--dpkg
-)PRGN
-- (see
-AID CDATA conffiles
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-conffiles
-ACHAPT CDATA 9
-ASECT IMPLIED
-AHNAME CDATA chapter 9
-(REF
-L2733 programmer.sgml
--Configuration file handling
-L2734
-)REF
--). Note\nthat not necessarily every configuration file should be listed here.\n
-L271
-)P
-)ITEM
-(TAG
-(TT
--shlibs
-)TT
-L272
-)TAG
-(ITEM
-L274
-(P
--This file contains a list of the shared libraries supplied by the\npackage, with dependency details for each. This is used by\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- when it determines what dependencies are\nrequired in a package control file.
-L278
-)P
-(P
-L279
--\nEach line is of the form:\n
-(EXAMPLE
-L282
-(VAR
--library-name
-)VAR
--
-(VAR
--version-or-soname
-)VAR
--
-(VAR
--dependencies ...
-)VAR
-L283
-)EXAMPLE
-L284
-)P
-(P
-L285
--\n
-(VAR
--library-name
-)VAR
-- is the name of the shared library, for example\n
-(TT
--libc5
-)TT
--.
-L288
-)P
-(P
-L289
--\n
-(VAR
--version-or-soname
-)VAR
-- is the soname of the library - ie, the thing\nthat must exactly match for the library to be recognised by\n
-(PRGN
--ld.so
-)PRGN
--. Usually this is major version number of the library.
-L293
-)P
-(P
-L294
--\n
-(VAR
--dependencies
-)VAR
-- has the same syntax as a dependency field in a\nbinary package control file. It should give details of which\npackage(s) are required to satisfy a binary built against the version\nof the library contained in the package. See
-AID CDATA depsyntax
-ALEVEL CDATA SECT
-ASRID CDATA s-depsyntax
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .1
-AHNAME CDATA section 8.1
-(REF
-L2319 programmer.sgml
--Syntax of relationship fields
-L2320
-)REF
--.
-L299
-)P
-(P
-L300
--\nFor example, if the package
-(TT
--foo
-)TT
-- contains
-(TT
--libfoo.so.1.2.3
-)TT
--,\nwhere the soname of the library is
-(TT
--libfoo.so.1
-)TT
--, and the first\nversion of the package which contained a minor number of at least\n
-(TT
--2.3
-)TT
-- was
-(VAR
--1.2.3-1
-)VAR
--, then the package's
-(VAR
--shlibs
-)VAR
-- could\nsay:\n
-(EXAMPLE
-L307
--libfoo 1\011foo (>= 1.2.3-1)
-L308
-)EXAMPLE
-L309
-)P
-(P
-L310
--\nThe version-specific dependency is to avoid warnings from
-(PRGN
--ld.so
-)PRGN
--\nabout using older shared libraries with newer binaries.\n
-L314
-)P
-)ITEM
-)TAGLIST
--\n
-L316
-)P
-)SECT
-AID CDATA controlfile
-ASRID CDATA s-controlfile
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .3
-AHNAME CDATA section 2.3
-(SECT
-(HEADING
--The main control information file:
-(TT
--control
-)TT
-L317
-)HEADING
-(P
-L318
--\nThe most important control information file used by
-(PRGN
--dpkg
-)PRGN
-- when it\ninstalls a package is
-(TT
--control
-)TT
--. It contains all the package's\n`vital statistics'.
-L322
-)P
-(P
-L323
--\nThe binary package control files of packages built from Debian sources\nare made by a special tool,
-(PRGN
--dpkg-gencontrol
-)PRGN
--, which reads\n
-(TT
--debian/control
-)TT
-- and
-(TT
--debian/changelog
-)TT
-- to find the\ninformation it needs. See
-AID CDATA sourcepkg
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-sourcepkg
-ACHAPT CDATA 3
-ASECT IMPLIED
-AHNAME CDATA chapter 3
-(REF
-L356 programmer.sgml
--Source packages
-L357
-)REF
-- for more details.
-L328
-)P
-(P
-L329
--\nThe fields in binary package control files are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L333
-(ITEM
-(P
-AID CDATA f-Package
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Package
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.1
-AHNAME CDATA subsection 4.2.1
-(QREF
-(TT
--Package
-)TT
-)QREF
-- (mandatory)
-L334
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA versions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(QREF
-(TT
--Version
-)TT
-)QREF
-- (mandatory)\n
-L336
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Architecture
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Architecture
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.3
-AHNAME CDATA subsection 4.2.3
-(QREF
-(TT
--Architecture
-)TT
-)QREF
--\n(mandatory)
-(FOOTNOTE
-(P
--This field should appear in all packages, though\n
-(PRGN
--dpkg
-)PRGN
-- doesn't require it yet so that old packages can still be\ninstalled.
-)P
-)FOOTNOTE
--\n
-L341
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA relationships
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-relationships
-ACHAPT CDATA 8
-ASECT IMPLIED
-AHNAME CDATA chapter 8
-(QREF
-(TT
--Depends
-)TT
--,
-(TT
--Provides
-)TT
-- et al.
-)QREF
-L342
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Essential
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Essential
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.8
-AHNAME CDATA subsection 4.2.8
-(QREF
-(TT
--Essential
-)TT
-)QREF
-L343
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Maintainer
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Maintainer
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.4
-AHNAME CDATA subsection 4.2.4
-(QREF
-(TT
--Maintainer
-)TT
-)QREF
-L344
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-classification
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-classification
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.9
-AHNAME CDATA subsection 4.2.9
-(QREF
-(TT
--Section
-)TT
--,
-(TT
--Priority
-)TT
-)QREF
-L345
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Source
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Source
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.5
-AHNAME CDATA subsection 4.2.5
-(QREF
-(TT
--Source
-)TT
-)QREF
-L346
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA descriptions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-descriptions
-ACHAPT CDATA 7
-ASECT IMPLIED
-AHNAME CDATA chapter 7
-(QREF
-(TT
--Description
-)TT
-)QREF
-L347
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Installed-Size
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Installed-Size
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.11
-AHNAME CDATA subsection 4.2.11
-(QREF
-(TT
--Installed-Size
-)TT
-)QREF
--\n
-L349
-)P
-)ITEM
-)LIST
-L350
-)P
-(P
-L351
--\nA description of the syntax of control files and the purpose of these\nfields is available in
-AID CDATA controlfields
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-controlfields
-ACHAPT CDATA 4
-ASECT IMPLIED
-AHNAME CDATA chapter 4
-(REF
-L1190 programmer.sgml
--Control files and their fields
-L1191
-)REF
--.\n\n
-L356
-)P
-)SECT
-)CHAPT
-AID CDATA sourcepkg
-ASRID CDATA ch-sourcepkg
-ACHAPT CDATA 3
-ASECT IMPLIED
-AHNAME CDATA chapter 3
-(CHAPT
-(HEADING
--Source packages
-L357
-)HEADING
-(P
-L358
--\nThe Debian binary packages in the distribution are generated from\nDebian sources, which are in a special format to assist the easy and\nautomatic building of binaries.\n
-L363
-)P
-AID CDATA sourcetools
-ASRID CDATA s-sourcetools
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1
-AHNAME CDATA section 3.1
-(SECT
-(HEADING
--Tools for processing source packages
-L364
-)HEADING
-(P
-L365
--\nVarious tools are provided for manipulating source packages; they pack\nand unpack sources and help build of binary packages and help manage\nthe distribution of new versions.
-L369
-)P
-(P
-L370
--\nThey are introduced and typical uses described here; see
-ANAME CDATA dpkg-source
-ASECTION CDATA 1
-(MANREF
-)MANREF
-L372
-- for full documentation about their\narguments and operation.
-L374
-)P
-(P
-L375
--\nFor examples of how to construct a Debian source package, and how to\nuse those utilities that are used by Debian source packages, please\nsee the
-(PRGN
--hello
-)PRGN
-- example package.\n
-L380
-)P
-AID IMPLIED
-ASRID CDATA s3.1.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.1
-AHNAME CDATA subsection 3.1.1
-(SECT1
-(HEADING
-(PRGN
--dpkg-source
-)PRGN
-- - packs and unpacks Debian source packages
-L381
-)HEADING
-(P
-L382
--\nThis program is frequently used by hand, and is also called from\npackage-independent automated building scripts such as\n
-(PRGN
--dpkg-buildpackage
-)PRGN
--.
-L386
-)P
-(P
-L387
--\nTo unpack a package it is typically invoked with\n
-(EXAMPLE
-L390
--dpkg-source -x
-(VAR
--.../path/to/filename
-)VAR
--.dsc
-L391
-)EXAMPLE
--\nwith the
-(TT
-(VAR
--filename
-)VAR
--.tar.gz
-)TT
-- and\n
-(TT
-(VAR
--filename
-)VAR
--.diff.gz
-)TT
-- (if applicable) in the same directory. It\nunpacks into
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
-)TT
--, and if applicable\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
--.orig
-)TT
--, in the current directory.
-L396
-)P
-(P
-L397
--\nTo create a packed source archive it is typically invoked:\n
-(EXAMPLE
-L400
--dpkg-source -b
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
-L401
-)EXAMPLE
--\nThis will create the
-(TT
--.dsc
-)TT
--,
-(TT
--.tar.gz
-)TT
-- and
-(TT
--.diff.gz
-)TT
-- (if\nappropriate) in the current directory.
-(PRGN
--dpkg-source
-)PRGN
-- does not\nclean the source tree first - this must be done separately if it is\nrequired.
-L406
-)P
-(P
-L407
--\nSee also
-AID CDATA sourcearchives
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcearchives
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .3
-AHNAME CDATA section 3.3
-(REF
-L1055 programmer.sgml
--Source packages as archives
-L1056
-)REF
--.\n\n
-L411
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.2
-AHNAME CDATA subsection 3.1.2
-(SECT1
-(HEADING
-(PRGN
--dpkg-buildpackage
-)PRGN
-- - overall package-building control\nscript
-L413
-)HEADING
-(P
-L414
--\n
-(PRGN
--dpkg-buildpackage
-)PRGN
-- is a script which invokes
-(PRGN
--dpkg-source
-)PRGN
--,\nthe
-(TT
--debian/rules
-)TT
-- targets
-(PRGN
--clean
-)PRGN
--,
-(PRGN
--build
-)PRGN
-- and\n
-(PRGN
--binary
-)PRGN
--,
-(PRGN
--dpkg-genchanges
-)PRGN
-- and
-(PRGN
--pgp
-)PRGN
-- to build a signed\nsource and binary package upload.
-L419
-)P
-(P
-L420
--\nIt is usually invoked by hand from the top level of the built or\nunbuilt source directory. It may be invoked with no arguments; useful\narguments include:\n
-ACOMPACT TOKEN COMPACT
-(TAGLIST
-L425
-(TAG
-(TT
---uc
-)TT
--,
-(TT
---us
-)TT
-L426
-)TAG
-(ITEM
-(P
--Do not PGP-sign the
-(TT
--.changes
-)TT
-- file or the source package\n
-(TT
--.dsc
-)TT
-- file, respectively.\n
-L429
-)P
-)ITEM
-(TAG
-(TT
---p
-(VAR
--pgp-command
-)VAR
-)TT
-L430
-)TAG
-(ITEM
-(P
--Invoke
-(VAR
--pgp-command
-)VAR
-- instead of finding
-(TT
--pgp
-)TT
-- on the\n
-(PRGN
--PATH
-)PRGN
--.
-(VAR
--pgp-command
-)VAR
-- must behave just like
-(PRGN
--pgp
-)PRGN
--.\n
-L433
-)P
-)ITEM
-(TAG
-(TT
---r
-(VAR
--root-command
-)VAR
-)TT
-L434
-)TAG
-(ITEM
-(P
--When root privilege is required, invoke the command\n
-(VAR
--root-command
-)VAR
--.
-(VAR
--root-command
-)VAR
-- should invoke its first\nargument as a command, from the
-(PRGN
--PATH
-)PRGN
-- if necessary, and pass its\nsecond and subsequent arguments to the command it calls. If no\n
-(VAR
--root-command
-)VAR
-- is supplied then
-(VAR
--dpkg-buildpackage
-)VAR
-- will take\nno special action to gain root privilege, so that for most packages it\nwill have to be invoked as root to start with.\n
-L442
-)P
-)ITEM
-(TAG
-(TT
---b
-)TT
--,
-(TT
---B
-)TT
-L443
-)TAG
-(ITEM
-(P
--Two types of binary-only build and upload - see
-ANAME CDATA dpkg-source
-ASECTION CDATA 1
-(MANREF
-)MANREF
-L444
--.
-L445
-)P
-)ITEM
-)TAGLIST
--\n\n
-L448
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.3
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.3
-AHNAME CDATA subsection 3.1.3
-(SECT1
-(HEADING
-(PRGN
--dpkg-gencontrol
-)PRGN
-- - generates binary package control files
-L449
-)HEADING
-(P
-L450
--\nThis program is usually called from
-(TT
--debian/rules
-)TT
-- (see
-AID CDATA sourcetree
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcetree
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2
-AHNAME CDATA section 3.2
-(REF
-L605 programmer.sgml
--The Debianised source tree
-L606
-)REF
-L452
--) in the top level of the source tree.
-L453
-)P
-(P
-L454
--\nThis is usually done just before the files and directories in the\ntemporary directory tree where the package is being built have their\npermissions and ownerships set and the package is constructed using\n
-(PRGN
--dpkg-deb
-)PRGN
-(FOOTNOTE
-(P
--This is so that the control file which is\nproduced has the right permissions
-)P
-)FOOTNOTE
--.
-L460
-)P
-(P
-L461
--\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- must be called after all the files which are to\ngo into the package have been placed in the temporary build directory,\nso that its calculation of the installed size of a package is correct.
-L465
-)P
-(P
-L466
--\nIt is also necessary for
-(PRGN
--dpkg-gencontrol
-)PRGN
-- to be run after\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- so that the variable substitutions created by\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- in
-(TT
--debian/substvars
-)TT
-- are available.
-L470
-)P
-(P
-L471
--\nFor a package which generates only one binary package, and which\nbuilds it in
-(TT
--debian/tmp
-)TT
-- relative to the top of the source\npackage, it is usually sufficient to call:\n
-(EXAMPLE
-L476
--dpkg-gencontrol
-L477
-)EXAMPLE
-L478
-)P
-(P
-L479
--\nSources which build several binaries will typically need something\nlike:\n
-(EXAMPLE
-L483
--dpkg-gencontrol -Pdebian/tmp-
-(VAR
--pkg
-)VAR
-- -p
-(VAR
--package
-)VAR
-L484
-)EXAMPLE
--\nThe
-(TT
---P
-)TT
-- tells
-(PRGN
--dpkg-gencontrol
-)PRGN
-- that the package is being\nbuilt in a non-default directory, and the
-(TT
---p
-)TT
-- tells it which\npackage's control file should be generated.
-L488
-)P
-(P
-L489
--\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- also adds information to the list of files in\n
-(TT
--debian/files
-)TT
--, for the benefit of (for example) a future\ninvocation of
-(PRGN
--dpkg-genchanges
-)PRGN
--.\n\n
-L495
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.4
-AHNAME CDATA subsection 3.1.4
-(SECT1
-(HEADING
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- - calculates shared library dependencies
-L496
-)HEADING
-(P
-L497
--\nThis program is usually called from
-(TT
--debian/rules
-)TT
-- just before\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- (see
-AID CDATA sourcetree
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcetree
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2
-AHNAME CDATA section 3.2
-(REF
-L605 programmer.sgml
--The Debianised source tree
-L606
-)REF
--), in the top level\nof the source tree.
-L501
-)P
-(P
-L502
--\nIts arguments are executables
-(FOOTNOTE
-(P
--They may be specified either\nin the locations in the source tree where they are created or in the\nlocations in the temporary build tree where they are installed prior\nto binary package creation.
-)P
-)FOOTNOTE
-- for which shared library\ndependencies should be included in the binary package's control file.
-L508
-)P
-(P
-L509
--\nIf some of the executable(s) shared libraries should only warrant a\n
-(TT
--Recommends
-)TT
-- or
-(TT
--Suggests
-)TT
--, or if some warrant a\n
-(TT
--Pre-Depends
-)TT
--, this can be achieved by using the\n
-(TT
---d
-(VAR
--dependency-field
-)VAR
-)TT
-- option before those executable(s).\n(Each
-(TT
---d
-)TT
-- option takes effect until the next
-(TT
---d
-)TT
--.)
-L515
-)P
-(P
-L516
--\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- does not directly cause the output control file\nto be modified. Instead by default it adds to the\n
-(TT
--debian/substvars
-)TT
-- file variable settings like\n
-(TT
--shlibs:Depends
-)TT
--. These variable settings must be referenced in\ndependency fields in the appropriate per-binary-package sections of\nthe source control file.
-L523
-)P
-(P
-L524
--\nFor example, the
-(PRGN
--procps
-)PRGN
-- package generates two kinds of\nbinaries, simple C binaries like
-(PRGN
--ps
-)PRGN
-- which require a\npredependency and full-screen ncurses binaries like
-(PRGN
--top
-)PRGN
-- which\nrequire only a recommendation. It can say in its
-(TT
--debian/rules
-)TT
--:\n
-(EXAMPLE
-L530
--dpkg-shlibdeps -dPre-Depends ps -dRecommends top
-L531
-)EXAMPLE
--\nand then in its main control file
-(TT
--debian/control
-)TT
--:\n
-(EXAMPLE
-L534
-(VAR
--...
-)VAR
--\nPackage: procps\nPre-Depends: ${shlibs:Pre-Depends}\nRecommends: ${shlibs:Recommends}\n
-(VAR
--...
-)VAR
-L539
-)EXAMPLE
-L540
-)P
-(P
-L541
--\nSources which produce several binary packages with different shared\nlibrary dependency requirements can use the
-(TT
---p
-(VAR
--varnameprefix
-)VAR
-)TT
--\noption to override the default
-(TT
--shlib:
-)TT
-- prefix (one invocation of\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- per setting of this option). They can thus\nproduce several sets of dependency variables, each of the form\n
-(TT
-(VAR
--varnameprefix
-)VAR
--:
-(VAR
--dependencyfield
-)VAR
-)TT
--, which can be referred\nto in the appropriate parts of the binary package control files.\n\n
-L551
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.5
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.5
-AHNAME CDATA subsection 3.1.5
-(SECT1
-(HEADING
-(PRGN
--dpkg-distaddfile
-)PRGN
-- - adds a file to
-(TT
--debian/files
-)TT
-L552
-)HEADING
-(P
-L553
--\nSome packages' uploads need to include files other than the source and\nbinary package files.
-L556
-)P
-(P
-L557
--\n
-(PRGN
--dpkg-distaddfile
-)PRGN
-- adds a file to the
-(TT
--debian/files
-)TT
-- file so\nthat it will be included in the
-(TT
--.changes
-)TT
-- file when\n
-(PRGN
--dpkg-genchanges
-)PRGN
-- is run.
-L561
-)P
-(P
-L562
--\nIt is usually invoked from the
-(PRGN
--binary
-)PRGN
-- target of\n
-(TT
--debian/rules
-)TT
--:\n
-(EXAMPLE
-L566
--dpkg-distaddfile
-(VAR
--filename
-)VAR
--
-(VAR
--section
-)VAR
--
-(VAR
--priority
-)VAR
-L567
-)EXAMPLE
--\nThe
-(VAR
--filename
-)VAR
-- is relative to the directory where\n
-(PRGN
--dpkg-genchanges
-)PRGN
-- will expect to find it - this is usually the\ndirectory above the top level of the source tree. The\n
-(TT
--debian/rules
-)TT
-- target should put the file there just before or\njust after calling
-(PRGN
--dpkg-distaddfile
-)PRGN
--.
-L573
-)P
-(P
-L574
--\nThe
-(VAR
--section
-)VAR
-- and
-(VAR
--priority
-)VAR
-- are passed unchanged into the\nresulting
-(TT
--.changes
-)TT
-- file. See
-AID CDATA f-classification
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-classification
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.9
-AHNAME CDATA subsection 4.2.9
-(REF
-L1400 programmer.sgml
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-L1401
-)REF
--.\n\n
-L579
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.6
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.6
-AHNAME CDATA subsection 3.1.6
-(SECT1
-(HEADING
-(PRGN
--dpkg-genchanges
-)PRGN
-- - generates a
-(TT
--.changes
-)TT
-- upload\ncontrol file
-L581
-)HEADING
-(P
-L582
--\nThis program is usually called by package-independent automatic\nbuilding scripts such as
-(PRGN
--dpkg-buildpackage
-)PRGN
--, but it may also be\ncalled by hand.
-L586
-)P
-(P
-L587
--\nIt is usually called in the top level of a built source tree, and when\ninvoked with no arguments will print out a straightforward\n
-(TT
--.changes
-)TT
-- file based on the information in the source package's\nchangelog and control file and the binary and source packages which\nshould have been built.\n\n
-L595
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.1.7
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1.7
-AHNAME CDATA subsection 3.1.7
-(SECT1
-(HEADING
-(PRGN
--dpkg-parsechangelog
-)PRGN
-- - produces parsed representation of\na changelog
-L597
-)HEADING
-(P
-L598
--\nThis program is used internally by
-(PRGN
--dpkg-source
-)PRGN
-- et al. It may\nalso occasionally be useful in
-(TT
--debian/rules
-)TT
-- and elsewhere. It\nparses a changelog,
-(TT
--debian/changelog
-)TT
-- by default, and prints a\ncontrol-file format representation of the information in it to\nstandard output.\n
-L605
-)P
-)SECT1
-)SECT
-AID CDATA sourcetree
-ASRID CDATA s-sourcetree
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2
-AHNAME CDATA section 3.2
-(SECT
-(HEADING
--The Debianised source tree
-L606
-)HEADING
-(P
-L607
--\nThe source archive scheme described later is intended to allow a\nDebianised source tree with some associated control information to be\nreproduced and transported easily. The Debianised source tree is a\nversion of the original program with certain files added for the\nbenefit of the Debianisation process, and with any other changes\nrequired made to the rest of the source code and installation scripts.
-L614
-)P
-(P
-L615
--\nThe extra files created for Debian are in the subdirectory
-(TT
--debian
-)TT
--\nof the top level of the Debianised source tree. They are described\nbelow.\n
-L620
-)P
-AID IMPLIED
-ASRID CDATA s3.2.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.1
-AHNAME CDATA subsection 3.2.1
-(SECT1
-(HEADING
-(TT
--debian/rules
-)TT
-- - the main building script
-L621
-)HEADING
-(P
-L622
--\nThis file is an executable makefile, and contains the package-specific\nrecipies for compiling the package and building binary package(s) out\nof the source.
-L626
-)P
-(P
-L627
--\nIt must start with the line
-(TT
--#!/usr/bin/make -f
-)TT
--, so that it\ncan be invoked by saying its name rather than invoking
-(PRGN
--make
-)PRGN
--\nexplicitly.
-L631
-)P
-(P
-L632
--\nThe targets which are required to be present are:\n\n
-ACOMPACT IMPLIED
-(TAGLIST
-L636
-(TAG
-(TT
--build
-)TT
-)TAG
-L637
-(ITEM
-L639
-(P
--This should perform all non-interactive configuration and compilation\nof the package. If a package has an interactive pre-build\nconfiguration routine, the Debianised source package should be built\nafter this has taken place, so that it can be built without rerunning\nthe configuration.
-L644
-)P
-(P
-L645
--\nFor some packages, notably ones where the same source tree is compiled\nin different ways to produce two binary packages, the
-(PRGN
--build
-)PRGN
--\ntarget does not make much sense. For these packages it is good enough\nto provide two (or more) targets (
-(TT
--build-a
-)TT
-- and
-(TT
--build-b
-)TT
-- or\nwhatever) for each of the ways of building the package, and a\n
-(PRGN
--build
-)PRGN
-- target that does nothing. The
-(PRGN
--binary
-)PRGN
-- target will have\nto build the package in each of the possible ways and make the binary\npackage out of each.
-L654
-)P
-(P
-L655
--\nThe
-(PRGN
--build
-)PRGN
-- target must not do anything that might require root\nprivilege.
-L658
-)P
-(P
-L659
--\nThe
-(PRGN
--build
-)PRGN
-- target may need to run
-(PRGN
--clean
-)PRGN
-- first - see below.
-L661
-)P
-(P
-L662
--\nWhen a package has a configuration routine that takes a long time, or\nwhen the makefiles are poorly designed, or when
-(PRGN
--build
-)PRGN
-- needs to\nrun
-(PRGN
--clean
-)PRGN
-- first, it is a good idea to
-(TT
--touch build
-)TT
-- when the\nbuild process is complete. This will ensure that if
-(TT
--debian/rules\nbuild
-)TT
-- is run again it will not rebuild the whole program.\n
-L669
-)P
-)ITEM
-(TAG
-(TT
--binary
-)TT
--,
-(TT
--binary-arch
-)TT
--,
-(TT
--binary-indep
-)TT
-L670
-)TAG
-(ITEM
-L672
-(P
--The
-(PRGN
--binary
-)PRGN
-- target should be all that is necessary for the user\nto build the binary package. It is split into two parts:\n
-(PRGN
--binary-arch
-)PRGN
-- builds the packages' output files which are\nspecific to a particular architecture, and
-(PRGN
--binary-indep
-)PRGN
--\nbuilds those which are not.
-L677
-)P
-(P
-L678
--\n
-(PRGN
--binary
-)PRGN
-- should usually be a target with no commands which simply\ndepends on
-(PRGN
--binary-arch
-)PRGN
-- and
-(PRGN
--binary-indep
-)PRGN
--.
-L681
-)P
-(P
-L682
--\nBoth
-(PRGN
--binary-*
-)PRGN
-- targets should depend on the
-(PRGN
--build
-)PRGN
-- target,\nabove, so that the package is built if it has not been already. It\nshould then create the relevant binary package(s), using\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- to make their control files and
-(PRGN
--dpkg-deb
-)PRGN
--\nto build them and place them in the parent of the top level directory.
-L688
-)P
-(P
-L689
--\nIf one of the
-(PRGN
--binary-*
-)PRGN
-- targets has nothing to do (this will be\nalways be the case if the source generates only a single binary\npackage, whether architecture-dependent or not) it
-(EM
--must
-)EM
-- still\nexist, but should always succeed.
-L694
-)P
-(P
-L695
--\n
-AID CDATA binarypkg
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-binarypkg
-ACHAPT CDATA 2
-ASECT IMPLIED
-AHNAME CDATA chapter 2
-(REF
-L124 programmer.sgml
--Binary packages
-L125
-)REF
-- describes how to construct binary packages.
-L697
-)P
-(P
-L698
--\nThe
-(PRGN
--binary
-)PRGN
-- targets must be invoked as root.\n
-L701
-)P
-)ITEM
-(TAG
-(TT
--clean
-)TT
-)TAG
-L702
-(ITEM
-L704
-(P
--This should undo any effects that the
-(PRGN
--build
-)PRGN
-- and
-(PRGN
--binary
-)PRGN
--\ntargets may have had, except that it should leave alone any output\nfiles created in the parent directory by a run of
-(PRGN
--binary
-)PRGN
--.
-L707
-)P
-(P
-L708
--\nIf a
-(PRGN
--build
-)PRGN
-- file is touched at the end of the
-(PRGN
--build
-)PRGN
-- target,\nas suggested above, it must be removed as the first thing that\n
-(PRGN
--clean
-)PRGN
-- does, so that running
-(PRGN
--build
-)PRGN
-- again after an interrupted\n
-(PRGN
--clean
-)PRGN
-- doesn't think that everything is already done.
-L713
-)P
-(P
-L714
--\nThe
-(PRGN
--clean
-)PRGN
-- target must be invoked as root if
-(PRGN
--binary
-)PRGN
-- has\nbeen invoked since the last
-(PRGN
--clean
-)PRGN
--, or if
-(PRGN
--build
-)PRGN
-- has been\ninvoked as root (since
-(PRGN
--build
-)PRGN
-- may create directories, for\nexample).\n
-L720
-)P
-)ITEM
-(TAG
-(TT
--get-orig-source
-)TT
-)TAG
-L721
-(ITEM
-L723
-(P
--This target fetches the most recent version of the original source\npackage from a canonical archive site (via FTP or WWW, for example),\ndoes any necessary rearrangement to turn it into the original source\ntarfile format described below, and leaves it in the current directory.
-L727
-)P
-(P
-L728
--\nThis target may be invoked in any directory, and should take care to\nclean up any temporary files it may have left.
-L731
-)P
-(P
-L732
--\nThis target is optional, but providing it if possible is a good idea.\n
-L735
-)P
-)ITEM
-)TAGLIST
--\n\nThe
-(PRGN
--build
-)PRGN
--,
-(PRGN
--binary
-)PRGN
-- and
-(PRGN
--clean
-)PRGN
-- targets must be\ninvoked with a current directory of the package's top-level\ndirectory.\n
-L741
-)P
-(P
-L742
--\nAdditional targets may exist in
-(TT
--debian/rules
-)TT
--, either as\npublished or undocumented interfaces or for the package's internal\nuse.\n\n
-L748
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.2
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.2
-AHNAME CDATA subsection 3.2.2
-(SECT1
-(HEADING
-(TT
--debian/control
-)TT
-L749
-)HEADING
-(P
-L750
--\nThis file contains version-independent details about the source\npackage and about the binary packages it creates.
-L753
-)P
-(P
-L754
--\nIt is a series of sets of control fields, each syntactically similar\nto a binary package control file. The sets are separated by one or\nmore blank lines. The first set is information about the source\npackage in general; each subsequent set describes one binary package\nthat the source tree builds.
-L760
-)P
-(P
-L761
--\nThe syntax and semantics of the fields are described below in\n
-AID CDATA controlfields
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-controlfields
-ACHAPT CDATA 4
-ASECT IMPLIED
-AHNAME CDATA chapter 4
-(REF
-L1190 programmer.sgml
--Control files and their fields
-L1191
-)REF
--.
-L764
-)P
-(P
-L765
--\nThe general (binary-package-independent) fields are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L768
-(ITEM
-(P
-AID CDATA f-Source
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Source
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.5
-AHNAME CDATA subsection 4.2.5
-(QREF
-(TT
--Source
-)TT
-)QREF
-- (mandatory)
-L769
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Maintainer
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Maintainer
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.4
-AHNAME CDATA subsection 4.2.4
-(QREF
-(TT
--Maintainer
-)TT
-)QREF
-L770
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-classification
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-classification
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.9
-AHNAME CDATA subsection 4.2.9
-(QREF
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-)QREF
--\n(classification, mandatory)
-L772
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Standards-Version
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Standards-Version
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.13
-AHNAME CDATA subsection 4.2.13
-(QREF
-(TT
--Standards-Version
-)TT
-)QREF
-L773
-)P
-)ITEM
-)LIST
-L774
-)P
-(P
-L775
--\nThe per-binary-package fields are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L778
-(ITEM
-(P
-AID CDATA f-Package
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Package
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.1
-AHNAME CDATA subsection 4.2.1
-(QREF
-(TT
--Package
-)TT
-)QREF
-- (mandatory)
-L779
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Architecture
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Architecture
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.3
-AHNAME CDATA subsection 4.2.3
-(QREF
-(TT
--Architecture
-)TT
-)QREF
-- (mandatory)
-L780
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA descriptions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-descriptions
-ACHAPT CDATA 7
-ASECT IMPLIED
-AHNAME CDATA chapter 7
-(QREF
-(TT
--Description
-)TT
-)QREF
-L781
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-classification
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-classification
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.9
-AHNAME CDATA subsection 4.2.9
-(QREF
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-)QREF
-- (classification)
-L782
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Essential
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Essential
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.8
-AHNAME CDATA subsection 4.2.8
-(QREF
-(TT
--Essential
-)TT
-)QREF
-L783
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA relationships
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-relationships
-ACHAPT CDATA 8
-ASECT IMPLIED
-AHNAME CDATA chapter 8
-(QREF
-(TT
--Depends
-)TT
-- et al.
-)QREF
-- (package interrelationships)
-L784
-)P
-)ITEM
-)LIST
-L785
-)P
-(P
-L786
--\nThese fields are used by
-(PRGN
--dpkg-gencontrol
-)PRGN
-- to generate control\nfiles for binary packages (see below), by
-(PRGN
--dpkg-genchanges
-)PRGN
-- to\ngenerate the
-(TT
--.changes
-)TT
-- file to accompany the upload, and by\n
-(PRGN
--dpkg-source
-)PRGN
-- when it creates the
-(TT
--.dsc
-)TT
-- source control file as\npart of a source archive.
-L792
-)P
-(P
-L793
--\nThe fields here may contain variable references - their values will be\nsubstituted by
-(PRGN
--dpkg-gencontrol
-)PRGN
--,
-(PRGN
--dpkg-genchanges
-)PRGN
-- or\n
-(PRGN
--dpkg-source
-)PRGN
-- when they generate output control files. See
-AID CDATA srcsubstvars
-ALEVEL CDATA SECT1
-ASRID CDATA s-srcsubstvars
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.4
-AHNAME CDATA subsection 3.2.4
-(REF
-L983 programmer.sgml
-(TT
--debian/substvars
-)TT
-- and variable substitutions
-L984
-)REF
-L797
-- for details.
-L798
-)P
-(P
-L800
-)P
-AID IMPLIED
-ASRID CDATA s3.2.2.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.2.1
-AHNAME CDATA subsubsection 3.2.2.1
-(SECT2
-(HEADING
--User-defined fields
-L801
-)HEADING
-(P
-L802
--\nAdditional user-defined fields may be added to the source package\ncontrol file. Such fields will be ignored, and not copied to (for\nexample) binary or source package control files or upload control\nfiles.
-L807
-)P
-(P
-L808
--\nIf you wish to add additional unsupported fields to these output files\nyou should use the mechanism described here.
-L811
-)P
-(P
-L812
--\nFields in the main source control information file with names starting\n
-(TT
--X
-)TT
--, followed by one or more of the letters
-(TT
--BCS
-)TT
-- and a hyphen\n
-(TT
---
-)TT
--, will be copied to the output files. Only the part of the\nfield name after the hyphen will be used in the output file. Where\nthe letter
-(TT
--B
-)TT
-- is used the field will appear in binary package\ncontrol files, where the letter
-(TT
--S
-)TT
-- is used in source package\ncontrol files and where
-(TT
--C
-)TT
-- is used in upload control\n(
-(TT
--.changes
-)TT
--) files.
-L821
-)P
-(P
-L822
--\nFor example, if the main source information control file contains the\nfield\n
-(EXAMPLE
-L826
--XBS-Comment: I stand between the candle and the star.
-L827
-)EXAMPLE
--\nthen the binary and source package control files will contain the\nfield\n
-(EXAMPLE
-L831
--Comment: I stand between the candle and the star.
-L832
-)EXAMPLE
--\n
-L834
-)P
-)SECT2
-)SECT1
-AID CDATA dpkgchangelog
-ASRID CDATA s-dpkgchangelog
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.3
-AHNAME CDATA subsection 3.2.3
-(SECT1
-(HEADING
-(TT
--debian/changelog
-)TT
-L835
-)HEADING
-(P
-L836
--\nThis file records the changes to the Debian-specific parts of the\npackage
-(FOOTNOTE
-(P
--Though there is nothing stopping an author who is\nalso the Debian maintainer from using it for all their changes, it\nwill have to be renamed if the Debian and upstream maintainers become\ndifferent people.
-)P
-)FOOTNOTE
--.
-L842
-)P
-(P
-L843
--\nIt has a special format which allows the package building tools to\ndiscover which version of the package is being built and find out\nother release-specific information.
-L847
-)P
-(P
-L848
--\nThat format is a series of entries like this:\n
-(EXAMPLE
-L851
-(VAR
--package
-)VAR
-- (
-(VAR
--version
-)VAR
--)
-(VAR
--distribution(s)
-)VAR
--; urgency=
-(VAR
--urgency
-)VAR
--\n\n *
-(VAR
--change details
-)VAR
--\n
-(VAR
--more change details
-)VAR
--\n *
-(VAR
--even more change details
-)VAR
--\n\n --
-(VAR
--maintainer name and email address
-)VAR
--
-(VAR
--date
-)VAR
-L858
-)EXAMPLE
-L859
-)P
-(P
-L860
--\n
-(VAR
--package
-)VAR
-- and
-(VAR
--version
-)VAR
-- are the source package name and\nversion number.
-(VAR
--distribution(s)
-)VAR
-- lists the distributions where\nthis version should be installed when it is uploaded - it is copied to\nthe
-(TT
--Distribution
-)TT
-- field in the
-(TT
--.changes
-)TT
-- file. See
-AID CDATA f-Distribution
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Distribution
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.14
-AHNAME CDATA subsection 4.2.14
-(REF
-L1528 programmer.sgml
-(TT
--Distribution
-)TT
-L1529
-)REF
-L865
--.
-L866
-)P
-(P
-L867
--\n
-(VAR
--urgency
-)VAR
-- is the value for the
-(TT
--Urgency
-)TT
-- field in the\n
-(TT
--.changes
-)TT
-- file for the upload. See
-AID CDATA f-Urgency
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Urgency
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.15
-AHNAME CDATA subsection 4.2.15
-(REF
-L1540 programmer.sgml
-(TT
--Urgency
-)TT
-L1541
-)REF
--. It is\nnot possible to specify an urgency containing commas; commas are used\nto separate
-(TT
-(VAR
--keyword
-)VAR
--=
-(VAR
--value
-)VAR
-)TT
-- settings in the
-(PRGN
--dpkg
-)PRGN
--\nchangelog format (though there is currently only one useful\n
-(VAR
--keyword
-)VAR
--,
-(TT
--urgency
-)TT
--).
-L874
-)P
-(P
-L875
--\nThe change details may in fact be any series of lines starting with at\nleast two spaces, but conventionally each change starts with an\nasterisk and a separating space and continuation lines are indented so\nas to bring them in line with the start of the text above. Blank\nlines may be used here to separate groups of changes, if desired.
-L881
-)P
-(P
-L882
--\nThe maintainer name and email address should
-(EM
--not
-)EM
-- necessarily be\nthose of the usual package maintainer. They should be the details of\nthe person doing
-(EM
--this
-)EM
-- version. The information here will be\ncopied to the
-(TT
--.changes
-)TT
-- file, and then later used to send an\nacknowledgement when the upload has been installed.
-L888
-)P
-(P
-L889
--\nThe
-(VAR
--date
-)VAR
-- should be in RFC822 format; it should include the\ntimezone specified numerically, with the timezone name or abbreviation\noptionally present as a comment.
-L893
-)P
-(P
-L894
--\nThe first `title' line with the package name should start at the left\nhand margin; the `trailer' line with the maintainer and date details\nshould be preceded by exactly one space. The maintainer details and\nthe date must be separated by exactly two spaces.
-L899
-)P
-(P
-L900
--\nAn Emacs mode for editing this format is available: it is called\n
-(TT
--debian-changelog-mode
-)TT
--. You can have this mode selected\nautomatically when you edit a Debian changelog by adding a local\nvariables clause to the end of the changelog.\n
-L906
-)P
-AID IMPLIED
-ASRID CDATA s3.2.3.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.3.1
-AHNAME CDATA subsubsection 3.2.3.1
-(SECT2
-(HEADING
--Defining alternative changelog formats
-L907
-)HEADING
-(P
-L908
--\nIt is possible to use a different format to the standard one, by\nproviding a parser for the format you wish to use.
-L911
-)P
-(P
-L912
--\nIn order to have
-(TT
--dpkg-parsechangelog
-)TT
-- run your parser, you must\ninclude a line within the last 40 lines of your file matching the Perl\nregular expression:\n
-(EXAMPLE
-L917
--\\schangelog-format:\\s+([0-9a-z]+)\\W
-L918
-)EXAMPLE
--\nThe part in parentheses should be the name of the format.
-L920
-)P
-(P
-L921
--\nIf such a line exists then
-(TT
--dpkg-parsechangelog
-)TT
-- will look for the\nparser as
-(TT
--/usr/lib/dpkg/parsechangelog/
-(VAR
--format-name
-)VAR
-)TT
-- or\n
-(TT
--/usr/local/lib/dpkg/parsechangelog/
-(VAR
--format-name
-)VAR
-)TT
--; it is an\nerror for it not to find it, or for it not to be an executable\nprogram. The default changelog format is
-(TT
--dpkg
-)TT
--, and a parser for\nit is provided with the
-(TT
--dpkg
-)TT
-- package.
-L928
-)P
-(P
-L929
--\nThe parser will be invoked with the changelog open on standard input\nat the start of the file. It should read the file (it may seek if it\nwishes) to determine the information required and return the parsed\ninformation to standard output in the form of a series of control\nfields in the standard format. By default it should return\ninformation about only the most recent version in the changelog; it\nshould accept a
-(TT
---v
-(VAR
--version
-)VAR
-)TT
-- option to return changes\ninformation from all versions present
-(EM
--strictly after
-)EM
--\n
-(VAR
--version
-)VAR
--, and it should then be an error for
-(VAR
--version
-)VAR
-- not to\nbe present in the changelog.
-L940
-)P
-(P
-L941
--\nThe fields are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L944
-(ITEM
-(P
-AID CDATA f-Source
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Source
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.5
-AHNAME CDATA subsection 4.2.5
-(QREF
-(TT
--Source
-)TT
-)QREF
-L945
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA versions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(QREF
-(TT
--Version
-)TT
-)QREF
-- (mandatory)
-L946
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Distribution
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Distribution
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.14
-AHNAME CDATA subsection 4.2.14
-(QREF
-(TT
--Distribution
-)TT
-)QREF
-- (mandatory)
-L947
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Urgency
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Urgency
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.15
-AHNAME CDATA subsection 4.2.15
-(QREF
-(TT
--Urgency
-)TT
-)QREF
-- (mandatory)
-L948
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Maintainer
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Maintainer
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.4
-AHNAME CDATA subsection 4.2.4
-(QREF
-(TT
--Maintainer
-)TT
-)QREF
-- (mandatory)
-L949
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Date
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Date
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.16
-AHNAME CDATA subsection 4.2.16
-(QREF
-(TT
--Date
-)TT
-)QREF
-L950
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Changes
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Changes
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.18
-AHNAME CDATA subsection 4.2.18
-(QREF
-(TT
--Changes
-)TT
-)QREF
-- (mandatory)
-L951
-)P
-)ITEM
-)LIST
-L952
-)P
-(P
-L953
--\nIf several versions are being returned (due to the use of
-(TT
---v
-)TT
--),\nthe urgency value should be of the highest urgency code listed at the\nstart of any of the versions requested followed by the concatenated\n(space-separated) comments from all the versions requested; the\nmaintainer, version, distribution and date should always be from the\nmost recent version.
-L960
-)P
-(P
-L961
--\nFor the format of the
-(TT
--Changes
-)TT
-- field see
-AID CDATA f-Changes
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Changes
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.18
-AHNAME CDATA subsection 4.2.18
-(REF
-L1575 programmer.sgml
-(TT
--Changes
-)TT
-L1576
-)REF
--.
-L963
-)P
-(P
-L964
--\nIf the changelog format which is being parsed always or almost always\nleaves a blank line between individual change notes these blank lines\nshould be stripped out, so as to make the resulting output compact.
-L968
-)P
-(P
-L969
--\nIf the changelog format does not contain date or package name\ninformation this information should be omitted from the output. The\nparser should not attempt to synthesise it or find it from other\nsources.
-L974
-)P
-(P
-L975
--\nIf the changelog does not have the expected format the parser should\nexit with a nonzero exit status, rather than trying to muddle through\nand possibly generating incorrect output.
-L979
-)P
-(P
-L980
--\nA changelog parser may not interact with the user at all.\n
-L983
-)P
-)SECT2
-)SECT1
-AID CDATA srcsubstvars
-ASRID CDATA s-srcsubstvars
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.4
-AHNAME CDATA subsection 3.2.4
-(SECT1
-(HEADING
-(TT
--debian/substvars
-)TT
-- and variable substitutions
-L984
-)HEADING
-(P
-L985
--\nWhen
-(PRGN
--dpkg-gencontrol
-)PRGN
--,
-(PRGN
--dpkg-genchanges
-)PRGN
-- and\n
-(PRGN
--dpkg-source
-)PRGN
-- generate control files they do variable\nsubstitutions on their output just before writing it. Variable\nsubstitutions have the form
-(TT
--${
-(VAR
--variable-name
-)VAR
--}
-)TT
--. The optional\nfile
-(TT
--debian/substvars
-)TT
-- contains variable substitutions to be\nused; variables can also be set directly from
-(TT
--debian/rules
-)TT
--\nusing the
-(TT
---V
-)TT
-- option to the source packaging commands, and certain\npredefined variables are available.
-L994
-)P
-(P
-L995
--\nThe file may be a static part of the source archive, or generated and\nmodified dynamically by
-(TT
--debian/rules
-)TT
-- targets. In the latter\ncase it must be removed by the
-(PRGN
--clean
-)PRGN
-- target.
-L999
-)P
-(P
-L1000
--\nSee
-ANAME CDATA dpkg-source
-ASECTION CDATA 1
-(MANREF
-)MANREF
-- for full details about source\nvariable substitutions, including the format of\n
-(TT
--debian/substvars
-)TT
--.\n
-L1005
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.5
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.5
-AHNAME CDATA subsection 3.2.5
-(SECT1
-(HEADING
-(TT
--debian/files
-)TT
-L1006
-)HEADING
-(P
-L1007
--\nThis file is not a permanent part of the source tree; it is used while\nbuilding packages to record which files are being generated.\n
-(PRGN
--dpkg-genchanges
-)PRGN
-- uses it when it generates a
-(TT
--.changes
-)TT
-- file.
-L1011
-)P
-(P
-L1012
--\nIt should not exist in a shipped source package, and so it (and any\nbackup files or temporary files such as\n
-(TT
--files.new
-)TT
-(FOOTNOTE
-(P
-(TT
--files.new
-)TT
-- is used as a temporary file by\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- and
-(PRGN
--dpkg-distaddfile
-)PRGN
-- - they write a new\nversion of
-(TT
--files
-)TT
-- here before renaming it, to avoid leaving a\ncorrupted copy if an error occurs
-)P
-)FOOTNOTE
--) should be removed by the\n
-(PRGN
--clean
-)PRGN
-- target. It may also be wise to ensure a fresh start by\nemptying or removing it at the start of the
-(PRGN
--binary
-)PRGN
-- target.
-L1021
-)P
-(P
-L1022
--\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- adds an entry to this file for the
-(TT
--.deb
-)TT
--\nfile that will be created by
-(PRGN
--dpkg-deb
-)PRGN
-- from the control file\nthat it generates, so for most packages all that needs to be done with\nthis file is to delete it in
-(PRGN
--clean
-)PRGN
--.
-L1027
-)P
-(P
-L1028
--\nIf a package upload includes files besides the source package and any\nbinary packages whose control files were made with\n
-(PRGN
--dpkg-gencontrol
-)PRGN
-- then they should be placed in the parent of the\npackage's top-level directory and
-(PRGN
--dpkg-distaddfile
-)PRGN
-- should be\ncalled to add the file to the list in
-(TT
--debian/files
-)TT
--.\n
-L1035
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s3.2.6
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.6
-AHNAME CDATA subsection 3.2.6
-(SECT1
-(HEADING
-(TT
--debian/tmp
-)TT
-L1036
-)HEADING
-(P
-L1037
--\nThis is the canonical temporary location for the construction of\nbinary packages by the
-(PRGN
--binary
-)PRGN
-- target. The directory
-(TT
--tmp
-)TT
--\nserves as the root of the filesystem tree as it is being constructed\n(for example, by using the package's upstream makefiles install\ntargets and redirecting the output there), and it also contains the\n
-(TT
--DEBIAN
-)TT
-- subdirectory. See
-AID CDATA bincreating
-ALEVEL CDATA SECT
-ASRID CDATA s-bincreating
-ACHAPT CDATA 2
-ACSRID CDATA ch-binarypkg
-ASECT CDATA .1
-AHNAME CDATA section 2.1
-(REF
-L140 programmer.sgml
--Creating package files -
-(PRGN
--dpkg-deb
-)PRGN
-L141
-)REF
--.
-L1044
-)P
-(P
-L1045
--\nIf several binary packages are generated from the same source tree it\nis usual to use several
-(TT
--debian/tmp
-(VAR
--something
-)VAR
-)TT
-- directories,\nfor example
-(TT
--tmp-a
-)TT
-- or
-(TT
--tmp-doc
-)TT
--.
-L1049
-)P
-(P
-L1050
--\nWhatever
-(TT
--tmp
-)TT
-- directories are created and used by
-(PRGN
--binary
-)PRGN
--\nmust of course be removed by the
-(PRGN
--clean
-)PRGN
-- target.\n\n
-L1055
-)P
-)SECT1
-)SECT
-AID CDATA sourcearchives
-ASRID CDATA s-sourcearchives
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .3
-AHNAME CDATA section 3.3
-(SECT
-(HEADING
--Source packages as archives
-L1056
-)HEADING
-(P
-L1057
--\nAs it exists on the FTP site, a Debian source package consists of\nthree related files. You must have the right versions of all three to\nbe able to use them.
-L1061
-)P
-(P
-L1062
--\n
-ACOMPACT IMPLIED
-(TAGLIST
-L1064
-(TAG
--Debian source control file -
-(TT
--.dsc
-)TT
-)TAG
-L1065
-(ITEM
-L1067
-(P
--This file contains a series of fields, identified and separated just\nlike the fields in the control file of a binary package. The fields\nare listed below; their syntax is described above, in\n
-AID CDATA controlfields
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-controlfields
-ACHAPT CDATA 4
-ASECT IMPLIED
-AHNAME CDATA chapter 4
-(REF
-L1190 programmer.sgml
--Control files and their fields
-L1191
-)REF
--.\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1072
-(ITEM
-(P
-AID CDATA f-Source
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Source
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.5
-AHNAME CDATA subsection 4.2.5
-(QREF
-(TT
--Source
-)TT
-)QREF
-L1073
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA versions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(QREF
-(TT
--Version
-)TT
-)QREF
-L1074
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Maintainer
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Maintainer
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.4
-AHNAME CDATA subsection 4.2.4
-(QREF
-(TT
--Maintainer
-)TT
-)QREF
-L1075
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Binary
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Binary
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.10
-AHNAME CDATA subsection 4.2.10
-(QREF
-(TT
--Binary
-)TT
-)QREF
-L1076
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Architecture
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Architecture
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.3
-AHNAME CDATA subsection 4.2.3
-(QREF
-(TT
--Architecture
-)TT
-)QREF
-L1077
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Standards-Version
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Standards-Version
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.13
-AHNAME CDATA subsection 4.2.13
-(QREF
-(TT
--Standards-Version
-)TT
-)QREF
-L1078
-)P
-)ITEM
-(ITEM
-(P
-AID CDATA f-Files
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Files
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.12
-AHNAME CDATA subsection 4.2.12
-(QREF
-(TT
--Files
-)TT
-)QREF
-L1079
-)P
-)ITEM
-)LIST
-L1080
-)P
-(P
-L1081
--\nThe source package control file is generated by
-(PRGN
--dpkg-source
-)PRGN
--\nwhen it builds the source archive, from other files in the source\npackage, described above. When unpacking it is checked against the\nfiles and directories in the other parts of the source package, as\ndescribed below.\n
-L1088
-)P
-)ITEM
-(TAG
--Original source archive -
-(TT
-(VAR
--package
-)VAR
--_
-(VAR
--upstream-version
-)VAR
--.orig.tar.gz
-)TT
-)TAG
-L1089
-(ITEM
-L1091
-(P
--This is a compressed (with
-(TT
--gzip -9
-)TT
--)
-(PRGN
--tar
-)PRGN
-- file containing\nthe source code from the upstream authors of the program. The tarfile\nunpacks into a directory\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--upstream-version
-)VAR
--.orig
-)TT
--, and does not contain\nfiles anywhere other than in there or in its subdirectories.\n
-L1097
-)P
-)ITEM
-(TAG
--Debianisation diff -
-(TT
-(VAR
--package
-)VAR
--_
-(VAR
--version-revision
-)VAR
--.diff.gz
-)TT
-)TAG
-L1098
-(ITEM
-L1100
-(P
--This is a unified context diff (
-(TT
--diff -u
-)TT
--) giving the changes which\nare required to turn the original source into the Debian source.\nThese changes may only include editing and creating plain files. The\npermissions of files, the targets of symbolic links and the\ncharacteristics of special files or pipes may not be changed and no\nfiles may be removed or renamed.
-L1106
-)P
-(P
-L1107
--\nAll the directories in the diff must exist, except the
-(TT
--debian
-)TT
--\nsubdirectory of the top of the source tree, which will be created by\n
-(PRGN
--dpkg-source
-)PRGN
-- if necessary when unpacking.
-L1111
-)P
-(P
-L1112
--\nThe
-(PRGN
--dpkg-source
-)PRGN
-- program will automatically make the\n
-(TT
--debian/rules
-)TT
-- file executable (see below).\n
-L1116
-)P
-)ITEM
-)TAGLIST
-L1117
-)P
-(P
-L1118
--\nIf there is no original source code - for example, if the package is\nspecially prepared for Debian or the Debian maintainer is the same as\nthe upstream maintainer - the format is slightly different: then there\nis no diff, and the tarfile is named\n
-(TT
-(VAR
--package
-)VAR
--_
-(VAR
--version
-)VAR
--.tar.gz
-)TT
-- and contains a directory\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
-)TT
--.\n
-L1126
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s3.4
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .4
-AHNAME CDATA section 3.4
-(SECT
-(HEADING
--Unpacking a Debian source package without
-(PRGN
--dpkg-source
-)PRGN
-L1127
-)HEADING
-(P
-L1128
--\n
-(TT
--dpkg-source -x
-)TT
-- is the recommended way to unpack a Debian source\npackage. However, if it is not available it is possible to unpack a\nDebian source archive as follows:\n\n
-ACOMPACT TOKEN COMPACT
-(ENUMLIST
-L1134
-(ITEM
-(P
--Untar the tarfile, which will create a
-(TT
--.orig
-)TT
-- directory.
-L1135
-)P
-)ITEM
-(ITEM
-(P
--Rename the
-(TT
--.orig
-)TT
-- directory to\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--version
-)VAR
-)TT
--.
-L1137
-)P
-)ITEM
-(ITEM
-(P
--Create the subdirectory
-(TT
--debian
-)TT
-- at the top of the source\ntree.
-L1139
-)P
-)ITEM
-(ITEM
-(P
--Apply the diff using
-(TT
--patch -p0
-)TT
--.
-L1140
-)P
-)ITEM
-(ITEM
-(P
--Untar the tarfile again if you want a copy of the original\nsource code alongside the Debianised version.
-L1142
-)P
-)ITEM
-)ENUMLIST
-L1143
-)P
-(P
-L1144
--\nIt is not possible to generate a valid Debian source archive without\nusing
-(PRGN
--dpkg-source
-)PRGN
--. In particular, attempting to use\n
-(PRGN
--diff
-)PRGN
-- directly to generate the
-(TT
--.diff.gz
-)TT
-- file will not work.\n
-L1149
-)P
-AID IMPLIED
-ASRID CDATA s3.4.1
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .4.1
-AHNAME CDATA subsection 3.4.1
-(SECT1
-(HEADING
--Restrictions on objects in source packages
-L1150
-)HEADING
-(P
-L1151
--\nThe source package may not contain any device special files, sockets\nor setuid or setgid files.
-(FOOTNOTE
-(P
--Setgid directories are\nallowed.
-)P
-)FOOTNOTE
-L1155
-)P
-(P
-L1156
--\nThe source packaging tools manage the changes between the original and\nDebianised source using
-(PRGN
--diff
-)PRGN
-- and
-(PRGN
--patch
-)PRGN
--. Turning the\noriginal source tree as included in the
-(TT
--.orig.tar.gz
-)TT
-- into the\ndebianised source must not involve any changes which cannot be handled\nby these tools. Problematic changes which cause
-(PRGN
--dpkg-source
-)PRGN
-- to\nhalt with an error when building the source package are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1164
-(ITEM
-(P
--Adding or removing symbolic links, sockets or pipes.
-L1165
-)P
-)ITEM
-(ITEM
-(P
--Changing the targets of symbolic links.
-L1166
-)P
-)ITEM
-(ITEM
-(P
--Creating directories, other than
-(TT
--debian
-)TT
--.
-L1167
-)P
-)ITEM
-(ITEM
-(P
--Changes to the contents of binary files.
-L1168
-)P
-)ITEM
-)LIST
--\nChanges which cause
-(PRGN
--dpkg-source
-)PRGN
-- to print a warning but continue\nanyway are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1172
-(ITEM
-(P
--Removing files, directories or symlinks.
-(FOOTNOTE
-(P
--Renaming a\nfile is not treated specially - it is seen as the removal of the old\nfile (which generates a warning, but is otherwise ignored), and the\ncreation of the new one.
-)P
-)FOOTNOTE
-L1176
-)P
-)ITEM
-)LIST
--\nChanges which are not represented, but which are not detected by\n
-(PRGN
--dpkg-source
-)PRGN
--, are:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1180
-(ITEM
-(P
--Changing the permissions of files (other than\n
-(TT
--debian/rules
-)TT
--) and directories.
-L1182
-)P
-)ITEM
-)LIST
-L1183
-)P
-(P
-L1184
--\nThe
-(TT
--debian
-)TT
-- directory and
-(TT
--debian/rules
-)TT
-- are handled\nspecially by
-(PRGN
--dpkg-source
-)PRGN
-- - before applying the changes it will\ncreate the
-(TT
--debian
-)TT
-- directory, and afterwards it will make\n
-(TT
--debian/rules
-)TT
-- world-exectuable.\n
-L1190
-)P
-)SECT1
-)SECT
-)CHAPT
-AID CDATA controlfields
-ASRID CDATA ch-controlfields
-ACHAPT CDATA 4
-ASECT IMPLIED
-AHNAME CDATA chapter 4
-(CHAPT
-(HEADING
--Control files and their fields
-L1191
-)HEADING
-(P
-L1192
--\nMany of the tools in the
-(PRGN
--dpkg
-)PRGN
-- suite manipulate data in a common\nformat, known as control files. Binary and source packages have\ncontrol data as do the
-(TT
--.changes
-)TT
-- files which control the\ninstallation of uploaded files, and
-(PRGN
--dpkg
-)PRGN
--'s internal databases\nare in a similar format.\n
-L1199
-)P
-AID IMPLIED
-ASRID CDATA s4.1
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .1
-AHNAME CDATA section 4.1
-(SECT
-(HEADING
--Syntax of control files
-L1200
-)HEADING
-(P
-L1201
--\nA file consists of one or more paragraphs of fields. The paragraphs\nare separated by blank lines. Some control files only allow one\nparagraph; others allow several, in which case each paragraph often\nrefers to a different package.
-L1206
-)P
-(P
-L1207
--\nEach paragraph is a series of fields and values; each field consists\nof a name, followed by a colon and the value. It ends at the end of\nthe line. Horizontal whitespace (spaces and tabs) may occur before or\nafter the value and is ignored there; it is conventional to put a\nsingle space after the colon.
-L1213
-)P
-(P
-L1214
--\nSome fields' values may span several lines; in this case each\ncontinuation line
-(EM
--must
-)EM
-- start with a space or tab. Any trailing\nspaces or tabs at the end of individual lines of a field value are\nignored.
-L1219
-)P
-(P
-L1220
--\nExcept where otherwise stated only a single line of data is allowed\nand whitespace is not significant in a field body. Whitespace may\nnever appear inside names (of packages, architectures, files or\nanything else), version numbers or in between the characters of\nmulti-character version relationships.
-L1226
-)P
-(P
-L1227
--\nField names are not case-sensitive, but it is usual to capitalise the\nfields using mixed case as shown below.
-L1230
-)P
-(P
-L1231
--\nBlank lines, or lines consisting only of spaces and tabs, are not\nallowed within field values or between fields - that would mean a new\nparagraph.
-L1235
-)P
-(P
-L1236
--\nIt is important to note that there are several fields which are\noptional as far as
-(PRGN
--dpkg
-)PRGN
-- and the related tools are concerned,\nbut which must appear in every Debian package, or whose omission may\ncause problems. When writing the control files for Debian packages\nyou
-(EM
--must
-)EM
-- read the Debian policy manual in conjuction with the\ndetails below and the list of fields for the particular file.\n
-L1244
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s4.2
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2
-AHNAME CDATA section 4.2
-(SECT
-(HEADING
--List of fields\n
-L1246
-)HEADING
-AID CDATA f-Package
-ASRID CDATA s-f-Package
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.1
-AHNAME CDATA subsection 4.2.1
-(SECT1
-(HEADING
-(TT
--Package
-)TT
-L1247
-)HEADING
-(P
-L1248
--\nThe name of the binary package. Package names consist of the\nalphanumerics and
-(TT
--+
-)TT
--
-(TT
---
-)TT
--
-(TT
--.
-)TT
-- (plus, minus and full\nstop).
-(FOOTNOTE
-(P
--The characters
-(TT
--@
-)TT
--
-(TT
--:
-)TT
--
-(TT
--=
-)TT
--
-(TT
--%
-)TT
--
-(TT
--_
-)TT
-- (at,\ncolon, equals, percent and underscore) used to be legal and are still\naccepted when found in a package file, but may not be used in new\npackages
-)P
-)FOOTNOTE
-L1255
-)P
-(P
-L1256
--\nThey must be at least two characters and must start with an\nalphanumeric. In current versions of dpkg they are sort of\ncase-sensitive
-(FOOTNOTE
-(P
--This is a bug.
-)P
-)FOOTNOTE
--; use lowercase\npackage names unless the package you're building (or referring to, in\nother fields) is already using uppercase.\n
-L1263
-)P
-)SECT1
-AID CDATA f-Version
-ASRID CDATA s-f-Version
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.2
-AHNAME CDATA subsection 4.2.2
-(SECT1
-(HEADING
-(TT
--Version
-)TT
-L1264
-)HEADING
-(P
-L1265
--\nThis lists the source or binary package's version number - see
-AID CDATA versions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(REF
-L1664 programmer.sgml
--Version numbering
-L1665
-)REF
-L1267
--.\n
-L1269
-)P
-)SECT1
-AID CDATA f-Architecture
-ASRID CDATA s-f-Architecture
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.3
-AHNAME CDATA subsection 4.2.3
-(SECT1
-(HEADING
-(TT
--Architecture
-)TT
-L1270
-)HEADING
-(P
-L1271
--\nThis is the architecture string; it is a single word for the CPU\narchitecture.
-L1274
-)P
-(P
-L1275
--\n
-(PRGN
--dpkg
-)PRGN
-- will check the declared architecture of a binary package\nagainst its own compiled-in value before it installs it.
-L1278
-)P
-(P
-L1279
--\nThe special value
-(TT
--all
-)TT
-- indicates that the package is\narchitecture-independent.
-L1282
-)P
-(P
-L1283
--\nIn the main
-(TT
--debian/control
-)TT
-- file in the source package, or in\nthe source package control file
-(TT
--.dsc
-)TT
--, a list of architectures\n(separated by spaces) is also allowed, as is the special value\n
-(TT
--any
-)TT
--. A list indicates that the source will build an\narchitecture-dependent package, and will only work correctly on the\nlisted architectures.
-(TT
--any
-)TT
-- indicates that though the source\npackage isn't dependent on any particular architecture and should\ncompile fine on any one, the binary package(s) produced are not\narchitecture-independent but will instead be specific to whatever the\ncurrent build architecture is.
-L1294
-)P
-(P
-L1295
--\nIn a
-(TT
--.changes
-)TT
-- file the
-(TT
--Architecture
-)TT
-- field lists the\narchitecture(s) of the package(s) currently being uploaded. This will\nbe a list; if the source for the package is being uploaded too the\nspecial entry
-(TT
--source
-)TT
-- is also present.
-L1300
-)P
-(P
-L1301
--\nThe current build architecture can be determined using
-(TT
--dpkg\n--print-architecture
-)TT
--.
-(FOOTNOTE
-(P
--This actually invokes\n
-(EXAMPLE
-L1305
--gcc --print-libgcc-file-name
-L1306
-)EXAMPLE
--\nand parses and decomposes the output and looks the CPU type from the\nGCC configuration in a table in
-(PRGN
--dpkg
-)PRGN
--. This is so that it will\nwork if you're cross-compiling.
-L1310
-)P
-)FOOTNOTE
--\nThis value is automatically used by
-(PRGN
--dpkg-gencontrol
-)PRGN
-- when\nbuilding the control file for a binary package for which the source\ncontrol information doesn't specify architecture
-(TT
--all
-)TT
--.
-L1314
-)P
-(P
-L1315
--\nThere is a separate option,
-(TT
----print-installation-architecture
-)TT
--,\nfor finding out what architecture
-(PRGN
--dpkg
-)PRGN
-- is willing to install.\nThis information is also in the output of
-(TT
--dpkg --version
-)TT
--.\n
-L1320
-)P
-)SECT1
-AID CDATA f-Maintainer
-ASRID CDATA s-f-Maintainer
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.4
-AHNAME CDATA subsection 4.2.4
-(SECT1
-(HEADING
-(TT
--Maintainer
-)TT
-L1321
-)HEADING
-(P
-L1322
--\nThe package maintainer's name and email address. The name should come\nfirst, then the email address inside angle brackets
-(TT
--\|<\|\|>\|
-)TT
-- (in\nRFC822 format).
-L1326
-)P
-(P
-L1327
--\nIf the maintainer's name contains a full stop then the whole field\nwill not work directly as an email address due to a misfeature in the\nsyntax specified in RFC822; a program using this field as an address\nmust check for this and correct the problem if necessary (for example\nby putting the name in round brackets and moving it to the end, and\nbringing the email address forward).
-L1334
-)P
-(P
-L1335
--\nIn a
-(TT
--.changes
-)TT
-- file or parsed changelog data this contains the\nname and email address of the person responsible for the particular\nversion in question - this may not be the package's usual maintainer.
-L1339
-)P
-(P
-L1340
--\nThis field is usually optional in as far as the
-(PRGN
--dpkg
-)PRGN
-- are\nconcerned, but its absence when building packages usually generates a\nwarning.\n
-L1345
-)P
-)SECT1
-AID CDATA f-Source
-ASRID CDATA s-f-Source
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.5
-AHNAME CDATA subsection 4.2.5
-(SECT1
-(HEADING
-(TT
--Source
-)TT
-L1346
-)HEADING
-(P
-L1347
--\nThis field identifies the source package name.
-L1349
-)P
-(P
-L1350
--\nIn a main source control information or a
-(TT
--.changes
-)TT
-- or
-(TT
--.dsc
-)TT
--\nfile or parsed changelog data this may contain only the name of the\nsource package.
-L1354
-)P
-(P
-L1355
--\nIn the control file of a binary package (or in a
-(TT
--Packages
-)TT
-- file)\nit may be followed by a version number in parentheses.
-(FOOTNOTE
-(P
--It is\nusual to leave a space after the package name if a version number is\nspecified.
-)P
-)FOOTNOTE
-- This version number may be omitted (and is, by\n
-(PRGN
--dpkg-gencontrol
-)PRGN
--) if it has the same value as the
-(TT
--Version
-)TT
--\nfield of the binary package in question. The field itself may be\nomitted from a binary package control file when the source package has\nthe same name and version as the binary package.\n
-L1365
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s4.2.6
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.6
-AHNAME CDATA subsection 4.2.6
-(SECT1
-(HEADING
--Package interrelationship fields:\n
-(TT
--Depends
-)TT
--,
-(TT
--Pre-Depends
-)TT
--,
-(TT
--Recommends
-)TT
--\n
-(TT
--Suggests
-)TT
--,
-(TT
--Conflicts
-)TT
--,
-(TT
--Provides
-)TT
--,
-(TT
--Replaces
-)TT
-L1368
-)HEADING
-(P
-L1369
--\nThese fields describe the package's relationships with other packages.\nTheir syntax and semantics are described in
-AID CDATA relationships
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-relationships
-ACHAPT CDATA 8
-ASECT IMPLIED
-AHNAME CDATA chapter 8
-(REF
-L2305 programmer.sgml
--Declaring relationships between packages
-L2306
-)REF
--.\n
-L1373
-)P
-)SECT1
-AID CDATA f-Description
-ASRID CDATA s-f-Description
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.7
-AHNAME CDATA subsection 4.2.7
-(SECT1
-(HEADING
-(TT
--Description
-)TT
-L1374
-)HEADING
-(P
-L1375
--\nIn a binary package
-(TT
--Packages
-)TT
-- file or main source control file\nthis field contains a description of the binary package, in a special\nformat. See
-AID CDATA descriptions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-descriptions
-ACHAPT CDATA 7
-ASECT IMPLIED
-AHNAME CDATA chapter 7
-(REF
-L2156 programmer.sgml
--Descriptions of packages - the\n
-(TT
--Description
-)TT
-- field
-L2158
-)REF
-- for details.
-L1379
-)P
-(P
-L1380
--\nIn a
-(TT
--.changes
-)TT
-- file it contains a summary of the descriptions for\nthe packages being uploaded. The part of the field before the first\nnewline is empty; thereafter each line has the name of a binary\npackage and the summary description line from that binary package.\nEach line is indented by one space.\n
-L1387
-)P
-)SECT1
-AID CDATA f-Essential
-ASRID CDATA s-f-Essential
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.8
-AHNAME CDATA subsection 4.2.8
-(SECT1
-(HEADING
-(TT
--Essential
-)TT
-L1388
-)HEADING
-(P
-L1389
--\nThis is a boolean field which may occur only in the control file of a\nbinary package (or in the
-(TT
--Packages
-)TT
-- file) or in a per-package\nfields paragraph of a main source control data file.
-L1393
-)P
-(P
-L1394
--\nIf set to
-(TT
--yes
-)TT
-- then
-(PRGN
--dpkg
-)PRGN
-- and
-(PRGN
--dselect
-)PRGN
-- will refuse to\nremove the package (though it can be upgraded and/or replaced). The\nother possible value is
-(TT
--no
-)TT
--, which is the same as not having the\nfield at all.\n
-L1400
-)P
-)SECT1
-AID CDATA f-classification
-ASRID CDATA s-f-classification
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.9
-AHNAME CDATA subsection 4.2.9
-(SECT1
-(HEADING
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-L1401
-)HEADING
-(P
-L1402
--\nThese two fields classify the package. The
-(TT
--Priority
-)TT
-- represents\nhow important that it is that the user have it installed; the\n
-(TT
--Section
-)TT
-- represents an application area into which the package has\nbeen classified.
-L1407
-)P
-(P
-L1408
--\nWhen they appear in the
-(TT
--debian/control
-)TT
-- file these fields give\nvalues for the section and priority subfields of the
-(TT
--Files
-)TT
-- field\nof the
-(TT
--.changes
-)TT
-- file, and give defaults for the section and\npriority of the binary packages.
-L1413
-)P
-(P
-L1414
--\nThe section and priority are represented, though not as separate\nfields, in the information for each file in the
-AID CDATA f-Files
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Files
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.12
-AHNAME CDATA subsection 4.2.12
-(QREF
-L1417
-(TT
--Files
-)TT
-)QREF
-- field of a
-(TT
--.changes
-)TT
-- file. The\nsection value in a
-(TT
--.changes
-)TT
-- file is used to decide where to\ninstall a package in the FTP archive.
-L1420
-)P
-(P
-L1421
--\nThese fields are not used by by
-(PRGN
--dpkg
-)PRGN
-- proper, but by\n
-(PRGN
--dselect
-)PRGN
-- when it sorts packages and selects defaults. See the\nDebian policy manual for the priorities in use and the criteria for\nselecting the priority for a Debian package, and look at the Debian\nFTP archive for a list of currently in-use priorities.
-L1427
-)P
-(P
-L1428
--\nThese fields may appear in binary package control files, in which case\nthey provide a default value in case the
-(TT
--Packages
-)TT
-- files are\nmissing the information.
-(PRGN
--dpkg
-)PRGN
-- and
-(PRGN
--dselect
-)PRGN
-- will only use\nthe value from a
-(TT
--.deb
-)TT
-- file if they have no other information; a\nvalue listed in a
-(TT
--Packages
-)TT
-- file will always take precedence. By\ndefault
-(PRGN
--dpkg-genchanges
-)PRGN
-- does not include the section and\npriority in the control file of a binary package - use the
-(TT
---isp
-)TT
--,\n
-(TT
---is
-)TT
-- or
-(TT
---ip
-)TT
-- options to achieve this effect.\n
-L1438
-)P
-)SECT1
-AID CDATA f-Binary
-ASRID CDATA s-f-Binary
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.10
-AHNAME CDATA subsection 4.2.10
-(SECT1
-(HEADING
-(TT
--Binary
-)TT
-L1439
-)HEADING
-(P
-L1440
--\nThis field is a list of binary packages.
-L1442
-)P
-(P
-L1443
--\nWhen it appears in the
-(TT
--.dsc
-)TT
-- file it is the list of binary\npackages which a source package can produce. It does not necessarily\nproduce all of these binary packages for every architecture. The\nsource control file doesn't contain details of which architectures are\nappropriate for which of the binary packages.
-L1449
-)P
-(P
-L1450
--\nWhen it appears in a
-(TT
--.changes
-)TT
-- file it lists the names of the\nbinary packages actually being uploaded.
-L1453
-)P
-(P
-L1454
--\nThe syntax is a list of binary packages separated by\ncommas.
-(FOOTNOTE
-(P
--A space after each comma is conventional.
-)P
-)FOOTNOTE
--\nCurrently the packages must be separated using only spaces in the\n
-(TT
--.changes
-)TT
-- file.\n
-L1460
-)P
-)SECT1
-AID CDATA f-Installed-Size
-ASRID CDATA s-f-Installed-Size
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.11
-AHNAME CDATA subsection 4.2.11
-(SECT1
-(HEADING
-(TT
--Installed-Size
-)TT
-L1461
-)HEADING
-(P
-L1462
--\nThis field appears in the control files of binary packages, and in the\n
-(TT
--Packages
-)TT
-- files. It gives the total amount of disk space\nrequired to install the named package.
-L1466
-)P
-(P
-L1467
--\nThe disk space is represented in kilobytes as a simple decimal number.\n
-L1470
-)P
-)SECT1
-AID CDATA f-Files
-ASRID CDATA s-f-Files
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.12
-AHNAME CDATA subsection 4.2.12
-(SECT1
-(HEADING
-(TT
--Files
-)TT
-L1471
-)HEADING
-(P
-L1472
--\nThis field contains a list of files with information about each one.\nThe exact information and syntax varies with the context. In all\ncases the the part of the field contents on the same line as the field\nname is empty. The remainder of the field is one line per file, each\nline being indented by one space and containing a number of sub-fields\nseparated by spaces.
-L1479
-)P
-(P
-L1480
--\nIn the
-(TT
--.dsc
-)TT
-- (Debian source control) file each line contains the\nMD5 checksum, size and filename of the tarfile and (if applicable)\ndiff file which make up the remainder of the source\npackage.
-(FOOTNOTE
-(P
--That is, the parts which are not the\n
-(TT
--.dsc
-)TT
--.
-)P
-)FOOTNOTE
-- The exact forms of the filenames are described\nin
-AID CDATA sourcearchives
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcearchives
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .3
-AHNAME CDATA section 3.3
-(REF
-L1055 programmer.sgml
--Source packages as archives
-L1056
-)REF
--.
-L1487
-)P
-(P
-L1488
--\nIn the
-(TT
--.changes
-)TT
-- file this contains one line per file being\nuploaded. Each line contains the MD5 checksum, size, section and\npriority and the filename. The section and priority are the values of\nthe corresponding fields in the main source control file - see
-AID CDATA f-classification
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-classification
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.9
-AHNAME CDATA subsection 4.2.9
-(REF
-L1400 programmer.sgml
-(TT
--Section
-)TT
-- and
-(TT
--Priority
-)TT
-L1401
-)REF
-L1493
--. If no section or priority is specified then\n
-(TT
---
-)TT
-- should be used, though section and priority values must be\nspecified for new packages to be installed properly.
-L1496
-)P
-(P
-L1497
--\nThe special value
-(TT
--byhand
-)TT
-- for the section in a
-(TT
--.changes
-)TT
-- file\nindicates that the file in question is not an ordinary package file\nand must by installed by hand by the distribution maintainers. If the\nsection is
-(TT
--byhand
-)TT
-- the priority should be
-(TT
---
-)TT
--.
-L1502
-)P
-(P
-L1503
--\nIf a new Debian revision of a package is being shipped and no new\noriginal source archive is being distributed the
-(TT
--.dsc
-)TT
-- must still\ncontain the
-(TT
--Files
-)TT
-- field entry for the original source archive\n
-(TT
-(VAR
--package
-)VAR
---
-(VAR
--upstream-version
-)VAR
--.orig.tar.gz
-)TT
--, but the\n
-(TT
--.changes
-)TT
-- file should leave it out. In this case the original\nsource archive on the distribution site must match exactly,\nbyte-for-byte, the original source archive which was used to generate\nthe
-(TT
--.dsc
-)TT
-- file and diff which are being uploaded.\n\n
-L1514
-)P
-)SECT1
-AID CDATA f-Standards-Version
-ASRID CDATA s-f-Standards-Version
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.13
-AHNAME CDATA subsection 4.2.13
-(SECT1
-(HEADING
-(TT
--Standards-Version
-)TT
-L1515
-)HEADING
-(P
-L1516
--\nThe most recent version of the standards (the
-(PRGN
--dpkg
-)PRGN
-- programmers'\nand policy manuals and associated texts) with which the package\ncomplies. This is updated manually when editing the source package to\nconform to newer standards; it can sometimes be used to tell when a\npackage needs attention.
-L1522
-)P
-(P
-L1523
--\nIts format is the same as that of a version number except that no\nepoch or Debian revision is allowed - see
-AID CDATA versions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(REF
-L1664 programmer.sgml
--Version numbering
-L1665
-)REF
--.\n\n
-L1528
-)P
-)SECT1
-AID CDATA f-Distribution
-ASRID CDATA s-f-Distribution
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.14
-AHNAME CDATA subsection 4.2.14
-(SECT1
-(HEADING
-(TT
--Distribution
-)TT
-L1529
-)HEADING
-(P
-L1530
--\nIn a
-(TT
--.changes
-)TT
-- file or parsed changelog output this contains the\n(space-separated) name(s) of the distribution(s) where this version of\nthe package should be or was installed. Distribution names follow the\nrules for package names. (See
-AID CDATA f-Package
-ALEVEL CDATA SECT1
-ASRID CDATA s-f-Package
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.1
-AHNAME CDATA subsection 4.2.1
-(REF
-L1246 programmer.sgml
-(TT
--Package
-)TT
-L1247
-)REF
--).
-L1535
-)P
-(P
-L1536
--\nCurrent distribution values are
-(TT
--stable
-)TT
--,
-(TT
--unstable
-)TT
--,\n
-(TT
--contrib
-)TT
--,
-(TT
--non-free
-)TT
-- and
-(TT
--experimental
-)TT
--.\n
-L1540
-)P
-)SECT1
-AID CDATA f-Urgency
-ASRID CDATA s-f-Urgency
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.15
-AHNAME CDATA subsection 4.2.15
-(SECT1
-(HEADING
-(TT
--Urgency
-)TT
-L1541
-)HEADING
-(P
-L1542
--\nThis is a description of how important it is to upgrade to this\nversion from previous ones. It consists of a single keyword usually\ntaking one of the values
-(TT
--LOW
-)TT
--,
-(TT
--MEDIUM
-)TT
-- or
-(TT
--HIGH
-)TT
--) followed\nby an optional commentary (separated by a space) which is usually in\nparentheses. For example:\n
-(EXAMPLE
-L1549
--Urgency: LOW (HIGH for diversions users)
-L1550
-)EXAMPLE
-L1551
-)P
-(P
-L1552
--\nThis field appears in the
-(TT
--.changes
-)TT
-- file and in parsed changelogs;\nits value appears as the value of the
-(TT
--urgency
-)TT
-- attribute in a\n
-(PRGN
--dpkg
-)PRGN
---style changelog (see
-AID CDATA dpkgchangelog
-ALEVEL CDATA SECT1
-ASRID CDATA s-dpkgchangelog
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.3
-AHNAME CDATA subsection 3.2.3
-(REF
-L834 programmer.sgml
-(TT
--debian/changelog
-)TT
-L835
-)REF
--).
-L1556
-)P
-(P
-L1557
--\nUrgency keywords are not case-sensitive.\n
-L1560
-)P
-)SECT1
-AID CDATA f-Date
-ASRID CDATA s-f-Date
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.16
-AHNAME CDATA subsection 4.2.16
-(SECT1
-(HEADING
-(TT
--Date
-)TT
-L1561
-)HEADING
-(P
-L1562
--\nIn
-(TT
--.changes
-)TT
-- files and parsed changelogs, this gives the date the\npackage was built or last edited.\n
-L1566
-)P
-)SECT1
-AID CDATA f-Format
-ASRID CDATA s-f-Format
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.17
-AHNAME CDATA subsection 4.2.17
-(SECT1
-(HEADING
-(TT
--Format
-)TT
-L1567
-)HEADING
-(P
-L1568
--\nThis field occurs in
-(TT
--.changes
-)TT
-- files, and specifies a format\nrevision for the file. The format described here is version
-(TT
--1.5
-)TT
--.\nThe syntax of the format value is the same as that of a package\nversion number except that no epoch or Debian revision is allowed -\nsee
-AID CDATA versions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(REF
-L1664 programmer.sgml
--Version numbering
-L1665
-)REF
--.\n
-L1575
-)P
-)SECT1
-AID CDATA f-Changes
-ASRID CDATA s-f-Changes
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.18
-AHNAME CDATA subsection 4.2.18
-(SECT1
-(HEADING
-(TT
--Changes
-)TT
-L1576
-)HEADING
-(P
-L1577
--\nIn a
-(TT
--.changes
-)TT
-- file or parsed changelog this field contains the\nhuman-readable changes data, describing the differences between the\nlast version and the current one.
-L1581
-)P
-(P
-L1582
--\nThere should be nothing in this field before the first newline; all\nthe subsequent lines must be indented by at least one space; blank\nlines must be represented by a line consiting only of a space and a\nfull stop.
-L1587
-)P
-(P
-L1588
--\nEach version's change information should be preceded by a `title' line\ngiving at least the version, distribution(s) and urgency, in a\nhuman-readable way.
-L1592
-)P
-(P
-L1593
--\nIf data from several versions is being returned the entry for the most\nrecent version should be returned first, and entries should be\nseparated by the representation of a blank line (the `title' line may\nalso be followed by the representation of blank line).\n
-L1599
-)P
-)SECT1
-AID CDATA f-Filename
-ASRID CDATA s-f-Filename
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.19
-AHNAME CDATA subsection 4.2.19
-(SECT1
-(HEADING
-(TT
--Filename
-)TT
-- and
-(TT
--MSDOS-Filename
-)TT
-L1600
-)HEADING
-(P
-L1601
--\nThese fields in
-(TT
--Packages
-)TT
-- files give the filename(s) of (the parts\nof) a package in the distribution directories, relative to the root of\nthe Debian hierarchy. If the package has been split into several\nparts the parts are all listed in order, separated by spaces.\n
-L1607
-)P
-)SECT1
-AID CDATA f-Size
-ASRID CDATA s-f-Size
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.20
-AHNAME CDATA subsection 4.2.20
-(SECT1
-(HEADING
-(TT
--Size
-)TT
-- and
-(TT
--MD5sum
-)TT
-L1608
-)HEADING
-(P
-L1609
--\nThese fields in
-(TT
--Packages
-)TT
-- files give the size (in bytes, expressed\nin decimal) and MD5 checksum of the file(s) which make(s) up a binary\npackage in the distribution. If the package is split into several\nparts the values for the parts are listed in order, separated by\nspaces.\n
-L1616
-)P
-)SECT1
-AID CDATA f-Status
-ASRID CDATA s-f-Status
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.21
-AHNAME CDATA subsection 4.2.21
-(SECT1
-(HEADING
-(TT
--Status
-)TT
-L1617
-)HEADING
-(P
-L1618
--\nThis field in
-(PRGN
--dpkg
-)PRGN
--'s status file records whether the user wants a\npackage installed, removed or left alone, whether it is broken\n(requiring reinstallation) or not and what its current state on the\nsystem is. Each of these pieces of information is a single word.\n
-L1624
-)P
-)SECT1
-AID CDATA f-Config-Version
-ASRID CDATA s-f-Config-Version
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.22
-AHNAME CDATA subsection 4.2.22
-(SECT1
-(HEADING
-(TT
--Config-Version
-)TT
-L1625
-)HEADING
-(P
-L1626
--\nIf a package is not installed or not configured, this field in\n
-(PRGN
--dpkg
-)PRGN
--'s status file records the last version of the package which\nwas successfully configured.\n
-L1631
-)P
-)SECT1
-AID CDATA f-Conffiles
-ASRID CDATA s-f-Conffiles
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.23
-AHNAME CDATA subsection 4.2.23
-(SECT1
-(HEADING
-(TT
--Conffiles
-)TT
-L1632
-)HEADING
-(P
-L1633
--\nThis field in
-(PRGN
--dpkg
-)PRGN
--'s status file contains information about the\nautomatically-managed configuration files held by a package. This\nfield should
-(EM
--not
-)EM
-- appear anywhere in a package!\n
-L1638
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s4.2.24
-ACHAPT CDATA 4
-ACSRID CDATA ch-controlfields
-ASECT CDATA .2.24
-AHNAME CDATA subsection 4.2.24
-(SECT1
-(HEADING
--Obsolete fields
-L1639
-)HEADING
-(P
-L1640
--\nThese are still recognised by
-(PRGN
--dpkg
-)PRGN
-- but should not appear anywhere\nany more.\n\n
-ACOMPACT TOKEN COMPACT
-(TAGLIST
-L1646
-(TAG
-(TT
--Revision
-)TT
-L1647
-)TAG
-(TAG
-(TT
--Package-Revision
-)TT
-L1648
-)TAG
-(TAG
-(TT
--Package_Revision
-)TT
-L1649
-)TAG
-(ITEM
-L1650
-(P
--The Debian revision part of the package version was at one point in a\nseparate control file field. This field went through several names.\n
-L1653
-)P
-)ITEM
-(TAG
-(TT
--Recommended
-)TT
-L1654
-)TAG
-(ITEM
-(P
--Old name for
-(TT
--Recommends
-)TT
--\n
-L1656
-)P
-)ITEM
-(TAG
-(TT
--Optional
-)TT
-L1657
-)TAG
-(ITEM
-(P
--Old name for
-(TT
--Suggests
-)TT
--.\n
-L1659
-)P
-)ITEM
-(TAG
-(TT
--Class
-)TT
-L1660
-)TAG
-(ITEM
-(P
--Old name for
-(TT
--Priority
-)TT
--.\n
-L1662
-)P
-)ITEM
-)TAGLIST
--\n
-L1664
-)P
-)SECT1
-)SECT
-)CHAPT
-AID CDATA versions
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(CHAPT
-(HEADING
--Version numbering
-L1665
-)HEADING
-(P
-L1666
--\nEvery package has a version number, in its
-(TT
--Version
-)TT
-- control file\nfield.
-L1669
-)P
-(P
-L1670
--\n
-(PRGN
--dpkg
-)PRGN
-- imposes an ordering on version numbers, so that it can tell\nwhether packages are being up- or downgraded and so that
-(PRGN
--dselect
-)PRGN
--\ncan tell whether a package it finds available is newer than the one\ninstalled on the system. The version number format has the most\nsignificant parts (as far as comparison is concerned) at the\nbeginning.
-L1677
-)P
-(P
-L1678
--\nThe version number format is:\n\|[\|
-(VAR
--epoch
-)VAR
-(TT
--:
-)TT
--\|]\|
-(VAR
--upstream-version
-)VAR
--\|[\|
-(TT
---
-)TT
-(VAR
--debian-revision
-)VAR
--\|]\|.
-L1681
-)P
-(P
-L1682
--\nThe three components here are:\n\n
-ACOMPACT IMPLIED
-(TAGLIST
-L1687
-(TAG
-(VAR
--epoch
-)VAR
-L1688
-)TAG
-(ITEM
-L1690
-(P
--This is a single unsigned integer, which should usually be small. It\nmay be omitted, in which case zero is assumed. If it is omitted then\nthe
-(VAR
--upstream-version
-)VAR
-- may not contain any colons.
-L1693
-)P
-(P
-L1694
--\nIt is provided to allow mistakes in the version numbers of older\nversions of a package, and also a package's previous version numbering\nschemes, to be left behind.
-L1698
-)P
-(P
-L1699
--\n
-(PRGN
--dpkg
-)PRGN
-- will not usually display the epoch unless it is essential\n(non-zero, or if the
-(VAR
--upstream-version
-)VAR
-- contains a colon);\n
-(PRGN
--dselect
-)PRGN
-- does not display epochs at all in the main part of the\npackage selection display.\n
-L1705
-)P
-)ITEM
-(TAG
-(VAR
--upstream-version
-)VAR
-L1706
-)TAG
-(ITEM
-L1708
-(P
--This is the main part of the version. It is usually version number of\nthe original (`upstream') package of which the
-(TT
--.deb
-)TT
-- file has been\nmade, if this is applicable. Usually this will be in the same format\nas that specified by the upstream author(s); however, it may need to\nbe reformatted to fit into
-(PRGN
--dpkg
-)PRGN
--'s format and comparison scheme.
-L1713
-)P
-(P
-L1714
--\nThe comparison behaviour of
-(PRGN
--dpkg
-)PRGN
-- with respect to the\n
-(VAR
--upstream-version
-)VAR
-- is described below. The
-(VAR
--upstream-version
-)VAR
--\nportion of the version number is mandatory.
-L1718
-)P
-(P
-L1719
--\nThe
-(VAR
--upstream-version
-)VAR
-- may contain only alphanumerics and the\ncharacters
-(TT
--+
-)TT
--
-(TT
--.
-)TT
--
-(TT
---
-)TT
--
-(TT
--:
-)TT
-- (full stop, plus, hyphen,\ncolon) and should start with a digit. If there is no\n
-(VAR
--debian-revision
-)VAR
-- then hyphens are not allowed; if there is no\n
-(VAR
--epoch
-)VAR
-- then colons are not allowed.\n
-L1726
-)P
-)ITEM
-(TAG
-(VAR
--debian-revision
-)VAR
-L1727
-)TAG
-(ITEM
-L1729
-(P
--This part of the version represents the version of the modifications\nthat were made to the package to make it a Debian binary package. It\nis in the same format as the
-(VAR
--upstream-version
-)VAR
-- and
-(PRGN
--dpkg
-)PRGN
--\ncompares it in the same way.
-L1733
-)P
-(P
-L1734
--\nIt is optional; if it isn't present then the
-(VAR
--upstream-version
-)VAR
--\nmay not contain a hyphen. This format represents the case where a\npiece of software was written specifically to be turned into a Debian\nbinary package, and so there is only one `debianization' of it and\ntherefore no revision indication is required.
-L1740
-)P
-(P
-L1741
--\nIt is conventional to restart the
-(VAR
--debian-revision
-)VAR
-- at
-(TT
--1
-)TT
-- each\ntime the
-(VAR
--upstream-version
-)VAR
-- is increased.
-L1744
-)P
-(P
-L1745
--\n
-(PRGN
--dpkg
-)PRGN
-- will break the
-(VAR
--upstream-version
-)VAR
-- and\n
-(VAR
--debian-revision
-)VAR
-- apart at the last hyphen in the string. The\nabsence of a
-(VAR
--debian-revision
-)VAR
-- compares earlier than the presence\nof one (but note that the
-(VAR
--debian-revision
-)VAR
-- is the least\nsignificant part of the version number).
-L1751
-)P
-(P
-L1752
--\nThe
-(VAR
--debian-revision
-)VAR
-- may contain only alphanumerics and the\ncharacters
-(TT
--+
-)TT
-- and
-(TT
--.
-)TT
-- (plus and full stop).\n
-L1756
-)P
-)ITEM
-)TAGLIST
--\n\nThe
-(VAR
--upstream-version
-)VAR
-- and
-(VAR
--debian-revision
-)VAR
-- parts are\ncompared by
-(PRGN
--dpkg
-)PRGN
-- using the same algorithm:
-L1760
-)P
-(P
-L1761
--\nThe strings are compared from left to right.
-L1763
-)P
-(P
-L1764
--\nFirst the initial part of each string consisting entirely of non-digit\ncharacters is determined. These two parts (one of which may be empty)\nare compared lexically. If a difference is found it is returned. The\nlexical comparison is a comparison of ASCII values modified so that\nall the letters sort earlier than all the non-letters.
-L1770
-)P
-(P
-L1771
--\nThen the initial part of the remainder of each string which consists\nentirely of digit characters is determined. The numerical values of\nthese two parts are compared, and any difference found is returned as\nthe result of the comparison. For these purposes an empty string\n(which can only occur at the end of one or both version strings being\ncompared) counts as zero.
-L1778
-)P
-(P
-L1779
--\nThese two steps are repeated (chopping initial non-digit strings and\ninitial digit strings off from the start) until a difference is found\nor both strings are exhausted.
-L1783
-)P
-(P
-L1784
--\nNote that the purpose of epochs is to allow us to leave behind\nmistakes in version numbering, and to cope with situations where the\nversion numbering changes. It is
-(EM
--not
-)EM
-- there to cope with version\nnumbers containing strings of letters which
-(PRGN
--dpkg
-)PRGN
-- cannot interpret\n(such as
-(TT
--ALPHA
-)TT
-- or
-(TT
--pre-
-)TT
--), or with silly orderings (the author\nof this manual has heard of a package whose versions went
-(TT
--1.1
-)TT
--,\n
-(TT
--1.2
-)TT
--,
-(TT
--1.3
-)TT
--,
-(TT
--1
-)TT
--,
-(TT
--2.1
-)TT
--,
-(TT
--2.2
-)TT
--,
-(TT
--2
-)TT
-- and so forth).
-L1792
-)P
-(P
-L1793
--\nIf an upstream package has problematic version numbers they should be\nconverted to a sane form for use in the
-(TT
--Version
-)TT
-- field.\n\n
-L1798
-)P
-)CHAPT
-AID CDATA maintainerscripts
-ASRID CDATA ch-maintainerscripts
-ACHAPT CDATA 6
-ASECT IMPLIED
-AHNAME CDATA chapter 6
-(CHAPT
-(HEADING
--Package maintainer scripts\nand installation procedure
-L1800
-)HEADING
-AID IMPLIED
-ASRID CDATA s6.1
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .1
-AHNAME CDATA section 6.1
-(SECT
-(HEADING
--Introduction to package maintainer scripts
-L1801
-)HEADING
-(P
-L1802
--\nIt is possible supply scripts as part of a package which
-(PRGN
--dpkg
-)PRGN
--\nwill run for you when your package is installed, upgraded or removed.
-L1805
-)P
-(P
-L1806
--\nThese scripts should be the files
-(TT
--preinst
-)TT
--,
-(TT
--postinst
-)TT
--,\n
-(TT
--prerm
-)TT
-- and
-(TT
--postrm
-)TT
-- in the control area of the package. They\nmust be proper exectuable files; if they are scripts (which is\nrecommended) they must start with the usual
-(TT
--#!
-)TT
-- convention. They\nshould be readable and executable to anyone, and not world-writeable.
-L1812
-)P
-(P
-L1813
--\n
-(PRGN
--dpkg
-)PRGN
-- looks at the exit status from these scripts. It is\nimportant that they exit with a non-zero status if there is an error,\nso that
-(PRGN
--dpkg
-)PRGN
-- can stop its processing. For shell scripts this\nmeans that you
-(EM
--almost always
-)EM
-- need to use
-(TT
--set -e
-)TT
-- (this is\nusually true when writing shell scripts, in fact). It is also\nimportant, of course, that they don't exit with a non-zero status if\neverything went well.
-L1821
-)P
-(P
-L1822
--\nIt is necessary for the error recovery procedures that the scripts be\nidempotent: ie, invoking the same script several times in the same\nsituation should do no harm. If the first call failed, or aborted\nhalf way through for some reason, the second call should merely do the\nthings that were left undone the first time, if any, and exit with a\nsuccess status.
-L1829
-)P
-(P
-L1830
--\nWhen a package is upgraded a combination of the scripts from the old\nand new packages is called in amongst the other steps of the upgrade\nprocedure. If your scripts are going to be at all complicated you\nneed to be aware of this, and may need to check the arguments to your\nscripts.
-L1836
-)P
-(P
-L1837
--\nBroadly speaking the
-(PRGN
--preinst
-)PRGN
-- is called before (a particular\nversion of) a package is installed, and the
-(PRGN
--postinst
-)PRGN
-- afterwards;\nthe
-(PRGN
--prerm
-)PRGN
-- before (a version of) a package is removed and the\n
-(PRGN
--postrm
-)PRGN
-- afterwards.\n\n
-L1844
-)P
-)SECT
-AID CDATA mscriptsinstact
-ASRID CDATA s-mscriptsinstact
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .2
-AHNAME CDATA section 6.2
-(SECT
-(HEADING
--Summary of ways maintainer scripts are called
-L1845
-)HEADING
-(P
-L1846
--\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1848
-(ITEM
-(P
-(VAR
--new-preinst
-)VAR
--
-(TT
--install
-)TT
-L1849
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-preinst
-)VAR
--
-(TT
--install
-)TT
--
-(VAR
--old-version
-)VAR
-L1850
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-preinst
-)VAR
--
-(TT
--upgrade
-)TT
--
-(VAR
--old-version
-)VAR
-L1851
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--old-preinst
-)VAR
--
-(TT
--abort-upgrade
-)TT
--
-(VAR
--new-version
-)VAR
-L1852
-)P
-)ITEM
-)LIST
-L1853
-)P
-(P
-L1854
--\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1856
-(ITEM
-(P
-(VAR
--postinst
-)VAR
--
-(TT
--configure
-)TT
--
-(VAR
--most-recently-configured-version
-)VAR
-L1857
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--old-postinst
-)VAR
--
-(TT
--abort-upgrade
-)TT
--
-(VAR
--new version
-)VAR
-L1858
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--conflictor's-postinst
-)VAR
--
-(TT
--abort-remove
-)TT
--\n
-(TT
--in-favour
-)TT
--
-(VAR
--package
-)VAR
--
-(VAR
--new-version
-)VAR
-L1860
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--deconfigured's-postinst
-)VAR
--
-(TT
--abort-deconfigure
-)TT
--\n
-(TT
--in-favour
-)TT
--
-(VAR
--failed-install-package
-)VAR
--
-(VAR
--version
-)VAR
--\n
-(TT
--removing
-)TT
--
-(VAR
--conflicting-package
-)VAR
--
-(VAR
--version
-)VAR
-L1863
-)P
-)ITEM
-)LIST
-L1864
-)P
-(P
-L1865
--\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1867
-(ITEM
-(P
-(VAR
--prerm
-)VAR
--
-(TT
--remove
-)TT
-L1868
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--old-prerm
-)VAR
--
-(TT
--upgrade
-)TT
--
-(VAR
--new-version
-)VAR
-L1869
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-prerm
-)VAR
--
-(TT
--failed-upgrade
-)TT
--
-(VAR
--old-version
-)VAR
-L1870
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--conflictor's-prerm
-)VAR
--
-(TT
--remove
-)TT
--
-(TT
--in-favour
-)TT
--\n
-(VAR
--package
-)VAR
--
-(VAR
--new-version
-)VAR
-L1872
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--deconfigured's-prerm
-)VAR
--
-(TT
--deconfigure
-)TT
--\n
-(TT
--in-favour
-)TT
--
-(VAR
--package-being-installed
-)VAR
--
-(VAR
--version
-)VAR
--\n
-(TT
--removing
-)TT
--
-(VAR
--conflicting-package
-)VAR
--
-(VAR
--version
-)VAR
-L1875
-)P
-)ITEM
-)LIST
-L1876
-)P
-(P
-L1877
--\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L1879
-(ITEM
-(P
-(VAR
--postrm
-)VAR
--
-(TT
--remove
-)TT
-L1880
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--postrm
-)VAR
--
-(TT
--purge
-)TT
-L1881
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--old-postrm
-)VAR
--
-(TT
--upgrade
-)TT
--
-(VAR
--new-version
-)VAR
-L1882
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-postrm
-)VAR
--
-(TT
--failed-upgrade
-)TT
--
-(VAR
--old-version
-)VAR
-L1883
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-postrm
-)VAR
--
-(TT
--abort-install
-)TT
-L1884
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-postrm
-)VAR
--
-(TT
--abort-install
-)TT
--
-(VAR
--old-version
-)VAR
-L1885
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--new-postrm
-)VAR
--
-(TT
--abort-upgrade
-)TT
--
-(VAR
--old-version
-)VAR
-L1886
-)P
-)ITEM
-(ITEM
-(P
-(VAR
--disappearer's-postrm
-)VAR
--
-(TT
--disappear
-)TT
--
-(VAR
--overwriter
-)VAR
--
-(VAR
--new-version
-)VAR
-L1887
-)P
-)ITEM
-)LIST
--\n\n
-L1890
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s6.3
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .3
-AHNAME CDATA section 6.3
-(SECT
-(HEADING
--Details of unpack phase of installation or upgrade
-L1891
-)HEADING
-(P
-L1892
--\nThe procedure on installation/upgrade/overwrite/disappear (ie, when\nrunning
-(TT
--dpkg --unpack
-)TT
--, or the unpack stage of
-(TT
--dpkg\n--install
-)TT
--) is as follows. In each case if an error occurs the\nactions in are general run backwards - this means that the maintainer\nscripts are run with different arguments in reverse order. These are\nthe `error unwind' calls listed below.\n\n
-ACOMPACT IMPLIED
-(ENUMLIST
-L1901
-(ITEM
-L1903
-(P
-ACOMPACT IMPLIED
-(ENUMLIST
-L1904
-(ITEM
-L1905
-(P
--If a version the package is already\ninstalled, call\n
-(EXAMPLE
-L1908
-(VAR
--old-prerm
-)VAR
-- upgrade
-(VAR
--new-version
-)VAR
-L1909
-)EXAMPLE
--\n
-L1911
-)P
-)ITEM
-(ITEM
-L1912
-(P
--If this gives an error (ie, a non-zero exit status), dpkg will\nattempt instead:\n
-(EXAMPLE
-L1915
-(VAR
--new-prerm
-)VAR
-- failed-upgrade
-(VAR
--old-version
-)VAR
-L1916
-)EXAMPLE
--\nError unwind, for both the above cases:\n
-(EXAMPLE
-L1919
-(VAR
--old-postinst
-)VAR
-- abort-upgrade
-(VAR
--new-version
-)VAR
-L1920
-)EXAMPLE
--\n
-L1922
-)P
-)ITEM
-)ENUMLIST
--\n
-L1924
-)P
-)ITEM
-(ITEM
-L1925
-(P
--If a `conflicting' package is being removed at the same time:\n
-ACOMPACT IMPLIED
-(ENUMLIST
-L1928
-(ITEM
-L1929
-(P
--If any packages depended on that conflicting package and\n
-(TT
----auto-deconfigure
-)TT
-- is specified, call, for each such package:\n
-(EXAMPLE
-L1932
-(VAR
--deconfigured's-prerm
-)VAR
-- deconfigure \\\n in-favour
-(VAR
--package-being-installed
-)VAR
--
-(VAR
--version
-)VAR
-- \\\n removing
-(VAR
--conflicting-package
-)VAR
--
-(VAR
--version
-)VAR
-L1935
-)EXAMPLE
--\nError unwind:\n
-(EXAMPLE
-L1938
-(VAR
--deconfigured's-postinst
-)VAR
-- abort-deconfigure \\\n in-favour
-(VAR
--package-being-installed-but-failed
-)VAR
--
-(VAR
--version
-)VAR
-- \\\n removing
-(VAR
--conflicting-package
-)VAR
--
-(VAR
--version
-)VAR
-L1941
-)EXAMPLE
--\nThe deconfigured packages are marked as requiring configuration, so\nthat if
-(TT
----install
-)TT
-- is used they will be configured again if\npossible.\n
-L1946
-)P
-)ITEM
-(ITEM
-L1947
-(P
--To prepare for removal of the conflicting package, call:\n
-(EXAMPLE
-L1949
-(VAR
--conflictor's-prerm
-)VAR
-- remove in-favour
-(VAR
--package
-)VAR
--
-(VAR
--new-version
-)VAR
-L1950
-)EXAMPLE
--\nError unwind:\n
-(EXAMPLE
-L1953
-(VAR
--conflictor's-postinst
-)VAR
-- abort-remove \\\n in-favour
-(VAR
--package
-)VAR
--
-(VAR
--new-version
-)VAR
-L1955
-)EXAMPLE
--\n
-L1957
-)P
-)ITEM
-)ENUMLIST
--\n
-L1959
-)P
-)ITEM
-(ITEM
-L1960
-(P
-ACOMPACT IMPLIED
-(ENUMLIST
-L1961
-(ITEM
-L1962
-(P
--If the package is being upgraded, call:\n
-(EXAMPLE
-L1964
-(VAR
--new-preinst
-)VAR
-- upgrade
-(VAR
--old-version
-)VAR
-L1965
-)EXAMPLE
--\n
-L1967
-)P
-)ITEM
-(ITEM
-L1968
-(P
--Otherwise, if the package had some configuration files from a previous\nversion installed (ie, it is in the `configuration files only' state):\n
-(EXAMPLE
-L1971
-(VAR
--new-preinst
-)VAR
-- install
-(VAR
--old-version
-)VAR
-L1972
-)EXAMPLE
--\n
-L1974
-)P
-)ITEM
-(ITEM
-L1975
-(P
--Otherwise (ie, the package was completely purged):\n
-(EXAMPLE
-L1977
-(VAR
--new-preinst
-)VAR
-- install
-L1978
-)EXAMPLE
--\nError unwind versions, respectively:\n
-(EXAMPLE
-L1981
-(VAR
--new-postrm
-)VAR
-- abort-upgrade
-(VAR
--old-version
-)VAR
--\n
-(VAR
--new-postrm
-)VAR
-- abort-install
-(VAR
--old-version
-)VAR
--\n
-(VAR
--new-postrm
-)VAR
-- abort-install
-L1984
-)EXAMPLE
--\n
-L1986
-)P
-)ITEM
-)ENUMLIST
--\n
-L1988
-)P
-)ITEM
-(ITEM
-L1989
-(P
--The new package's files are unpacked, overwriting any that may be on\nthe system already, for example any from the old version of the same\npackage or from another package (backups of the old files are left\naround, and if anything goes wrong dpkg will attempt to put them back\nas part of the error unwind).
-L1994
-)P
-(P
-L1995
--\nIt is an error for a package to contains files which are on the system\nin another package, unless
-(TT
--Replaces
-)TT
-- is used (see\n
-AID CDATA replaces
-ALEVEL CDATA SECT
-ASRID CDATA s-replaces
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .5
-AHNAME CDATA section 8.5
-(REF
-L2626 programmer.sgml
-(TT
--Replaces
-)TT
-- - overwriting files and replacing packages
-L2627
-)REF
--). Currently the
-(TT
----force-overwrite
-)TT
-- flag is\nenabled, downgrading it to a warning, but this may not always be the\ncase.
-L2001
-)P
-(P
-L2002
--\nPackages which overwrite each other's files produce behaviour which\nthough deterministic is hard for the system administrator to\nunderstand. It can easily lead to `missing' programs if, for example,\na package is installed which overwrites a file from another package,\nand is then removed again.
-(FOOTNOTE
-(P
--Part of the problem is due to what\nis arguably a bug in
-(PRGN
--dpkg
-)PRGN
--.
-)P
-)FOOTNOTE
--\n
-L2010
-)P
-)ITEM
-(ITEM
-L2012
-(P
-ACOMPACT IMPLIED
-(ENUMLIST
-L2013
-(ITEM
-L2014
-(P
--If the package is being upgraded, call\n
-(EXAMPLE
-L2016
-(VAR
--old-postrm
-)VAR
-- upgrade
-(VAR
--new-version
-)VAR
-L2017
-)EXAMPLE
--\n
-L2019
-)P
-)ITEM
-(ITEM
-L2020
-(P
--If this fails,
-(PRGN
--dpkg
-)PRGN
-- will attempt:\n
-(EXAMPLE
-L2022
-(VAR
--new-postrm
-)VAR
-- failed-upgrade
-(VAR
--old-version
-)VAR
-L2023
-)EXAMPLE
--\nError unwind, for both cases:\n
-(EXAMPLE
-L2026
-(VAR
--old-preinst
-)VAR
-- abort-upgrade
-(VAR
--new-version
-)VAR
-L2027
-)EXAMPLE
--\n
-L2029
-)P
-)ITEM
-)ENUMLIST
--\n\nThis is the point of no return - if
-(PRGN
--dpkg
-)PRGN
-- gets this far, it won't\nback off past this point if an error occurs. This will leave the\npackage in a fairly bad state, which will require a successful\nreinstallation to clear up, but it's when
-(PRGN
--dpkg
-)PRGN
-- starts doing\nthings that are irreversible.\n
-L2037
-)P
-)ITEM
-(ITEM
-L2038
-(P
--Any files which were in the old version of the package but not in the\nnew are removed.\n
-L2041
-)P
-)ITEM
-(ITEM
-L2042
-(P
--The new file list replaces the old.\n
-L2044
-)P
-)ITEM
-(ITEM
-L2045
-(P
--The new maintainer scripts replace the old.\n
-L2047
-)P
-)ITEM
-(ITEM
-L2048
-(P
--Any packages all of whose files have been overwritten during the\ninstallation, and which aren't required for dependencies, are considered\nto have been removed. For each such package,\n\n
-ACOMPACT IMPLIED
-(ENUMLIST
-L2053
-(ITEM
-L2054
-(P
-(PRGN
--dpkg
-)PRGN
-- calls:\n
-(EXAMPLE
-L2056
-(VAR
--disappearer's-postrm
-)VAR
-- disappear \\\n
-(VAR
--overwriter
-)VAR
--
-(VAR
--overwriter-version
-)VAR
-L2058
-)EXAMPLE
--\n
-L2060
-)P
-)ITEM
-(ITEM
-L2061
-(P
--The package's maintainer scripts are removed.\n
-L2063
-)P
-)ITEM
-(ITEM
-L2064
-(P
--It is noted in the status database as being in a sane state, namely\nnot installed (any conffiles it may have are ignored, rather than\nbeing removed by
-(PRGN
--dpkg
-)PRGN
--). Note that disappearing packages do not\nhave their prerm called, because
-(PRGN
--dpkg
-)PRGN
-- doesn't know in advance\nthat the package is going to vanish.\n
-L2070
-)P
-)ITEM
-)ENUMLIST
--\n
-L2072
-)P
-)ITEM
-(ITEM
-L2073
-(P
--Any files in the package we're unpacking that are also listed in the\nfile lists of other packages are removed from those lists. (This will\nlobotomise the file list of the `conflicting' package if there is one.)\n
-L2077
-)P
-)ITEM
-(ITEM
-L2078
-(P
--The backup files made during installation, above, are deleted.\n
-L2080
-)P
-)ITEM
-(ITEM
-L2081
-(P
--The new package's status is now sane, and recorded as `unpacked'. Here\nis another point of no return - if the conflicting package's removal\nfails we do not unwind the rest of the installation; the conflicting\npackage is left in a half-removed limbo.\n
-L2086
-)P
-)ITEM
-(ITEM
-L2087
-(P
--If there was a conflicting package we go and do the removal actions\n(described below), starting with the removal of the conflicting\npackage's files (any that are also in the package being installed\nhave already been removed from the conflicting package's file list,\nand so do not get removed now).\n
-L2093
-)P
-)ITEM
-)ENUMLIST
--\n
-L2095
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s6.4
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .4
-AHNAME CDATA section 6.4
-(SECT
-(HEADING
--Details of configuration
-L2096
-)HEADING
-(P
-L2097
--\nWhen we configure a package (this happens with
-(TT
--dpkg --install
-)TT
--, or\nwith
-(TT
----configure
-)TT
--), we first update the conffiles and then call:\n
-(EXAMPLE
-L2101
-(VAR
--postinst
-)VAR
-- configure
-(VAR
--most-recently-configured-version
-)VAR
-L2102
-)EXAMPLE
-L2103
-)P
-(P
-L2104
--\nNo attempt is made to unwind after errors during configuration.
-L2106
-)P
-(P
-L2107
--\nIf there is no most recently configured version
-(PRGN
--dpkg
-)PRGN
-- will pass a\nnull argument; older versions of dpkg may pass\n
-(TT
--\|<\|unknown\|>\|
-)TT
-- (including the angle brackets) in this case.\nEven older ones do not pass a second argument at all, under any\ncircumstances.\n
-L2114
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s6.5
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .5
-AHNAME CDATA section 6.5
-(SECT
-(HEADING
--Details of removal and/or configuration purging
-L2115
-)HEADING
-(P
-L2116
--\n
-ACOMPACT IMPLIED
-(ENUMLIST
-L2118
-(ITEM
-L2119
-(P
-(EXAMPLE
-L2120
-(VAR
--prerm
-)VAR
-- remove
-L2121
-)EXAMPLE
--\n
-L2123
-)P
-)ITEM
-(ITEM
-L2124
-(P
--The package's files are removed (except conffiles).\n
-L2126
-)P
-)ITEM
-(ITEM
-L2127
-(P
-(EXAMPLE
-L2128
-(VAR
--postrm
-)VAR
-- remove
-L2129
-)EXAMPLE
--\n
-L2131
-)P
-)ITEM
-(ITEM
-L2132
-(P
--All the maintainer scripts except the postrm are removed.
-L2133
-)P
-(P
-L2134
--\nIf we aren't purging the package we stop here. Note that packages\nwhich have no postrm and no conffiles are automatically purged when\nremoved, as there is no difference except for the
-(PRGN
--dpkg
-)PRGN
-- status.\n
-L2139
-)P
-)ITEM
-(ITEM
-L2140
-(P
--The conffiles and any backup files (
-(TT
--~
-)TT
---files,
-(TT
--#*#
-)TT
-- files,\n
-(TT
--%
-)TT
---files,
-(TT
--.dpkg-{old,new,tmp}
-)TT
--, etc.) are removed.\n
-L2143
-)P
-)ITEM
-(ITEM
-L2144
-(P
-(EXAMPLE
-L2145
-(VAR
--postrm
-)VAR
-- purge
-L2146
-)EXAMPLE
--\n
-L2148
-)P
-)ITEM
-(ITEM
-L2149
-(P
--The package's file list is removed.\n
-L2151
-)P
-)ITEM
-)ENUMLIST
--\n\nNo attempt is made to unwind after errors during removal.\n\n
-L2156
-)P
-)SECT
-)CHAPT
-AID CDATA descriptions
-ASRID CDATA ch-descriptions
-ACHAPT CDATA 7
-ASECT IMPLIED
-AHNAME CDATA chapter 7
-(CHAPT
-(HEADING
--Descriptions of packages - the\n
-(TT
--Description
-)TT
-- field
-L2158
-)HEADING
-(P
-L2159
--\nThe
-(TT
--Description
-)TT
-- control file field is used by
-(PRGN
--dselect
-)PRGN
-- when\nthe user is selecting which packages to install and by
-(PRGN
--dpkg
-)PRGN
--\nwhen it displays information about the status of packages and so\nforth. It is included on the FTP site in the
-(PRGN
--Packages
-)PRGN
-- files,\nand may also be used by the Debian WWW pages.
-L2165
-)P
-(P
-L2166
--\nThe description is intended to describe the program to a user who has\nnever met it before so that they know whether they want to install it.\nIt should also give information about the significant dependencies and\nconflicts between this package and others, so that the user knows why\nthese dependencies and conflicts have been declared.
-L2172
-)P
-(P
-L2173
--\nThe field's format is as follows:\n
-(EXAMPLE
-L2176
--Description:
-(VAR
--single line synopsis
-)VAR
--\n
-(VAR
--extended description over several lines
-)VAR
-L2178
-)EXAMPLE
-L2179
-)P
-(P
-L2180
--\nThe synopsis is often printed in lists of packages and so forth, and\nshould be as informative as possible. Every package should also have\nan extended description.
-L2184
-)P
-(P
-L2186
-)P
-AID IMPLIED
-ASRID CDATA s7.1
-ACHAPT CDATA 7
-ACSRID CDATA ch-descriptions
-ASECT CDATA .1
-AHNAME CDATA section 7.1
-(SECT
-(HEADING
--Types of formatting line in the extended description
-L2187
-)HEADING
-(P
-L2188
--\n
-ACOMPACT IMPLIED
-(LIST
-L2190
-(ITEM
-L2191
-(P
--Those starting with a single space are part of a paragraph.\nSuccessive lines of this form will be word-wrapped when displayed.\nThe leading space will usually be stripped off.\n
-L2195
-)P
-)ITEM
-(ITEM
-L2196
-(P
--Those starting with two or more spaces. These will be displayed\nverbatim. If the display cannot be panned horizontally the\ndisplaying program will linewrap them `hard' (ie, without taking\naccount of word breaks). If it can they will be allowed to trail\noff to the right. None, one or two initial spaces may be deleted,\nbut the number of spaces deleted from each line will be the same\n(so that you can have indenting work correctly, for example).\n
-L2204
-)P
-)ITEM
-(ITEM
-L2205
-(P
--Those containing a single space followed by a single full stop\ncharacter. These are rendered as blank lines. This is the
-(EM
--only
-)EM
--\nway to get a blank line - see below.\n
-L2209
-)P
-)ITEM
-(ITEM
-L2210
-(P
--Those containing a space, a full stop and some more characters. These\nare for future expansion. Do not use them.
-L2212
-)P
-)ITEM
-)LIST
--\n
-L2214
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s7.2
-ACHAPT CDATA 7
-ACSRID CDATA ch-descriptions
-ASECT CDATA .2
-AHNAME CDATA section 7.2
-(SECT
-(HEADING
--Notes about writing descriptions
-L2215
-)HEADING
-(P
-L2216
--\n
-(EM
--Always
-)EM
-- start extended description lines with at least one\nwhitespace character. Fields in the control file and in the Packages\nfile are separated by field names starting in the first column, just\nas message header fields are in RFC822. Forgetting the whitespace\nwill cause
-(PRGN
--dpkg-deb
-)PRGN
-(FOOTNOTE
-(P
--Version 0.93.23 or\nlater.
-)P
-)FOOTNOTE
-- to produce a syntax error when trying to build the\npackage. If you force it to build anyway
-(PRGN
--dpkg
-)PRGN
-- will refuse to\ninstall the resulting mess.
-L2225
-)P
-(P
-L2226
--\n
-(EM
--Do not
-)EM
-- include any completely
-(EM
--empty
-)EM
-- lines. These separate\ndifferent records in the Packages file and different packages in the\n
-(TT
--debian/control
-)TT
-- file, and are forbidden in package control\nfiles. See the previous paragraph for what happens if you get this\nwrong.
-L2232
-)P
-(P
-L2233
--\nThe single line synopsis should be kept brief - certainly under 80\ncharacters.
-(PRGN
--dselect
-)PRGN
-- displays between 25 and 49 characters\nwithout panning if you're using an 80-column terminal, depending on\nwhat display options are in effect.
-L2238
-)P
-(P
-L2239
--\nDo not include the package name in the synopsis line. The display\nsoftware knows how to display this already, and you do not need to\nstate it. Remember that in many situations the user may only see\nthe synopsis line - make it as informative as you can.
-L2244
-)P
-(P
-L2245
--\nThe extended description should describe what the package does and\nhow it relates to the rest of the system (in terms of, for\nexample, which subsystem it is which part of).
-L2249
-)P
-(P
-L2250
--\nThe blurb that comes with a program in its announcements and/or\n
-(PRGN
--README
-)PRGN
-- files is rarely suitable for use in a description. It\nis usually aimed at people who are already in the community where the\npackage is used. The description field needs to make sense to anyone,\neven people who have no idea about any of the\nthings the package deals with.
-L2257
-)P
-(P
-L2258
--\nPut important information first, both in the synopis and extended\ndescription. Sometimes only the first part of the synopsis or of\nthe description will be displayed. You can assume that there will\nusually be a way to see the whole extended description.
-L2263
-)P
-(P
-L2264
--\nYou may include information about dependencies and so forth in the\nextended description, if you wish.
-L2267
-)P
-(P
-L2268
--\nDo not use tab characters. Their effect is not predictable.
-L2270
-)P
-(P
-L2271
--\nDo not try to linewrap the summary (the part on the same line as the\nfield name
-(TT
--Description
-)TT
--) into the extended description. This will\nnot work correctly when the full description is displayed, and makes\nno sense where only the summary is available.\n
-L2277
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s7.3
-ACHAPT CDATA 7
-ACSRID CDATA ch-descriptions
-ASECT CDATA .3
-AHNAME CDATA section 7.3
-(SECT
-(HEADING
--Example description in control file for Smail
-L2278
-)HEADING
-(P
-L2279
--\n
-(EXAMPLE
-L2281
--Package: smail\nVersion: 3.1.29.1-13\nMaintainer: Ian Jackson \|<\|iwj10@cus.cam.ac.uk\|>\|\nRecommends: pine | mailx | elm | emacs | mail-user-agent\nSuggests: metamail\nDepends: cron, libc5\nConflicts: sendmail\nProvides: mail-transport-agent\nDescription: Electronic mail transport system.\n Smail is the recommended mail transport agent (MTA) for Debian.\n .\n An MTA is the innards of the mail system - it takes messages from\n user-friendly mailer programs and arranges for them to be delivered\n locally or passed on to other systems as required.\n .\n In order to make use of it you must have one or more user level\n mailreader programs such as elm, pine, mailx or Emacs (which has Rmail\n and VM as mailreaders) installed. If you wish to send messages other\n than just to other users of your system you must also have appropriate\n and VM as mailreaders) installed. If you wish to send messages other\n than just to other users of your system you must also have appropriate\n networking support, in the form of IP or UUCP.
-L2303
-)EXAMPLE
--\n
-L2305
-)P
-)SECT
-)CHAPT
-AID CDATA relationships
-ASRID CDATA ch-relationships
-ACHAPT CDATA 8
-ASECT IMPLIED
-AHNAME CDATA chapter 8
-(CHAPT
-(HEADING
--Declaring relationships between packages
-L2306
-)HEADING
-(P
-L2307
--\nPackages can declare in their control file that they have certain\nrelationships to other packages - for example, that they may not be\ninstalled at the same time as certain other packages, and/or that they\ndepend on the presence of others, or that they should overwrite files\nin certain other packages if present.
-L2313
-)P
-(P
-L2314
--\nThis is done using the
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
--,\n
-(TT
--Conflicts
-)TT
--,
-(TT
--Provides
-)TT
-- and
-(TT
--Replaces
-)TT
-- control file fields.
-L2317
-)P
-(P
-L2319
-)P
-AID CDATA depsyntax
-ASRID CDATA s-depsyntax
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .1
-AHNAME CDATA section 8.1
-(SECT
-(HEADING
--Syntax of relationship fields
-L2320
-)HEADING
-(P
-L2321
--\nThese fields all have a uniform syntax. They are a list of package\nnames separated by commas.
-L2324
-)P
-(P
-L2325
--\nIn
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
-- and
-(TT
--Pre-Depends
-)TT
--\n(the fields which declare dependencies of the package in which they\noccur on other packages) these package names may also be lists of\nalternative package names, separated by vertical bar symbols
-(TT
--|
-)TT
--\n(pipe symbols).
-L2331
-)P
-(P
-L2332
--\nAll the fields except
-(TT
--Provides
-)TT
-- may restrict their applicability\nto particular versions of each named package. This is done in\nparentheses after each individual package name; the parentheses should\ncontain a relation from the list below followed by a version number,\nin the format described in
-AID CDATA versions
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-versions
-ACHAPT CDATA 5
-ASECT IMPLIED
-AHNAME CDATA chapter 5
-(REF
-L1664 programmer.sgml
--Version numbering
-L1665
-)REF
--.
-L2338
-)P
-(P
-L2339
--\nThe relations allowed are\n
-(TT
--\|<\|\|<\|
-)TT
--,\n
-(TT
--\|<\|=
-)TT
--,\n
-(TT
--=
-)TT
--,\n
-(TT
--\|>\|=
-)TT
-- and\n
-(TT
--\|>\|\|>\|
-)TT
--\nfor strictly earlier, earlier or equal, exactly equal, later or equal\nand strictly later, respectively. The forms
-(TT
--\|<\|
-)TT
-- and
-(TT
--\|>\|
-)TT
--\nwere used to mean earlier/later or equal, rather than strictly\nearlier/later, so they should not appear in new packages (though\n
-(PRGN
--dpkg
-)PRGN
-- still supports them).
-L2351
-)P
-(P
-L2352
--\nWhitespace may appear at any point in the version specification, and\nmust appear where it's necessary to disambiguate; it is not otherwise\nsignificant. For consistency and in case of future changes to\n
-(PRGN
--dpkg
-)PRGN
-- it is recommended that a single space be used after a\nversion relationship and before a version number; it is usual also to\nput a single space after each comma, on either side of each vertical\nbar, and before each open parenthesis.
-L2360
-)P
-(P
-L2361
--\nFor example:\n
-(EXAMPLE
-L2364
--Package: metamail\nVersion: 2.7-3\nDepends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
-L2367
-)EXAMPLE
--\n
-L2369
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s8.2
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .2
-AHNAME CDATA section 8.2
-(SECT
-(HEADING
--Dependencies -
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
--,
-(TT
--Pre-Depends
-)TT
-L2370
-)HEADING
-(P
-L2371
--\nThese four fields are used to declare a dependency by one package on\nanother. They appear in the depending package's control file.
-L2374
-)P
-(P
-L2375
--\nAll but
-(TT
--Pre-Depends
-)TT
-- (discussed below) take effect
-(EM
--only
-)EM
-- when\na package is to be configured. They do not prevent a package being on\nthe system in an unconfigured state while its dependencies are\nunsatisfied, and it is possible to replace a package whose\ndependencies are satisfied and which is properly installed with a\ndifferent version whose dependencies are not and cannot be satisfied;\nwhen this is done the depending package will be left unconfigured\n(since attempts to configure it will give errors) and will not\nfunction properly.
-L2385
-)P
-(P
-L2386
--\nFor this reason packages in an installation run are usually all\nunpacked first and all configured later; this gives later versions of\npackages with dependencies on later versions of other packages the\nopportunity to have their dependencies satisfied.
-L2391
-)P
-(P
-L2392
--\nThus
-(TT
--Depends
-)TT
-- allows package maintainers to impose an order in\nwhich packages should be configured.\n\n
-ACOMPACT IMPLIED
-(TAGLIST
-L2397
-(TAG
-(TT
--Depends
-)TT
-L2398
-)TAG
-(ITEM
-L2400
-(P
--This declares an absolute dependency.
-L2401
-)P
-(P
-L2402
--\n
-(PRGN
--dpkg
-)PRGN
-- will not configure\npackages whose dependencies aren't satisfied. If it is asked to make\nan installation which would cause an installed package's dependencies\nto become unsatisfied it will complain
-(FOOTNOTE
-(P
--Current versions\n(1.2.4) of
-(PRGN
--dpkg
-)PRGN
-- have a bug in this area which will cause some of\nthese problems to be ignored.
-)P
-)FOOTNOTE
--, unless\n
-(TT
----auto-deconfigure
-)TT
-- is specified, in which case those packages\nwill be deconfigured before the installation proceeds.
-L2411
-)P
-(P
-L2412
--\n
-(PRGN
--dselect
-)PRGN
-- makes it hard for the user to select packages for\ninstallation, removal or upgrade in a way that would mean that\npackages'
-(PRGN
--Depends
-)PRGN
-- fields would be unsatisfied. The user can\noverride this if they wish, for example if they know that
-(PRGN
--dselect
-)PRGN
--\nhas an out-of-date view of the real package relationships.
-L2418
-)P
-(P
-L2419
--\nThe
-(TT
--Depends
-)TT
-- field should be used if the depended-on package is\nrequired for the depending package to provide a significant amount of\nfunctionality.\n
-L2424
-)P
-)ITEM
-(TAG
-(TT
--Recommends
-)TT
-L2425
-)TAG
-(ITEM
-L2426
-(P
--This declares a strong, but not absolute, dependency.
-L2427
-)P
-(P
-L2428
--\n
-(TT
--Recommends
-)TT
-- is ignored by
-(PRGN
--dpkg
-)PRGN
--, so that users using the\ncommand-line (who are presumed to know what they're doing) will not be\nimpeded.
-L2432
-)P
-(P
-L2433
--\nIt is treated by
-(PRGN
--dselect
-)PRGN
-- exactly as
-(TT
--Depends
-)TT
-- is; this makes\nit hard for the user to select things so as to leave
-(TT
--Recommends
-)TT
--\nfields unsatisfied, but they are able to do so by being persistent.
-L2437
-)P
-(P
-L2438
--\nThe
-(TT
--Recommends
-)TT
-- field should list packages that would be found\ntogether with this one in all but unusual installations.\n
-L2442
-)P
-)ITEM
-(TAG
-(TT
--Suggests
-)TT
-L2443
-)TAG
-(ITEM
-L2445
-(P
--This is used to declare that one package may be more useful with one\nor more others. Using this field tells the packaging system and the\nuser that the listed packages are be related to this one and can\nperhaps enhance its usefulness, but that installing this one without\nthem is perfectly reasonable.
-L2450
-)P
-(P
-L2451
--\n
-(PRGN
--dselect
-)PRGN
-- will offer suggsted packages to the system administrator\nwhen they select the suggesting package, but the default is not to\ninstall the suggested package.\n
-L2456
-)P
-)ITEM
-(TAG
-(TT
--Pre-Depends
-)TT
-L2457
-)TAG
-(ITEM
-L2459
-(P
--This field is like
-(TT
--Depends
-)TT
--, except that it also forces
-(PRGN
--dpkg
-)PRGN
--\nto complete installation of the packages named before even starting\nthe installation of the package which declares the predependency.
-L2462
-)P
-(P
-L2463
--\n
-(PRGN
--dselect
-)PRGN
-- checks for predependencies when it is doing an\ninstallation run, and will attempt to find the packages which are\nrequired to be installed first and do so in the right order.
-L2467
-)P
-(P
-L2468
--\nHowever, this process is slow (because it requires repeated\ninvocations of
-(PRGN
--dpkg
-)PRGN
--) and troublesome (because it requires\nguessing where to find the appropriate files).
-L2472
-)P
-(P
-L2473
--\nFor these reasons, and because this field imposes restrictions on the\norder in which packages may be unpacked (which can be difficult for\ninstallations from multipart media, for example),
-(TT
--Pre-Depends
-)TT
--\nshould be used sparingly, preferably only by packages whose premature\nupgrade or installation would hamper the ability of the system to\ncontinue with any upgrade that might be in progress.
-L2480
-)P
-(P
-L2481
--\nWhen the package declaring it is being configured, a\n
-(TT
--Pre-Dependency
-)TT
-- will be considered satisfied only if the depending\npackage has been correctly configured, just as if an ordinary\n
-(TT
--Depends
-)TT
-- had been used.
-L2486
-)P
-(P
-L2487
--\nHowever, when a package declaring a predependency is being unpacked\nthe predependency can be satisfied even if the depended-on package(s)\nare only unpacked or half-configured, provided that they have been\nconfigured correctly at some point in the past (and not removed or\npartially removed since). In this case both the previously-configured\nand currently unpacked or half-configured versions must satisfy any\nversion clause in the
-(TT
--Pre-Depends
-)TT
-- field.\n
-L2496
-)P
-)ITEM
-)TAGLIST
--\n
-L2498
-)P
-AID IMPLIED
-ASRID CDATA s8.2.1
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .2.1
-AHNAME CDATA subsection 8.2.1
-(SECT1
-(HEADING
--Dependencies on shared libraries
-L2499
-)HEADING
-(P
-L2500
--\nThe dependency fields listed above are used by packages which need\nshared libraries to declare dependencies on the appropriate packages.
-L2503
-)P
-(P
-L2504
--\nThese dependencies are usually determined automatically using\n
-(PRGN
--dpkg-shlibdeps
-)PRGN
-- and inserted in the package control file using\nthe control file substitution variables mechanism; see
-AID CDATA srcsubstvars
-ALEVEL CDATA SECT1
-ASRID CDATA s-srcsubstvars
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .2.4
-AHNAME CDATA subsection 3.2.4
-(REF
-L983 programmer.sgml
-(TT
--debian/substvars
-)TT
-- and variable substitutions
-L984
-)REF
-L2508
-- and
-AID CDATA sourcetools
-ALEVEL CDATA SECT
-ASRID CDATA s-sourcetools
-ACHAPT CDATA 3
-ACSRID CDATA ch-sourcepkg
-ASECT CDATA .1
-AHNAME CDATA section 3.1
-(REF
-L363 programmer.sgml
--Tools for processing source packages
-L364
-)REF
--.\n
-L2510
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s8.2.2
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .2.2
-AHNAME CDATA subsection 8.2.2
-(SECT1
-(HEADING
--Deconfiguration due to removal during bulk installations
-L2511
-)HEADING
-(P
-L2512
--\nIf
-(PRGN
--dpkg
-)PRGN
-- would like to remove a package due to a conflict, as\ndescribed above, but this would violate a dependency of some other\npackage on the system,
-(PRGN
--dpkg
-)PRGN
-- will usually not remove the\nconflicting package and halt with an error.
-L2517
-)P
-(P
-L2518
--\nHowever, if the
-(TT
----auto-deconfigure
-)TT
-- (
-(TT
---B
-)TT
--) option is used\n
-(PRGN
--dpkg
-)PRGN
-- will automatically `deconfigure' the package with the\nproblematic dependency, so that the conflicting package can be removed\nand the package we're trying to install can be installed. If\n
-(PRGN
--dpkg
-)PRGN
-- is being asked to install packages (rather than just\nunpacking them) it will try to reconfigure the package when it has\nunpacked all its arguments, in the hope that one of the other packages\nit is installing will satisfy the problematic dependency.
-L2527
-)P
-(P
-L2528
--\n
-(PRGN
--dselect
-)PRGN
-- supplies this argument to
-(PRGN
--dpkg
-)PRGN
-- when it invokes it,\nso that bulk installations proceed smoothly.\n
-L2532
-)P
-)SECT1
-)SECT
-AID CDATA conflicts
-ASRID CDATA s-conflicts
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .3
-AHNAME CDATA section 8.3
-(SECT
-(HEADING
--Alternative packages -
-(TT
--Conflicts
-)TT
-- and
-(TT
--Replaces
-)TT
-L2533
-)HEADING
-(P
-L2534
--\nWhen one package declares a conflict with another
-(PRGN
--dpkg
-)PRGN
-- will\nrefuse to allow them to be installed on the system at the same time.
-L2537
-)P
-(P
-L2538
--\nIf one package is to be installed, the other must be removed first -\nif the package being installed is marked as replacing (
-AID CDATA replaces
-ALEVEL CDATA SECT
-ASRID CDATA s-replaces
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .5
-AHNAME CDATA section 8.5
-(REF
-L2626 programmer.sgml
-(TT
--Replaces
-)TT
-- - overwriting files and replacing packages
-L2627
-)REF
-L2541
--) the one on the system, or the one on the system is\nmarked as deselected, or both packages are marked
-(TT
--Essential
-)TT
--, then\n
-(PRGN
--dpkg
-)PRGN
-- will automatically remove the package which is causing the\nconflict, otherwise it will halt the installation of the new package\nwith an error.
-L2546
-)P
-(P
-L2547
--\n
-(PRGN
--dselect
-)PRGN
-- makes it hard to select conflicting packages, though the\nuser can override this if they wish. If they do not override it then\n
-(PRGN
--dselect
-)PRGN
-- will select one of the packages for removal, and the user\nmust make sure it is the right one. In the future
-(PRGN
--dselect
-)PRGN
-- will\nlook for the presence of a
-(TT
--Replaces
-)TT
-- field to help decide which\npackage should be installed and which removed.
-L2554
-)P
-(P
-L2555
--\nA package will not cause a conflict merely because its configuration\nfiles are still installed; it must be at least half-installed.
-L2558
-)P
-(P
-L2559
--\nA special exception is made for packages which declare a conflict with\ntheir own package name, or with a virtual package which they provide\n(see below): this does not prevent their installation, and allows a\npackage to conflict with others providing a replacement for it. You\nuse this feature when you want the package in question to be the only\npackage providing something.
-L2566
-)P
-(P
-L2567
--\nA
-(TT
--Conflicts
-)TT
-- entry should almost never have an `earlier than'\nversion clause. This would prevent
-(PRGN
--dpkg
-)PRGN
-- from upgrading or\ninstalling the package which declared such a conflict until the\nupgrade or removal of the conflicted-with package had been completed.\nThis aspect of installation ordering is not handled by
-(PRGN
--dselect
-)PRGN
--,\nso that the use
-(TT
--Conflicts
-)TT
-- in this way is likely to cause problems\nfor `bulk run' upgrades and installations.
-L2575
-)P
-(P
-L2576
--\n
-L2578
-)P
-)SECT
-AID CDATA virtual
-ASRID CDATA s-virtual
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .4
-AHNAME CDATA section 8.4
-(SECT
-(HEADING
--Virtual packages -
-(TT
--Provides
-)TT
-L2579
-)HEADING
-(P
-L2580
--\nAs well as the names of actual (`concrete') packages, the package\nrelationship fields
-(TT
--Depends
-)TT
--,
-(TT
--Recommends
-)TT
--,
-(TT
--Suggests
-)TT
-- and\n
-(TT
--Conflicts
-)TT
-- may mention virtual packages.
-L2584
-)P
-(P
-L2585
--\nA virtual package is one which appears in the
-(TT
--Provides
-)TT
-- control\nfile field of another package. The effect is as if the package(s)\nwhich provide a particular virtual package name had been listed by\nname everywhere were the virtual package name appears.
-L2590
-)P
-(P
-L2591
--\nIf there are both a real and a virtual package of the same name then\nthe dependency may be satisfied (or the conflict caused) by either the\nreal package or any of the virtual packages which provide it. This is\nso that, for example, supposing we have\n
-(EXAMPLE
-L2597
--Package: vm\nDepends: emacs
-L2599
-)EXAMPLE
--\nand someone else releases an xemacs package they can say\n
-(EXAMPLE
-L2602
--Package: xemacs\nProvides: emacs
-L2604
-)EXAMPLE
--\nand all will work in the interim (until a purely virtual package name\nis decided on and the
-(TT
--emacs
-)TT
-- and
-(TT
--vm
-)TT
-- packages are changed to\nuse it).
-L2608
-)P
-(P
-L2609
--\nIf a dependency or a conflict has a version number attached then only\nreal packages will be considered to see whether the relationship is\nsatisfied (or the prohibition violated, for a conflict) - it is\nassumed that a real package which provides virtual package is not of\nthe `right' version. So, a
-(TT
--Provides
-)TT
-- field may not contain\nversion numbers, and the version number of the concrete package which\nprovides a particular virtual package will not be looked at when\nconsidering a dependency on or conflict with the virtual package name.
-L2618
-)P
-(P
-L2619
--\nIf you want to specify which of a set of real packages should be the\ndefault to satisfy a particular dependency on a virtual package, you\nshould list the real package as alternative before the virtual.
-L2623
-)P
-(P
-L2624
--\n
-L2626
-)P
-)SECT
-AID CDATA replaces
-ASRID CDATA s-replaces
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .5
-AHNAME CDATA section 8.5
-(SECT
-(HEADING
-(TT
--Replaces
-)TT
-- - overwriting files and replacing packages
-L2627
-)HEADING
-(P
-L2628
--\nThe
-(TT
--Replaces
-)TT
-- control file field has two purposes, which come into\nplay in different situations.
-L2631
-)P
-(P
-L2632
--\nVirtual packages (
-AID CDATA virtual
-ALEVEL CDATA SECT
-ASRID CDATA s-virtual
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .4
-AHNAME CDATA section 8.4
-(REF
-L2578 programmer.sgml
--Virtual packages -
-(TT
--Provides
-)TT
-L2579
-)REF
--) are not considered when looking\nat a
-(TT
--Replaces
-)TT
-- field - the packages declared as being replaced\nmust be mentioned by their real names.\n
-L2637
-)P
-AID IMPLIED
-ASRID CDATA s8.5.1
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .5.1
-AHNAME CDATA subsection 8.5.1
-(SECT1
-(HEADING
--Overwriting files in other packages
-L2638
-)HEADING
-(P
-L2639
--\nFirstly, as mentioned before, it is usually an error for a package to\ncontains files which are on the system in another package, though\ncurrently the
-(TT
----force-overwrite
-)TT
-- flag is enabled by default,\ndowngrading the error to a warning,
-L2644
-)P
-(P
-L2645
--\nIf the overwriting package declares that it replaces the one\ncontaining the file being overwritten then
-(PRGN
--dpkg
-)PRGN
-- will proceed, and\nreplace the file from the old package with that from the new. The\nfile will no longer be listed as `owned' by the old package.
-L2650
-)P
-(P
-L2651
--\nIf a package is completely replaced in this way, so that
-(PRGN
--dpkg
-)PRGN
--\ndoes not know of any files it still contains, it is considered to have\ndisappeared. It will be marked as not wanted on the system (selected\nfor removal) and not installed. Any conffiles details noted in the\npackage will be ignored, as they will have been taken over by the\nreplacing package(s). The package's
-(PRGN
--postrm
-)PRGN
-- script will be run to\nallow the package to do any final cleanup required.\nSee
-AID CDATA mscriptsinstact
-ALEVEL CDATA SECT
-ASRID CDATA s-mscriptsinstact
-ACHAPT CDATA 6
-ACSRID CDATA ch-maintainerscripts
-ASECT CDATA .2
-AHNAME CDATA section 6.2
-(REF
-L1844 programmer.sgml
--Summary of ways maintainer scripts are called
-L1845
-)REF
--.
-L2660
-)P
-(P
-L2661
--\nIn the future
-(PRGN
--dpkg
-)PRGN
-- will discard files which overwrite those from\nanother package which declares that it replaces the one being\ninstalled (so that you can install an older version of a package\nwithout problems).
-L2666
-)P
-(P
-L2667
--\nThis usage of
-(TT
--Replaces
-)TT
-- only takes effect when both packages are\nat least partially on the system at once, so that it can only happen\nif they do not conflict or if the conflict has been overridden.\n
-L2672
-)P
-)SECT1
-AID IMPLIED
-ASRID CDATA s8.5.2
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .5.2
-AHNAME CDATA subsection 8.5.2
-(SECT1
-(HEADING
--Replacing whole packages, forcing their removal
-L2673
-)HEADING
-(P
-L2674
--\nSecondly,
-(TT
--Replaces
-)TT
-- allows
-(PRGN
--dpkg
-)PRGN
-- and
-(PRGN
--dselect
-)PRGN
-- to resolve\nwhich package should be removed when a conflict - see\n
-AID CDATA conflicts
-ALEVEL CDATA SECT
-ASRID CDATA s-conflicts
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .3
-AHNAME CDATA section 8.3
-(REF
-L2532 programmer.sgml
--Alternative packages -
-(TT
--Conflicts
-)TT
-- and
-(TT
--Replaces
-)TT
-L2533
-)REF
--. This usage only takes effect when the two\npackages
-(EM
--do
-)EM
-- conflict, so that the two effects do not interfere\nwith each other.
-L2680
-)P
-(P
-L2682
-)P
-)SECT1
-)SECT
-AID IMPLIED
-ASRID CDATA s8.6
-ACHAPT CDATA 8
-ACSRID CDATA ch-relationships
-ASECT CDATA .6
-AHNAME CDATA section 8.6
-(SECT
-(HEADING
--Defaults for satisfying dependencies - ordering
-L2683
-)HEADING
-(P
-L2684
--\nOrdering is significant in dependency fields.
-L2686
-)P
-(P
-L2687
--\nUsually dselect will suggest to the user that they select the package\nwith the most `fundamental' class (eg, it will prefer Base packages to\nOptional ones), or the one that they `most wanted' to select in some\nsense.
-L2692
-)P
-(P
-L2693
--\nIn the absence of other information
-(PRGN
--dselect
-)PRGN
-- will offer a\ndefault selection of the first named package in a list of\nalternatives.
-L2697
-)P
-(P
-L2698
--\nHowever, there is no way to specify the `order' of several packages\nwhich all provide the same thing, when that thing is listed as a\ndependency.
-L2702
-)P
-(P
-L2703
--\nTherefore a dependency on a virtual package should contain a concrete\npackage name as the first alternative, so that this is the default.
-L2706
-)P
-(P
-L2707
--\nFor example, consider the set of packages:\n\n
-(EXAMPLE
-L2711
--Package: glibcdoc\nRecommends: info-browser\n\nPackage: info\nProvides: info-browser\n\nPackage: emacs\nProvides: info-browser
-L2719
-)EXAMPLE
-L2720
-)P
-(P
-L2721
--\nIf
-(PRGN
--emacs
-)PRGN
-- and
-(PRGN
--info
-)PRGN
-- both have the same priority then\n
-(PRGN
--dselect
-)PRGN
--'s choice is essentially random. Better would be\n
-(EXAMPLE
-L2725
--Package: glibcdoc\nRecommends: info | info-browser
-L2727
-)EXAMPLE
--\nso that
-(PRGN
--dselect
-)PRGN
-- defaults to selecting the lightweight standalone\ninfo browser.\n\n\n
-L2733
-)P
-)SECT
-)CHAPT
-AID CDATA conffiles
-ASRID CDATA ch-conffiles
-ACHAPT CDATA 9
-ASECT IMPLIED
-AHNAME CDATA chapter 9
-(CHAPT
-(HEADING
--Configuration file handling
-L2734
-)HEADING
-(P
-L2735
--\n
-(PRGN
--dpkg
-)PRGN
-- can do a certain amount of automatic handling of package\nconfiguration files.
-L2738
-)P
-(P
-L2739
--\nWhether this mechanism is appropriate depends on a number of factors,\nbut basically there are two approaches to any particular configuration\nfile.
-L2743
-)P
-(P
-L2744
--\nThe easy method is to ship a best-effort configuration in the package,\nand use
-(PRGN
--dpkg
-)PRGN
--'s conffile mechanism to handle updates. If the user\nis unlikely to want to edit the file, but you need them to be able to\nwithout losing their changes, and a new package with a changed version\nof the file is only released infrequently, this is a good approach.
-L2750
-)P
-(P
-L2751
--\nThe hard method is to build the configuration file from scratch in the\n
-(PRGN
--postinst
-)PRGN
-- script, and to take the responsibility for fixing any\nmistakes made in earlier versions of the package automatically. This\nwill be appropriate if the file is likely to need to be different on\neach system.\n
-L2758
-)P
-AID IMPLIED
-ASRID CDATA s9.1
-ACHAPT CDATA 9
-ACSRID CDATA ch-conffiles
-ASECT CDATA .1
-AHNAME CDATA section 9.1
-(SECT
-(HEADING
--Automatic handling of configuration files by
-(PRGN
--dpkg
-)PRGN
-L2759
-)HEADING
-(P
-L2760
--\nA package may contain a control area file called
-(TT
--conffiles
-)TT
--. This\nfile should be a list of filenames of configuration files needing\nautomatic handling, separated by newlines. The filenames should be\nabsolute pathnames, and the files referred to should actually exist in\nthe package.
-L2766
-)P
-(P
-L2767
--\nWhen a package is upgraded
-(PRGN
--dpkg
-)PRGN
-- will process the configuration\nfiles during the configuration stage, shortly before it runs the\npackage's
-(PRGN
--postinst
-)PRGN
-- script,
-L2771
-)P
-(P
-L2772
--\nFor each file it checks to see whether the version of the file\nincluded in the package is the same as the one that was included in\nthe last version of the package (the one that is being upgraded\nfrom); it also compares the version currently installed on the system\nwith the one shipped with the last version.
-L2778
-)P
-(P
-L2779
--\nIf neither the user nor the package maintainer has changed the file,\nit is left alone. If one or the other has changed their version, then\nthe changed version is preferred - ie, if the user edits their file,\nbut the package maintainer doesn't ship a different version, the\nuser's changes will stay, silently, but if the maintainer ships a new\nversion and the user hasn't edited it the new version will be\ninstalled (with an informative message). If both have changed their\nversion the user is prompted about the problem and must resolve the\ndifferences themselves.
-L2789
-)P
-(P
-L2790
--\nThe comparisons are done by calculating the MD5 message digests of the\nfiles, and storing the MD5 of the file as it was included in the most\nrecent version of the package.
-L2794
-)P
-(P
-L2795
--\nWhen a package is installed for the first time
-(PRGN
--dpkg
-)PRGN
-- will install\nthe file that comes with it, unless that would mean overwriting a file\nalready on the filesystem.
-L2799
-)P
-(P
-L2800
--\nHowever, note that
-(PRGN
--dpkg
-)PRGN
-- will
-(EM
--not
-)EM
-- replace a conffile that\nwas removed by the user (or by a script). This is necessary because\nwith some programs a missing file produces an effect hard or\nimpossible to achieve in another way, so that a missing file needs to\nbe kept that way if the user did it.
-L2806
-)P
-(P
-L2807
--\nNote that a package should
-(EM
--not
-)EM
-- modify a
-(PRGN
--dpkg
-)PRGN
---handled\nconffile in its maintainer scripts. Doing this will lead to\n
-(PRGN
--dpkg
-)PRGN
-- giving the user confusing and possibly dangerous options\nfor conffile update when the package is upgraded.\n
-L2813
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s9.2
-ACHAPT CDATA 9
-ACSRID CDATA ch-conffiles
-ASECT CDATA .2
-AHNAME CDATA section 9.2
-(SECT
-(HEADING
--Fully-featured maintainer script configuration handling
-L2814
-)HEADING
-(P
-L2815
--\nFor files which contain site-specific information such as the hostname\nand networking details and so forth, it is better to create the file\nin the package's
-(PRGN
--postinst
-)PRGN
-- script.
-L2819
-)P
-(P
-L2820
--\nThis will typically involve examining the state of the rest of the\nsystem to determine values and other information, and may involve\nprompting the user for some information which can't be obtained some\nother way.
-L2825
-)P
-(P
-L2826
--\nWhen using this method there are a couple of important issues which\nshould be considered:
-L2829
-)P
-(P
-L2830
--\nIf you discover a bug in the program which generates the configuration\nfile, or if the format of the file changes from one version to the\nnext, you will have to arrange for the postinst script to do something\nsensible - usually this will mean editing the installed configuration\nfile to remove the problem or change the syntax. You will have to do\nthis very carefully, since the user may have changed the file, perhaps\nto fix the very problem that your script is trying to deal with - you\nwill have to detect these situations and deal with them correctly.
-L2839
-)P
-(P
-L2840
--\nIf you do go down this route it's probably a good idea to make the\nprogram that generates the configuration file(s) a separate program in\n
-(TT
--/usr/sbin
-)TT
--, by convention called
-(TT
-(VAR
--package
-)VAR
--config
-)TT
-- and\nthen run that if appropriate from the post-installation script. The\n
-(TT
-(VAR
--package
-)VAR
--config
-)TT
-- program should not unquestioningly overwrite\nan existing configuration - if its mode of operation is geared towards\nsetting up a package for the first time (rather than any arbitrary\nreconfiguration later) you should have it check whether the\nconfiguration already exists, and require a
-(TT
----force
-)TT
-- flag to\noverwrite it.\n\n\n
-L2854
-)P
-)SECT
-)CHAPT
-AID CDATA alternatives
-ASRID CDATA ch-alternatives
-ACHAPT CDATA 10
-ASECT IMPLIED
-AHNAME CDATA chapter 10
-(CHAPT
-(HEADING
--Alternative versions of an interface -\n
-(PRGN
--update-alternatives
-)PRGN
-L2856
-)HEADING
-(P
-L2857
--\nWhen several packages all provide different versions of the same\nprogram or file it is useful to have the system select a default, but\nto allow the system administrator to change it and have their\ndecisions respected.
-L2862
-)P
-(P
-L2863
--\nFor example, there are several versions of the
-(PRGN
--vi
-)PRGN
-- editor, and\nthere is no reason to prevent all of them from being installed at\nonce, each under their own name (
-(PRGN
--nvi
-)PRGN
--,
-(PRGN
--vim
-)PRGN
-- or whatever).\nNevertheless it is desirable to have the name
-(TT
--vi
-)TT
-- refer to\nsomething, at least by default.
-L2869
-)P
-(P
-L2870
--\nIf all the packages involved cooperate, this can be done with\n
-(PRGN
--update-alternatives
-)PRGN
--.
-L2873
-)P
-(P
-L2874
--\nEach package provides its own version under its own name, and calls\n
-(PRGN
--update-alternatives
-)PRGN
-- in its postinst to register its version\n(and again in its prerm to deregister it).
-L2878
-)P
-(P
-L2879
--\nSee the manpage
-ANAME CDATA update-alternatives
-ASECTION CDATA 8
-(MANREF
-)MANREF
-- for\ndetails.
-L2882
-)P
-(P
-L2883
--\nIf
-(PRGN
--update-alternatives
-)PRGN
-- does not seem appropriate you may wish\nto consider using diversions instead.\n\n
-L2888
-)P
-)CHAPT
-AID CDATA diversions
-ASRID CDATA ch-diversions
-ACHAPT CDATA 11
-ASECT IMPLIED
-AHNAME CDATA chapter 11
-(CHAPT
-(HEADING
--Diversions - overriding a package's version of a file
-L2889
-)HEADING
-(P
-L2890
--\nIt is possible to have
-(PRGN
--dpkg
-)PRGN
-- not overwrite a file when it\nreinstalls the package it belongs to, and to have it put the file from\nthe package somewhere else instead.
-L2894
-)P
-(P
-L2895
--\nThis can be used locally to override a package's version of a file, or\nby one package to override another's version (or provide a wrapper for\nit).
-L2899
-)P
-(P
-L2900
--\nBefore deciding to use a diversion, read
-AID CDATA alternatives
-ALEVEL CDATA CHAPT
-ASRID CDATA ch-alternatives
-ACHAPT CDATA 10
-ASECT IMPLIED
-AHNAME CDATA chapter 10
-(REF
-L2854 programmer.sgml
--Alternative versions of an interface -\n
-(PRGN
--update-alternatives
-)PRGN
-L2856
-)REF
-- to\nsee if you really want a diversion rather than several alternative\nversions of a program.
-L2904
-)P
-(P
-L2905
--\nThere is a diversion list, which is read by
-(PRGN
--dpkg
-)PRGN
--, and updated\nby a special program
-(PRGN
--dpkg-divert
-)PRGN
--. Please see
-ANAME CDATA dpkg-divert
-ASECTION CDATA 8
-(MANREF
-)MANREF
-L2908
-- for full details of its operation.
-L2909
-)P
-(P
-L2910
--\nWhen a package wishes to divert a file from another, it should call\n
-(PRGN
--dpkg-divert
-)PRGN
-- in its preinst to add the diversion and rename the\nexisting file. For example, supposing that a
-(PRGN
--smailwrapper
-)PRGN
--\npackage wishes to install a wrapper around
-(TT
--/usr/sbin/smail
-)TT
--:\n
-(EXAMPLE
-L2916
--if [ install = "$1" ]; then\n dpkg-divert --package smailwrapper --add --rename \\\n\011\011--divert /usr/sbin/smail.real /usr/sbin/smail\nfi
-L2920
-)EXAMPLE
--\nTesting
-(TT
--$1
-)TT
-- is necessary so that the script doesn't try to add the\ndiversion again when
-(PRGN
--smailwrapper
-)PRGN
-- is upgraded. The\n
-(TT
----package smailwrapper
-)TT
-- ensures that
-(PRGN
--smailwrapper
-)PRGN
--'s copy of\n
-(TT
--/usr/sbin/smail
-)TT
-- can bypass the diversion and get installed as\nthe true version.
-L2926
-)P
-(P
-L2927
--\nThe postrm has to do the reverse:\n
-(EXAMPLE
-L2930
--if [ remove = "$1" ]; then\n dpkg-divert --package smailwrapper --remove --rename \\\n --divert /usr/sbin/smail.real /usr/sbin/smail\nfi
-L2934
-)EXAMPLE
-L2935
-)P
-(P
-L2936
--\nDo not attempt to divert a file which is vitally important for the\nsystem's operation - when using
-(PRGN
--dpkg-divert
-)PRGN
-- there is a time,\nafter it has been diverted but before
-(PRGN
--dpkg
-)PRGN
-- has installed the\nnew version, when the file does not exist.\n\n
-L2943
-)P
-)CHAPT
-AID CDATA sharedlibs
-ASRID CDATA ch-sharedlibs
-ACHAPT CDATA 12
-ASECT IMPLIED
-AHNAME CDATA chapter 12
-(CHAPT
-(HEADING
--Shared libraries
-L2944
-)HEADING
-(P
-L2945
--\nPackages containing shared libraries must be constructed with a little\ncare to make sure that the shared library is always available. This\nis especially important for packages whose shared libraries are\nvitally important, such as the libc.
-L2950
-)P
-(P
-L2951
--\nFirstly, your package should install the shared libraries under their\nnormal names. For example, the
-(PRGN
--libgdbm1
-)PRGN
-- package should install\n
-(TT
--libgdbm.so.1.7.3
-)TT
-- as
-(TT
--/usr/lib/libgdbm.so.1.7.3
-)TT
--. The\nfiles should not be renamed or relinked by any prerm or postrm\nscripts;
-(PRGN
--dpkg
-)PRGN
-- will take care of renaming things safely without\naffecting running programs, and attempts to interfere with this are\nlikely to lead to problems.
-L2959
-)P
-(P
-L2960
--\nSecondly, your package should include the symlink that
-(PRGN
--ldconfig
-)PRGN
--\nwould create for the shared libraries. For example, the
-(PRGN
--libgdbm1
-)PRGN
--\npackage should include a symlink from
-(TT
--/usr/lib/libgdbm.so.1
-)TT
--\nto
-(TT
--libgdbm.so.1.7.3
-)TT
--. This is needed so that
-(PRGN
--ld.so
-)PRGN
-- can find\nthe library in between the time
-(PRGN
--dpkg
-)PRGN
-- installs it and\n
-(PRGN
--ldconfig
-)PRGN
-- is run in the
-(PRGN
--postinst
-)PRGN
-- script. Futhermore, and
-(EM
--this\nis very important
-)EM
--, the symlink must be placed before the library it\npoints to in the
-(TT
--.deb
-)TT
-- file. Currently the way to ensure the\nordering is done properly is to create the symlink in the appropriate\n
-(TT
--debian/tmp/.../lib
-)TT
-- directory before installing the library\nwhen you build the package.
-L2972
-)P
-(P
-L2973
--\nIf you do the above your package does not need to call
-(PRGN
--ldconfig
-)PRGN
--\nin its maintainer scripts. It is especially important not to call\n
-(PRGN
--ldconfig
-)PRGN
-- in the postrm or preinst scripts in the case where the\npackage is being upgraded (see the programmer's manual), as\n
-(PRGN
--ldconfig
-)PRGN
-- will see the temporary names that
-(PRGN
--dpkg
-)PRGN
-- uses for the\nfiles while it is installing them and will make the shared library\nlinks point to them, just before
-(PRGN
--dpkg
-)PRGN
-- continues the installation\nand removes the links!\n\n\n
-L2985
-)P
-)CHAPT
-AID CDATA sysvinit
-ASRID CDATA ch-sysvinit
-ACHAPT CDATA 13
-ASECT IMPLIED
-AHNAME CDATA chapter 13
-(CHAPT
-(HEADING
--Configuration of
-(PRGN
--init
-)PRGN
-L2986
-)HEADING
-(P
-L2988
-)P
-AID IMPLIED
-ASRID CDATA s13.1
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .1
-AHNAME CDATA section 13.1
-(SECT
-(HEADING
--Introduction to the
-(TT
--init.d
-)TT
-- scheme
-L2989
-)HEADING
-(P
-L2990
--\nThe
-(TT
--/etc/init.d
-)TT
-- directory contains the scripts executed by\n
-(PRGN
--init
-)PRGN
-- when init state (or `runlevel') is changed (see
-ANAME CDATA init
-ASECTION CDATA 8
-(MANREF
-)MANREF
-L2993
--).
-L2994
-)P
-(P
-L2995
--\nThese scripts are be referenced by symbolic links in the\n
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
-- directories. When changing runlevels, init\nlooks in the directory
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
-- for the scripts it\nshould execute, where
-(VAR
--n
-)VAR
-- is the runlevel that is being changed\nto.
-L3001
-)P
-(P
-L3002
--\nThe names of the links all have the form
-(TT
--S
-(VAR
--mm
-)VAR
-(VAR
--script
-)VAR
-)TT
-- or\n
-(TT
--K
-(VAR
--mm
-)VAR
-(VAR
--script
-)VAR
-)TT
-- where
-(VAR
--mm
-)VAR
-- is a two-digit number and\n
-(VAR
--script
-)VAR
-- is the name of the script (this should be the same as the\nname of the actual script in
-(TT
--/etc/init.d
-)TT
--.\n\nWhen
-(PRGN
--init
-)PRGN
-- changes runlevel first the targets of the links whose\nnames starting with a
-(TT
--K
-)TT
-- are executed, each with the single\nargument
-(TT
--stop
-)TT
--, followed by the scripts prefixed with an
-(TT
--S
-)TT
--,\neach with the single argument
-(TT
--start
-)TT
--. The
-(TT
--K
-)TT
-- links are\nresponsible for killing services and the
-(TT
--S
-)TT
-- link for starting\nservices upon entering the runlevel.
-L3014
-)P
-(P
-L3015
--\nFor example, if we are changing from runlevel 2 to runlevel 3, init\nwill first execute all of the
-(TT
--K
-)TT
-- prefixed scripts it finds in\n
-(TT
--/etc/rc3.d
-)TT
--, and then all of the
-(TT
--S
-)TT
-- prefixed scripts. The\nlinks starting with
-(TT
--K
-)TT
-- will cause the referred-to file to be\nexecuted with an argument of
-(TT
--stop
-)TT
--, and the
-(TT
--S
-)TT
-- links with an\nargument of
-(TT
--start
-)TT
--.
-L3022
-)P
-(P
-L3023
--\nThe two-digit number
-(VAR
--mm
-)VAR
-- is used to decide which order to start\nand stop things in - low-numbered links have their scripts run first.\nFor example, the
-(TT
--K20
-)TT
-- scripts will be executed before the
-(TT
--K30
-)TT
--\nscripts. This is used when a certain service must be started before\nanother. For example, the name server
-(PRGN
--bind
-)PRGN
-- might need to be\nstarted before the news server
-(PRGN
--inn
-)PRGN
-- so that
-(PRGN
--inn
-)PRGN
-- can set\nup its access lists. In this case, the script that starts
-(PRGN
--bind
-)PRGN
--\nshould have a lower number than the script that starts
-(PRGN
--inn
-)PRGN
-- so\nthat it runs first:\n
-(EXAMPLE
-L3034
--/etc/rc2.d/S17bind\n/etc/rc2.d/S70inn
-L3036
-)EXAMPLE
--\n
-L3038
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s13.2
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .2
-AHNAME CDATA section 13.2
-(SECT
-(HEADING
--Writing
-(TT
--init.d
-)TT
-- scripts
-L3039
-)HEADING
-(P
-L3040
--\nPackages can and should place scripts in
-(TT
--/etc/init.d
-)TT
-- to start\nor stop services at boot time or during a change of runlevel. These\nscripts should be named
-(TT
--/etc/init.d/
-(VAR
--package
-)VAR
-)TT
--, and they\nshould accept one argument, saying what to do:
-(TT
--start
-)TT
--, meaning to\nstarts the service, or
-(TT
--stop
-)TT
--, to stop the service. Optionally\nthey can support
-(TT
--reload
-)TT
-- which causes the configuration to be\nreloaded.
-L3048
-)P
-(P
-L3049
--\nThe
-(TT
--init.d
-)TT
-- scripts should ensure that they will behave sensibly\nif invoked with
-(TT
--start
-)TT
-- when the service is already running, or\nwith
-(TT
--stop
-)TT
-- when it isn't, and that they don't kill\nunfortunately-named user processes. The best way to achieve this is\nusually to use
-(PRGN
--start-stop-daemon
-)PRGN
--.
-L3055
-)P
-(P
-L3056
--\nThese scripts should not fail obscurely when the configuration files\nremain but the package has been removed, as the default in
-(PRGN
--dpkg
-)PRGN
--\nis to leave configuration files on the system after the package has\nbeen removed. Only when it is executed with the
-(TT
----purge
-)TT
-- option\nwill dpkg remove configuration files. Therefore, you should include a\n
-(TT
--test
-)TT
-- statement at the top of the script, like this:\n
-(EXAMPLE
-L3064
--test -f
-(VAR
--program-executed-later-in-script
-)VAR
-- || exit 0
-L3065
-)EXAMPLE
--\n
-L3067
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s13.3
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .3
-AHNAME CDATA section 13.3
-(SECT
-(HEADING
--Managing the
-(TT
--rc
-(VAR
--n
-)VAR
--.d
-)TT
-- links -
-(PRGN
--update-rc.d
-)PRGN
-L3068
-)HEADING
-(P
-L3069
--\nA program is provided,
-(PRGN
--update-rc.d
-)PRGN
--, to make it easier for\npackage maintainers to arrange for the proper creation and removal of\n
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
-- symbolic links from their postinst and postrm\nscripts.
-L3074
-)P
-(P
-L3075
--\nYou should use this script to make changes to
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
--\nand
-(EM
--never
-)EM
-- include any
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
-- symbolic links in\nthe actual archive.
-L3079
-)P
-(P
-L3080
--\nBy default
-(PRGN
--update-rc.d
-)PRGN
-- will start services in each of the\nmulti-user state runlevels (2, 3, 4, and 5) and stop them in the halt\nrunlevel (0), the single-user runlevel (1) and the reboot runlevel\n(6). The system administrator will have the opportunity to customize\nrunlevels by simply adding, moving, or removing the symbolic links in\n
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d
-)TT
--.
-L3087
-)P
-(P
-L3088
--\nTo get the default behaviour for your package, put in your postinst\nscript\n
-(EXAMPLE
-L3092
--update-rc.d
-(VAR
--package
-)VAR
-- default \|>\|/dev/null
-L3093
-)EXAMPLE
--\nand in your postrm\n
-(EXAMPLE
-L3096
--if [ purge = "$1" ]; then\n update-rc.d
-(VAR
--package
-)VAR
-- remove \|>\|/dev/null\nfi
-L3099
-)EXAMPLE
-L3100
-)P
-(P
-L3101
--\nThis will use a default sequence number of 20. If it does not matter\nwhen or in which order the script is run, use this default. If it\ndoes, then you should talk to the maintainer of the
-(PRGN
--sysvinit
-)PRGN
--\npackage or post to
-(TT
--debian-devel
-)TT
--, and they will help you choose\na number.
-L3107
-)P
-(P
-L3108
--\nFor more information about using
-(TT
--update-rc.d
-)TT
--, please consult its\nmanpage
-ANAME CDATA update-rc.d
-ASECTION CDATA 8
-(MANREF
-)MANREF
--.\n
-L3112
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s13.4
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .4
-AHNAME CDATA section 13.4
-(SECT
-(HEADING
--Boot-time initialisation -
-(TT
--rc.boot
-)TT
-L3113
-)HEADING
-(P
-L3114
--\nThere is another directory,
-(TT
--/etc/rc.boot
-)TT
--, which contains\nscripts which are run once per machine boot. This facility is\nprovided for initialisation of hardware devices, cleaning up of\nleftover files, and so forth.
-L3119
-)P
-(P
-L3120
--\nFor example, the
-(PRGN
--kbd
-)PRGN
-- package provides a script here for\ninitialising the keyboard layout and console font and mode.
-L3123
-)P
-(P
-L3124
--\nThe files in
-(TT
--/etc/rc.boot
-)TT
-- should
-(EM
--not
-)EM
-- be links into\n
-(TT
--/etc/init.d
-)TT
-- - they should be the scripts themselves.
-L3127
-)P
-(P
-L3128
--\n
-(TT
--rc.boot
-)TT
-- should
-(EM
--not
-)EM
-- be used for starting general-purpose\ndaemons and similar activities. This should be done using the\n
-(TT
--rc
-(VAR
--n
-)VAR
--.d
-)TT
-- scheme, above, so that the services can be started\nand stopped cleanly when the runlevel changes or the machine is to be\nshut down or rebooted.\n
-L3135
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s13.5
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .5
-AHNAME CDATA section 13.5
-(SECT
-(HEADING
--Notes
-L3136
-)HEADING
-(P
-L3137
--\n
-(EM
--Do not
-)EM
-- include the
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d/*
-)TT
-- symbolic links in\nthe
-(TT
--.deb
-)TT
-- filesystem archive!
-(EM
--This will cause problems!
-)EM
--\nYou should create them with
-(PRGN
--update-rc.d
-)PRGN
--, as above.
-L3141
-)P
-(P
-L3142
--\n
-(EM
--Do not
-)EM
-- include the
-(TT
--/etc/rc
-(VAR
--n
-)VAR
--.d/*
-)TT
-- symbolic links in\n
-(PRGN
--dpkg
-)PRGN
--'s conffiles list!
-(EM
--This will cause problems!
-)EM
--\n
-(EM
--Do
-)EM
--, however, include the
-(TT
--/etc/init.d
-)TT
-- scripts in conffiles.\n
-L3147
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s13.6
-ACHAPT CDATA 13
-ACSRID CDATA ch-sysvinit
-ASECT CDATA .6
-AHNAME CDATA section 13.6
-(SECT
-(HEADING
--Example
-L3148
-)HEADING
-(P
-L3149
--\nThe
-(PRGN
--bind
-)PRGN
-- DNS (nameserver) package wants to make sure that the\nnameserver is running in multiuser runlevels, and is properly shut\ndown with the system. It puts a script in
-(TT
--/etc/init.d
-)TT
--, naming\nthe script appropriately
-(TT
--bind
-)TT
--. As you can see, the script\ninterprets the argument
-(TT
--reload
-)TT
-- to send the nameserver a
-(TT
--HUP
-)TT
--\nsignal (causing it to reload its configuration); this way the user can\nsay
-(TT
--/etc/init.d/bind reload
-)TT
-- to reload the nameserver.
-L3157
-)P
-(P
-L3158
--\n
-(EXAMPLE
-L3160
--#!/bin/sh\n# Original version by Robert Leslie \|<\|rob@mars.org\|>\|, edited by iwj\ntest -x /usr/sbin/named || exit 0\ncase "$1" in\n start)\n test -f /etc/named.boot -a -f /var/named/boot.options || exit 0\n start-stop-daemon --start --verbose --exec /usr/sbin/named\n ;;\n stop)\n start-stop-daemon --stop --verbose \\\n --pidfile /var/run/named.pid --exec /usr/sbin/named\n ;;\n reload)\n start-stop-daemon --stop --signal 1 --verbose \\\n --pidfile /var/run/named.pid --exec /usr/sbin/named\n ;;\n *)\n echo "Usage: /etc/init.d/bind {start|stop|reload}" >&2\n exit 1\n ;;\nesac\nexit 0
-L3182
-)EXAMPLE
-L3183
-)P
-(P
-L3184
--\nAnother example on which to base your
-(TT
--/etc/init.d
-)TT
-- scripts is in\n
-(TT
--/etc/init.d/skeleton
-)TT
--.
-L3187
-)P
-(P
-L3188
--\nIf this package is happy with the default setup from\n
-(PRGN
--update-rc.d
-)PRGN
--, namely an ordering number of 20 and having named\nrunning in all runlevels, it can say in its postinst:\n
-(EXAMPLE
-L3193
--update-rc.d bind default >/dev/null
-L3194
-)EXAMPLE
--\nAnd in its postrm, to remove the links when the package is purged:\n
-(EXAMPLE
-L3197
--if [ purge = "$1" ]; then\n update-rc.d acct remove >/dev/null\nfi
-L3200
-)EXAMPLE
--\n\n\n
-L3204
-)P
-)SECT
-)CHAPT
-AID CDATA methif
-ASRID CDATA ch-methif
-ACHAPT CDATA 14
-ASECT IMPLIED
-AHNAME CDATA chapter 14
-(CHAPT
-(HEADING
-(PRGN
--dselect
-)PRGN
--'s interface to its installation methods
-L3205
-)HEADING
-(P
-L3206
--\n
-(PRGN
--dselect
-)PRGN
-- calls scripts from its installation methods when it\nneeds to actually access data from the distribution. The core program\n
-(PRGN
--dselect
-)PRGN
-- itself just calls these scripts and provides the\npackage and access method selection interfaces. The installation\nmethods are responsible for invoking
-(PRGN
--dpkg
-)PRGN
-- as appropriate.
-L3212
-)P
-(P
-L3213
--\nEach installation method has three scripts:\n
-ACOMPACT TOKEN COMPACT
-(LIST
-L3216
-(ITEM
-(P
--Setup installation parameters.
-L3217
-)P
-)ITEM
-(ITEM
-(P
--Update list of available packages.
-L3218
-)P
-)ITEM
-(ITEM
-(P
--Install.
-L3219
-)P
-)ITEM
-)LIST
-L3220
-)P
-(P
-L3221
--\n
-(PRGN
--dselect
-)PRGN
-- searches for methods in
-(TT
--/usr/lib/dpkg/methods
-)TT
--\nand
-(TT
--/usr/local/lib/dpkg/methods
-)TT
--.\n
-L3225
-)P
-AID IMPLIED
-ASRID CDATA s14.1
-ACHAPT CDATA 14
-ACSRID CDATA ch-methif
-ASECT CDATA .1
-AHNAME CDATA section 14.1
-(SECT
-(HEADING
--Functions of the method scripts
-L3226
-)HEADING
-(P
-L3227
--\nThe setup script is run just after the user has chosen an installation\nmethod. It should prompt the user for parameters like the site to\nNFS-mount or FTP from, the directory to use, or the directory or\nfilesystem where the
-(TT
--.deb
-)TT
-- files can be found, or the tape or\nfloppy device to install from. It should store the responses under\n
-(TT
--/var/lib/dpkg/methods
-)TT
-- - see below. If no available\npackages list is available it should perhaps offer to scan the\navailable packages.
-L3236
-)P
-(P
-L3237
--\nThe update script should obtain a list of available packages if\npossible, and run
-(TT
--dpkg --update-avail
-)TT
--,
-(TT
--dpkg --merge-avail
-)TT
--\nand/or
-(TT
--dpkg --forget-old-unavail
-)TT
-- to load it into
-(PRGN
--dpkg
-)PRGN
-- and\n
-(PRGN
--dselect
-)PRGN
--'s database of available packages. If no packages list\nwas available and the user was offered and accepted the option of\nscanning the actual files available this scan should be done here,\nusing
-(TT
--dpkg --record-avail
-)TT
--.
-L3245
-)P
-(P
-L3246
--\nThe install script should feed all the available
-(TT
--.deb
-)TT
-- files to\n
-(TT
--dpkg --iGOEB
-)TT
-- (this is equivalent to
-(TT
--dpkg --install\n--refuse-downgrade --selected-only --skip-same-version\n--auto-deconfigure
-)TT
--). The
-(TT
---R
-)TT
-- (
-(TT
----recursive
-)TT
--) option for\ntraversing subdirectories may also be useful here).
-L3252
-)P
-(P
-L3253
--\nIf any of these scripts needs to display a message for the user, it\nshould wait for the user to hit `return' before exiting so that\ndselect doesn't immediately rewrite the screen.
-L3257
-)P
-(P
-L3258
--\nIf a method script succeeds (returns a zero exit status)\n
-(PRGN
--dselect
-)PRGN
-- will return immediately to the main menu, with the\n`next' option highlighted ready for the user to select it. If it\nfails
-(PRGN
--dselect
-)PRGN
-- will display a message and wait for the user to\nhit return.\n
-L3265
-)P
-)SECT
-AID IMPLIED
-ASRID CDATA s14.2
-ACHAPT CDATA 14
-ACSRID CDATA ch-methif
-ASECT CDATA .2
-AHNAME CDATA section 14.2
-(SECT
-(HEADING
--Location and arguments of the method scripts
-L3266
-)HEADING
-(P
-L3267
--\nA set of scripts (henceforth known as a group) may provide several\nmethods on the `main menu' with different behaviour. For example,\nthere might be a generic get-packages-by-FTP group which might provide\nmethods in the main menu for installation directly from one of the\nDebian mirror sites as well as for installation from a user-specified\nsite.
-L3274
-)P
-(P
-L3275
--\nEach group of methods implemented by the same set of scripts should\nhave a subdirectory
-(TT
--/usr/lib/dpkg/methods/
-(VAR
--group
-)VAR
-)TT
-- or\n
-(TT
--/usr/local/lib/dpkg/methods/
-(VAR
--group
-)VAR
-)TT
--, containing:\n
-ACOMPACT TOKEN COMPACT
-(TAGLIST
-L3280
-(TAG
-(TT
--names
-)TT
-L3281
-)TAG
-(ITEM
-(P
--a list of user-visible methods provided by these scripts.
-L3282
-)P
-)ITEM
-(TAG
-(TT
--setup
-)TT
-L3283
-)TAG
-(TAG
-(TT
--update
-)TT
-L3284
-)TAG
-(TAG
-(TT
--install
-)TT
-L3285
-)TAG
-(ITEM
-(P
--executable programs, the scripts themselves.
-L3286
-)P
-)ITEM
-(TAG
-(TT
--desc.
-(VAR
--option
-)VAR
-)TT
-L3287
-)TAG
-(ITEM
-(P
--description file.
-L3288
-)P
-)ITEM
-)TAGLIST
-L3289
-)P
-(P
-L3290
--\n
-(TT
--names
-)TT
-- will be formatted as a list of lines, each containing:\n
-(EXAMPLE
-L3293
-(VAR
--sequence
-)VAR
--
-(VAR
--method
-)VAR
--
-(VAR
--summary
-)VAR
-L3294
-)EXAMPLE
-L3295
-)P
-(P
-L3296
--\n
-(VAR
--sequence
-)VAR
-- is a two-digit number that will be used much like\n
-(TT
--rc.d
-)TT
-- prefixes to control the order in the main menu. If in doubt\nuse 50.
-L3300
-)P
-(P
-L3301
--\n
-(VAR
--method
-)VAR
-- is a name which is displayed by
-(PRGN
--dselect
-)PRGN
-- as the\nname of the method, and which will be passed to
-(TT
--setup
-)TT
--,\n
-(TT
--update
-)TT
-- and
-(TT
--unpack
-)TT
-- as their first argument.
-L3305
-)P
-(P
-L3306
--\n
-(VAR
--summary
-)VAR
-- is the brief description string for
-(PRGN
--dselect
-)PRGN
--'s menu.
-L3308
-)P
-(P
-L3309
--\nEach of the three scripts gets the same three arguments:
-(VAR
--vardir
-)VAR
--,\n
-(VAR
--group
-)VAR
-- and
-(VAR
--method
-)VAR
--.
-(VAR
--vardir
-)VAR
-- is the base directory for\nstoring
-(PRGN
--dpkg
-)PRGN
-- and
-(PRGN
--dselect
-)PRGN
--'s state, usually\n
-(TT
--/var/lib/dpkg
-)TT
--; this is passed in so that the
-(TT
----admindir
-)TT
--\noption to
-(PRGN
--dselect
-)PRGN
-- is honoured).
-L3315
-)P
-(P
-L3316
--\nEach option may have an extended description in\n
-(TT
--desc.
-(VAR
--option
-)VAR
-)TT
--. This should be formatted like the extended\ndescription part of a
-(TT
--Description
-)TT
-- field entry
-(EM
--shifted one\ncharacter to the left
-)EM
--.
-L3321
-)P
-(P
-L3322
--\n
-(TT
-(VAR
--vardir
-)VAR
--/methods
-)TT
-- will exist, and a method group may use a\n
-(TT
-(VAR
--vardir
-)VAR
--/methods/
-(VAR
--group
-)VAR
-)TT
-- directory to store its state.
-L3325
-)P
-(P
-L3326
--\nThe group name and method name must follow the rules for C identifiers.\n
-L3329
-)P
-)SECT
-)CHAPT
-)BOOK
-)DEBIANDOC
-C
case.
<p>
+It is a more serious error for a package to contain a plain file or
+other kind of nondirectory where another package has a directory
+(again, unless <tt/Replaces/ is used). This error can be overridden
+if desired using <tt/--force-overwrite-dir/, but this is not -->
+--advisable.
+<p>
+
Packages which overwrite each other's files produce behaviour which
though deterministic is hard for the system administrator to
understand. It can easily lead to `missing' programs if, for example,
a package is installed which overwrites a file from another package,
and is then removed again.<footnote>Part of the problem is due to what
is arguably a bug in <prgn/dpkg/.</footnote>
+<p>
+
+A directory will never be replaced by a symbolic links to a directory
+or vice versa; instead, the existing state (symlink or not) will be
+left alone and <prgn/dpkg/ will follow the symlink if there is one.
<item>
man8dir = $(mandir)/man8
man8 = 8
-SRC = main.c enquiry.c filesdb.c archives.c processarc.c cleanup.c \
+SRC = main.c enquiry.c filesdb.c archives.c processarc.c cleanup.c select.c \
packages.c configure.c remove.c help.c depcon.c errors.c update.c
-OBJ = main.o enquiry.o filesdb.o archives.o processarc.o cleanup.o \
+OBJ = main.o enquiry.o filesdb.o archives.o processarc.o cleanup.o select.o \
packages.o configure.o remove.o help.o depcon.o errors.o update.o
INSTALL = @INSTALL@
printf("Replacing files in old package %s ...\n",otherpkg->name);
otherpkg->clientdata->replacingfilesandsaid= 1;
} else {
- forcibleerr(fc_overwrite,
- "trying to overwrite `%.250s', which is also in package %.250s",
- nifd->namenode->name,otherpkg->name);
+ if (S_ISDIR(stab.st_mode)) {
+ forcibleerr(fc_overwritedir, "trying to overwrite directory `%.250s' "
+ "in package %.250s with nondirectory",
+ nifd->namenode->name,otherpkg->name);
+ } else {
+ forcibleerr(fc_overwrite,
+ "trying to overwrite `%.250s', which is also in package %.250s",
+ nifd->namenode->name,otherpkg->name);
+ }
}
}
}
modstatdb_init(admindir,
f_noact ? msdbrw_readonly
: cipaction->arg == act_avail ? msdbrw_write
+ : fc_nonroot ? msdbrw_write
: msdbrw_needsuperuser);
currenttime= time(0);
#include "filesdb.h"
#include "main.h"
-static int listqcmp(const void *a, const void *b) {
+int pkglistqsortcmp(const void *a, const void *b) {
struct pkginfo *pa= *(struct pkginfo**)a;
struct pkginfo *pb= *(struct pkginfo**)b;
return strcmp(pa->name,pb->name);
iterpkgend(it);
assert(i==np);
- qsort(pkgl,np,sizeof(struct pkginfo*),listqcmp);
+ qsort(pkgl,np,sizeof(struct pkginfo*),pkglistqsortcmp);
head=0;
if (!*argv) {
" DPKG " -A|--record-avail <.deb file name> ... | -R|--recursive <dir> ...\n\
" DPKG " --configure <package name> ... | -a|--pending\n\
" DPKG " -r|--remove | --purge <package name> ... | -a|--pending\n\
+ " DPKG " --get-selections [<pattern> ...] get list of selections to stdout\n\
+ " DPKG " --set-selections set package selections from stdin\n\
" DPKG " --update-avail <Packages-file> replace available packages info\n\
" DPKG " --merge-avail <Packages-file> merge with info from file\n\
" DPKG " --clear-avail erase existing available info\n\
int fc_downgrade=1, fc_configureany=0, fc_hold=0, fc_removereinstreq=0, fc_overwrite=1;
int fc_removeessential=0, fc_conflicts=0, fc_depends=0, fc_dependsversion=0;
int fc_autoselect=1, fc_badpath=0, fc_overwritediverted=0, fc_architecture=0;
+int fc_nonroot=0, fc_overwritedir=0;
const char *admindir= ADMINDIR;
const char *instdir= "";
{ "depends-version", &fc_dependsversion },
{ "auto-select", &fc_autoselect },
{ "bad-path", &fc_badpath },
+ { "not-root", &fc_nonroot },
{ "overwrite", &fc_overwrite },
{ "overwrite-diverted", &fc_overwritediverted },
+ { "overwrite-dir", &fc_overwritedir },
{ "architecture", &fc_architecture },
{ 0 }
};
configure-any Configure any package which may help this one\n\
hold Process incidental packages even when on hold\n\
bad-path PATH is missing important programs, problems likely\n\
+ not-root Try to (de)install things even when not root\n\
overwrite [*] Overwrite a file from one package with another\n\
overwrite-diverted Overwrite a diverted file with an undiverted version\n\
depends-version [!] Turn dependency version problems into warnings\n\
depends [!] Turn all dependency problems into warnings\n\
conflicts [!] Allow installation of conflicting packages\n\
architecture [!] Process even packages with wrong architecture\n\
+ overwrite-dir [!] Overwrite one package's directory with another's file\n\
remove-reinstreq [!] Remove packages which require installation\n\
remove-essential [!] Remove an essential package\n\
\n\
ACTION( "purge", 0, act_purge, packages ),
ACTION( "listfiles", 'L', act_listfiles, enqperpackage ),
ACTION( "status", 's', act_status, enqperpackage ),
+ ACTION( "get-selections", 0, act_getselections, getselections ),
+ ACTION( "set-selections", 0, act_setselections, setselections ),
ACTION( "print-avail", 0, act_printavail, enqperpackage ),
ACTION( "update-avail", 0, act_avreplace, updateavailable ),
ACTION( "merge-avail", 0, act_avmerge, updateavailable ),
act_unpackchk, act_status, act_searchfiles, act_audit, act_listfiles,
act_assertpredep, act_printarch, act_predeppackage, act_cmpversions,
act_printinstarch, act_compareversions, act_printavail, act_avclear,
- act_forgetold };
+ act_forgetold, act_getselections, act_setselections };
enum conffopt {
cfof_prompt = 001,
extern int fc_downgrade, fc_configureany, fc_hold, fc_removereinstreq, fc_overwrite;
extern int fc_removeessential, fc_conflicts, fc_depends, fc_dependsversion;
extern int fc_autoselect, fc_badpath, fc_overwritediverted, fc_architecture;
+extern int fc_nonroot, fc_overwritedir;
extern const char *admindir;
extern const char *instdir;
void printinstarch(const char *const *argv);
void cmpversions(const char *const *argv);
+/* Intended for use as a comparison function for qsort when
+ * sorting an array of pointers to struct pkginfo:
+ */
+int pkglistqsortcmp(const void *a, const void *b);
+
+/* from select.c */
+
+void getselections(const char *const *argv);
+void setselections(const char *const *argv);
+
/* from packages.c, remove.c and configure.c */
void add_to_queue(struct pkginfo *pkg);
int l;
checkpath();
- modstatdb_init(admindir, f_noact ? msdbrw_readonly : msdbrw_needsuperuser);
+ modstatdb_init(admindir,
+ f_noact ? msdbrw_readonly
+ : fc_nonroot ? msdbrw_write
+ : msdbrw_needsuperuser);
if (f_pending) {
--- /dev/null
+/*
+ * dpkg - main program for package management
+ * select.c - by-hand (rather than dselect-based) package selection
+ *
+ * Copyright (C) 1995,1996 Ian Jackson <ijackson@gnu.ai.mit.edu>
+ *
+ * This is free software; you can 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,
+ * 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.
+ *
+ * You should have received a copy of the GNU General Public
+ * License along with dpkg; if not, write to the Free Software
+ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <stdio.h>
+#include <string.h>
+#include <assert.h>
+#include <fnmatch.h>
+#include <ctype.h>
+
+#include "config.h"
+#include "dpkg.h"
+#include "dpkg-db.h"
+#include "myopt.h"
+
+#include "filesdb.h"
+#include "main.h"
+
+static void getsel1package(struct pkginfo *pkg) {
+ int l;
+
+ if (pkg->want == want_unknown) return;
+ l= strlen(pkg->name); l >>= 3; l= 6-l; if (l<1) l=1;
+ printf("%s%.*s%s\n",pkg->name,l,"\t\t\t\t\t\t",wantinfos[pkg->want].name);
+}
+
+void getselections(const char *const *argv) {
+ struct pkgiterator *it;
+ struct pkginfo *pkg;
+ struct pkginfo **pkgl;
+ const char *thisarg;
+ int np, i, head, found;
+
+ modstatdb_init(admindir,msdbrw_readonly);
+
+ np= countpackages();
+ pkgl= m_malloc(sizeof(struct pkginfo*)*np);
+ it= iterpkgstart(); i=0;
+ while ((pkg= iterpkgnext(it))) {
+ assert(i<np);
+ pkgl[i++]= pkg;
+ }
+ iterpkgend(it);
+ assert(i==np);
+
+ qsort(pkgl,np,sizeof(struct pkginfo*),pkglistqsortcmp);
+ head=0;
+
+ if (!*argv) {
+ for (i=0; i<np; i++) {
+ pkg= pkgl[i];
+ if (pkg->status == stat_notinstalled) continue;
+ getsel1package(pkg);
+ }
+ } else {
+ while ((thisarg= *argv++)) {
+ found= 0;
+ for (i=0; i<np; i++) {
+ pkg= pkgl[i];
+ if (fnmatch(thisarg,pkg->name,0)) continue;
+ getsel1package(pkg); found++;
+ }
+ if (!found)
+ fprintf(stderr,"No packages found matching %s.\n",thisarg);
+ }
+ }
+ if (ferror(stdout)) werr("stdout");
+ if (ferror(stderr)) werr("stderr");
+}
+
+void setselections(const char *const *argv) {
+ const struct namevalue *nvp;
+ struct pkginfo *pkg;
+ const char *e;
+ int c, lno;
+ struct varbuf namevb;
+ struct varbuf selvb;
+
+ if (*argv) badusage("--set-selections does not take any argument");
+
+ modstatdb_init(admindir,msdbrw_write);
+
+ varbufinit(&namevb);
+ varbufinit(&selvb);
+ lno= 1;
+ for (;;) {
+ varbufreset(&namevb);
+ varbufreset(&selvb);
+ do { c= getchar(); if (c == '\n') lno++; } while (c != EOF && isspace(c));
+ if (c == EOF) break;
+ if (c == '#') {
+ do { c= getchar(); if (c == '\n') lno++; } while (c != EOF && c != '\n');
+ continue;
+ }
+ while (!isspace(c)) {
+ varbufaddc(&namevb,c);
+ c= getchar();
+ if (c == EOF) ohshit("unexpected eof in package name at line %d",lno);
+ if (c == '\n') ohshit("unexpected end of line in package name at line %d",lno);
+ }
+ while (c != EOF && isspace(c)) {
+ c= getchar();
+ if (c == EOF) ohshit("unexpected eof after package name at line %d",lno);
+ if (c == '\n') ohshit("unexpected end of line after package name at line %d",lno);
+ }
+ while (c != EOF && !isspace(c)) {
+ varbufaddc(&selvb,c);
+ c= getchar();
+ }
+ while (c != EOF && c != '\n') {
+ c= getchar();
+ if (!isspace(c))
+ ohshit("unexpected data after package and selection at line %d",lno);
+ }
+ varbufaddc(&namevb,0);
+ varbufaddc(&selvb,0);
+ e= illegal_packagename(namevb.buf,0);
+ if (e) ohshit("illegal package name at line %d: %.250s",lno,e);
+ for (nvp=wantinfos; nvp->name && strcmp(nvp->name,selvb.buf); nvp++);
+ if (!nvp->name) ohshit("unknown wanted status at line %d: %.250s",lno,selvb.buf);
+ pkg= findpackage(namevb.buf);
+ pkg->want= nvp->value;
+ if (c == EOF) break;
+ lno++;
+ }
+ if (ferror(stdin)) ohshite("read error on standard input");
+ modstatdb_shutdown();
+ varbufreset(&namevb);
+ varbufreset(&selvb);
+}
-#define DPKG_VERSION "1.3.7" /* This line modified by Makefile */
+#define DPKG_VERSION "1.3.9" /* This line modified by Makefile */
projects / dpkg / commitdiff