<abstract>
This manual describes the technical aspects of creating Debian
- binary and source packages. It also documents the interface
- between <prgn>dselect</prgn> and its access method scripts.
- It does not deal with the Debian Project policy requirements,
- and it assumes familiarity with <prgn>dpkg</prgn>'s functions
- from the system administrator's perspective.
+ binary and source packages. It does not deal with the Debian
+ Project policy requirements, and it assumes familiarity with
+ <prgn>dpkg</prgn>'s functions from the system administrator's
+ perspective. This package itself is maintained by a group of
+ maintainers that have no editorial powers. At the moment, the
+ list of maintainers is:
+ <enumlist>
+ <item>
+ <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
+ </item>
+ <item>
+ <p>Richard Braakman <email>dark@xs4all.nl</email></p>
+ </item>
+ <item>
+ <p>Philip Hands <email>phil@hands.com</email></p>
+ </item>
+ <item>
+ <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
+ </item>
+ </enumlist>
+ </abstract>
+
<copyright>
<copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
This manual describes the technical aspects of creating Debian
binary packages (<tt>.deb</tt> files). It documents the
behaviour of the package management programs
- <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and and the way
+ <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
they interact with packages.</p>
<p>
<p>
When you've prepared the package, you should invoke:
<example>
- dpkg --build <var>directory</var>
+ dpkg --build <var>directory</var>
</example>
</p>
to examine the contents of this newly-created file. You may find the
output of following commands enlightening:
<example>
-dpkg-deb --info <var>filename</var>.deb
-dpkg-deb --contents <var>filename</var>.deb
-dpkg --contents <var>filename</var>.deb
-</example>
+ dpkg-deb --info <var>filename</var>.deb
+ dpkg-deb --contents <var>filename</var>.deb
+ dpkg --contents <var>filename</var>.deb
+ </example>
To view the copyright file for a package you could use this command:
-<example>
-dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
-</example></p>
-
+ <example>
+ dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
+ </example>
+ </p>
+ </sect>
+
<sect id="controlarea">
<heading>
Package control information files
</footnote>
</p>
</sect>
-
+ </chapt>
+
<chapt id="sourcepkg">
<heading>Source packages</heading>
<p>
To unpack a package it is typically invoked with
<example>
- dpkg-source -x <var>.../path/to/filename</var>.dsc
+ dpkg-source -x <var>.../path/to/filename</var>.dsc
</example>
</p>
<p>
To create a packed source archive it is typically invoked:
<example>
- dpkg-source -b <var>package</var>-<var>version</var>
+ dpkg-source -b <var>package</var>-<var>version</var>
</example>
</p>
<p>
For a package which generates only one binary package, and
which builds it in <tt>debian/tmp</tt> relative to the top
- of the source package, it is usually sufficient to call:
- <example>
- dpkg-gencontrol
- </example>
+ of the source package, it is usually sufficient to call
+ <prgn>dpkg-gencontrol</prgn>.
</p>
<p>
Sources which build several binaries will typically need
something like:
<example>
- dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
+ dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
</example> The <tt>-P</tt> tells
<prgn>dpkg-gencontrol</prgn> that the package is being
built in a non-default directory, and the <tt>-p</tt>
binaries like <prgn>top</prgn> which require only a
recommendation. It can say in its <tt>debian/rules</tt>:
<example>
- dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+ dpkg-shlibdeps -dPre-Depends ps -dRecommends top
</example>
and then in its main control file <tt>debian/control</tt>:
<example>
- <var>...</var>
- Package: procps
- Pre-Depends: ${shlibs:Pre-Depends}
- Recommends: ${shlibs:Recommends}
- <var>...</var>
+ <var>...</var>
+ Package: procps
+ Pre-Depends: ${shlibs:Pre-Depends}
+ Recommends: ${shlibs:Recommends}
+ <var>...</var>
</example>
</p>
It is usually invoked from the <prgn>binary</prgn> target of
<tt>debian/rules</tt>:
<example>
- dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
+ dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
</example>
The <var>filename</var> is relative to the directory where
<prgn>dpkg-genchanges</prgn> will expect to find it - this
information in it to standard output.
</p>
</sect1>
+
+ <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
+ information about the build and host system
+ </heading>
+
+ <p>
+ This program can be used manually, but is also invoked by
+ <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
+ to set environment or make variables which specify the build and
+ host architecture for the package building process.
+ </p>
+ </sect1>
</sect>
<sect id="sourcetree"><heading>The Debianised source tree
tree. They are described below.
</p>
- <sect1><heading><tt>debian/rules</tt> - the main building
+ <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
script
</heading>
either as published or undocumented interfaces or for the
package's internal use.
</p>
+
+ <p>
+ The architecture we build on and build for is determined by make
+ variables via dpkg-architecture (see <ref id="dpkgarch">). You can
+ get the Debian architecture and the GNU style architecture
+ specification string for the build machine as well as the host
+ machine. Here is a list of supported make variables:
+ <list compact="compact">
+ <item>
+ <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
+ specification string)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
+ DEB_*_GNU_TYPE)</p>
+ </list>
+ </p>
+
+ <p>
+ where <tt>*</tt> is either <tt>BUILD</tt> for specification of
+ the build machine or <tt>HOST</tt> for specification of the machine
+ we build for.
+ </p>
+
+ <p>
+ Backward compatibility can be provided in the rules file
+ by setting the needed variables to suitable default
+ values, please refer to the documentation of
+ dpkg-architecture for details.
+ </p>
+
+ <p>
+ It is important to understand that the <tt>DEB_*_ARCH</tt>
+ string does only determine which Debian architecture we
+ build on resp. for. It should not be used to get the CPU
+ or System information, the GNU style variables should be
+ used for that.
+ </p>
</sect1>
(classification, mandatory)
</p>
</item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Build-Depends</tt> et
+ al.</qref> (source package interrelationships)
+ </p>
+ </item>
<item>
<p>
<qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
<item>
<p>
<qref id="relationships"><tt>Depends</tt> et
- al.</qref> (package interrelationships)
+ al.</qref> (binary package interrelationships)
</p>
</item>
</list>
For example, if the main source information control file
contains the field
<example>
- XBS-Comment: I stand between the candle and the star.
+ XBS-Comment: I stand between the candle and the star.
</example>
then the binary and source package control files will contain the
field
<example>
- Comment: I stand between the candle and the star.
+ Comment: I stand between the candle and the star.
</example>
</p>
</sect2>
<p>
That format is a series of entries like this:
<example>
- <var>package</var> (<var>version</var>) <var>distribution(s)</var>;
- urgency=<var>urgency</var>
-
- * <var>change details</var>
- <var>more change details</var>
- * <var>even more change details</var>
+ <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
- -- <var>maintainer name and email address</var> <var>date</var>
+ -- <var>maintainer name and email address</var> <var>date</var>
</example>
</p>
parentheses should be the name of the format. For
example, you might say:
<example>
- @@@ changelog-format: joebloggs @@@
+ @@@ changelog-format: joebloggs @@@
</example>
Changelog format names are non-empty strings of alphanumerics.
</p>
<item>
<p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
</item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Build-Depends</tt> et
+ al.</qref> (source package interrelationships)
+ </p>
+ </item>
<item>
<p>
<qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
<p>
Field names are not case-sensitive, but it is usual to
- capitalise the fields using mixed case as shown below.
+ capitalise the field names using mixed case as shown below.
</p>
<p>
<footnote>
<p>
The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
- <tt>t</tt>t> <tt>_</tt> (at, colon, equals, percent
+ <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
and underscore) used to be legal and are still
accepted when found in a package file, but may not be
used in new packages
<p>
This is the architecture string; it is a single word for
- the CPU architecture.
+ the Debian architecture.
</p>
<p>
</p>
<p>
- The current build architecture can be determined using <tt>dpkg
- --print-architecture</tt>.
- <footnote>
- <p>
- This actually invokes
- <example>
- gcc --print-libgcc-file-name
- </example> and parses and decomposes the output and
- looks the CPU type from the GCC configuration in a
- table in <prgn>dpkg</prgn>. This is so that it will
- work if you're cross-compiling.
- </p>
- </footnote> This value is automatically used by
- <prgn>dpkg-gencontrol</prgn> when building the control
- file for a binary package for which the source control
- information doesn't specify architecture <tt>all</tt>.
+ See <ref id="debianrules"> for information how to get the
+ architecture for the build process.
</p>
-
- <p>
- There is a separate option,
- <tt>--print-installation-architecture</tt>, for finding
- out what architecture <prgn>dpkg</prgn> is willing to
- install. This information is also in the output of
- <tt>dpkg --version</tt>.</p>
</sect1>
<sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
the value from a <tt>.deb</tt> file if they have no other
information; a value listed in a <tt>Packages</tt> file
will always take precedence. By default
- <prgn>dpkg-genchanges</prgn> does not include the section
+ <prgn>dpkg-gencontrol</prgn> does not include the section
and priority in the control file of a binary package - use
the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
achieve this effect.</p>
been <em>frozen</em> for a month of testing. Once the
distribution is <em>stable</em> only major bug fixes
are allowed. When changes are made to this
- distribution, the minor version number is increased
- (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).
+ distribution, the release number is increased
+ (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
</p>
</item>
commentary (separated by a space) which is usually in
parentheses. For example:
<example>
- Urgency: LOW (HIGH for diversions users)
+ Urgency: LOW (HIGH for diversions users)
</example>
</p>
<p>
The <var>upstream-version</var> may contain only
- alphanumerics and the characters <tt>+</tt> <tt>.</tt>
+ alphanumerics and the characters <tt>.</tt> <tt>+</tt>
<tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
and should start with a digit. If there is no
<var>debian-revision</var> then hyphens are not allowed;
<p>
If you need to compare version numbers in a script, you may use
<tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
- --help</tt> --> --for details on arguments.
+ --help</tt> for details on arguments.
</p>
+
+ <sect>
+ <heading>Version numbers based on dates</heading>
+ <p>
+ In general, Debian packages should use the same version
+ numbers as the upstream sources.</p>
+
+ <p>
+ However, in some cases where the upstream version number is
+ based on a date (e.g., a development `snapshot' release)
+ dpkg cannot handle these version numbers currently, without
+ epochs. For example, dpkg will consider `96May01' to be
+ greater than `96Dec24'.</p>
+
+ <p>
+ To prevent having to use epochs for every new upstream
+ version, the version number should be changed to the
+ following format in such cases: `19960501', `19961224'. It
+ is up to the maintainer whether he/she wants to bother the
+ upstream maintainer to change the version numbers upstream,
+ too.</p>
+
+ <p>
+ Note, that other version formats based on dates which are
+ parsed correctly by dpkg should <em>not</em> be changed.</p>
+
+ <p>
+ Native Debian packages (i.e., packages which have been
+ written especially for Debian) whose version numbers include
+ dates should always use the `YYYYMMDD' format.</p>
+ </sect>
</chapt>
<chapt id="maintainerscripts"><heading>Package maintainer scripts
</heading>
<p>
- It is possible supply scripts as part of a package which
+ It is possible to supply scripts as part of a package which
<prgn>dpkg</prgn> will run for you when your package is
installed, upgraded or removed.
</p>
<item>
<p>
<var>disappearer's-postrm</var> <tt>disappear</tt>
- <var>r>overwrit</var>r>
- <var>new-version</var></p></item>
+ <var>overwriter</var>
+ <var>overwriter-version</var></p></item>
</list>
</p>
<p>If a version the package is already
installed, call
<example>
- <var>old-prerm</var> upgrade <var>new-version</var>
+ <var>old-prerm</var> upgrade <var>new-version</var>
</example></p>
</item>
<item>
If this gives an error (ie, a non-zero exit
status), dpkg will attempt instead:
<example>
- <var>new-prerm</var> failed-upgrade <var>old-version</var>
+ <var>new-prerm</var> failed-upgrade <var>old-version</var>
</example>
Error unwind, for both the above cases:
<example>
- <var>old-postinst</var> abort-upgrade <var>new-version</var>
+ <var>old-postinst</var> abort-upgrade <var>new-version</var>
</example>
</p>
</item>
package and <tt>--auto-deconfigure</tt> is
specified, call, for each such package:
<example>
- <var>deconfigured's-prerm</var> deconfigure \
- in-favour <var>package-being-installed</var> <var>version</var> \
- removing <var>conflicting-package</var> <var>version</var>
+ <var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
</example>
Error unwind:
<example>
- <var>deconfigured's-postinst</var> abort-deconfigure \
- in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
- removing <var>conflicting-package</var> <var>version</var>
+ <var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
</example>
The deconfigured packages are marked as
requiring configuration, so that if
<item>
<p>To prepare for removal of the conflicting package, call:
<example>
- <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+ <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
</example>
Error unwind:
<example>
- <var>conflictor's-postinst</var> abort-remove \
- in-favour <var>package</var> <var>new-version</var>
+ <var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
</example>
</p>
</item>
<item>
<p>If the package is being upgraded, call:
<example>
- <var>new-preinst</var> upgrade <var>old-version</var>
+ <var>new-preinst</var> upgrade <var>old-version</var>
</example></p>
</item>
<item>
files from a previous version installed (ie, it
is in the `configuration files only' state):
<example>
- <var>new-preinst</var> install <var>old-version</var>
+ <var>new-preinst</var> install <var>old-version</var>
</example></p>
<item>
<p>Otherwise (ie, the package was completely purged):
<example>
- <var>new-preinst</var> install
+ <var>new-preinst</var> install
</example>
Error unwind versions, respectively:
<example>
- <var>new-postrm</var> abort-upgrade <var>old-version</var>
- <var>new-postrm</var> abort-install <var>old-version</var>
- <var>new-postrm</var> abort-install
+ <var>new-postrm</var> abort-upgrade <var>old-version</var>
+ <var>new-postrm</var> abort-install <var>old-version</var>
+ <var>new-postrm</var> abort-install
</example>
</p>
</item>
<footnote>
<p>
Part of the problem is due to what is arguably a
- bug in <prgn>dpkg</prgn> .
+ bug in <prgn>dpkg</prgn>.
</p>
</footnote>
</p>
<item>
<p>If the package is being upgraded, call
<example>
- <var>old-postrm</var> upgrade <var>new-version</var>
+ <var>old-postrm</var> upgrade <var>new-version</var>
</example></p>
</item>
<item>
<p>If this fails, <prgn>dpkg</prgn> will attempt:
<example>
- <var>new-postrm</var> failed-upgrade <var>old-version</var>
+ <var>new-postrm</var> failed-upgrade <var>old-version</var>
</example>
Error unwind, for both cases:
<example>
- <var>old-preinst</var> abort-upgrade <var>new-version</var>
+ <var>old-preinst</var> abort-upgrade <var>new-version</var>
</example>
</p>
</item>
<item>
<p><prgn>dpkg</prgn> calls:
<example>
- <var>disappearer's-postrm</var> disappear \
- <var>overwriter</var> <var>overwriter-version</var>
- </example></p>
+ <var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example>
+ </p>
</item>
<item>
<p>The package's maintainer scripts are removed.
--install</tt>, or with <tt>--configure</tt>), we first
update the conffiles and then call:
<example>
- <var>postinst</var> configure <var>most-recently-configured-version</var>
+ <var>postinst</var> configure <var>most-recently-configured-version</var>
</example>
</p>
<p>
<enumlist>
<item>
- <p><example>
- <var>prerm</var> remove
- </example></p>
+ <p>
+ <example>
+ <var>prerm</var> remove
+ </example>
+ </p>
</item>
<item>
<p>
</item>
<item>
<p><example>
- <var>postrm</var> remove
+ <var>postrm</var> remove
</example></p>
</item>
<item>
</item>
<item>
<p><example>
- <var>postrm</var> purge
+ <var>postrm</var> purge
</example></p>
</item>
<item>
<p>
The field's format is as follows:
<example>
- Description: <var>single line synopsis</var>
- <var>extended description over several lines</var>
+ Description: <var>single line synopsis</var>
+ <var>extended description over several lines</var>
</example>
</p>
<p>
<example>
- Package: smail
- Version: 3.1.29.1-13
- Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
- Recommends: pine | mailx | elm | emacs | mail-user-agent
- Suggests: metamail
- Depends: cron, libc5
- Conflicts: sendmail
- Provides: mail-transport-agent
- Description: Electronic mail transport system.
- Smail is the recommended mail transport agent (MTA) for Debian.
- .
- An MTA is the innards of the mail system - it takes messages from
- user-friendly mailer programs and arranges for them to be delivered
- locally or passed on to other systems as required.
- .
- In order to make use of it you must have one or more user level
- mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
- and VM as mailreaders) installed. If you wish to send messages other
- than just to other users of your system you must also have appropriate
- networking support, in the form of IP or UUCP.
+ Package: smail
+ Version: 3.1.29.1-13
+ Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
+ Recommends: pine | mailx | elm | emacs | mail-user-agent
+ Suggests: metamail
+ Depends: cron, libc5
+ Conflicts: sendmail
+ Provides: mail-transport-agent
+ Description: Electronic mail transport system.
+ Smail is the recommended mail transport agent (MTA) for Debian.
+ .
+ An MTA is the innards of the mail system - it takes messages from
+ user-friendly mailer programs and arranges for them to be delivered
+ locally or passed on to other systems as required.
+ .
+ In order to make use of it you must have one or more user level
+ mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
+ and VM as mailreaders) installed. If you wish to send messages other
+ than just to other users of your system you must also have appropriate
+ networking support, in the form of IP or UUCP.
</example>
</p>
</sect>
<tt>Replaces</tt> control file fields.
</p>
+ <p>
+ Source packages may declare relationships to binary packages,
+ saying that they require certain binary packages being
+ installed or absent at the time of building the package.
+ </p>
+
+ <p>
+ This is done using the <tt>Build-Depends</tt>,
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
+ <tt>Build-Conflicts-Indep</tt> control file fields.
+ </p>
+
<sect id="depsyntax"><heading>Syntax of relationship fields
</heading>
package names separated by commas.
</p>
- <p>
- In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>
- and <tt>Pre-Depends</tt> (the fields which declare
- dependencies of the package in which they occur on other
- packages) these package names may also be lists of
- alternative package names, separated by vertical bar symbols
- <tt>|</tt> (pipe symbols).
+ <p>
+ In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
+ <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
+ <tt>Build-Depends-Indep</tt>(the fields which declare
+ dependencies of the package in which they occur on other
+ packages) these package names may also be lists of
+ alternative package names, separated by vertical bar symbols
+ <tt>|</tt> (pipe symbols).
</p>
<p>
<p>
For example:
<example>
- Package: metamail
- Version: 2.7-3
- Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ Package: metamail
+ Version: 2.7-3
+ Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
</example>
</p>
+
+ <p>
+ All fields that specify build-time relationships
+ (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
+ may be restricted to a certain set of architectures. This
+ is done in brackets after each individual package name and
+ the optional version specification. The brackets enclose a
+ list of Debian architecture names separated by whitespace.
+ An exclamation mark may be prepended to each name. If the
+ current Debian host architecture is not in this list and
+ there are no exclamation marks in the list, or it is in the
+ list with a prepended exclamation mark, the package name and
+ the associated version specification are ignored completely
+ for the purposes of defining the relationships.
+ </p>
+
+ <p>
+ For example:
+ <example>
+ Source: glibc
+ Build-Depends-Indep: texinfo
+ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
+ hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+ </example>
+ </p>
</sect>
-
- <sect><heading>Dependencies - <tt>Depends</tt>, <tt>Recommends</tt>,
- <tt>tt>Sugge</tt>tt>, <tt>Pre-Depends</tt>
+
+ <sect>
+ <heading>Binary Dependencies - <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
</heading>
<p>
This is used to declare that one package may be more
useful with one or more others. Using this field
tells the packaging system and the user that the
- listed packages are be related to this one and can
+ listed packages are related to this one and can
perhaps enhance its usefulness, but that installing
this one without them is perfectly reasonable.
</p>
</p>
</sect1>
- <sect id="conflicts"><heading>Alternative packages -
- <tt>tt>Confli</tt>tt> and <tt>Replaces</tt>
+ <sect id="conflicts"><heading>Alternative binary packages -
+ <tt>Conflicts</tt> and <tt>Replaces</tt>
</heading>
<p>
- When one package declares a conflict with another
+ When one binary package declares a conflict with another
<prgn>dpkg</prgn> will refuse to allow them to be installed
on the system at the same time.
</p>
<p>
- If one package is to be installed, the other must be removed first -
- if the package being installed is marked as replacing (<ref
- id="replaces">) the one on the system, or the one on the system is
- marked as deselected, or both packages are marked
- <tt>Essential</tt>, then <prgn>dpkg</prgn> will
- automatically remove the package which is causing the
- conflict, otherwise it will halt the installation of the new
- package with an error.
+ If one package is to be installed, the other must be removed
+ first - if the package being installed is marked as
+ replacing (<ref id="replaces">) the one on the system, or
+ the one on the system is marked as deselected, or both
+ packages are marked <tt>Essential</tt>, then
+ <prgn>dpkg</prgn> will automatically remove the package
+ which is causing the conflict, otherwise it will halt the
+ installation of the new package with an error. This
+ mechanism specifically doesn't work when the installed
+ package is tt>Essential</tt>, but the new package is not.
</p>
<p>
<sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
</heading>
- <p>
- As well as the names of actual (`concrete') packages, the
- package relationship fields <tt>Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt> and
- <tt>Conflicts</tt> may mention virtual packages.
+ <p>
+ As well as the names of actual (`concrete') packages, the
+ package relationship fields <tt>Depends</tt>,
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
+ mention virtual packages.
</p>
<p>
<tt>Provides</tt> control file field of another package.
The effect is as if the package(s) which provide a
particular virtual package name had been listed by name
- everywhere were the virtual package name appears.
+ everywhere the virtual package name appears.
</p>
<p>
packages which provide it. This is so that, for example,
supposing we have
<example>
- Package: vm
- Depends: emacs
+ Package: vm
+ Depends: emacs
</example>
and someone else releases an xemacs package they can say
<example>
- Package: xemacs
- Provides: emacs
+ Package: xemacs
+ Provides: emacs
</example> and all will work in the interim (until a purely
virtual package name is decided on and the <tt>emacs</tt>
and <tt>vm</tt> packages are changed to use it).
<p>
If you want to specify which of a set of real packages should be the
default to satisfy a particular dependency on a virtual package, you
- should list the real package as alternative before the virtual.
+ should list the real package as an alternative before the virtual.
</p>
</sect>
<p>
Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
<prgn>dselect</prgn> to resolve which package should be
- removed when a conflict - see <ref id="conflicts">. This
+ removed when there is a conflict - see <ref id="conflicts">. This
usage only takes effect when the two packages <em>do</em>
conflict, so that the two effects do not interfere with
each other.
<p>
For example, consider the set of packages:
<example>
- Package: glibcdoc
- Recommends: info-browser
-
- Package: info
- Provides: info-browser
-
- Package: emacs
- Provides: info-browser
+ Package: glibcdoc
+ Recommends: info-browser
+
+ Package: info
+ Provides: info-browser
+
+ Package: emacs
+ Provides: info-browser
</example>
</p>
same priority then <prgn>dselect</prgn>'s choice is
essentially random. Better would be
<example>
- Package: glibcdoc
- Recommends: info | info-browser
+ Package: glibcdoc
+ Recommends: info | info-browser
</example>
so that <prgn>dselect</prgn> defaults to selecting the
lightweight standalone info browser.
</p>
</sect>
- </chapt>
+
+ <sect><heading>Relationships between source and binary packages -
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
+ </heading>
+
+ <p>
+ A source package may declare a dependency or a conflict on a
+ binary package. This is done with the control file fields
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt>, and <tt>Build-Conflicts-Indep</tt>. Their
+ semantics is that the dependencies and conflicts they define
+ must be satisfied (as defined earlier for binary packages),
+ when one of the targets in <tt>debian/rules</tt> that the
+ particular field applies to is invoked.
+
+ <taglist>
+ <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
+ <item>
+ <p>
+ The <tt>Build-Depends</tt> and
+ <tt>Build-Conflicts</tt> fields apply to the targets
+ <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
+ and <tt>binary-indep</tt>.
+ </p>
+ </item>
+ <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
+ <item>
+ <p>
+ The <tt>Build-Depends-Indep</tt> and
+ <tt>Build-Conflicts-Indep</tt> fields apply to the
+ targets <tt>binary</tt> and <tt>binary-indep</tt>.
+ </p>
+ </item>
+ </taglist>
+
+ </p>
+
+ </sect>
+ </chapt>
+
+
<chapt id="conffiles"><heading>Configuration file handling
</heading>
<p>
If neither the user nor the package maintainer has changed
the file, it is left alone. If one or the other has changed
- their version, then the changed version is preferred - ie,
+ their version, then the changed version is preferred - i.e.,
if the user edits their file, but the package maintainer
doesn't ship a different version, the user's changes will
stay, silently, but if the maintainer ships a new version
supposing that a <prgn>smailwrapper</prgn> package wishes to
install a wrapper around <tt>/usr/sbin/smail</tt>:
<example>
- if [ install = "$1" ]; then
- dpkg-divert --package smailwrapper --add --rename \
- --divert /usr/sbin/smail.real /usr/sbin/smail
- fi
+ if [ install = "$1" -o upgrade = "$1" ]; then
+ dpkg-divert --package smailwrapper --add --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
</example> Testing <tt>$1</tt> is necessary so that the script
doesn't try to add the diversion again when
<prgn>smailwrapper</prgn> is upgraded. The <tt>--package
<p>
The postrm has to do the reverse:
<example>
- if [ remove = "$1" ]; then
- dpkg-divert --package smailwrapper --remove --rename \
- --divert /usr/sbin/smail.real /usr/sbin/smail
- fi
+ if [ remove = "$1" ]; then
+ dpkg-divert --package smailwrapper --remove --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
</example>
</p>
<tt>libgdbm.so.1.7.3</tt>. This is needed so that
<prgn>ld.so</prgn> can find the library in between the time
<prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
- in the <prgn>postinst</prgn> script. Futhermore, and <em>this
- is very important</em>, the library must be placed before the
- symlink pointing to it in the <tt>.deb</tt> file. This is so
- that by the time <prgn>dpkg</prgn> comes to install the
- symlink (overwriting the previous symlink pointing at an older
- version of the library) the new shared library is already in
- place. Currently the way to ensure the ordering is done
- properly is to install the library in the appropriate
- <tt>debian/tmp/.../lib</tt> directory before creating the
- symlink, by putting the commands in the <tt>debian/rules</tt>
- in the appropriate order.
+ in the <prgn>postinst</prgn> script. Futhermore, older
+ versions of the package management system required the library
+ must be placed before the symlink pointing to it in the
+ <tt>.deb</tt> file. This is so that by the time
+ <prgn>dpkg</prgn> comes to install the symlink (overwriting
+ the previous symlink pointing at an older version of the
+ library) the new shared library is already in place.
+ Unfortunately, this was not not always possible, since it
+ highly depends on the behaviour of the filesystem. Some
+ filesystems (such as reisefs) will reorder the files so it
+ doesn't matter in what order you create them. In newer
+ versions of <prgn>dpkg</prgn>, this is handled automatically.
</p>
<!--
<p>
Each line is of the form:
<example>
- <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
+ <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
</example>
</p>
<var>1.2.3-1</var>, then the package's <var>shlibs</var>
could say:
<example>
- libfoo 1 foo (>= 1.2.3-1)
+ libfoo 1 foo (>= 1.2.3-1)
</example>
</p>
<tt>debian/rules</tt> file. If your package contains
only binaries (e.g. no scripts) use:
<example>
- dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
+ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
</example>
If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
done. If it does complain you might need to create your
Create a <tt>debian/shlibs</tt> file and let
<tt>debian/rules</tt> install it in the control area:
<example>
- install -m644 debian/shlibs debian/tmp/DEBIAN
+ install -m644 debian/shlibs debian/tmp/DEBIAN
</example>
If your package contains additional binaries see above.
</p>
<p>
This file is intended only as a <em>temporary</em> fix if
your binaries depend on a library which doesn't provide
- its own <tt>/var/lib/dpkg/*.shlibs</tt> file yet.
+ its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
</p>
<p>
Let's assume you are packaging a binary <tt>foo</tt>. Your
output in building the package might look like this.
<example>
- $ ldd foo
- libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
- libc.so.5 => /lib/libc.so.5.2.18
- libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
+ $ ldd foo
+ libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
+ libc.so.5 => /lib/libc.so.5.2.18
+ libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
</example>
And when you ran <prgn>dpkg-shlibdeps</prgn>
<example>
- $ dpkg-shlibdeps -o foo
- dpkg-shlibdeps: warning: unable to find dependency information
- for shared library libbar
- (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
- shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
+ $ dpkg-shlibdeps -o foo
+ dpkg-shlibdeps: warning: unable to find dependency information
+ for shared library libbar
+ (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
+ shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
</example>
The <prgn>foo</prgn> binary depends on the
<prgn>libbar</prgn> shared library, but no package seems
<p>
<example>
- $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
- bar1: /usr/X11R6/lib/libbar.so.1.0
- $ dpkg -s bar1 | grep Version
- Version: 1.0-1
+ $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
+ bar1: /usr/X11R6/lib/libbar.so.1.0
+ $ dpkg -s bar1 | grep Version
+ Version: 1.0-1
</example>
This tells us that the <prgn>bar1</prgn> package, version
1.0-1 is the one we are using. Now we can create our own
problem. Include the following line into your
<tt>debian/shlibs.local</tt> file.
<example>
- libbar 1 bar1 (>= 1.0-1)
+ libbar 1 bar1 (>= 1.0-1)
</example>
Now your package build should work. As soon as the
maintainer of <prgn>libbar1</prgn> provides a
<p>
<tt>names</tt> will be formatted as a list of lines, each containing:
<example>
- <var>sequence</var> <var>method</var> <var>summary</var>
+ <var>sequence</var> <var>method</var> <var>summary</var>
</example>
</p>
<p>
appropriate details, and a local variables entry to the
bottom to set Emacs to the right mode:
<example>
- Local variables:
- mode: debian-changelog
- End:
+ Local variables:
+ mode: debian-changelog
+ End:
</example>
</p>
</item>
</book>
</debiandoc>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-