<!-- include version information so we don't have to hard code it
within the document -->
<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+<!-- current Debian changes file format -->
+<!entity changesversion "1.8">
]>
<debiandoc>
</p>
<p>
- You should not use <prgn>dpkg-divert</prgn> on a file
- belonging to another package without consulting the
- maintainer of that package first.
+ You should not use <prgn>dpkg-divert</prgn> on a file belonging
+ to another package without consulting the maintainer of that
+ package first. When adding or removing diversions, package
+ maintainer scripts must provide the <tt>--package</tt> flag
+ to <prgn>dpkg-divert</prgn> and must not use <tt>--local</tt>.
</p>
<p>
The <tt>build</tt> target should perform all the
configuration and compilation of the package.
If a package has an interactive pre-build
- configuration routine, the Debianized source package
+ configuration routine, the Debian source package
must either be built after this has taken place (so
that the binary package can be built without rerunning
the configuration) or the configuration routine
These fields are used by <prgn>dpkg-gencontrol</prgn> to
generate control files for binary packages (see below), by
<prgn>dpkg-genchanges</prgn> to generate the
- <tt>.changes</tt> file to accompany the upload, and by
+ <file>.changes</file> file to accompany the upload, and by
<prgn>dpkg-source</prgn> when it creates the
<file>.dsc</file> source control file as part of a source
archive. Many fields are permitted to span multiple lines in
<p>
The <file>DEBIAN/control</file> file contains the most vital
- (and version-dependent) information about a binary package.
+ (and version-dependent) information about a binary package. It
+ consists of a single paragraph.
</p>
<p>
<heading>Debian source control files -- <tt>.dsc</tt></heading>
<p>
- This file contains a series of fields, identified and
- separated just like the fields in the control file of
- a binary package. The fields are listed below; their
- syntax is described above, in <ref id="pkg-controlfields">.
+ This file consists of a single paragraph, possibly surrounded by
+ a PGP signature. The fields of that paragraph are listed below.
+ Their syntax is described above, in <ref id="pkg-controlfields">.
<list compact="compact">
<item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
<heading>Debian changes files -- <file>.changes</file></heading>
<p>
- The .changes files are used by the Debian archive maintenance
- software to process updates to packages. They contain one
- paragraph which contains information from the
- <tt>debian/control</tt> file and other data about the
- source package gathered via <tt>debian/changelog</tt>
- and <tt>debian/rules</tt>.
+ The <file>.changes</file> files are used by the Debian archive
+ maintenance software to process updates to packages. They
+ consist of a single paragraph, possibly surrounded by a PGP
+ signature. That paragraph contains information from the
+ <file>debian/control</file> file and other data about the
+ source package gathered via <file>debian/changelog</file>
+ and <file>debian/rules</file>.
+ </p>
+
+ <p>
+ <file>.changes</file> files have a format version that is
+ incremented whenever the documented fields or their meaning
+ change. This document describes format &changesversion;.
</p>
<p>
It is optional; if it isn't present then the
<var>upstream_version</var> may not contain a hyphen.
This format represents the case where a piece of
- software was written specifically to be turned into a
- Debian package, and so there is only one "debianisation"
- of it and therefore no revision indication is required.
+ software was written specifically to be a Debian
+ package, where the Debian package source must always
+ be identical to the pristine source and therefore no
+ revision indication is required.
</p>
<p>
<heading><tt>Format</tt></heading>
<p>
- This field specifies a format revision for the file.
- The most current format described in the Policy Manual
- is version <strong>1.5</strong>. The syntax of the
- format value is the same as that of a package version
- number except that no epoch or Debian revision is allowed
- - see <ref id="f-Version">.
+ In <qref id="debianchangesfiles"><file>.changes</file></qref>
+ files, this field declares the format version of that file.
+ The syntax of the field value is the same as that of
+ a <qref id="f-Version">package version number</qref> except
+ that no epoch or Debian revision is allowed. The format
+ described in this document is <tt>&changesversion;</tt>.
+ </p>
+
+ <p>
+ In <qref id="debiansourcecontrolfiles"><file>.dsc</file>
+ Debian source control</qref> files, this field declares the
+ format of the source package. The field value is used by
+ programs acting on a source package to interpret the list of
+ files in the source package and determine how to unpack it.
+ The syntax of the field value is a numeric major revision, a
+ period, a numeric minor revision, and then an optional subtype
+ after whitespace, which if specified is an alphanumeric word
+ in parentheses. The subtype is optional in the syntax but may
+ be mandatory for particular source format revisions.
+ <footnote>
+ The source formats currently supported by the Debian archive
+ software are <tt>1.0</tt>, <tt>3.0 (native)</tt>,
+ and <tt>3.0 (quilt)</tt>.
+ </footnote>
</p>
</sect1>
must match the list of files in the <tt>Files</tt> field.
</p>
</sect1>
-
</sect>
<sect>
</p>
<p>
- All fields that specify build-time relationships
+ Relationships may be restricted to a certain set of
+ architectures. This is indicated in brackets after each
+ individual package name and the optional version specification.
+ The brackets enclose a list of Debian architecture names
+ separated by whitespace. Exclamation marks may be prepended to
+ each of the names. (It is not permitted for some names to be
+ prepended with exclamation marks while others aren't.)
+ </p>
+
+ <p>
+ For build relationship fields
(<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 indicated in brackets after each individual package name and
- the optional version specification. The brackets enclose a
- list of Debian architecture names separated by whitespace.
- Exclamation marks may be prepended to each of the names.
- (It is not permitted for some names to be prepended with
- exclamation marks while others aren't.) 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.
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>), 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>
<tt>gnumach-dev</tt> only on hurd-i386.
</p>
+ <p>
+ For binary relationship fields, the architecture restriction
+ syntax is only supported in the source package control
+ file <file>debian/control</file>. When the corresponding binary
+ package control file is generated, the relationship will either
+ be omitted or included without the architecture restriction
+ based on the architecture of the binary package. This means
+ that architecture restrictions must not be used in binary
+ relationship fields for architecture-independent packages
+ (<tt>Architecture: all</tt>).
+ </p>
+
+ <p>
+ For example:
+ <example compact="compact">
+Depends: foo [i386], bar [amd64]
+ </example>
+ becomes <tt>Depends: foo</tt> when the package is built on
+ the <tt>i386</tt> architecture, <tt>Depends: bar</tt> when the
+ package is built on the <tt>amd64</tt> architecture, and omitted
+ entirely in binary packages built on all other architectures.
+ </p>
+
<p>
If the architecture-restricted dependency is part of a set of
alternatives using <tt>|</tt>, that alternative is ignored
</p>
<p>
- All fields that specify build-time relationships may also be
- restricted to a certain set of architectures using architecture
- wildcards. The syntax for declaring such restrictions is the
- same as declaring restrictions using a certain set of
- architectures without architecture wildcards. For example:
+ Relationships may also be restricted to a certain set of
+ architectures using architecture wildcards. The syntax for
+ declaring such restrictions is the same as declaring
+ restrictions using a certain set of architectures without
+ architecture wildcards. For example:
<example compact="compact">
Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
</example>
version of an (implicit or explicit) dependency which violates
an assumption or reveals a bug in earlier versions of the broken
package, or which takes over a file from earlier versions of the
- broken package. This use of <tt>Breaks</tt> will inform
- higher-level package management tools that the broken package
- must be upgraded before the new one.
+ package named in <tt>Breaks</tt>. This use of <tt>Breaks</tt>
+ will inform higher-level package management tools that the
+ broken package must be upgraded before the new one.
</p>
<p>
<tt>Conflicts</tt> should be used
<list>
<item>when two packages provide the same file and will
- continue to do so (but be aware that this is often an error
- that should be fixed rather than using <tt>Conflicts</tt> --
- see, for example, <ref id="binaries">),</item>
+ continue to do so,</item>
<item>in conjunction with <tt>Provides</tt> when only one
package providing a given virtual facility may be installed
at a time (see <ref id="virtual">),</item>
that must prevent both packages from being unpacked at the
same time, not just configured.</item>
</list>
+ Be aware that adding <tt>Conflicts</tt> is normally not the best
+ solution when two packages provide the same files. Depending on
+ the reason for that conflict, using alternatives or renaming the
+ files is often a better approach. See, for
+ example, <ref id="binaries">.
+ </p>
+
+ <p>
+ Neither <tt>Breaks</tt> nor <tt>Conflicts</tt> should be used
+ unless two packages cannot be installed at the same time or
+ installing them both causes one of them to be broken or
+ unusable. Having similar functionality or performing the same
+ tasks as another package is not sufficient reason to
+ declare <tt>Breaks</tt> or <tt>Conflicts</tt> with that package.
</p>
<p>
breakage). In other words, if a version number is specified,
this is a request to ignore all <tt>Provides</tt> for that
package name and consider only real packages. The package
- manager will assume that a package which package which provides
- that virtual package is not of the "right" version.
- A <tt>Provides</tt> field may not contain version numbers, and
- the version number of the concrete package which provides a
- particular virtual package will not be considered when
- considering a dependency on or conflict with the virtual package
- name.<footnote>
+ manager will assume that a package providing that virtual
+ package is not of the "right" version. A <tt>Provides</tt>
+ field may not contain version numbers, and the version number of
+ the concrete package which provides a particular virtual package
+ will not be considered when considering a dependency on or
+ conflict with the virtual package name.<footnote>
It is possible that a future release of <prgn>dpkg</prgn> may
add the ability to specify a version number for each virtual
package it provides. This feature is not yet present,
package and will be taken over by the new package.
Normally, <tt>Breaks</tt> should be used in conjunction
with <tt>Replaces</tt>.<footnote>
- To see why <tt>Breaks</tt> is required in addition
- to <tt>Provides</tt>, consider the
- case of a file in the package <package>foo</package> being
-
taken over by the package <package>foo-data</package>.
+ To see why <tt>Breaks</tt> is normally needed in addition
+ to <tt>Replaces</tt>, consider the case of a file in the
+ package <package>foo</package> being taken over by the
+ package <package>foo-data</package>.
<tt>Replaces</tt> will allow <package>foo-data</package> to
be installed and take over that file. However,
without <tt>Breaks</tt>, nothing
<example compact="compact">
Replaces: foo (<< 1.2-3)
Breaks: foo (<< 1.2-3)
- </example compact="compact">
+ </example>
in its control file. The new version of the
package <package>foo</package> would normally have the field
- <example>
+ <example compact="compact">
Depends: foo-data (>= 1.2-3)
</example>
(or possibly <tt>Recommends</tt> or even <tt>Suggests</tt> if
<p>
There is no Build-Depends-Arch; this role is essentially
met with Build-Depends. Anyone building the
- <tt>build-indep</tt> and binary-indep<tt></tt> targets is
+ <tt>build-indep</tt> and <tt>binary-indep</tt> targets is
assumed to be building the whole package, and therefore
installation of all build dependencies is required.
</p>
</p>
<p>
- Thus, when a package is built which contains any shared
- libraries, it must provide a <file>shlibs</file> file for other
- packages to use, and when a package is built which contains
- any shared libraries or compiled binaries, it must run
+ When a package is built which contains any shared libraries, it
+ must provide a <file>shlibs</file> file for other packages to
+ use. When a package is built which contains any shared
+ libraries or compiled binaries, it must run
<qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
on these to determine the libraries used and hence the
dependencies needed by this package.<footnote>
<p>
- In the past, the shared libraries linked to were
- determined by calling <prgn>ldd</prgn>, but now
- <prgn>objdump</prgn> is used to do this. The only
- change this makes to package building is that
- <prgn>dpkg-shlibdeps</prgn> must also be run on shared
- libraries, whereas in the past this was unnecessary.
- The rest of this footnote explains the advantage that
- this method gives.
+ <prgn>dpkg-shlibdeps</prgn> will use a program
+ like <prgn>objdump</prgn> or <prgn>readelf</prgn> to find
+ the libraries directly needed by the binaries or shared
+ libraries in the package.
</p>
<p>
We say that a binary <tt>foo</tt> <em>directly</em> uses
a library <tt>libbar</tt> if it is explicitly linked
- with that library (that is, it uses the flag
- <tt>-lbar</tt> during the linking stage). Other
+ with that library (that is, the library is listed in the ELF
+ <tt>NEEDED</tt> attribute, caused by adding <tt>-lbar</tt>
+ to the link line when the binary is created). Other
libraries that are needed by <tt>libbar</tt> are linked
<em>indirectly</em> to <tt>foo</tt>, and the dynamic
linker will load them automatically when it loads
- <tt>libbar</tt>. A package should depend on
- the libraries it directly uses, and the dependencies for
- those libraries should automatically pull in the other
- libraries.
- </p>
-
- <p>
- Unfortunately, the <prgn>ldd</prgn> program shows both
- the directly and indirectly used libraries, meaning that
- the dependencies determined included both direct and
- indirect dependencies. The use of <prgn>objdump</prgn>
- avoids this problem by determining only the directly
- used libraries.
+ <tt>libbar</tt>. A package should depend on the libraries
+ it directly uses, but not the libraries it indirectly uses.
+ The dependencies for those libraries will automatically pull
+ in the other libraries.
</p>
<p>
A good example of where this helps is the following. We
could update <tt>libimlib</tt> with a new version that
- supports a new graphics format called dgf (but retaining
- the same major version number). If we used the old
- <prgn>ldd</prgn> method, every package that uses
- <tt>libimlib</tt> would need to be recompiled so it
- would also depend on <tt>libdgf</tt> or it wouldn't run
- due to missing symbols. However with the new system,
- packages using <tt>libimlib</tt> can rely on
- <tt>libimlib</tt> itself having the dependency on
- <tt>libdgf</tt> and so they would not need rebuilding.
+ supports a new graphics format called dgf (but retaining the
+ same major version number) and depends on <tt>libdgf</tt>.
+ If we used <prgn>ldd</prgn> to add dependencies for every
+ library directly or indirectly linked with a binary, every
+ package that uses <tt>libimlib</tt> would need to be
+ recompiled so it would also depend on <tt>libdgf</tt> or it
+ wouldn't run due to missing symbols. Since dependencies are
+ only added based on ELF <tt>NEEDED</tt> attribute, packages
+ using <tt>libimlib</tt> can rely on <tt>libimlib</tt> itself
+ having the dependency on <tt>libdgf</tt> and so they would
+ not need rebuilding.
</p>
</footnote>
</p>
<p><file>debian/shlibs.local</file></p>
<p>
- This lists overrides for this package. Its use is
- described below (see <ref id="shlibslocal">).
+ This lists overrides for this package. This file should
+ normally not be used, but may be needed temporarily in
+ unusual situations to work around bugs in other packages,
+ or in unusual cases where the normally declared dependency
+ information in the installed <file>shlibs</file> file for
+ a library cannot be used. This file overrides information
+ obtained from any other source.
</p>
</item>
<p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
<p>
- When packages are being built, any
- <file>debian/shlibs</file> files are copied into the
+ When packages are being built,
+ any <file>debian/shlibs</file> files are copied into the
control file area of the temporary build directory and
given the name <file>shlibs</file>. These files give
- details of any shared libraries included in the
+ details of any shared libraries included in the same
package.<footnote>
- An example may help here. Let us say that the
- source package <tt>foo</tt> generates two binary
- packages, <tt>libfoo2</tt> and
- <tt>foo-runtime</tt>. When building the binary
- packages, the two packages are created in the
- directories <file>debian/libfoo2</file> and
- <file>debian/foo-runtime</file> respectively.
- (<file>debian/tmp</file> could be used instead of one
- of these.) Since <tt>libfoo2</tt> provides the
- <tt>libfoo</tt> shared library, it will require a
- <tt>shlibs</tt> file, which will be installed in
- <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
- to become
- <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
- when <prgn>dpkg-shlibdeps</prgn> is run on the
- executable
- <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
- will examine the
- <file>debian/libfoo2/DEBIAN/shlibs</file> file to
- determine whether <tt>foo-prog</tt>'s library
- dependencies are satisfied by any of the libraries
- provided by <tt>libfoo2</tt>. For this reason,
- <prgn>dpkg-shlibdeps</prgn> must only be run once
- all of the individual binary packages'
- <tt>shlibs</tt> files have been installed into the
- build directory.
+ An example may help here. Let us say that the source
+ package <tt>foo</tt> generates two binary
+ packages, <tt>libfoo2</tt> and <tt>foo-runtime</tt>.
+ When building the binary packages, the two packages are
+ created in the directories <file>debian/libfoo2</file>
+ and <file>debian/foo-runtime</file> respectively.
+ (<file>debian/tmp</file> could be used instead of one of
+ these.) Since <tt>libfoo2</tt> provides the
+ <tt>libfoo</tt> shared library, it will require a
+ <tt>shlibs</tt> file, which will be installed in
+ <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually to
+ become <file>/var/lib/dpkg/info/libfoo2.shlibs</file>.
+ When <prgn>dpkg-shlibdeps</prgn> is run on the
+ executable <file>debian/foo-runtime/usr/bin/foo-prog</file>,
+ it will examine
+ the <file>debian/libfoo2/DEBIAN/shlibs</file> file to
+ determine whether <tt>foo-prog</tt>'s library
+ dependencies are satisfied by any of the libraries
+ provided by <tt>libfoo2</tt>. For this reason,
+ <prgn>dpkg-shlibdeps</prgn> must only be run once all of
+ the individual binary packages' <tt>shlibs</tt> files
+ have been installed into the build directory.
</footnote>
</p>
</item>
</example>
Otherwise, you will need to explicitly list the compiled
binaries and libraries.<footnote>
- If you are using <tt>debhelper</tt>, the
- <prgn>dh_shlibdeps</prgn> program will do this work for
- you. It will also correctly handle multi-binary
- packages.
+ If you are using <tt>debhelper</tt>, the
+ <prgn>dh_shlibdeps</prgn> program will do this work for you.
+ It will also correctly handle multi-binary packages.
</footnote>
</p>
field in the control file for this to work.
</p>
- <p>
- If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
- done. If it does complain you might need to create your own
- <file>debian/shlibs.local</file> file, as explained below (see
- <ref id="shlibslocal">).
- </p>
-
<p>
If you have multiple binary packages, you will need to call
<prgn>dpkg-shlibdeps</prgn> on each one which contains
you will need to specify that <prgn>dpkg-shlibdeps</prgn>
should use the dependency line of type <tt>udeb</tt> by
adding the <tt>-tudeb</tt> option<footnote>
- <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
- will automatically add this option if it knows it is
- processing a udeb.
- </footnote>. If there is no dependency line of type <tt>udeb</tt>
- in the <file>shlibs</file> file, <prgn>dpkg-shlibdeps</prgn> will
- fall back to the regular dependency line.
+ <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
+ will automatically add this option if it knows it is
+ processing a udeb.
+ </footnote>. If there is no dependency line of
+ type <tt>udeb</tt> in the <file>shlibs</file>
+ file, <prgn>dpkg-shlibdeps</prgn> will fall back to the regular
+ dependency line.
</p>
<p>
- For more details on dpkg-shlibdeps, please see
+ For more details on <prgn>dpkg-shlibdeps</prgn>, please see
<ref id="pkg-dpkg-shlibdeps"> and
<manref name="dpkg-shlibdeps" section="1">.
</p>
usually of the form
<tt><var>name</var>.so.<var>major-version</var></tt>, in our
example, <tt>libz.so.1</tt>.<footnote>
- This can be determined using the command
- <example compact="compact">
+ This can be determined using the command
+ <example compact="compact">
objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
- </example>
+ </example>
</footnote>
The version part is the part which comes after
- <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
+ <tt>.so.</tt>, so in our case, it is <tt>1</tt>. The soname may
+ instead be of the form
+ <tt><var>name</var>-<var>major-version</var>.so</tt>, such
+ as <tt>libdb-4.8.so</tt>, in which case the name would
+ be <tt>libdb</tt> and the version would be <tt>4.8</tt>.
</p>
<p>
<file>shlibs</file> file in the control area directly from
<file>debian/rules</file> without using a <file>debian/shlibs</file>
file at all,<footnote>
- This is what <prgn>dh_makeshlibs</prgn> in the
- <tt>debhelper</tt> suite does. If your package also has a udeb
- that provides a shared library, <prgn>dh_makeshlibs</prgn> can
- automatically generate the <tt>udeb:</tt> lines if you specify
- the name of the udeb with the <tt>--add-udeb</tt> option.
+ This is what <prgn>dh_makeshlibs</prgn> in
+ the <package>debhelper</package> suite does. If your package
+ also has a udeb that provides a shared
+ library, <prgn>dh_makeshlibs</prgn> can automatically generate
+ the <tt>udeb:</tt> lines if you specify the name of the udeb
+ with the <tt>--add-udeb</tt> option.
</footnote>
since the <file>debian/shlibs</file> file itself is ignored by
<prgn>dpkg-shlibdeps</prgn>.
packages.
</p>
</sect1>
-
- <sect1 id="shlibslocal">
- <heading>Writing the <file>debian/shlibs.local</file> file</heading>
-
- <p>
- This file is intended only as a <em>temporary</em> fix if
- your binaries or libraries depend on a library whose package
- does not yet provide a correct <file>shlibs</file> file.
- </p>
-
- <p>
- We will assume that you are trying to package a binary
- <tt>foo</tt>. When you try running
- <prgn>dpkg-shlibdeps</prgn> you get the following error
- message (<tt>-O</tt> displays the dependency information on
- <tt>stdout</tt> instead of writing it to
- <tt>debian/substvars</tt>, and the lines have been wrapped
- for ease of reading):
- <example compact="compact">
-$ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
-dpkg-shlibdeps: warning: unable to find dependency
- information for shared library libbar (soname 1,
- path /usr/lib/libbar.so.1, dependency field Depends)
-shlibs:Depends=libc6 (>= 2.2.2-2)
- </example>
- You can then run <prgn>ldd</prgn> on the binary to find the
- full location of the library concerned:
- <example compact="compact">
-$ ldd foo
-libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
-libc.so.6 => /lib/libc.so.6 (0x40032000)
-/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
- </example>
- So the <prgn>foo</prgn> binary depends on the
- <prgn>libbar</prgn> shared library, but no package seems to
- provide a <file>*.shlibs</file> file handling
- <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
- determine the package responsible:
- <example compact="compact">
-$ dpkg -S /usr/lib/libbar.so.1
-bar1: /usr/lib/libbar.so.1
-$ dpkg -s bar1 | grep Version
-Version: 1.0-1
- </example>
- This tells us that the <tt>bar1</tt> package, version 1.0-1,
- is the one we are using. Now we can file a bug against the
- <tt>bar1</tt> package and create our own
- <file>debian/shlibs.local</file> to locally fix the problem.
- Including the following line into your
- <file>debian/shlibs.local</file> file:
- <example compact="compact">
-libbar 1 bar1 (>= 1.0-1)
- </example>
- should allow the package build to work.
- </p>
-
- <p>
- As soon as the maintainer of <tt>bar1</tt> provides a
- correct <file>shlibs</file> file, you should remove this line
- from your <file>debian/shlibs.local</file> file. (You should
- probably also then have a versioned <tt>Build-Depends</tt>
- on <tt>bar1</tt> to help ensure that others do not have the
- same problem building your package.)
- </p>
- </sect1>
-
</sect>
-
</chapt>
for C files) will need to be compiled twice, for the normal
case.
</p>
+
<p>
- You must specify the gcc option <tt>-D_REENTRANT</tt>
- when building a library (either static or shared) to make
- the library compatible with LinuxThreads.
+ Libraries should be built with threading support and to be
+ thread-safe if the library supports this.
</p>
<p>
</p>
<p>
- An ever increasing number of packages are using
- <prgn>libtool</prgn> to do their linking. The latest GNU
- libtools (>= 1.3a) can take advantage of the metadata in the
- installed <prgn>libtool</prgn> archive files (<file>*.la</file>
- files). The main advantage of <prgn>libtool</prgn>'s
- <file>.la</file> files is that it allows <prgn>libtool</prgn> to
- store and subsequently access metadata with respect to the
- libraries it builds. <prgn>libtool</prgn> will search for
- those files, which contain a lot of useful information about
- a library (such as library dependency information for static
- linking). Also, they're <em>essential</em> for programs
- using <tt>libltdl</tt>.<footnote>
- Although <prgn>libtool</prgn> is fully capable of
- linking against shared libraries which don't have
- <tt>.la</tt> files, as it is a mere shell script it can
- add considerably to the build time of a
- <prgn>libtool</prgn>-using package if that shell script
- has to derive all this information from first principles
- for each library every time it is linked. With the
- advent of <prgn>libtool</prgn> version 1.4 (and to a
- lesser extent <prgn>libtool</prgn> version 1.3), the
- <file>.la</file> files also store information about
- inter-library dependencies which cannot necessarily be
- derived after the <file>.la</file> file is deleted.
+ Packages that use <prgn>libtool</prgn> to create and install
+ their shared libraries install a file containing additional
+ metadata (ending in <file>.la</file>) alongside the library.
+ For public libraries intended for use by other packages, these
+ files normally should not be included in the Debian package,
+ since the information they include is not necessary to link with
+ the shared library on Debian and can add unnecessary additional
+ dependencies to other programs or libraries.<footnote>
+ These files store, among other things, all libraries on which
+ that shared library depends. Unfortunately, if
+ the <file>.la</file> file is present and contains that
+ dependency information, using <prgn>libtool</prgn> when
+ linking against that library will cause the resulting program
+ or library to be linked against those dependencies as well,
+ even if this is unnecessary. This can create unneeded
+ dependencies on shared library packages that would otherwise
+ be hidden behind the library ABI, and can make library
+ transitions to new SONAMEs unnecessarily complicated and
+ difficult to manage.
</footnote>
+ If the <file>.la</file> file is required for that library (if,
+ for instance, it's loaded via <tt>libltdl</tt> in a way that
+ requires that meta-information), the <tt>dependency_libs</tt>
+ setting in the <file>.la</file> file should normally be set to
+ the empty string. If the shared library development package has
+ historically included the <file>.la</file>, it must be retained
+ in the development package (with <tt>dependency_libs</tt>
+ emptied) until all libraries that depend on it have removed or
+ emptied <tt>dependency_libs</tt> in their <file>.la</file>
+ files to prevent linking with those other libraries
+ using <prgn>libtool</prgn> from failing.
+ </p>
+
+ <p>
+ If the <file>.la</file> must be included, it should be included
+ in the development (<tt>-dev</tt>) package, unless the library
+ will be loaded by <prgn>libtool</prgn>'s <tt>libltdl</tt>
+ library. If it is intended for use with <tt>libltdl</tt>,
+ the <file>.la</file> files must go in the run-time library
+ package.
</p>
<p>
- Packages that use <prgn>libtool</prgn> to create shared
- libraries should include the <file>.la</file> files in the
- <tt>-dev</tt> package, unless the package relies on
- <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
- the <tt>.la</tt> files must go in the run-time library
- package.
+ These requirements for handling of <file>.la</file> files do not
+ apply to loadable modules or libraries not installed in
+ directories searched by default by the dynamic linker. Packages
+ installing loadable modules will frequently need to install
+ the <file>.la</file> files alongside the modules so that they
+ can be loaded by <tt>libltdl</tt>. <tt>dependency_libs</tt>
+ does not need to be modified for libraries or modules that are
+ not installed in directories searched by the dynamic linker by
+ default and not intended for use by other packages.
</p>
<p>
<example compact="compact">
/usr/lib/cgi-bin/<var>cgi-bin-name</var>
</example>
- and should be referred to as
+ or a subdirectory of that directory, and should be
+ referred to as
<example compact="compact">
http://localhost/cgi-bin/<var>cgi-bin-name</var>
</example>
-
+ (possibly with a subdirectory name
+ before <var>cgi-bin-name</var>).
</item>
<item>
<p>
Packages distributed under the Apache license (version 2.0), the
- Artistic license, the GNU GPL (version 2 or 3), the GNU LGPL
- (versions 2, 2.1, or 3), and the GNU FDL (versions 1.2 or 1.3)
- should refer to the corresponding files
+ Artistic license, the GNU GPL (versions 1, 2, or 3), the GNU
+ LGPL (versions 2, 2.1, or 3), and the GNU FDL (versions 1.2 or
+ 1.3) should refer to the corresponding files
under <file>/usr/share/common-licenses</file>,<footnote>
<p>
In particular,
<file>/usr/share/common-licenses/Apache-2.0</file>,
<file>/usr/share/common-licenses/Artistic</file>,
+ <file>/usr/share/common-licenses/GPL-1</file>,
<file>/usr/share/common-licenses/GPL-2</file>,
<file>/usr/share/common-licenses/GPL-3</file>,
<file>/usr/share/common-licenses/LGPL-2</file>,
</sect>
<sect id="pkg-sourcetree">
- <heading>The Debianised source tree</heading>
+ <heading>The Debian package source tree</heading>
<p>
The source archive scheme described later is intended to
- allow a Debianised source tree with some associated control
- information to be reproduced and transported easily. The
- Debianised source tree is a version of the original program
- with certain files added for the benefit of the
- Debianisation process, and with any other changes required
+ allow a Debian package source tree with some associated
+ control information to be reproduced and transported easily.
+ The Debian package source tree is a version of the original
+ program with certain files added for the benefit of the
+ packaging process, and with any other changes required
made to the rest of the source code and installation
scripts.
</p>
<p>
The extra files created for Debian are in the subdirectory
- <file>debian</file> of the top level of the Debianised source
- tree. They are described below.
+ <file>debian</file> of the top level of the Debian package
+ source tree. They are described below.
</p>
<sect1 id="pkg-debianrules">
</item>
<tag>
- Debianisation diff -
+ Debian package diff -
<file>
<var>package</var>_<var>upstream_version-revision</var>.diff.gz
</file>
<item><p>Apply the diff using <tt>patch -p0</tt>.</p>
</item>
<item><p>Untar the tarfile again if you want a copy of the original
- source code alongside the Debianised version.</p>
+ source code alongside the Debian version.</p>
</item>
</enumlist>
<p>
The source packaging tools manage the changes between the
- original and Debian
ised source using <prgn>diff</prgn> and
+ original and Debian source using <prgn>diff</prgn> and
<prgn>patch</prgn>. Turning the original source tree as
- included in the <file>.orig.tar.gz</file> into the debianised
- source must not involve any changes which cannot be
+ included in the <file>.orig.tar.gz</file> into the Debian
+ package source must not involve any changes which cannot be
handled by these tools. Problematic changes which cause
<prgn>dpkg-source</prgn> to halt with an error when
building the source package are:
projects / debian / debian-policy.git / blobdiff