Gecko [ fernandoquevedodop.com ]

Name	Size	Permission
_images	[ DIR ]	drwxr-xr-x
_sources	[ DIR ]	drwxr-xr-x
_static	[ DIR ]	drwxr-xr-x
ap-flowcharts.html	7.02 KB	-rw-r--r--
ap-license.html	4.8 KB	-rw-r--r--
ap-pkg-alternatives.html	6.79 KB	-rw-r--r--
ap-pkg-binarypkg.html	17.44 KB	-rw-r--r--
ap-pkg-conffiles.html	12.14 KB	-rw-r--r--
ap-pkg-controlfields.html	12.4 KB	-rw-r--r--
ap-pkg-diversions.html	11.4 KB	-rw-r--r--
ap-pkg-scope.html	7.81 KB	-rw-r--r--
ap-pkg-sourcepkg.html	33.32 KB	-rw-r--r--
ap-process.html	18.49 KB	-rw-r--r--
ch-archive.html	28.57 KB	-rw-r--r--
ch-binary.html	38.01 KB	-rw-r--r--
ch-controlfields.html	107.38 KB	-rw-r--r--
ch-customized-programs.html	53.09 KB	-rw-r--r--
ch-docs.html	33.97 KB	-rw-r--r--
ch-files.html	69.51 KB	-rw-r--r--
ch-maintainerscripts.html	40.34 KB	-rw-r--r--
ch-opersys.html	84.18 KB	-rw-r--r--
ch-relationships.html	67.18 KB	-rw-r--r--
ch-scope.html	18.54 KB	-rw-r--r--
ch-sharedlibs.html	88.6 KB	-rw-r--r--
ch-source.html	79.4 KB	-rw-r--r--
genindex.html	3.48 KB	-rw-r--r--
index.html	59.51 KB	-rw-r--r--
objects.inv	4.75 KB	-rw-r--r--
search.html	2.99 KB	-rw-r--r--
searchindex.js	58.77 KB	-rw-r--r--
upgrading-checklist.html	121.38 KB	-rw-r--r--

Code Editor : ch-source.html

<!DOCTYPE html>

<title>4. Source packages &#8212; Debian Policy Manual v4.6.0.1</title>
 <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
 <link rel="stylesheet" type="text/css" href="_static/nature.css" />
 <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
 <script src="_static/jquery.js"></script>
 <script src="_static/underscore.js"></script>
 <script src="_static/doctools.js"></script>
 <link rel="index" title="Index" href="genindex.html" />
 <link rel="search" title="Search" href="search.html" />
 <link rel="next" title="5. Control files and their fields" href="ch-controlfields.html" />
 <link rel="prev" title="3. Binary packages" href="ch-binary.html" /> 
 </head><body>
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="ch-controlfields.html" title="5. Control files and their fields"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="ch-binary.html" title="3. Binary packages"
 accesskey="P">previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">4. Source packages</a></li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="source-packages">
<h1>4. Source packages<a class="headerlink" href="#source-packages" title="Permalink to this headline">¶</a></h1>
<section id="standards-conformance">
<h2>4.1. Standards conformance<a class="headerlink" href="#standards-conformance" title="Permalink to this headline">¶</a></h2>
Source packages should specify the most recent version number of this
policy document with which your package complied when it was last
updated.
The version is specified in the <code class="docutils literal notranslate">Standards-Version</code> control field. The
format of the <code class="docutils literal notranslate">Standards-Version</code> field is described in
<a class="reference internal" href="ch-controlfields.html#s-f-standards-version">Standards-Version</a>.
For a package to have an old Standards-Version value is not itself a
bug, however. It just means that no-one has yet reviewed the package
with changes to the standards in mind.
When updating existing packaging, the Standards-Version must not be
updated except after reviewing the changes between the old and the new
versions of the standards and updating your package if necessary (the
<a class="reference internal" href="upgrading-checklist.html">Upgrading checklist</a> can help with this task).
A very old Standards-Version can mean that infelicities in the package
are likely. It is recommended that each package be reviewed at least
once per Debian release, so a Standards-Version older than the
previous Debian release is indicative of work (if only review work)
that needs doing.
</section>
<section id="package-relationships">
<h2>4.2. Package relationships<a class="headerlink" href="#package-relationships" title="Permalink to this headline">¶</a></h2>
Source packages should specify which binary packages they require to be
installed or not to be installed in order to build correctly. For
example, if building a package requires a certain compiler, then the
compiler should be specified as a build-time dependency.
It is not necessary to explicitly specify build-time relationships on a
minimal set of packages that are always needed to compile, link and put
in a Debian package a standard “Hello World!” program written in C or
C++. The required packages are called build-essential, and an
informational list can be found in
<code class="docutils literal notranslate">/usr/share/doc/build-essential/list</code> (which is contained in the
<code class="docutils literal notranslate">build-essential</code> package). <a class="footnote-reference brackets" href="#id20" id="id1">1</a>
When specifying the set of build-time dependencies, one should list only
those packages explicitly required by the build. It is not necessary to
list packages which are required merely because some other package in
the list of build-time dependencies depends on them. <a class="footnote-reference brackets" href="#id21" id="id2">2</a>
If build-time dependencies are specified, it must be possible to build
the package and produce working binaries on a system with only essential
and build-essential packages installed and also those required to
satisfy the build-time relationships (including any implied
relationships). In particular, this means that version clauses should be
used rigorously in build-time relationships so that one cannot produce
bad or inconsistently configured packages when the relationships are
properly satisfied.
<a class="reference internal" href="ch-relationships.html">Declaring relationships between packages</a>
explains the technical details.
</section>
<section id="changes-to-the-upstream-sources">
<h2>4.3. Changes to the upstream sources<a class="headerlink" href="#changes-to-the-upstream-sources" title="Permalink to this headline">¶</a></h2>
If changes to the source code are made that are not specific to the
needs of the Debian system, they should be sent to the upstream authors
in whatever form they prefer so as to be included in the upstream
version of the package.
If you need to configure the package differently for Debian or for
Linux, and the upstream source doesn’t provide a way to do so, you
should add such configuration facilities (for example, a new
<code class="docutils literal notranslate">autoconf</code> test or <code class="docutils literal notranslate">#define</code>) and send the patch to the upstream
authors, with the default set to the way they originally had it. You can
then easily override the default in your <code class="docutils literal notranslate">debian/rules</code> or wherever is
appropriate.
You should make sure that the <code class="docutils literal notranslate">configure</code> utility detects the correct
architecture specification string (refer to
<a class="reference internal" href="ch-customized-programs.html#s-arch-spec">Architecture specification strings</a> for details).
If your package includes the scripts <code class="docutils literal notranslate">config.sub</code> and
<code class="docutils literal notranslate">config.guess</code>, you should arrange for the versions provided by the
package autotools-dev be used instead (see autotools-dev documentation
for details how to achieve that). This ensures that these files can be
updated distribution-wide at build time when introducing new
architectures.
If you need to edit a <code class="docutils literal notranslate">Makefile</code> where GNU-style <code class="docutils literal notranslate">configure</code> scripts
are used, you should edit the <code class="docutils literal notranslate">.in</code> files rather than editing the
<code class="docutils literal notranslate">Makefile</code> directly. This allows the user to reconfigure the package
if necessary. You should not configure the package and edit the
generated <code class="docutils literal notranslate">Makefile</code>! This makes it impossible for someone else to
later reconfigure the package without losing the changes you made.
</section>
<section id="debian-changelog-debian-changelog">
<h2>4.4. Debian changelog: <code class="docutils literal notranslate">debian/changelog</code><a class="headerlink" href="#debian-changelog-debian-changelog" title="Permalink to this headline">¶</a></h2>
Every source package must include the Debian changelog file,
<code class="docutils literal notranslate">debian/changelog</code>. Changes in the Debian version of the package
should be briefly explained in this file. <a class="footnote-reference brackets" href="#id22" id="id3">3</a> This includes
modifications made in the Debian package compared to the upstream one
as well as other changes and updates to the package. <a class="footnote-reference brackets" href="#id23" id="id4">4</a>
The format of the <code class="docutils literal notranslate">debian/changelog</code> allows the package building tools
to discover which version of the package is being built and find out
other release-specific information.
That format is a series of entries like this:
<div class="highlight-default notranslate"><div class="highlight"><pre>package (version) distribution(s); urgency=urgency
 [optional blank line(s), stripped]
 * change details
 more change details
 [blank line(s), included in output of dpkg-parsechangelog]
 * even more change details
 [optional blank line(s), stripped]
 -- maintainer name &lt;email address&gt;[two spaces] date
</pre></div>
</div>
<code class="docutils literal notranslate">package</code> and <code class="docutils literal notranslate">version</code> are the source package name and version
number.
<code class="docutils literal notranslate">distribution(s)</code> lists the distributions where this version should
be installed when it is uploaded - it is copied to the
<code class="docutils literal notranslate">Distribution</code> field in the <code class="docutils literal notranslate">.changes</code> file. See
<a class="reference internal" href="ch-controlfields.html#s-f-distribution">Distribution</a>.
<code class="docutils literal notranslate">urgency</code> is the value for the <code class="docutils literal notranslate">Urgency</code> field in the <code class="docutils literal notranslate">.changes</code>
file for the upload (see <a class="reference internal" href="ch-controlfields.html#s-f-urgency">Urgency</a>). It is not possible to
specify an urgency containing commas; commas are used to separate
<code class="docutils literal notranslate">keyword=value</code> settings in the <code class="docutils literal notranslate">dpkg</code> changelog format (though
there is currently only one useful keyword, <code class="docutils literal notranslate">urgency</code>).
The change details may in fact be any series of lines starting with at
least two spaces, but conventionally each change starts with an asterisk
and a separating space and continuation lines are indented so as to
bring them in line with the start of the text above. Blank lines may be
used here to separate groups of changes, if desired.
If this upload resolves bugs recorded in the Bug Tracking System (BTS),
they may be automatically closed on the inclusion of this package into
the Debian archive by including the string: <code class="docutils literal notranslate">closes:&#160; Bug#nnnnn</code> in
the change details. <a class="footnote-reference brackets" href="#id24" id="id5">5</a> This information is conveyed via the
<code class="docutils literal notranslate">Closes</code> field in the <code class="docutils literal notranslate">.changes</code> file (see
<a class="reference internal" href="ch-controlfields.html#s-f-closes">Closes</a>).
The maintainer name and email address used in the changelog should be
the details of the person who prepared this release of the package. They
are not necessarily those of the uploader or usual package maintainer.
<a class="footnote-reference brackets" href="#id25" id="id6">6</a> The information here will be copied to the <code class="docutils literal notranslate">Changed-By</code> field
in the <code class="docutils literal notranslate">.changes</code> file (see <a class="reference internal" href="ch-controlfields.html#s-f-changed-by">Changed-By</a>), and
then later used to send an acknowledgement when the upload has been
installed.
The date has the following format <a class="footnote-reference brackets" href="#id26" id="id7">7</a> (compatible and with the same
semantics of RFC 2822 and RFC 5322):
<div class="highlight-default notranslate"><div class="highlight"><pre>day-of-week, dd month yyyy hh:mm:ss +zzzz
</pre></div>
</div>
where:
<ul class="simple">
<li><code class="docutils literal notranslate">day-of-week</code> is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun</li>
<li><code class="docutils literal notranslate">dd</code> is a one- or two-digit day of the month (01-31)</li>
<li><code class="docutils literal notranslate">month</code> is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
Nov, Dec</li>
<li><code class="docutils literal notranslate">yyyy</code> is the four-digit year (e.g. 2010)</li>
<li><code class="docutils literal notranslate">hh</code> is the two-digit hour (00-23)</li>
<li><code class="docutils literal notranslate">mm</code> is the two-digit minutes (00-59)</li>
<li><code class="docutils literal notranslate">ss</code> is the two-digit seconds (00-60)</li>
<li><dl class="simple">
<dt><code class="docutils literal notranslate">+zzzz</code> or <code class="docutils literal notranslate">-zzzz</code> is the time zone offset from Coordinated</dt><dd>Universal Time (UTC). “+” indicates that the time is ahead of
(i.e., east of) UTC and “-” indicates that the time is behind
(i.e., west of) UTC. The first two digits indicate the hour
difference from UTC and the last two digits indicate the number of
additional minutes difference from UTC. The last two digits must be
in the range 00-59.
</dd>
</dl>
</li>
</ul>
The first “title” line with the package name must start at the left hand
margin. The “trailer” line with the maintainer and date details must be
preceded by exactly one space. The maintainer details and the date must
be separated by exactly two spaces.
The entire changelog must be encoded in UTF-8.
For more information on placement of the changelog files within binary
packages, please see <a class="reference internal" href="ch-docs.html#s-changelogs">Changelog files and release notes</a>.
</section>
<section id="copyright-debian-copyright">
<h2>4.5. Copyright: <code class="docutils literal notranslate">debian/copyright</code><a class="headerlink" href="#copyright-debian-copyright" title="Permalink to this headline">¶</a></h2>
Every package must be accompanied by a verbatim copy of its
distribution license(s) in the file <code class="docutils literal notranslate">/usr/share/doc/PACKAGE/copyright</code>.
This file is often required to contain a verbatim copy of the
package’s copyright information, too; see <a class="reference internal" href="ch-docs.html#s-copyrightfile">Copyright information</a> and
<a class="reference internal" href="ch-archive.html#s-pkgcopyright">Copyright considerations</a> for details, and for further considerations
related to copyrights for packages.
</section>
<section id="error-trapping-in-makefiles">
<h2>4.6. Error trapping in makefiles<a class="headerlink" href="#error-trapping-in-makefiles" title="Permalink to this headline">¶</a></h2>
When <code class="docutils literal notranslate">make</code> invokes a command in a makefile (including your package’s
upstream makefiles and <code class="docutils literal notranslate">debian/rules</code>), it does so using <code class="docutils literal notranslate">sh</code>. This
means that <code class="docutils literal notranslate">sh</code>’s usual bad error handling properties apply: if you
include a miniature script as one of the commands in your makefile
you’ll find that if you don’t do anything about it then errors are not
detected and <code class="docutils literal notranslate">make</code> will blithely continue after problems.
Every time you put more than one shell command (this includes using a
loop) in a makefile command you must make sure that errors are trapped.
For simple compound commands, such as changing directory and then
running a program, using <code class="docutils literal notranslate">&amp;&amp;</code> rather than semicolon as a command
separator is sufficient. For more complex commands including most loops
and conditionals you should include a separate <code class="docutils literal notranslate">set -e</code> command at the start of every makefile command that’s
actually one of these miniature shell scripts.
</section>
<section id="time-stamps">
<h2>4.7. Time Stamps<a class="headerlink" href="#time-stamps" title="Permalink to this headline">¶</a></h2>
Maintainers should preserve the modification times of the upstream
source files in a package, as far as is reasonably possible. <a class="footnote-reference brackets" href="#id27" id="id8">8</a>
</section>
<section id="restrictions-on-objects-in-source-packages">
<h2>4.8. Restrictions on objects in source packages<a class="headerlink" href="#restrictions-on-objects-in-source-packages" title="Permalink to this headline">¶</a></h2>
The source package must not contain any hard links, <a class="footnote-reference brackets" href="#id28" id="id9">9</a> device special
files, sockets or setuid or setgid files.. <a class="footnote-reference brackets" href="#id29" id="id10">10</a>
</section>
<section id="main-building-script-debian-rules">
<h2>4.9. Main building script: <code class="docutils literal notranslate">debian/rules</code><a class="headerlink" href="#main-building-script-debian-rules" title="Permalink to this headline">¶</a></h2>
This file must be an executable makefile. It contains the
package-specific recipes for compiling the source (if required) and
constructing one or more binary packages.
<code class="docutils literal notranslate">debian/rules</code> must start with the line <code class="docutils literal notranslate">#!/usr/bin/make -f</code>, so that
it can be invoked by saying its name rather than invoking <code class="docutils literal notranslate">make</code>
explicitly. That is, invoking either of <code class="docutils literal notranslate">make -f debian/rules args...</code>
or <code class="docutils literal notranslate">./debian/rules args...</code> must result in identical behavior.
The recommended way to implement the build process of a Debian package, in
the absence of a good reason to use a different approach, is the <code class="docutils literal notranslate">dh</code>
tool. This includes the contents of the <code class="docutils literal notranslate">debian/rules</code> building script.
<code class="docutils literal notranslate">dh</code> is the most common packaging helper tool in Debian. Using it will
usually save effort in complying with the rules in this document, because
<code class="docutils literal notranslate">dh</code> will automatically implement many of them without requiring
explicit instructions.
There are sometimes good reasons to use a different approach. For
example, the standard tools for packaging software written in some
languages may use another tool; some rarer packaging patterns, such as
multiple builds of the same software with different options, are easier to
express with other tools; and a packager working on a different packaging
helper might want to use their tool. The recommendation to use <code class="docutils literal notranslate">dh</code>
does not always apply, and use of <code class="docutils literal notranslate">dh</code> is not required.
For more information about how to use <code class="docutils literal notranslate">dh</code>, see the documentation in the
debhelper package, most notably the dh(1) manual page.
The following targets are required and must be implemented by
<code class="docutils literal notranslate">debian/rules</code>: <code class="docutils literal notranslate">clean</code>, <code class="docutils literal notranslate">binary</code>, <code class="docutils literal notranslate">binary-arch</code>,
<code class="docutils literal notranslate">binary-indep</code>, <code class="docutils literal notranslate">build</code>, <code class="docutils literal notranslate">build-arch</code> and <code class="docutils literal notranslate">build-indep</code>. These
are the targets called by <code class="docutils literal notranslate">dpkg-buildpackage</code>.
Since an interactive <code class="docutils literal notranslate">debian/rules</code> script makes it impossible to
auto-compile that package and also makes it hard for other people to
reproduce the same binary package, all required targets must be
non-interactive. It also follows that any target that these targets
depend on must also be non-interactive.
The package build should be as verbose as reasonably possible, except
where the <code class="docutils literal notranslate">terse</code> tag is included in <code class="docutils literal notranslate">DEB_BUILD_OPTIONS</code> (see
<a class="reference internal" href="#s-debianrules-options">debian/rules and DEB_BUILD_OPTIONS</a>). This makes life easier for porters and
bug squashers more generally, who can look at build logs for possible
problems. To accomplish this, <code class="docutils literal notranslate">debian/rules</code> should pass to the
commands it invokes options that cause them to produce verbose output.
For example, the build target should pass <code class="docutils literal notranslate">--disable-silent-rules</code>
to any configure scripts. See also <a class="reference internal" href="ch-files.html#s-binaries">Binaries</a>.
For packages in the main archive, required targets must not attempt
network access, except, via the loopback interface, to services on the
build host that have been started by the build.
Required targets must not attempt to write outside of the unpacked
source package tree. There are two exceptions. Firstly, the binary
targets may write the binary packages to the parent directory of the
unpacked source package tree. Secondly, required targets may write to
<code class="docutils literal notranslate">/tmp</code>, <code class="docutils literal notranslate">/var/tmp</code> and to the directory specified by the
<code class="docutils literal notranslate">TMPDIR</code> environment variable, but must not depend on the contents
of any of these.
This restriction is intended to prevent source package builds creating
and depending on state outside of themselves, thus affecting multiple
independent rebuilds. In particular, the required targets must not
attempt to write into <code class="docutils literal notranslate">HOME</code>.
The targets are as follows:
<dl>
<dt><code class="docutils literal notranslate">build</code> (required)</dt><dd>The <code class="docutils literal notranslate">build</code> target should perform all the configuration and
compilation of the package. If a package has an interactive
pre-build 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 modified to become non-interactive. (The
latter is preferable if there are architecture-specific features
detected by the configuration routine.)
For some packages, notably ones where the same source tree is
compiled in different ways to produce two binary packages, the
<code class="docutils literal notranslate">build</code> target does not make much sense. For these packages it is
good enough to provide two (or more) targets (<code class="docutils literal notranslate">build-a</code> and
<code class="docutils literal notranslate">build-b</code> or whatever) for each of the ways of building the
package, and a <code class="docutils literal notranslate">build</code> target that does nothing. The <code class="docutils literal notranslate">binary</code>
target will have to build the package in each of the possible ways
and make the binary package out of each.
The <code class="docutils literal notranslate">build</code> target must not do anything that might require root
privilege.
The <code class="docutils literal notranslate">build</code> target may need to run the <code class="docutils literal notranslate">clean</code> target first -
see below.
When a package has a configuration and build routine which takes a
long time, or when the makefiles are poorly designed, or when
<code class="docutils literal notranslate">build</code> needs to run <code class="docutils literal notranslate">clean</code> first, it is a good idea to
<code class="docutils literal notranslate">touch build</code> when the build process is complete. This will ensure
that if <code class="docutils literal notranslate">debian/rules build</code> is run again it will not rebuild the whole
program. <a class="footnote-reference brackets" href="#id30" id="id11">11</a>
</dd>
<dt><code class="docutils literal notranslate">build-arch</code> (required), <code class="docutils literal notranslate">build-indep</code> (required)</dt><dd>The <code class="docutils literal notranslate">build-arch</code> target must perform all the configuration and
compilation required for producing all architecture-dependent binary
packages (those packages for which the body of the <code class="docutils literal notranslate">Architecture</code>
field in <code class="docutils literal notranslate">debian/control</code> is not <code class="docutils literal notranslate">all</code>). Similarly, the
<code class="docutils literal notranslate">build-indep</code> target must perform all the configuration and
compilation required for producing all architecture-independent
binary packages (those packages for which the body of the
<code class="docutils literal notranslate">Architecture</code> field in <code class="docutils literal notranslate">debian/control</code> is <code class="docutils literal notranslate">all</code>). The
<code class="docutils literal notranslate">build</code> target should either depend on those targets or take the
same actions as invoking those targets would perform. <a class="footnote-reference brackets" href="#id31" id="id12">12</a>
The <code class="docutils literal notranslate">build-arch</code> and <code class="docutils literal notranslate">build-indep</code> targets must not do anything
that might require root privilege.
</dd>
<dt><code class="docutils literal notranslate">binary</code> (required), <code class="docutils literal notranslate">binary-arch</code> (required), <code class="docutils literal notranslate">binary-indep</code> (required)</dt><dd>The <code class="docutils literal notranslate">binary</code> target must be all that is necessary for the user to
build the binary package(s) produced from this source package. It is
split into two parts: <code class="docutils literal notranslate">binary-arch</code> builds the binary packages
which are specific to a particular architecture, and
<code class="docutils literal notranslate">binary-indep</code> builds those which are not.
<code class="docutils literal notranslate">binary</code> may be (and commonly is) a target with no commands which
simply depends on <code class="docutils literal notranslate">binary-arch</code> and <code class="docutils literal notranslate">binary-indep</code>.
Both <code class="docutils literal notranslate">binary-*</code> targets should depend on the <code class="docutils literal notranslate">build</code> target, or
on the appropriate <code class="docutils literal notranslate">build-arch</code> or <code class="docutils literal notranslate">build-indep</code> target, so that
the package is built if it has not been already. It should then
create the relevant binary package(s), using <code class="docutils literal notranslate">dpkg-gencontrol</code> to
make their control files and <code class="docutils literal notranslate">dpkg-deb</code> to build them and place
them in the parent of the top level directory.
Both the <code class="docutils literal notranslate">binary-arch</code> and <code class="docutils literal notranslate">binary-indep</code> targets must exist.
If one of them has nothing to do (which will always be the case if
the source generates only a single binary package, whether
architecture-dependent or not), it must still exist and must always
succeed.
The <code class="docutils literal notranslate">binary</code> targets may need to be invoked as root depending on
the value of the <a class="reference internal" href="ch-controlfields.html#s-f-rules-requires-root">Rules-Requires-Root</a> field. <a class="footnote-reference brackets" href="#id32" id="id13">13</a>
</dd>
<dt><code class="docutils literal notranslate">clean</code> (required)</dt><dd>This must undo any effects that the <code class="docutils literal notranslate">build</code> and <code class="docutils literal notranslate">binary</code>
targets may have had, except that it should leave alone any output
files created in the parent directory by a run of a <code class="docutils literal notranslate">binary</code>
target.
If a <code class="docutils literal notranslate">build</code> file is touched at the end of the <code class="docutils literal notranslate">build</code> target,
as suggested above, it should be removed as the first action that
<code class="docutils literal notranslate">clean</code> performs, so that running <code class="docutils literal notranslate">build</code> again after an
interrupted <code class="docutils literal notranslate">clean</code> doesn’t think that everything is already done.
The <code class="docutils literal notranslate">clean</code> target may need to be invoked as root if <code class="docutils literal notranslate">binary</code>
has been invoked since the last <code class="docutils literal notranslate">clean</code>, or if <code class="docutils literal notranslate">build</code> has been
invoked as root (since <code class="docutils literal notranslate">build</code> may create directories, for
example).
The <code class="docutils literal notranslate">clean</code> target cannot be used to remove files in the source
tree that are not compatible with the DFSG. This is because the
files would remain in the upstream tarball, and thus in the source
package, so the source package would continue to violate DFSG.
Instead, the upstream source should be repacked to remove those
files.
</dd>
<dt><code class="docutils literal notranslate">patch</code> (optional)</dt><dd>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 <code class="docutils literal notranslate">dpkg-source -x</code> does not result
in source ready for additional modification. See
<a class="reference internal" href="#s-readmesource">Source package handling: debian/README.source</a>.
</dd>
</dl>
The <code class="docutils literal notranslate">build</code>, <code class="docutils literal notranslate">binary</code> and <code class="docutils literal notranslate">clean</code> targets must be invoked with the
current directory being the package’s top-level directory.
Additional targets may exist in <code class="docutils literal notranslate">debian/rules</code>, either as published or
undocumented interfaces or for the package’s internal use.
The architectures we build on and build for are determined by <code class="docutils literal notranslate">make</code>
variables using the utility <code class="docutils literal notranslate">dpkg-architecture</code>. You can determine the
Debian architecture and the GNU style architecture specification string
for the build architecture as well as for the host architecture. The
build architecture is the architecture on which <code class="docutils literal notranslate">debian/rules</code> is run
and the package build is performed. The host architecture is the
architecture on which the resulting package will be installed and run.
The target architecture is the architecture of the packages that the
compiler currently being built will generate. These are normally the
same, but may be different in the case of cross-compilation (building
packages for one architecture on machines of a different architecture),
building a cross-compiler (a compiler package that will generate objects
for one architecture, built on a machine of a different architecture) or
a Canadian cross-compiler (a compiler that will generate objects for one
architecture, built on a machine of a different architecture, that will
run on yet a different architecture).
Here is a list of supported <code class="docutils literal notranslate">make</code> variables:
<ul class="simple">
<li><code class="docutils literal notranslate">DEB_*_ARCH</code> (the Debian architecture)</li>
<li><code class="docutils literal notranslate">DEB_*_ARCH_CPU</code> (the Debian CPU name)</li>
<li><code class="docutils literal notranslate">DEB_*_ARCH_BITS</code> (the Debian CPU pointer size in bits)</li>
<li><code class="docutils literal notranslate">DEB_*_ARCH_ENDIAN</code> (the Debian CPU endianness)</li>
<li><code class="docutils literal notranslate">DEB_*_ARCH_OS</code> (the Debian System name)</li>
<li><code class="docutils literal notranslate">DEB_*_GNU_TYPE</code> (the GNU style architecture specification string)</li>
<li><code class="docutils literal notranslate">DEB_*_GNU_CPU</code> (the CPU part of <code class="docutils literal notranslate">DEB_*_GNU_TYPE</code>)</li>
<li><code class="docutils literal notranslate">DEB_*_GNU_SYSTEM</code> (the System part of <code class="docutils literal notranslate">DEB_*_GNU_TYPE</code>)</li>
</ul>
where <code class="docutils literal notranslate">*</code> is either <code class="docutils literal notranslate">BUILD</code> for specification of the build
architecture, <code class="docutils literal notranslate">HOST</code> for specification of the host architecture or
<code class="docutils literal notranslate">TARGET</code> for specification of the target architecture.
Backward compatibility can be provided in the rules file by setting the
needed variables to suitable default values; please refer to the
documentation of <code class="docutils literal notranslate">dpkg-architecture</code> for details.
It is important to understand that the <code class="docutils literal notranslate">DEB_*_ARCH</code> string only
determines which Debian architecture we are building on or for. It
should not be used to get the CPU or system information; the
<code class="docutils literal notranslate">DEB_*_ARCH_CPU</code> and <code class="docutils literal notranslate">DEB_*_ARCH_OS</code> variables should be used for
that. GNU style variables should generally only be used with upstream
build systems.
The builder may set <code class="docutils literal notranslate">DEB_RULES_REQUIRES_ROOT</code> environment variable
when calling any of the mandatory targets as defined in
<a class="reference internal" href="ch-controlfields.html#s-f-rules-requires-root">Rules-Requires-Root</a>. If the variable
is not set, the package must behave as if it was set to
<code class="docutils literal notranslate">binary-targets</code>.
<section id="debian-rules-and-deb-build-options">
<h3>4.9.1. <code class="docutils literal notranslate">debian/rules</code> and <code class="docutils literal notranslate">DEB_BUILD_OPTIONS</code><a class="headerlink" href="#debian-rules-and-deb-build-options" title="Permalink to this headline">¶</a></h3>
Supporting the standardized environment variable <code class="docutils literal notranslate">DEB_BUILD_OPTIONS</code>
is recommended. This variable can contain several flags to change how a
package is compiled and built. Each flag must be in the form flag or
flag=options. If multiple flags are given, they must be separated by
whitespace. <a class="footnote-reference brackets" href="#id33" id="id14">14</a> flag must start with a lowercase letter (<code class="docutils literal notranslate">a-z</code>) and
consist only of lowercase letters, numbers (<code class="docutils literal notranslate">0-9</code>), and the characters
<code class="docutils literal notranslate">-</code> and <code class="docutils literal notranslate">_</code> (hyphen and underscore). options must not contain
whitespace. The same tag should not be given multiple times with
conflicting values. Package maintainers may assume that
<code class="docutils literal notranslate">DEB_BUILD_OPTIONS</code> will not contain conflicting tags.
The meaning of the following tags has been standardized:
<dl class="simple">
<dt><code class="docutils literal notranslate">nocheck</code></dt><dd>This tag says to not run any build-time test suite provided by the
package.
</dd>
<dt><code class="docutils literal notranslate">nodoc</code></dt><dd>This tag says to skip any build steps that only generate package
documentation. Files required by other sections of Debian Policy,
such as copyright and changelog files, must still be generated and
put in the package, but other generated documentation such as
help2man-generated pages, Doxygen-generated API documentation, or
info pages generated from Texinfo sources should be skipped if
possible. This option does not change the set of binary packages
generated by the source package, but documentation-only binary
packages may be nearly empty when built with this option.
</dd>
<dt><code class="docutils literal notranslate">noopt</code></dt><dd>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
<code class="docutils literal notranslate">-O0</code> to <code class="docutils literal notranslate">CFLAGS</code> (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 <code class="docutils literal notranslate">-O1</code>, for example.
</dd>
<dt><code class="docutils literal notranslate">nostrip</code></dt><dd>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.
</dd>
<dt><code class="docutils literal notranslate">parallel=n</code></dt><dd>This tag means that the package should be built using up to <code class="docutils literal notranslate">n</code>
parallel processes if the package build system supports this. <a class="footnote-reference brackets" href="#id34" id="id15">15</a>
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 n, 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.
</dd>
<dt><code class="docutils literal notranslate">terse</code></dt><dd>This tag means that the package build will be less verbose than
default. For example, <code class="docutils literal notranslate">debian/rules</code> might pass options to the
package’s configure script that cause the compiler to produce less
output.
</dd>
</dl>
Unknown flags must be ignored by <code class="docutils literal notranslate">debian/rules</code>.
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.
<div class="highlight-default notranslate"><div class="highlight"><pre>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

build:
 # ...
ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
 # Code to run the package test suite.
endif
</pre></div>
</div>
</section>
<section id="debian-rules-and-rules-requires-root">
<h3>4.9.2. <code class="docutils literal notranslate">debian/rules</code> and <code class="docutils literal notranslate">Rules-Requires-Root</code><a class="headerlink" href="#debian-rules-and-rules-requires-root" title="Permalink to this headline">¶</a></h3>
Depending on the value of the <a class="reference internal" href="ch-controlfields.html#s-f-rules-requires-root">Rules-Requires-Root</a> field, the package builder
(e.g. dpkg-buildpackage) may run the <code class="docutils literal notranslate">debian/rules</code> target as an
unprivileged user and provide a <cite>gain root command</cite>. This command
allows the <code class="docutils literal notranslate">debian/rules</code> target to run particular subcommands under
(fake)root.
The <cite>gain root command</cite> is passed to the build script via the
<code class="docutils literal notranslate">DEB_GAIN_ROOT_CMD</code> environment variable. The contents of this
variable is a space separated list, the first entry of which is the
command, and the proceeding entries of which are arguments to the
command. The <cite>gain root command</cite> must be available via PATH. The
<cite>gain root command</cite> must not rely on shell features because it will
not necessarily be invoked via a shell.
The <cite>gain root command</cite> must not run interactively, including
prompting for any user input. It must be possible to prepend the
<cite>gain root command</cite> to an existing command and its arguments, without
needing to alter or quote the existing command and its arguments.
Furthermore, the <cite>gain root command</cite> must preserve all environment
variables without the caller having to explicitly request any
preservation.
The following are examples of valid gain root commands (in syntax of
sh), assuming the tools used are available and properly configured:
<div class="highlight-default notranslate"><div class="highlight"><pre># Command &quot;sudo&quot;, with arguments &quot;-nE&quot; and &quot;--&quot;
export DEB_GAIN_ROOT_CMD=&#39;sudo -nE --&#39;
# Command &quot;fakeroot&quot; with the single argument &quot;--&quot;
export DEB_GAIN_ROOT_CMD=&#39;fakeroot --&#39;
</pre></div>
</div>
Examples of valid use of the <cite>gain root command</cite>:
<div class="highlight-default notranslate"><div class="highlight"><pre># sh-syntax (assumes set -e semantics for error handling)
$DEB_GAIN_ROOT_CMD some-cmd --which-requires-root

# perl
my @cmd = (&#39;some-cmd&#39;, &#39;--which-requires-root&#39;);
unshift(@cmd, split(&#39; &#39;, $ENV{DEB_GAIN_ROOT_CMD})) if $ENV{DEB_GAIN_ROOT_CMD};
system(@cmd) == 0 or die(&quot;@cmd failed&quot;);
</pre></div>
</div>
</section>
</section>
<section id="variable-substitutions-debian-substvars">
<h2>4.10. Variable substitutions: <code class="docutils literal notranslate">debian/substvars</code><a class="headerlink" href="#variable-substitutions-debian-substvars" title="Permalink to this headline">¶</a></h2>
When <code class="docutils literal notranslate">dpkg-gencontrol</code> generates <a class="reference internal" href="ch-controlfields.html#s-binarycontrolfiles">binary package control files</a> (<code class="docutils literal notranslate">DEBIAN/control</code>), it performs variable
substitutions on its output just before writing it. Variable
substitutions have the form <code class="docutils literal notranslate">${variable}</code>. The optional file
<code class="docutils literal notranslate">debian/substvars</code> contains variable substitutions to be used;
variables can also be set directly from <code class="docutils literal notranslate">debian/rules</code> using the
<code class="docutils literal notranslate">-V</code> option to the source packaging commands, and certain predefined
variables are also available.
The <code class="docutils literal notranslate">debian/substvars</code> file is usually generated and modified
dynamically by <code class="docutils literal notranslate">debian/rules</code> targets, in which case it must be
removed by the <code class="docutils literal notranslate">clean</code> target.
See deb-substvars(5) for full details about source variable
substitutions, including the format of <code class="docutils literal notranslate">debian/substvars</code>.
</section>
<section id="upstream-source-location-debian-watch">
<h2>4.11. Upstream source location: <code class="docutils literal notranslate">debian/watch</code><a class="headerlink" href="#upstream-source-location-debian-watch" title="Permalink to this headline">¶</a></h2>
This is a configuration file for the <code class="docutils literal notranslate">uscan</code> utility which defines how
to automatically scan ftp or http sites for newly available updates of the
package. This is also used by some Debian QA tools to help with quality
control and maintenance of the distribution as a whole. If the upstream
source of the package is available via a mechaism that <code class="docutils literal notranslate">uscan</code>
understands, including this configuration file is recommended.
If the upstream maintainer of the software provides OpenPGP signatures
for new releases, including the information required for <code class="docutils literal notranslate">uscan</code> to
verify signatures for new upstream releases is also recommended. To do
this, use the <code class="docutils literal notranslate">pgpsigurlmangle</code> option in <code class="docutils literal notranslate">debian/watch</code> to specify
the location of the upstream signature, and include the key or keys used
to sign upstream releases in the Debian source package as
<code class="docutils literal notranslate">debian/upstream/signing-key.asc</code>.
For more information about <code class="docutils literal notranslate">uscan</code> and these options, including how to
generate the file containing upstream signing keys, see
uscan(1).
</section>
<section id="generated-files-list-debian-files">
<h2>4.12. Generated files list: <code class="docutils literal notranslate">debian/files</code><a class="headerlink" href="#generated-files-list-debian-files" title="Permalink to this headline">¶</a></h2>
This file is not a permanent part of the source tree; it is used while
building packages to record which files are being generated.
<code class="docutils literal notranslate">dpkg-genchanges</code> uses it when it generates a <code class="docutils literal notranslate">.changes</code> file.
It should not exist in a shipped source package, and so it (and any
backup files or temporary files such as <code class="docutils literal notranslate">files.new</code>) <a class="footnote-reference brackets" href="#id35" id="id16">16</a> should be
removed by the <code class="docutils literal notranslate">clean</code> target. It may also be wise to ensure a fresh
start by emptying or removing it at the start of the <code class="docutils literal notranslate">binary</code> target.
When <code class="docutils literal notranslate">dpkg-gencontrol</code> is run for a binary package, it adds an entry
to <code class="docutils literal notranslate">debian/files</code> for the <code class="docutils literal notranslate">.deb</code> file that will be created when
<code class="docutils literal notranslate">dpkg-deb --build</code> is run for that binary package. So for most
packages all that needs to be done with this file is to delete it in the
<code class="docutils literal notranslate">clean</code> target.
If a package upload includes files besides the source package and any
binary packages whose control files were made with <code class="docutils literal notranslate">dpkg-gencontrol</code>
then they should be placed in the parent of the package’s top-level
directory and <code class="docutils literal notranslate">dpkg-distaddfile</code> should be called to add the file to
the list in <code class="docutils literal notranslate">debian/files</code>.
</section>
<section id="embedded-code-copies">
<h2>4.13. Embedded code copies<a class="headerlink" href="#embedded-code-copies" title="Permalink to this headline">¶</a></h2>
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. <a class="footnote-reference brackets" href="#id36" id="id17">17</a> 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. <a class="footnote-reference brackets" href="#id37" id="id18">18</a>
</section>
<section id="source-package-handling-debian-readme-source">
<h2>4.14. Source package handling: <code class="docutils literal notranslate">debian/README.source</code><a class="headerlink" href="#source-package-handling-debian-readme-source" title="Permalink to this headline">¶</a></h2>
If running <code class="docutils literal notranslate">dpkg-source -x</code> on a source package doesn’t produce the
source of the package, ready for editing, and allow one to make changes
and run <code class="docutils literal notranslate">dpkg-buildpackage</code> to produce a modified package without
taking any additional steps, creating a <code class="docutils literal notranslate">debian/README.source</code>
documentation file is recommended. This file should explain how to do
all of the following:
<ol class="arabic simple">
<li>Generate the fully patched source, in a form ready for editing, that
would be built to create Debian packages. Doing this with a <code class="docutils literal notranslate">patch</code>
target in <code class="docutils literal notranslate">debian/rules</code> is recommended; see
<a class="reference external" href="#s-debianrules">Main building script: debian/rules</a>.</li>
<li>Modify the source and save those modifications so that they will be
applied when building the package.</li>
<li>Remove source modifications that are currently being applied when
building the package.</li>
<li>Optionally, document what steps are necessary to upgrade the Debian
source package to a new upstream version, if applicable.</li>
</ol>
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.
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.
<code class="docutils literal notranslate">debian/README.source</code> 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 <code class="docutils literal notranslate">debian/README.source</code> 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).
</section>
<section id="reproducibility">
<h2>4.15. Reproducibility<a class="headerlink" href="#reproducibility" title="Permalink to this headline">¶</a></h2>
Packages should build reproducibly, which for the purposes of this
document <a class="footnote-reference brackets" href="#id38" id="id19">19</a> means that given
<ul class="simple">
<li>a version of a source package unpacked at a given path;</li>
<li>a set of versions of installed build dependencies;</li>
<li>a set of environment variable values;</li>
<li>a build architecture; and</li>
<li>a host architecture,</li>
</ul>
repeatedly building the source package for the build architecture on
any machine of the host architecture with those versions of the build
dependencies installed and exactly those environment variable values
set will produce bit-for-bit identical binary packages.
It is recommended that packages produce bit-for-bit identical binaries
even if most environment variables and build paths are varied. It is
intended for this stricter standard to replace the above when it is
easier for packages to meet it.
</section>
<section id="missing-sources-debian-missing-sources">
<h2>4.16. Missing sources: <code class="docutils literal notranslate">debian/missing-sources</code><a class="headerlink" href="#missing-sources-debian-missing-sources" title="Permalink to this headline">¶</a></h2>
Sometimes upstream does not include the source code for some files in
the upstream tarball. In order to satisfy the DFSG for packages in
<code class="docutils literal notranslate">main</code> or <code class="docutils literal notranslate">contrib</code>, you should either:
<ol class="arabic simple">
<li>repack the upstream tarball to include those sources; or</li>
<li>include a copy of the sources in the <code class="docutils literal notranslate">debian/missing-sources</code>
directory.</li>
</ol>
Package maintainers may optionally use the following convention to
organize the contents of <code class="docutils literal notranslate">debian/missing-sources</code>: for a sourceless file
<code class="docutils literal notranslate">foo</code> in the subdirectory <code class="docutils literal notranslate">bar</code> of the upstream tarball, where the
source of <code class="docutils literal notranslate">foo</code> has extension <code class="docutils literal notranslate">baz</code>, place the source at
<code class="docutils literal notranslate">debian/missing-sources/bar/foo.baz</code>. For example, according to this
convention, the C source code of an executable <code class="docutils literal notranslate">checksum/util</code> would be
located at <code class="docutils literal notranslate">debian/missing-sources/checksum/util.c</code>.
</section>
<section id="vendor-specific-patch-series">
<h2>4.17. Vendor-specific patch series<a class="headerlink" href="#vendor-specific-patch-series" title="Permalink to this headline">¶</a></h2>
Packages in the Debian archive using the 3.0 (quilt) source package
format must not contain a non-default series file. That is, there
must not exist a file <code class="docutils literal notranslate">debian/patches/foo.series</code> for any <code class="docutils literal notranslate">foo</code>.
<dl class="footnote brackets">
<dt class="label" id="id20"><a class="fn-backref" href="#id1">1</a></dt>
<dd>Rationale:
<ul class="simple">
<li>This allows maintaining the list separately from the policy
documents (the list does not need the kind of control that the
policy documents do).</li>
<li>Having a separate package allows one to install the
build-essential packages on a machine, as well as allowing other
packages such as tasks to require installation of the
build-essential packages using the depends relation.</li>
<li>The separate package allows bug reports against the list to be
categorized separately from the policy management process in the
BTS.</li>
</ul>
</dd>
<dt class="label" id="id21"><a class="fn-backref" href="#id2">2</a></dt>
<dd>The reason for this is that dependencies change, and you should list
all those packages, and only those packages that you need
directly. What others need is their business. For example, if you
only link against <code class="docutils literal notranslate">libimlib</code>, you will need to build-depend on
libimlib2-dev but not against any <code class="docutils literal notranslate">libjpeg*</code> packages, even though
<code class="docutils literal notranslate">libimlib2-dev</code> currently depends on them: installation of
libimlib2-dev will automatically ensure that all of its run-time
dependencies are satisfied.
</dd>
<dt class="label" id="id22"><a class="fn-backref" href="#id3">3</a></dt>
<dd>Mistakes in changelogs are usually best rectified by making a new
changelog entry rather than “rewriting history” by editing old
changelog entries.
</dd>
<dt class="label" id="id23"><a class="fn-backref" href="#id4">4</a></dt>
<dd>Although there is nothing stopping an author who is also the Debian
maintainer from using this changelog for all their changes, it will
have to be renamed if the Debian and upstream maintainers become
different people. In such a case, however, it might be better to
maintain the package as a non-native package.
</dd>
<dt class="label" id="id24"><a class="fn-backref" href="#id5">5</a></dt>
<dd>To be precise, the string should match the following Perl regular
expression:
<div class="highlight-default notranslate"><div class="highlight"><pre>/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
</pre></div>
</div>
Then all of the bug numbers listed will be closed by the archive
maintenance software (<code class="docutils literal notranslate">dak</code>) using the version of the changelog
entry.
</dd>
<dt class="label" id="id25"><a class="fn-backref" href="#id6">6</a></dt>
<dd>In the case of a sponsored upload, the uploader signs the files, but
the changelog maintainer name and address are those of the person who
prepared this release. If the preparer of the release is not one of the
usual maintainers of the package (as listed in the <a class="reference internal" href="ch-controlfields.html#s-f-maintainer">Maintainer</a> or <a class="reference internal" href="ch-controlfields.html#s-f-uploaders">Uploaders</a> control fields of
the package), the first line of the changelog is conventionally used to
explain why a non-maintainer is uploading the package. The Debian
Developer’s Reference (see <a class="reference internal" href="ch-scope.html#s-related">Related documents</a>) documents the conventions
used.
</dd>
<dt class="label" id="id26"><a class="fn-backref" href="#id7">7</a></dt>
<dd>This is the same as the format generated by <code class="docutils literal notranslate">date -R</code>.
</dd>
<dt class="label" id="id27"><a class="fn-backref" href="#id8">8</a></dt>
<dd>The rationale is that there is some information conveyed by knowing
the age of the file, for example, you could recognize that some
documentation is very old by looking at the modification time, so it
would be nice if the modification time of the upstream source would
be preserved.
</dd>
<dt class="label" id="id28"><a class="fn-backref" href="#id9">9</a></dt>
<dd>This is not currently detected when building source packages, but
only when extracting them.
Hard links may be permitted at some point in the future, but would
require a fair amount of work.
</dd>
<dt class="label" id="id29"><a class="fn-backref" href="#id10">10</a></dt>
<dd>Setgid directories are allowed.
</dd>
<dt class="label" id="id30"><a class="fn-backref" href="#id11">11</a></dt>
<dd>Another common way to do this is for <code class="docutils literal notranslate">build</code> to depend on
<code class="docutils literal notranslate">build-stamp</code> and to do nothing else, and for the <code class="docutils literal notranslate">build-stamp</code>
target to do the building and to <code class="docutils literal notranslate">touch build-stamp</code> on completion.
This is especially useful if the build routine creates a file or
directory called <code class="docutils literal notranslate">build</code>; in such a case, <code class="docutils literal notranslate">build</code> will need to be
listed as a phony target (i.e., as a dependency of the <code class="docutils literal notranslate">.PHONY</code>
target). See the documentation of <code class="docutils literal notranslate">make</code> for more information on
phony targets.
</dd>
<dt class="label" id="id31"><a class="fn-backref" href="#id12">12</a></dt>
<dd>This split allows binary-only builds to not install the dependencies
required for the <code class="docutils literal notranslate">build-indep</code> target and skip any
resource-intensive build tasks that are only required when building
architecture-independent binary packages.
</dd>
<dt class="label" id="id32"><a class="fn-backref" href="#id13">13</a></dt>
<dd>The <code class="docutils literal notranslate">fakeroot</code> package often allows one to build a package
correctly even without being root.
</dd>
<dt class="label" id="id33"><a class="fn-backref" href="#id14">14</a></dt>
<dd>Some packages support any delimiter, but whitespace is the easiest to
parse inside a makefile and avoids ambiguity with flag values that
contain commas.
</dd>
<dt class="label" id="id34"><a class="fn-backref" href="#id15">15</a></dt>
<dd>Packages built with <code class="docutils literal notranslate">make</code> can often implement this by passing the
<code class="docutils literal notranslate">-j</code>n option to <code class="docutils literal notranslate">make</code>.
</dd>
<dt class="label" id="id35"><a class="fn-backref" href="#id16">16</a></dt>
<dd><code class="docutils literal notranslate">files.new</code> is used as a temporary file by <code class="docutils literal notranslate">dpkg-gencontrol</code> and
<code class="docutils literal notranslate">dpkg-distaddfile</code> - they write a new version of <code class="docutils literal notranslate">files</code> here
before renaming it, to avoid leaving a corrupted copy if an error
occurs.
</dd>
<dt class="label" id="id36"><a class="fn-backref" href="#id17">17</a></dt>
<dd>For example, parts of the GNU build system work like this.
</dd>
<dt class="label" id="id37"><a class="fn-backref" href="#id18">18</a></dt>
<dd>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.
</dd>
<dt class="label" id="id38"><a class="fn-backref" href="#id19">19</a></dt>
<dd>This is Debian’s precisification of the <a class="reference external" href="https://reproducible-builds.org/docs/definition/">reproducible-builds.org
definition</a>.
</dd>
</dl>
</section>
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <h3><a href="index.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">4. Source packages</a><ul>
<li><a class="reference internal" href="#standards-conformance">4.1. Standards conformance</a></li>
<li><a class="reference internal" href="#package-relationships">4.2. Package relationships</a></li>
<li><a class="reference internal" href="#changes-to-the-upstream-sources">4.3. Changes to the upstream sources</a></li>
<li><a class="reference internal" href="#debian-changelog-debian-changelog">4.4. Debian changelog: <code class="docutils literal notranslate">debian/changelog</code></a></li>
<li><a class="reference internal" href="#copyright-debian-copyright">4.5. Copyright: <code class="docutils literal notranslate">debian/copyright</code></a></li>
<li><a class="reference internal" href="#error-trapping-in-makefiles">4.6. Error trapping in makefiles</a></li>
<li><a class="reference internal" href="#time-stamps">4.7. Time Stamps</a></li>
<li><a class="reference internal" href="#restrictions-on-objects-in-source-packages">4.8. Restrictions on objects in source packages</a></li>
<li><a class="reference internal" href="#main-building-script-debian-rules">4.9. Main building script: <code class="docutils literal notranslate">debian/rules</code></a><ul>
<li><a class="reference internal" href="#debian-rules-and-deb-build-options">4.9.1. <code class="docutils literal notranslate">debian/rules</code> and <code class="docutils literal notranslate">DEB_BUILD_OPTIONS</code></a></li>
<li><a class="reference internal" href="#debian-rules-and-rules-requires-root">4.9.2. <code class="docutils literal notranslate">debian/rules</code> and <code class="docutils literal notranslate">Rules-Requires-Root</code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#variable-substitutions-debian-substvars">4.10. Variable substitutions: <code class="docutils literal notranslate">debian/substvars</code></a></li>
<li><a class="reference internal" href="#upstream-source-location-debian-watch">4.11. Upstream source location: <code class="docutils literal notranslate">debian/watch</code></a></li>
<li><a class="reference internal" href="#generated-files-list-debian-files">4.12. Generated files list: <code class="docutils literal notranslate">debian/files</code></a></li>
<li><a class="reference internal" href="#embedded-code-copies">4.13. Embedded code copies</a></li>
<li><a class="reference internal" href="#source-package-handling-debian-readme-source">4.14. Source package handling: <code class="docutils literal notranslate">debian/README.source</code></a></li>
<li><a class="reference internal" href="#reproducibility">4.15. Reproducibility</a></li>
<li><a class="reference internal" href="#missing-sources-debian-missing-sources">4.16. Missing sources: <code class="docutils literal notranslate">debian/missing-sources</code></a></li>
<li><a class="reference internal" href="#vendor-specific-patch-series">4.17. Vendor-specific patch series</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="ch-binary.html"
 title="previous chapter">3. Binary packages</a>
 <h4>Next topic</h4>
 <a href="ch-controlfields.html"
 title="next chapter">5. Control files and their fields</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="_sources/ch-source.rst.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3 id="searchlabel">Quick search</h3>
 <div class="searchformwrapper">
 <form class="search" action="search.html" method="get">
 <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
 <input type="submit" value="Go" />
 </form>
 </div>
</div>
<script>$('#searchbox').show(0);</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="ch-controlfields.html" title="5. Control files and their fields"
 >next</a> |</li>
 <li class="right" >
 <a href="ch-binary.html" title="3. Binary packages"
 >previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">4. Source packages</a></li> 
 </ul>
 </div>
 <div class="footer" role="contentinfo">
 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.2.0.
 </div>
 </body>
</html>

${this.title}

Code Editor : ch-source.html