<name>Maintainer: Manoj Srivastava </name>
<email>srivasta@debian.org</email>
</author>
+ <author>
+ <name>Maintainer: Julian Gilbey </name>
+ <email>J.D.Gilbey@qmw.ac.uk</email>
+ </author>
<author>
<name>Maintainer: The Debian Policy group </name>
<email>debian-policy@lists.debian.org</email>
<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>Julian Gilbey <email>J.D.Gilbey@qmw.ac.uk</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>
</footnote>
</p>
</sect>
-
+ </chapt>
+
<chapt id="sourcepkg">
<heading>Source packages</heading>
</p>
<p>
- Its arguments are executables
+ Its arguments are executables and libraries
<footnote>
<p>
They may be specified either in the locations in the
</p>
<p>
- If some of the executable(s) shared libraries should only
+ If some of the found shared libraries should only
warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
some warrant a <tt>Pre-Depends</tt>, this can be achieved
by using the <tt>-d<var>dependency-field</var></tt> option
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>
<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>
<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>
<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>
<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>
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>
<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.
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
+ if [ install = "$1" -o upgrade = "$1" ]; then
dpkg-divert --package smailwrapper --add --rename \
--divert /usr/sbin/smail.real /usr/sbin/smail
fi
<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>
<!--
<sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
work?
</heading>
-
<p>
- <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
- determine the shared libraries used by the compiled
- binaries passed through its command line.
+ <prgn>dpkg-shlibdeps</prgn> calls <prgn>objdump</prgn> to
+ determine the shared libraries directly
+ <footnote> a binary <tt>foo</tt> directly use a library
+ <tt>libbar</tt> if it is linked with that library. Other
+ libraries that are needed by <tt>libbar</tt> are linked
+ indirectly to <tt>foo</tt>, and the dynamic linker will load
+ the automatically when it loads <tt>libbar</tt>.
+ </footnote> used by the compiled binaries and libraries
+ passed through its command line.
</p>
<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>
</book>
</debiandoc>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
projects / debian / debian-policy.git / blobdiff