<p>
The Debian archive maintainers provide the authoritative
list of sections. At present, they are:
- <em>admin</em>, <em>base</em>, <em>comm</em>,
- <em>contrib</em>, <em>devel</em>, <em>doc</em>,
+ <em>admin</em>, <em>comm</em>,
+ <em>devel</em>, <em>doc</em>,
<em>editors</em>, <em>electronics</em>, <em>embedded</em>,
<em>games</em>, <em>gnome</em>, <em>graphics</em>,
<em>hamradio</em>, <em>interpreters</em>, <em>kde</em>,
<em>libs</em>, <em>libdevel</em>, <em>mail</em>,
<em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
- <em>non-free</em>, <em>oldlibs</em>,
+ <em>oldlibs</em>,
<em>otherosfs</em>, <em>perl</em>, <em>python</em>,
<em>science</em>, <em>shells</em>,
<em>sound</em>, <em>tex</em>, <em>text</em>,
<p>
The <tt>base system</tt> is a minimum subset of the Debian
GNU/Linux system that is installed before everything else
- on a new system. Thus, only very few packages are allowed
- to go into the <tt>base</tt> section to keep the required
- disk usage very small.
+ on a new system. Only very few packages are allowed to form
+ part of the base system, in order to keep the required disk
+ usage very small.
</p>
<p>
- Most of these packages will have the priority value
- <tt>required</tt> or at least <tt>important</tt>, and many
- of them will be tagged <tt>essential</tt> (see below).
+ The base system consists of all those packages with priority
+ <tt>required</tt> or <tt>important</tt>. Many of them will
+ be tagged <tt>essential</tt> (see below).
</p>
</sect>
/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
</example>
Then all of the bug numbers listed will be closed by the
- archive maintenance script (<prgn>katie</prgn>), or in
- the case of an NMU, marked as fixed.
+ archive maintenance script (<prgn>katie</prgn>) using the
+ <var>version</var> of the changelog entry.
</footnote>
This information is conveyed via the <tt>Closes</tt> field
in the <tt>.changes</tt> file (see <ref id="f-Closes">).
possible is a good idea.
</p>
</item>
+
+ <tag><tt>patch</tt> (optional)</tag>
+ <item>
+ <p>
+ This target performs whatever additional actions are
+ required to make the source ready for editing (unpacking
+ additional upstream archives, applying patches, etc.).
+ It is recommended to be implemented for any package where
+ <tt>dpkg-source -x</tt> does not result in source ready
+ for additional modification. See
+ <ref id="readmesource">.
+ </p>
+ </item>
</taglist>
<p>
or system information; the GNU style variables should be
used for that.
</p>
+
+ <sect1 id="debianrules-options">
+ <heading><file>debian/rules</file> and
+ <tt>DEB_BUILD_OPTIONS</tt></heading>
+
+ <p>
+ Supporting the standardized environment variable
+ <tt>DEB_BUILD_OPTIONS</tt> is recommended. This variable can
+ contain several flags to change how a package is compiled and
+ built. Each flag must be in the form <var>flag</var> or
+ <var>flag</var>=<var>options</var>. If multiple flags are
+ given, they must be separated by whitespace.<footnote>
+ Some packages support any delimiter, but whitespace is the
+ easiest to parse inside a makefile and avoids ambiguity with
+ flag values that contain commas.
+ </footnote>
+ <var>flag</var> must start with a lowercase letter
+ (<tt>a-z</tt>) and consist only of lowercase letters,
+ numbers (<tt>0-9</tt>), and the characters
+ <tt>-</tt> and <tt>_</tt> (hyphen and underscore).
+ <var>options</var> must not contain whitespace. The same
+ tag should not be given multiple times with conflicting
+ values. Package maintainers may assume that
+ <tt>DEB_BUILD_OPTIONS</tt> will not contain conflicting tags.
+ </p>
+
+ <p>
+ The meaning of the following tags has been standardized:
+ <taglist>
+ <tag>noopt</tag>
+ <item>
+ The presence of this tag means that the package should
+ be compiled with a minimum of optimization. For C
+ programs, it is best to add <tt>-O0</tt> to
+ <tt>CFLAGS</tt> (although this is usually the default).
+ Some programs might fail to build or run at this level
+ of optimization; it may be necessary to use
+ <tt>-O1</tt>, for example.
+ </item>
+ <tag>nostrip</tag>
+ <item>
+ This tag means that the debugging symbols should not be
+ stripped from the binary during installation, so that
+ debugging information may be included in the package.
+ </item>
+ <tag>parallel=n</tag>
+ <item>
+ This tag means that the package should be built using up
+ to <tt>n</tt> parallel processes if the package build
+ system supports this.<footnote>
+ Packages built with <tt>make</tt> can often implement
+ this by passing the <tt>-j</tt><var>n</var> option to
+ <tt>make</tt>.
+ </footnote>
+ If the package build system does not support parallel
+ builds, this string must be ignored. If the package
+ build system only supports a lower level of concurrency
+ than <var>n</var>, the package should be built using as
+ many parallel processes as the package build system
+ supports. It is up to the package maintainer to decide
+ whether the package build times are long enough and the
+ package build system is robust enough to make supporting
+ parallel builds worthwhile.
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ Unknown flags must be ignored by <file>debian/rules</file>.
+ </p>
+
+ <p>
+ The following makefile snippet is an example of how one may
+ implement the build options; you will probably have to
+ massage this example in order to make it work for your
+ package.
+ <example compact="compact">
+CFLAGS = -Wall -g
+INSTALL = install
+INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
+INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
+INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
+INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
+
+ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
+ CFLAGS += -O0
+else
+ CFLAGS += -O2
+endif
+ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
+ INSTALL_PROGRAM += -s
+endif
+ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
+ NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
+ MAKEFLAGS += -j$(NUMJOBS)
+endif
+ </example>
+ </p>
+ </sect1>
</sect>
<!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
</p>
<p>
- See <manref name="dpkg-source" section="1"> for full
+ See <manref name="deb-substvars" section="5"> for full
details about source variable substitutions, including the
format of <file>debian/substvars</file>.</p>
</sect>
the file to the list in <file>debian/files</file>.</p>
</sect>
+ <sect id="embeddedfiles">
+ <heading>Convenience copies of code</heading>
+
+ <p>
+ Some software packages include in their distribution convenience
+ copies of code from other software packages, generally so that
+ users compiling from source don't have to download multiple
+ packages. Debian packages should not make use of these
+ convenience copies unless the included package is explicitly
+ intended to be used in this way.<footnote>
+ For example, parts of the GNU build system work like this.
+ </footnote>
+ If the included code is already in the Debian archive in the
+ form of a library, the Debian packaging should ensure that
+ binary packages reference the libraries already in Debian and
+ the convenience copy is not used. If the included code is not
+ already in Debian, it should be packaged separately as a
+ prerequisite if possible.
+ <footnote>
+ Having multiple copies of the same code in Debian is
+ inefficient, often creates either static linking or shared
+ library conflicts, and, most importantly, increases the
+ difficulty of handling security vulnerabilities in the
+ duplicated code.
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="readmesource">
+ <heading>Source package handling:
+ <file>debian/README.source</file></heading>
+
+ <p>
+ If running <prgn>dpkg-source -x</prgn> on a source package
+ doesn't produce the source of the package, ready for editing,
+ and allow one to make changes and run
+ <prgn>dpkg-buildpackage</prgn> to produce a modified package
+ without taking any additional steps, creating a
+ <file>debian/README.source</file> documentation file is
+ recommended. This file should explain how to do all of the
+ following:
+ <enumlist>
+ <item>Generate the fully patched source, in a form ready for
+ editing, that would be built to create Debian
+ packages. Doing this with a <tt>patch</tt> target in
+ <file>debian/rules</file> is recommended; see
+ <ref id="debianrules">.</item>
+ <item>Modify the source and save those modifications so that
+ they will be applied when building the package.</item>
+ <item>Remove source modifications that are currently being
+ applied when building the package.</item>
+ <item>Optionally, document what steps are necessary to
+ upgrade the Debian source package to a new upstream version,
+ if applicable.</item>
+ </enumlist>
+ This explanation should include specific commands and mention
+ any additional required Debian packages. It should not assume
+ familiarity with any specific Debian packaging system or patch
+ management tools.
+ </p>
+
+ <p>
+ This explanation may refer to a documentation file installed by
+ one of the package's build dependencies provided that the
+ referenced documentation clearly explains these tasks and is not
+ a general reference manual.
+ </p>
+
+ <p>
+ <file>debian/README.source</file> may also include any other
+ information that would be helpful to someone modifying the
+ source package. Even if the package doesn't fit the above
+ description, maintainers are encouraged to document in a
+ <file>debian/README.source</file> file any source package with a
+ particularly complex or unintuitive source layout or build
+ system (for example, a package that builds the same source
+ multiple times to generate different binary packages).
+ </p>
+ </sect>
</chapt>
<item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
<item><qref id="f-Essential"><tt>Essential</tt></qref></item>
<item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
<item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
</sect>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
<sect1>
<heading>Package interrelationship fields:
<tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>,
+ <tt>Breaks</tt>, <tt>Conflicts</tt>,
<tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
</heading>
number apart at the last hyphen in the string (if there
is one) to determine the <var>upstream_version</var> and
<var>debian_revision</var>. The absence of a
- <var>debian_revision</var> compares earlier than the
- presence of one (but note that the
- <var>debian_revision</var> is the least significant part
- of the version number).
+ <var>debian_revision</var> is equivalent to a
+ <var>debian_revision</var> of <tt>0</tt>.
</p>
</item>
</taglist>
</p>
<p>
- The <var>upstream_version</var> and <var>debian_revision</var>
+ When comparing two version numbers, first the <var>epoch</var>
+ of each are compared, then the <var>upstream_version</var> if
+ <var>epoch</var> is equal, and then <var>debian_revision</var>
+ if <var>upstream_version</var> is also equal.
+ <var>epoch</var> is compared numerically. The
+ <var>upstream_version</var> and <var>debian_revision</var>
parts are compared by the package management system using the
- same algorithm:
+ following algorithm:
</p>
<p>
</p>
</sect1>
+ <sect1 id="f-Homepage">
+ <heading><tt>Homepage</tt></heading>
+
+ <p>
+ The URL of the web site for this package, preferably (when
+ applicable) the site from which the original source can be
+ obtained and any additional upstream documentation or
+ information may be found. The content of this field is a
+ simple URL without any surrounding characters such as
+ <tt><></tt>.
+ </p>
+ </sect1>
+
</sect>
<sect>
<var>deconfigured's-postinst</var>
<tt>abort-deconfigure</tt> <tt>in-favour</tt>
<var>failed-install-package</var> <var>version</var>
- <tt>removing</tt> <var>conflicting-package</var>
- <var>version</var>
+ [<tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>]
</item>
</list>
<item>
<var>deconfigured's-prerm</var> <tt>deconfigure</tt>
<tt>in-favour</tt> <var>package-being-installed</var>
- <var>version</var> <tt>removing</tt>
+ <var>version</var> [<tt>removing</tt>
<var>conflicting-package</var>
- <var>version</var>
+ <var>version</var>]
</item>
</list>
</item>
<item>
- If a "conflicting" package is being removed at the same time:
+ If a "conflicting" package is being removed at the same time,
+ or if any package will be broken (due to <tt>Breaks</tt>):
<enumlist>
<item>
- If any packages depended on that conflicting
- package and <tt>--auto-deconfigure</tt> is
+ If <tt>--auto-deconfigure</tt> is
+ specified, call, for each package to be deconfigured
+ due to <tt>Breaks</tt>:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ If any packages depended on a conflicting
+ package being removed and <tt>--auto-deconfigure</tt> is
specified, call, for each such package:
<example compact="compact">
<var>deconfigured's-prerm</var> deconfigure \
configured again if possible.
</item>
<item>
- To prepare for removal of the conflicting package, call:
+ To prepare for removal of each conflicting package, call:
<example compact="compact">
<var>conflictor's-prerm</var> remove \
in-favour <var>package</var> <var>new-version</var>
<p>
This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
- <tt>Conflicts</tt> control file fields.
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Breaks</tt> and <tt>Conflicts</tt> control file fields.
</p>
<p>
- These six fields are used to declare a dependency
+ These seven fields are used to declare a dependency
relationship by one package on another. Except for
- <tt>Enhances</tt>, they appear in the depending (binary)
- package's control file. (<tt>Enhances</tt> appears in the
- recommending package's control file.)
+ <tt>Enhances</tt> and <tt>Breaks</tt>, they appear in the
+ depending (binary) package's control file.
+ (<tt>Enhances</tt> appears in the recommending package's
+ control file, and <tt>Breaks</tt> appears in the version of
+ depended-on package which causes the named package to
+ break).
</p>
<p>
(based on rules below), and some packages may not be able to
rely on their dependencies being present when being
installed or removed, depending on which side of the break
- of the circular dependcy loop they happen to be on. If one
+ of the circular dependency loop they happen to be on. If one
of the packages in the loop has no postinst script, then the
cycle will be broken at that package, so as to ensure that
all postinst scripts run with the dependencies properly
</p>
</sect>
+ <sect id="breaks">
+ <heading>Packages which break other packages - <tt>Breaks</tt></heading>
+
+ <p>
+ Using <tt>Breaks</tt> may cause problems for upgrades from older
+ versions of Debian and should not be used until the stable
+ release of Debian supports <tt>Breaks</tt>.
+ </p>
+
+ <p>
+ When one binary package declares that it breaks another,
+ <prgn>dpkg</prgn> will refuse to allow the package which
+ declares <tt>Breaks</tt> be installed unless the broken
+ package is deconfigured first, and it will refuse to
+ allow the broken package to be reconfigured.
+ </p>
+
+ <p>
+ A package will not be regarded as causing breakage merely
+ because its configuration files are still installed; it must
+ be at least half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare that
+ they break their own package name or a virtual package which
+ they provide (see below): this does not count as a real
+ breakage.
+ </p>
+
+ <p>
+ Normally a <tt>Breaks</tt> entry will have an "earlier than"
+ version clause; such a <tt>Breaks</tt> is introduced in the
+ version of an (implicit or explicit) dependency which
+ violates an assumption or reveals a bug in earlier versions
+ of the broken package. This use of <tt>Breaks</tt> will
+ inform higher-level package management tools that broken
+ package must be upgraded before the new one.
+ </p>
+
+ <p>
+ If the breaking package also overwrites some files from the
+ older package, it should use <tt>Replaces</tt> (not
+ <tt>Conflicts</tt>) to ensure this goes smoothly.
+ </p>
+ </sect>
+
<sect id="conflicts">
<heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
"earlier than" version clause. This would prevent
<prgn>dpkg</prgn> from upgrading or installing the package
which declared such a conflict until the upgrade or removal
- of the conflicted-with package had been completed.
+ of the conflicted-with package had been completed. Instead,
+ <tt>Breaks</tt> may be used (once <tt>Breaks</tt> is supported
+ by the stable release of Debian).
</p>
</sect>
As well as the names of actual ("concrete") packages, the
package relationship fields <tt>Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
+ <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>,
<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
<tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
may mention "virtual packages".
</p>
<p>
- If a dependency or a conflict has a version number attached
+ If a relationship field has a version number attached
then only real packages will be considered to see whether
the relationship is satisfied (or the prohibition violated,
- for a conflict) - it is assumed that a real package which
- provides the virtual package is not of the "right" version.
- So, 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
- looked at when considering a dependency on or conflict with
- the virtual package name.
+ for a conflict or breakage) - it is assumed that a real
+ package which provides the virtual package is not of the
+ "right" version. So, 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 looked at when considering a dependency on or
+ conflict with the virtual package name.
</p>
<p>
instead.
</p>
- <p>
- If your package includes run-time support programs that
- do not need to be invoked manually by users, but are
- nevertheless required for the package to function, then it
- is recommended that these programs are placed
- (if they are binary) in a subdirectory of
- <file>/usr/lib</file>, preferably under
- <file>/usr/lib/</file><var>package-name</var>.
- If the program is architecture independent, the
- recommendation is for it to be placed in a subdirectory of
- <file>/usr/share</file> instead, preferably under
- <file>/usr/share/</file><var>package-name</var>.
- </p>
-
-
<p>
If you have several shared libraries built from the same
source tree you may lump them all together into a single
</sect>
- <sect id="sharedlibs-runtime-progs">
- <heading>Run-time support programs</heading>
+ <sect id="sharedlibs-support-files">
+ <heading>Shared library support files</heading>
- <p>
- If your package has some run-time support programs which use
- the shared library you must not put them in the shared
- library package. If you do that then you won't be able to
- install several versions of the shared library without
- getting filename clashes.
- </p>
+ <p>
+ If your package contains files whose names do not change with
+ each change in the library shared object version, you must not
+ put them in the shared library package. Otherwise, several
+ versions of the shared library cannot be installed at the same
+ time without filename clashes, making upgrades and transitions
+ unnecessarily difficult.
+ </p>
- <p>
- Instead, either create another package for the runtime binaries
- (this package might typically be named
- <package><var>libraryname</var>-runtime</package>; note the absence
- of the <var>soversion</var> in the package name), or if the
- development package is small, include them in there.
- </p>
+ <p>
+ It is recommended that supporting files and run-time support
+ programs that do not need to be invoked manually by users, but
+ are nevertheless required for the package to function, be placed
+ (if they are binary) in a subdirectory of <file>/usr/lib</file>,
+ preferably under <file>/usr/lib/</file><var>package-name</var>.
+ If the program or file is architecture independent, the
+ recommendation is for it to be placed in a subdirectory of
+ <file>/usr/share</file> instead, preferably under
+ <file>/usr/share/</file><var>package-name</var>. Following the
+ <var>package-name</var> naming convention ensures that the file
+ names change when the shared object version changes.
+ </p>
+
+ <p>
+ Run-time support programs that use the shared library but are
+ not required for the library to function or files used by the
+ shared library that can be used by any version of the shared
+ library package should instead be put in a separate package.
+ This package might typically be named
+ <package><var>libraryname</var>-tools</package>; note the
+ absence of the <var>soversion</var> in the package name.
+ </p>
+
+ <p>
+ Files and support programs only useful when compiling software
+ against the library should be included in the development
+ package for the library.<footnote>
+ For example, a <file><var>package-name</var>-config</file>
+ script or <package>pkg-config</package> configuration files.
+ </footnote>
+ </p>
</sect>
<sect id="sharedlibs-static">
The <file>/usr/local</file> directory itself and all the
subdirectories created by the package should (by default) have
permissions 2775 (group-writable and set-group-id) and be
- owned by <tt>root.staff</tt>.
+ owned by <tt>root:staff</tt>.
</p>
</sect1>
<p>
The <file>init.d</file> scripts must ensure that they will
- behave sensibly if invoked with <tt>start</tt> when the
- service is already running, or with <tt>stop</tt> when it
- isn't, and that they don't kill unfortunately-named user
- processes. The best way to achieve this is usually to use
- <prgn>start-stop-daemon</prgn>.
+ behave sensibly (i.e., returning success and not starting
+ multiple copies of a service) if invoked with <tt>start</tt>
+ when the service is already running, or with <tt>stop</tt>
+ when it isn't, and that they don't kill unfortunately-named
+ user processes. The best way to achieve this is usually to
+ use <prgn>start-stop-daemon</prgn> with the <tt>--oknodo</tt>
+ option.
</p>
<p>
via cron, it should place a file with the name of the
package in one or more of the following directories:
<example compact="compact">
+/etc/cron.hourly
/etc/cron.daily
/etc/cron.weekly
/etc/cron.monthly
</example>
As these directory names imply, the files within them are
- executed on a daily, weekly, or monthly basis,
+ executed on an hourly, daily, weekly, or monthly basis,
respectively. The exact times are listed in
<file>/etc/crontab</file>.</p>
All files installed in any of these directories must be
scripts (e.g., shell scripts or Perl scripts) so that they
can easily be modified by the local system administrator.
- In addition, they should be treated as configuration
- files.
+ In addition, they must be treated as configuration files.
</p>
<p>
- If a certain job has to be executed more frequently than
- daily, the package should install a file
+ If a certain job has to be executed at some other frequency or
+ at a specific time, the package should install a file
<file>/etc/cron.d/<var>package</var></file>. This file uses the
same syntax as <file>/etc/crontab</file> and is processed by
<prgn>cron</prgn> automatically. The file must also be
<p>
Although binaries in the build tree should be compiled with
- debugging information by default, it can often be difficult
- to debug programs if they are also subjected to compiler
- optimization. For this reason, it is recommended to support
- the standardized environment
- variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
- contain several flags to change how a package is compiled
- and built.
- </p>
-
- <p>
- <taglist>
- <tag>noopt</tag>
- <item>
- The presence of this string means that the package
- should be compiled with a minimum of optimization.
- For C programs, it is best to add <tt>-O0</tt>
- to <tt>CFLAGS</tt> (although this is usually the
- default). Some programs might fail to build or run at
- this level of optimization; it may be necessary to
- use <tt>-O1</tt>, for example.
- </item>
- <tag>nostrip</tag>
- <item>
- This string means that the debugging symbols should
- not be stripped from the binary during installation,
- so that debugging information may be included in the package.
- </item>
- </taglist>
- </p>
-
- <p>
- The following makefile snippet is an example of how one may
- implement the build options; you will probably have to
- massage this example in order to make it work for your
- package.
- <example compact="compact">
-CFLAGS = -Wall -g
-INSTALL = install
-INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
-INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
-INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
-INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
-
-ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
-CFLAGS += -O0
-else
-CFLAGS += -O2
-endif
-ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
-INSTALL_PROGRAM += -s
-endif
- </example>
+ debugging information by default, it can often be difficult to
+ debug programs if they are also subjected to compiler
+ optimization. For this reason, it is recommended to support the
+ standardized environment variable <tt>DEB_BUILD_OPTIONS</tt>
+ (see <ref id="debianrules-options">). This variable can contain
+ several flags to change how a package is compiled and built.
</p>
<p>
</p>
<p>
- Note that a script that embeds configuration information
- (such as most of the files in <file>/etc/default</file> and
- <file>/etc/cron.{daily,weekly,monthly}</file>) is de-facto a
- configuration file and should be treated as such.
+ As noted elsewhere, <file>/etc/init.d</file> scripts,
+ <file>/etc/default</file> files, scripts installed in
+ <file>/etc/cron.{hourly,daily,weekly,monthly}</file>, and cron
+ configuration installed in <file>/etc/cron.d</file> must be
+ treated as configuration files. In general, any script that
+ embeds configuration information is de-facto a configuration
+ file and should be treated as such.
</p>
</sect1>
</p>
<p>
- Files should be owned by <tt>root.root</tt>, and made
+ Files should be owned by <tt>root:root</tt>, and made
writable only by the owner and universally readable (and
executable, if appropriate), that is mode 644 or 755.
</p>
description of the use of <prgn>dpkg-statoverride</prgn>.
</p>
- <p>
- <prgn>dpkg-statoverride</prgn> is a replacement for the
- deprecated <tt>suidmanager</tt> package. Packages which
- previously used <tt>suidmanager</tt> should have a
- <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
- <tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
- and <tt>suidunregister</tt> should now be simply removed
- from the maintainer scripts.
- </p>
-
<p>
If a system administrator wishes to have a file (or
directory or other such thing) installed with owner and
<p>
Mailboxes are generally mode 660
- <tt><var>user</var>.mail</tt> unless the system
+ <tt><var>user</var>:mail</tt> unless the system
administrator has chosen otherwise. A MUA may remove a
mailbox (unless it has nonstandard permissions) in which
case the MTA or another MUA must recreate it if needed.
</p>
<p>
- The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
+ The mail spool is 2775 <tt>root:mail</tt>, and MUAs should
be setgid mail to do the locking mentioned above (and
must obviously avoid accessing other users' mailboxes
using this privilege).</p>
in the <em>X Toolkit Intrinsics - C Language
Interface</em> manual is also permitted). They must be
registered as <tt>conffile</tt>s or handled as
- configuration files. Packages must not provide the
- directory <file>/usr/X11R6/lib/X11/app-defaults/</file>.
+ configuration files.
</p>
<p>
are stored in the X server and affect all connecting
clients.
</footnote>
- <em>Important:</em> packages that install files into the
- <file>/etc/X11/Xresources/</file> directory must conflict with
- <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is not done
- it is possible for the installing package to destroy a
- previously-existing <file>/etc/X11/Xresources</file> file
- which had been customized by the system administrator.
</p>
</sect1>
Games which require protected, privileged access to
high-score files, saved games, etc., may be made
set-<em>group</em>-id (mode 2755) and owned by
- <tt>root.games</tt>, and use files and directories with
- appropriate permissions (770 <tt>root.games</tt>, for
+ <tt>root:games</tt>, and use files and directories with
+ appropriate permissions (770 <tt>root:games</tt>, for
example). They must not be made
set-<em>user</em>-id, as this causes security problems. (If
an attacker can subvert any set-user-id game they can
be present in the future.
</footnote>
</p>
+
+ <p>
+ Manual pages in locale-specific subdirectories of
+ <file>/usr/share/man</file> should use either UTF-8 or the usual
+ legacy encoding for that language (normally the one corresponding
+ to the shortest relevant locale name in
+ <file>/usr/share/i18n/SUPPORTED</file>). For example, pages under
+ <file>/usr/share/man/fr</file> should use either UTF-8 or
+ ISO-8859-1.<footnote>
+ <prgn>man</prgn> will automatically detect whether UTF-8 is in
+ use. In future, all manual pages will be required to use
+ UTF-8.
+ </footnote>
+ </p>
+
+ <p>
+ A country name (the <tt>DE</tt> in <tt>de_DE</tt>) should not be
+ included in the subdirectory name unless it indicates a
+ significant difference in the language, as this excludes
+ speakers of the language in other countries.<footnote>
+ At the time of writing, Chinese and Portuguese are the main
+ languages with such differences, so <file>pt_BR</file>,
+ <file>zh_CN</file>, and <file>zh_TW</file> are all allowed.
+ </footnote>
+ </p>
+
+ <p>
+ Due to limitations in current implementations, all characters
+ in the manual page source should be representable in the usual
+ legacy encoding for that language, even if the file is
+ actually encoded in UTF-8. Safe alternative ways to write many
+ characters outside that range may be found in
+ <manref name="groff_char" section="7">.
+ </p>
</sect>
<sect>
In addition, the copyright file must say where the upstream
sources (if any) were obtained. It should name the original
authors of the package and the Debian maintainer(s) who were
- involved with its creation.</p>
+ involved with its creation.
+ </p>
+
+ <p>
+ Packages in the <em>contrib</em> or <em>non-free</em> categories
+ should state in the copyright file that the package is not part
+ of the Debian GNU/Linux distribution and briefly explain why.
+ </p>
<p>
A copy of the file which will be installed in
</p>
<p>
- Packages distributed under the UCB BSD license, the Artistic
- license, the GNU GPL (version 2 or 3), the GNU LGPL (versions
- 2, 2.1, or 3), and the GNU FDL (version 1.2) should refer to
- the corresponding files under
- <file>/usr/share/common-licenses</file>,<footnote>
+ Packages distributed under the UCB BSD license, 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 (version 1.2) should refer to the corresponding
+ files under <file>/usr/share/common-licenses</file>,<footnote>
<p>
In particular,
<file>/usr/share/common-licenses/BSD</file>,
+ <file>/usr/share/common-licenses/Apache-2.0</file>,
<file>/usr/share/common-licenses/Artistic</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>,
<file>/usr/share/common-licenses/LGPL-2.1</file>,
<file>/usr/share/common-licenses/LGPL-3</file>, and
- <file>/usr/share/common-licenses/GFDL-1.2</file>,
+ <file>/usr/share/common-licenses/GFDL-1.2</file>
respectively.
</p>
</footnote> rather than quoting them in the copyright
</p>
<p>
- Its arguments are executables.
+ Its arguments are executables and shared libraries
<footnote>
- <p>
- In a forthcoming dpkg version,
- <prgn>dpkg-shlibdeps</prgn> would be required to be
- called on shared libraries as well.
- </p>
<p>
They may be specified either in the locations in the
source tree where they are created or in the locations
and then in its main control file <file>debian/control</file>:
<example>
<var>...</var>
- Depends: ${shlibs:Pre-Depends}
+ Depends: ${shlibs:Depends}
Recommends: ${shlibs:Recommends}
<var>...</var>
</example>
<p>
This program can be used manually, but is also invoked by
<tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
- to set environment or make variables which specify the build and
- host architecture for the package building process.
+ environment or make variables which specify the build and host
+ architecture for the package building process.
</p>
</sect1>
</sect>
projects / debian / debian-policy.git / blobdiff