CINXE.COM
4. Source packages — Debian Policy Manual v4.7.0.2
<!DOCTYPE html> <html class="writer-html5" lang="en" data-content_root="./"> <head> <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>4. Source packages — Debian Policy Manual v4.7.0.2</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" /> <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=f5127f15" /> <link rel="stylesheet" type="text/css" href="_static/debian.css?v=bf0c9607" /> <script src="_static/jquery.js?v=8dae8fb0"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/documentation_options.js?v=77aade14"></script> <script src="_static/doctools.js?v=9bcbadda"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/js/theme.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 class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html" class="icon icon-home"> Debian Policy Manual </a> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="ch-scope.html">1. About this manual</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-archive.html">2. The Debian Archive</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-binary.html">3. Binary packages</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">4. Source packages</a><ul> <li class="toctree-l2"><a class="reference internal" href="#standards-conformance">4.1. Standards conformance</a></li> <li class="toctree-l2"><a class="reference internal" href="#package-relationships">4.2. Package relationships</a></li> <li class="toctree-l2"><a class="reference internal" href="#changes-to-the-upstream-sources">4.3. Changes to the upstream sources</a></li> <li class="toctree-l2"><a class="reference internal" href="#debian-changelog-debian-changelog">4.4. Debian changelog: <code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="#copyright-debian-copyright">4.5. Copyright: <code class="docutils literal notranslate"><span class="pre">debian/copyright</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="#error-trapping-in-makefiles">4.6. Error trapping in makefiles</a></li> <li class="toctree-l2"><a class="reference internal" href="#time-stamps">4.7. Time Stamps</a></li> <li class="toctree-l2"><a class="reference internal" href="#restrictions-on-objects-in-source-packages">4.8. Restrictions on objects in source packages</a></li> <li class="toctree-l2"><a class="reference internal" href="#main-building-script-debian-rules">4.9. Main building script: <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code></a><ul> <li class="toctree-l3"><a class="reference internal" href="#debian-rules-and-deb-build-options">4.9.1. <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> and <code class="docutils literal notranslate"><span class="pre">DEB_BUILD_OPTIONS</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="#debian-rules-and-rules-requires-root">4.9.2. <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> and <code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code></a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#variable-substitutions-debian-substvars">4.10. Variable substitutions: <code class="docutils literal notranslate"><span class="pre">debian/substvars</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="#upstream-source-location-debian-watch">4.11. Upstream source location: <code class="docutils literal notranslate"><span class="pre">debian/watch</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="#generated-files-list-debian-files">4.12. Generated files list: <code class="docutils literal notranslate"><span class="pre">debian/files</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="#embedded-code-copies">4.13. Embedded code copies</a></li> <li class="toctree-l2"><a class="reference internal" href="#source-package-handling-debian-readme-source">4.14. Source package handling: <code class="docutils literal notranslate"><span class="pre">debian/README.source</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="#reproducibility">4.15. Reproducibility</a></li> <li class="toctree-l2"><a class="reference internal" href="#missing-sources-debian-missing-sources">4.16. Missing sources: <code class="docutils literal notranslate"><span class="pre">debian/missing-sources</span></code></a></li> <li class="toctree-l2"><a class="reference internal" href="#vendor-specific-patch-series">4.17. Vendor-specific patch series</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="ch-controlfields.html">5. Control files and their fields</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-maintainerscripts.html">6. Package maintainer scripts and installation procedure</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-relationships.html">7. Declaring relationships between packages</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-sharedlibs.html">8. Shared libraries</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-opersys.html">9. The Operating System</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-files.html">10. Files</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-customized-programs.html">11. Customized programs</a></li> <li class="toctree-l1"><a class="reference internal" href="ch-docs.html">12. Documentation</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Appendices</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="ap-pkg-scope.html">1. Introduction and scope of these appendices</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-pkg-binarypkg.html">2. Binary packages (from old Packaging Manual)</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-pkg-sourcepkg.html">3. Source packages (from old Packaging Manual)</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-pkg-controlfields.html">4. Control files and their fields (from old Packaging Manual)</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-pkg-conffiles.html">5. Configuration file handling (from old Packaging Manual)</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-pkg-alternatives.html">6. Alternative versions of an interface - <code class="docutils literal notranslate"><span class="pre">update-alternatives</span></code> (from old Packaging Manual)</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-pkg-diversions.html">7. Diversions - overriding a package’s version of a file (from old Packaging Manual)</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-process.html">8. Debian Policy changes process</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-flowcharts.html">9. Maintainer script flowcharts</a></li> <li class="toctree-l1"><a class="reference internal" href="upgrading-checklist.html">10. Upgrading checklist</a></li> <li class="toctree-l1"><a class="reference internal" href="ap-license.html">11. License</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Debian Policy Manual</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active"><span class="section-number">4. </span>Source packages</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/ch-source.rst.txt" rel="nofollow"> View page source</a> </li> </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> <a href="ch-binary.html" class="btn btn-neutral float-left" title="3. Binary packages" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="ch-controlfields.html" class="btn btn-neutral float-right" title="5. Control files and their fields" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="source-packages"> <span id="s-source-packages"></span><h1><span class="section-number">4. </span>Source packages<a class="headerlink" href="#source-packages" title="Link to this heading"></a></h1> <p>A Debian source package contains the source material used to construct one or more <a class="reference internal" href="ch-binary.html"><span class="doc">binary packages</span></a>. A source package consists of a <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> file (see <a class="reference internal" href="ch-controlfields.html#s-debiansourcecontrolfiles"><span class="std std-ref">Debian source package control files – .dsc</span></a>), one or more compressed tar files, and possibly other files depending on the type and format of source package. Binary packages are contructed from the source package via a build process defined by <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> and other files in the <code class="docutils literal notranslate"><span class="pre">debian</span></code> directory of the unpacked source package.</p> <p>Debian source packages are classified as <em>native</em> or <em>non-native</em>.</p> <p>A native source package is one that does not distinguish between Debian packaging releases and upstream releases. A native source package contains a single tar file of source material, and the versioning does not have a Debian-specific component. Native packages are normally (but not exclusively) used for software that has no independent existence outside of Debian, such as software written specifically to be a Debian package.</p> <p>A non-native source package separates the upstream release from the Debian packaging and any Debian-specific changes. The source in a non-native source package is divided into one or more upstream tar files plus a collection of Debian-specific files. (Depending on the format of the source package, those Debian-specific files may come in the form of another tar file or in the form of a compressed diff.) The version of a non-native package has an upstream component and a Debian component, and there may be multiple Debian package versions associated with a single upstream release version and sharing the same upstream source tar files.</p> <p>Most source packages in Debian are non-native.</p> <section id="standards-conformance"> <span id="s-standardsversion"></span><h2><span class="section-number">4.1. </span>Standards conformance<a class="headerlink" href="#standards-conformance" title="Link to this heading"></a></h2> <p>Source packages should specify the most recent version number of this policy document with which your package complied when it was last updated.</p> <p>The version is specified in the <code class="docutils literal notranslate"><span class="pre">Standards-Version</span></code> control field. The format of the <code class="docutils literal notranslate"><span class="pre">Standards-Version</span></code> field is described in <a class="reference internal" href="ch-controlfields.html#s-f-standards-version"><span class="std std-ref">Standards-Version</span></a>.</p> <p>For a package to have an old Standards-Version value is not <em>itself</em> a bug, however. It just means that no-one has yet reviewed the package with changes to the standards in mind.</p> <p>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"><span class="doc">Upgrading checklist</span></a> can help with this task).</p> <p>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.</p> </section> <section id="package-relationships"> <span id="s-pkg-relations"></span><h2><span class="section-number">4.2. </span>Package relationships<a class="headerlink" href="#package-relationships" title="Link to this heading"></a></h2> <p>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.</p> <p>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 <em>build-essential</em>, and an informational list can be found in <code class="docutils literal notranslate"><span class="pre">/usr/share/doc/build-essential/list</span></code> (which is contained in the <code class="docutils literal notranslate"><span class="pre">build-essential</span></code> package). <a class="footnote-reference brackets" href="#id19" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p> <p>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="#id20" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p> <p>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.</p> <p><a class="reference internal" href="ch-relationships.html"><span class="doc">Declaring relationships between packages</span></a> explains the technical details.</p> </section> <section id="changes-to-the-upstream-sources"> <span id="s4-3"></span><h2><span class="section-number">4.3. </span>Changes to the upstream sources<a class="headerlink" href="#changes-to-the-upstream-sources" title="Link to this heading"></a></h2> <p>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.</p> <p>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"><span class="pre">autoconf</span></code> test or <code class="docutils literal notranslate"><span class="pre">#define</span></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"><span class="pre">debian/rules</span></code> or wherever is appropriate.</p> <p>You should make sure that the <code class="docutils literal notranslate"><span class="pre">configure</span></code> utility detects the correct architecture specification string (refer to <a class="reference internal" href="ch-customized-programs.html#s-arch-spec"><span class="std std-ref">Architecture specification strings</span></a> for details).</p> <p>If your package includes the scripts <code class="docutils literal notranslate"><span class="pre">config.sub</span></code> and <code class="docutils literal notranslate"><span class="pre">config.guess</span></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.</p> <p>If you need to edit a <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> where GNU-style <code class="docutils literal notranslate"><span class="pre">configure</span></code> scripts are used, you should edit the <code class="docutils literal notranslate"><span class="pre">.in</span></code> files rather than editing the <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> directly. This allows the user to reconfigure the package if necessary. You should <em>not</em> configure the package and edit the generated <code class="docutils literal notranslate"><span class="pre">Makefile</span></code>! This makes it impossible for someone else to later reconfigure the package without losing the changes you made.</p> </section> <section id="debian-changelog-debian-changelog"> <span id="s-dpkgchangelog"></span><h2><span class="section-number">4.4. </span>Debian changelog: <code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code><a class="headerlink" href="#debian-changelog-debian-changelog" title="Link to this heading"></a></h2> <p>Every source package must include the Debian changelog file, <code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code>. Changes in the Debian version of the package should be briefly explained in this file. <a class="footnote-reference brackets" href="#id21" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></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="#id22" id="id4" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a></p> <p>The format of the <code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code> allows the package building tools to discover which version of the package is being built and find out other release-specific information.</p> <p>That format is a series of entries like this:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">package</span> <span class="p">(</span><span class="n">version</span><span class="p">)</span> <span class="n">distribution</span><span class="p">(</span><span class="n">s</span><span class="p">);</span> <span class="n">urgency</span><span class="o">=</span><span class="n">urgency</span> <span class="p">[</span><span class="n">optional</span> <span class="n">blank</span> <span class="n">line</span><span class="p">(</span><span class="n">s</span><span class="p">),</span> <span class="n">stripped</span><span class="p">]</span> <span class="o">*</span> <span class="n">change</span> <span class="n">details</span> <span class="n">more</span> <span class="n">change</span> <span class="n">details</span> <span class="p">[</span><span class="n">blank</span> <span class="n">line</span><span class="p">(</span><span class="n">s</span><span class="p">),</span> <span class="n">included</span> <span class="ow">in</span> <span class="n">output</span> <span class="n">of</span> <span class="n">dpkg</span><span class="o">-</span><span class="n">parsechangelog</span><span class="p">]</span> <span class="o">*</span> <span class="n">even</span> <span class="n">more</span> <span class="n">change</span> <span class="n">details</span> <span class="p">[</span><span class="n">optional</span> <span class="n">blank</span> <span class="n">line</span><span class="p">(</span><span class="n">s</span><span class="p">),</span> <span class="n">stripped</span><span class="p">]</span> <span class="o">--</span> <span class="n">maintainer</span> <span class="n">name</span> <span class="o"><</span><span class="n">email</span> <span class="n">address</span><span class="o">></span><span class="p">[</span><span class="n">two</span> <span class="n">spaces</span><span class="p">]</span> <span class="n">date</span> </pre></div> </div> <p><code class="docutils literal notranslate"><span class="pre">package</span></code> and <code class="docutils literal notranslate"><span class="pre">version</span></code> are the source package name and version number.</p> <p><code class="docutils literal notranslate"><span class="pre">distribution(s)</span></code> lists the distributions where this version should be installed when it is uploaded - it is copied to the <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> field in the <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file. See <a class="reference internal" href="ch-controlfields.html#s-f-distribution"><span class="std std-ref">Distribution</span></a>.</p> <p><code class="docutils literal notranslate"><span class="pre">urgency</span></code> is the value for the <code class="docutils literal notranslate"><span class="pre">Urgency</span></code> field in the <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file for the upload (see <a class="reference internal" href="ch-controlfields.html#s-f-urgency"><span class="std std-ref">Urgency</span></a>). It is not possible to specify an urgency containing commas; commas are used to separate <code class="docutils literal notranslate"><span class="pre">keyword=value</span></code> settings in the <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> changelog format (though there is currently only one useful keyword, <code class="docutils literal notranslate"><span class="pre">urgency</span></code>).</p> <p>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.</p> <p>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"><span class="pre">closes:</span>  <span class="pre">Bug#nnnnn</span></code> in the change details, where <code class="docutils literal notranslate"><span class="pre">#nnnnn</span></code> is the bug number. <a class="footnote-reference brackets" href="#id23" id="id5" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a> This information is conveyed via the <code class="docutils literal notranslate"><span class="pre">Closes</span></code> field in the <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file (see <a class="reference internal" href="ch-controlfields.html#s-f-closes"><span class="std std-ref">Closes</span></a>).</p> <p>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 <em>not</em> necessarily those of the uploader or usual package maintainer. <a class="footnote-reference brackets" href="#id24" id="id6" role="doc-noteref"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></a> The information here will be copied to the <code class="docutils literal notranslate"><span class="pre">Changed-By</span></code> field in the <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file (see <a class="reference internal" href="ch-controlfields.html#s-f-changed-by"><span class="std std-ref">Changed-By</span></a>), and then later used to send an acknowledgement when the upload has been installed.</p> <p>The date has the following format <a class="footnote-reference brackets" href="#id25" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> (compatible and with the same semantics of RFC 2822 and RFC 5322):</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">day</span><span class="o">-</span><span class="n">of</span><span class="o">-</span><span class="n">week</span><span class="p">,</span> <span class="n">dd</span> <span class="n">month</span> <span class="n">yyyy</span> <span class="n">hh</span><span class="p">:</span><span class="n">mm</span><span class="p">:</span><span class="n">ss</span> <span class="o">+</span><span class="n">zzzz</span> </pre></div> </div> <p>where:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">day-of-week</span></code> is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">dd</span></code> is a one- or two-digit day of the month (01-31)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">month</span></code> is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">yyyy</span></code> is the four-digit year (e.g. 2010)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">hh</span></code> is the two-digit hour (00-23)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">mm</span></code> is the two-digit minutes (00-59)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">ss</span></code> is the two-digit seconds (00-60)</p></li> <li><dl class="simple"> <dt><code class="docutils literal notranslate"><span class="pre">+zzzz</span></code> or <code class="docutils literal notranslate"><span class="pre">-zzzz</span></code> is the time zone offset from Coordinated</dt><dd><p>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.</p> </dd> </dl> </li> </ul> <p>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.</p> <p>The entire changelog must be encoded in UTF-8.</p> <p>For more information on placement of the changelog files within binary packages, please see <a class="reference internal" href="ch-docs.html#s-changelogs"><span class="std std-ref">Changelog files and release notes</span></a>.</p> </section> <section id="copyright-debian-copyright"> <span id="s-dpkgcopyright"></span><h2><span class="section-number">4.5. </span>Copyright: <code class="docutils literal notranslate"><span class="pre">debian/copyright</span></code><a class="headerlink" href="#copyright-debian-copyright" title="Link to this heading"></a></h2> <p>Every package must be accompanied by a verbatim copy of its distribution license(s) in the file <code class="docutils literal notranslate"><span class="pre">/usr/share/doc/PACKAGE/copyright</span></code>.</p> <p>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"><span class="std std-ref">Copyright information</span></a> and <a class="reference internal" href="ch-archive.html#s-pkgcopyright"><span class="std std-ref">Copyright considerations</span></a> for details, and for further considerations related to copyrights for packages.</p> </section> <section id="error-trapping-in-makefiles"> <span id="s4-6"></span><h2><span class="section-number">4.6. </span>Error trapping in makefiles<a class="headerlink" href="#error-trapping-in-makefiles" title="Link to this heading"></a></h2> <p>When <code class="docutils literal notranslate"><span class="pre">make</span></code> invokes a command in a makefile (including your package’s upstream makefiles and <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code>), it does so using <code class="docutils literal notranslate"><span class="pre">sh</span></code>. This means that <code class="docutils literal notranslate"><span class="pre">sh</span></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"><span class="pre">make</span></code> will blithely continue after problems.</p> <p>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"><span class="pre">&&</span></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"><span class="pre">set</span> <span class="pre">-e</span></code> command at the start of every makefile command that’s actually one of these miniature shell scripts.</p> </section> <section id="time-stamps"> <span id="s-timestamps"></span><h2><span class="section-number">4.7. </span>Time Stamps<a class="headerlink" href="#time-stamps" title="Link to this heading"></a></h2> <p>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="#id26" id="id8" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a></p> </section> <section id="restrictions-on-objects-in-source-packages"> <span id="s-restrictions"></span><h2><span class="section-number">4.8. </span>Restrictions on objects in source packages<a class="headerlink" href="#restrictions-on-objects-in-source-packages" title="Link to this heading"></a></h2> <p>The source package must not contain device special files, sockets, or setuid or setgid files. <a class="footnote-reference brackets" href="#id27" id="id9" role="doc-noteref"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></a></p> </section> <section id="main-building-script-debian-rules"> <span id="s-debianrules"></span><h2><span class="section-number">4.9. </span>Main building script: <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code><a class="headerlink" href="#main-building-script-debian-rules" title="Link to this heading"></a></h2> <p>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.</p> <p><code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> must start with the line <code class="docutils literal notranslate"><span class="pre">#!/usr/bin/make</span> <span class="pre">-f</span></code>, so that it can be invoked by saying its name rather than invoking <code class="docutils literal notranslate"><span class="pre">make</span></code> explicitly. That is, invoking either of <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-f</span> <span class="pre">debian/rules</span> <span class="pre">args...</span></code> or <code class="docutils literal notranslate"><span class="pre">./debian/rules</span> <span class="pre">args...</span></code> must result in identical behavior.</p> <p>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"><span class="pre">dh</span></code> tool. This includes the contents of the <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> building script. <code class="docutils literal notranslate"><span class="pre">dh</span></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"><span class="pre">dh</span></code> will automatically implement many of them without requiring explicit instructions.</p> <p>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"><span class="pre">dh</span></code> does not always apply, and use of <code class="docutils literal notranslate"><span class="pre">dh</span></code> is not required.</p> <p>For more information about how to use <code class="docutils literal notranslate"><span class="pre">dh</span></code>, see the documentation in the debhelper package, most notably the <em class="manpage">dh(1)</em> manual page.</p> <p>The following targets are required and must be implemented by <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code>: <code class="docutils literal notranslate"><span class="pre">clean</span></code>, <code class="docutils literal notranslate"><span class="pre">binary</span></code>, <code class="docutils literal notranslate"><span class="pre">binary-arch</span></code>, <code class="docutils literal notranslate"><span class="pre">binary-indep</span></code>, <code class="docutils literal notranslate"><span class="pre">build</span></code>, <code class="docutils literal notranslate"><span class="pre">build-arch</span></code> and <code class="docutils literal notranslate"><span class="pre">build-indep</span></code>. These are the targets called by <code class="docutils literal notranslate"><span class="pre">dpkg-buildpackage</span></code>.</p> <p>Since an interactive <code class="docutils literal notranslate"><span class="pre">debian/rules</span></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.</p> <p>The package build should be as verbose as reasonably possible, except where the <code class="docutils literal notranslate"><span class="pre">terse</span></code> tag is included in <code class="docutils literal notranslate"><span class="pre">DEB_BUILD_OPTIONS</span></code> (see <a class="reference internal" href="#s-debianrules-options"><span class="std std-ref">debian/rules and DEB_BUILD_OPTIONS</span></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"><span class="pre">debian/rules</span></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"><span class="pre">--disable-silent-rules</span></code> to any configure scripts. See also <a class="reference internal" href="ch-files.html#s-binaries"><span class="std std-ref">Binaries</span></a>.</p> <p>Except for packages in the non-free archive with the <code class="docutils literal notranslate"><span class="pre">Autobuild</span></code> control field unset or set to <code class="docutils literal notranslate"><span class="pre">no</span></code>, 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.</p> <p>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"><span class="pre">/tmp</span></code>, <code class="docutils literal notranslate"><span class="pre">/var/tmp</span></code> and to the directory specified by the <code class="docutils literal notranslate"><span class="pre">TMPDIR</span></code> environment variable, but must not depend on the contents of any of these.</p> <p>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"><span class="pre">HOME</span></code>.</p> <p>The targets are as follows:</p> <dl> <dt><code class="docutils literal notranslate"><span class="pre">build</span></code> (required)</dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">build</span></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.)</p> <p>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"><span class="pre">build</span></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"><span class="pre">build-a</span></code> and <code class="docutils literal notranslate"><span class="pre">build-b</span></code> or whatever) for each of the ways of building the package, and a <code class="docutils literal notranslate"><span class="pre">build</span></code> target that does nothing. The <code class="docutils literal notranslate"><span class="pre">binary</span></code> target will have to build the package in each of the possible ways and make the binary package out of each.</p> <p>The <code class="docutils literal notranslate"><span class="pre">build</span></code> target must not do anything that might require root privilege.</p> <p>The <code class="docutils literal notranslate"><span class="pre">build</span></code> target may need to run the <code class="docutils literal notranslate"><span class="pre">clean</span></code> target first - see below.</p> <p>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"><span class="pre">build</span></code> needs to run <code class="docutils literal notranslate"><span class="pre">clean</span></code> first, it is a good idea to <code class="docutils literal notranslate"><span class="pre">touch</span> <span class="pre">build</span></code> when the build process is complete. This will ensure that if <code class="docutils literal notranslate"><span class="pre">debian/rules</span> <span class="pre">build</span></code> is run again it will not rebuild the whole program. <a class="footnote-reference brackets" href="#id28" id="id10" role="doc-noteref"><span class="fn-bracket">[</span>10<span class="fn-bracket">]</span></a></p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">build-arch</span></code> (required), <code class="docutils literal notranslate"><span class="pre">build-indep</span></code> (required)</dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">build-arch</span></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"><span class="pre">Architecture</span></code> field in <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> is not <code class="docutils literal notranslate"><span class="pre">all</span></code>). Similarly, the <code class="docutils literal notranslate"><span class="pre">build-indep</span></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"><span class="pre">Architecture</span></code> field in <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> is <code class="docutils literal notranslate"><span class="pre">all</span></code>). The <code class="docutils literal notranslate"><span class="pre">build</span></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="#id29" id="id11" role="doc-noteref"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></a></p> <p>The <code class="docutils literal notranslate"><span class="pre">build-arch</span></code> and <code class="docutils literal notranslate"><span class="pre">build-indep</span></code> targets must not do anything that might require root privilege.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">binary</span></code> (required), <code class="docutils literal notranslate"><span class="pre">binary-arch</span></code> (required), <code class="docutils literal notranslate"><span class="pre">binary-indep</span></code> (required)</dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">binary</span></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"><span class="pre">binary-arch</span></code> builds the binary packages which are specific to a particular architecture, and <code class="docutils literal notranslate"><span class="pre">binary-indep</span></code> builds those which are not.</p> <p><code class="docutils literal notranslate"><span class="pre">binary</span></code> may be (and commonly is) a target with no commands which simply depends on <code class="docutils literal notranslate"><span class="pre">binary-arch</span></code> and <code class="docutils literal notranslate"><span class="pre">binary-indep</span></code>.</p> <p>Both <code class="docutils literal notranslate"><span class="pre">binary-*</span></code> targets should depend on the <code class="docutils literal notranslate"><span class="pre">build</span></code> target, or on the appropriate <code class="docutils literal notranslate"><span class="pre">build-arch</span></code> or <code class="docutils literal notranslate"><span class="pre">build-indep</span></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"><span class="pre">dpkg-gencontrol</span></code> to make their control files and <code class="docutils literal notranslate"><span class="pre">dpkg-deb</span></code> to build them and place them in the parent of the top level directory.</p> <p>Both the <code class="docutils literal notranslate"><span class="pre">binary-arch</span></code> and <code class="docutils literal notranslate"><span class="pre">binary-indep</span></code> targets <em>must</em> 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.</p> <p>The <code class="docutils literal notranslate"><span class="pre">binary</span></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"><span class="std std-ref">Rules-Requires-Root</span></a> field. <a class="footnote-reference brackets" href="#id30" id="id12" role="doc-noteref"><span class="fn-bracket">[</span>12<span class="fn-bracket">]</span></a></p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">clean</span></code> (required)</dt><dd><p>This must undo any effects that the <code class="docutils literal notranslate"><span class="pre">build</span></code> and <code class="docutils literal notranslate"><span class="pre">binary</span></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"><span class="pre">binary</span></code> target.</p> <p>If a <code class="docutils literal notranslate"><span class="pre">build</span></code> file is touched at the end of the <code class="docutils literal notranslate"><span class="pre">build</span></code> target, as suggested above, it should be removed as the first action that <code class="docutils literal notranslate"><span class="pre">clean</span></code> performs, so that running <code class="docutils literal notranslate"><span class="pre">build</span></code> again after an interrupted <code class="docutils literal notranslate"><span class="pre">clean</span></code> doesn’t think that everything is already done.</p> <p>The <code class="docutils literal notranslate"><span class="pre">clean</span></code> target may need to be invoked as root if <code class="docutils literal notranslate"><span class="pre">binary</span></code> has been invoked since the last <code class="docutils literal notranslate"><span class="pre">clean</span></code>, or if <code class="docutils literal notranslate"><span class="pre">build</span></code> has been invoked as root (since <code class="docutils literal notranslate"><span class="pre">build</span></code> may create directories, for example).</p> <p>The <code class="docutils literal notranslate"><span class="pre">clean</span></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.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">patch</span></code> (optional)</dt><dd><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 <code class="docutils literal notranslate"><span class="pre">dpkg-source</span> <span class="pre">-x</span></code> does not result in source ready for additional modification. See <a class="reference internal" href="#s-readmesource"><span class="std std-ref">Source package handling: debian/README.source</span></a>.</p> </dd> </dl> <p>The <code class="docutils literal notranslate"><span class="pre">build</span></code>, <code class="docutils literal notranslate"><span class="pre">binary</span></code> and <code class="docutils literal notranslate"><span class="pre">clean</span></code> targets must be invoked with the current directory being the package’s top-level directory.</p> <p>Additional targets may exist in <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code>, either as published or undocumented interfaces or for the package’s internal use.</p> <p>The architectures we build on and build for are determined by <code class="docutils literal notranslate"><span class="pre">make</span></code> variables using the utility <code class="docutils literal notranslate"><span class="pre">dpkg-architecture</span></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"><span class="pre">debian/rules</span></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).</p> <p>Here is a list of supported <code class="docutils literal notranslate"><span class="pre">make</span></code> variables:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">DEB_*_ARCH</span></code> (the Debian architecture)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">DEB_*_ARCH_CPU</span></code> (the Debian CPU name)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">DEB_*_ARCH_BITS</span></code> (the Debian CPU pointer size in bits)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">DEB_*_ARCH_ENDIAN</span></code> (the Debian CPU endianness)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">DEB_*_ARCH_OS</span></code> (the Debian System name)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">DEB_*_GNU_TYPE</span></code> (the GNU style architecture specification string)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">DEB_*_GNU_CPU</span></code> (the CPU part of <code class="docutils literal notranslate"><span class="pre">DEB_*_GNU_TYPE</span></code>)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">DEB_*_GNU_SYSTEM</span></code> (the System part of <code class="docutils literal notranslate"><span class="pre">DEB_*_GNU_TYPE</span></code>)</p></li> </ul> <p>where <code class="docutils literal notranslate"><span class="pre">*</span></code> is either <code class="docutils literal notranslate"><span class="pre">BUILD</span></code> for specification of the build architecture, <code class="docutils literal notranslate"><span class="pre">HOST</span></code> for specification of the host architecture or <code class="docutils literal notranslate"><span class="pre">TARGET</span></code> for specification of the target architecture.</p> <p>Backward compatibility can be provided in the rules file by setting the needed variables to suitable default values; please refer to the documentation of <code class="docutils literal notranslate"><span class="pre">dpkg-architecture</span></code> for details.</p> <p>It is important to understand that the <code class="docutils literal notranslate"><span class="pre">DEB_*_ARCH</span></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"><span class="pre">DEB_*_ARCH_CPU</span></code> and <code class="docutils literal notranslate"><span class="pre">DEB_*_ARCH_OS</span></code> variables should be used for that. GNU style variables should generally only be used with upstream build systems.</p> <p>The builder may set <code class="docutils literal notranslate"><span class="pre">DEB_RULES_REQUIRES_ROOT</span></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"><span class="std std-ref">Rules-Requires-Root</span></a>. If the variable is not set, the package must behave as if it was set to <code class="docutils literal notranslate"><span class="pre">binary-targets</span></code>.</p> <section id="debian-rules-and-deb-build-options"> <span id="s-debianrules-options"></span><h3><span class="section-number">4.9.1. </span><code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> and <code class="docutils literal notranslate"><span class="pre">DEB_BUILD_OPTIONS</span></code><a class="headerlink" href="#debian-rules-and-deb-build-options" title="Link to this heading"></a></h3> <p>Supporting the standardized environment variable <code class="docutils literal notranslate"><span class="pre">DEB_BUILD_OPTIONS</span></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="#id31" id="id13" role="doc-noteref"><span class="fn-bracket">[</span>13<span class="fn-bracket">]</span></a> flag must start with a lowercase letter (<code class="docutils literal notranslate"><span class="pre">a-z</span></code>) and consist only of lowercase letters, numbers (<code class="docutils literal notranslate"><span class="pre">0-9</span></code>), and the characters <code class="docutils literal notranslate"><span class="pre">-</span></code> and <code class="docutils literal notranslate"><span class="pre">_</span></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"><span class="pre">DEB_BUILD_OPTIONS</span></code> will not contain conflicting tags.</p> <p>The meaning of the following tags has been standardized:</p> <dl class="simple"> <dt><code class="docutils literal notranslate"><span class="pre">nocheck</span></code></dt><dd><p>This tag says to not run any build-time test suite provided by the package.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">nodoc</span></code></dt><dd><p>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.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">noopt</span></code></dt><dd><p>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"><span class="pre">-O0</span></code> to <code class="docutils literal notranslate"><span class="pre">CFLAGS</span></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"><span class="pre">-O1</span></code>, for example.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">nostrip</span></code></dt><dd><p>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.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">parallel=n</span></code></dt><dd><p>This tag means that the package should be built using up to <code class="docutils literal notranslate"><span class="pre">n</span></code> parallel processes if the package build system supports this. <a class="footnote-reference brackets" href="#id32" id="id14" role="doc-noteref"><span class="fn-bracket">[</span>14<span class="fn-bracket">]</span></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.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">terse</span></code></dt><dd><p>This tag means that the package build will be less verbose than default. For example, <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> might pass options to the package’s configure script that cause the compiler to produce less output.</p> </dd> </dl> <p>Unknown flags must be ignored by <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code>.</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.</p> <div class="highlight-Makefile notranslate"><div class="highlight"><pre><span></span><span class="nv">CFLAGS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>-Wall<span class="w"> </span>-g <span class="nv">INSTALL</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>install <span class="nv">INSTALL_FILE</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">$(</span>INSTALL<span class="k">)</span><span class="w"> </span>-p<span class="w"> </span>-o<span class="w"> </span>root<span class="w"> </span>-g<span class="w"> </span>root<span class="w"> </span>-m<span class="w"> </span><span class="m">644</span> <span class="nv">INSTALL_PROGRAM</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">$(</span>INSTALL<span class="k">)</span><span class="w"> </span>-p<span class="w"> </span>-o<span class="w"> </span>root<span class="w"> </span>-g<span class="w"> </span>root<span class="w"> </span>-m<span class="w"> </span><span class="m">755</span> <span class="nv">INSTALL_SCRIPT</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">$(</span>INSTALL<span class="k">)</span><span class="w"> </span>-p<span class="w"> </span>-o<span class="w"> </span>root<span class="w"> </span>-g<span class="w"> </span>root<span class="w"> </span>-m<span class="w"> </span><span class="m">755</span> <span class="nv">INSTALL_DIR</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">$(</span>INSTALL<span class="k">)</span><span class="w"> </span>-p<span class="w"> </span>-d<span class="w"> </span>-o<span class="w"> </span>root<span class="w"> </span>-g<span class="w"> </span>root<span class="w"> </span>-m<span class="w"> </span><span class="m">755</span> <span class="cp">ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))</span> <span class="w"> </span><span class="nv">CFLAGS</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span>-O0 <span class="cp">else</span> <span class="w"> </span><span class="nv">CFLAGS</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span>-O2 <span class="cp">endif</span> <span class="cp">ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))</span> <span class="w"> </span><span class="nv">INSTALL_PROGRAM</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span>-s <span class="cp">endif</span> <span class="cp">ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))</span> <span class="w"> </span><span class="nv">NUMJOBS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">$(</span>patsubst<span class="w"> </span><span class="nv">parallel</span><span class="o">=</span>%,%,<span class="k">$(</span>filter<span class="w"> </span><span class="nv">parallel</span><span class="o">=</span>%,<span class="k">$(</span>DEB_BUILD_OPTIONS<span class="k">)))</span> <span class="w"> </span><span class="nv">MAKEFLAGS</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span>-j<span class="k">$(</span>NUMJOBS<span class="k">)</span> <span class="cp">endif</span> <span class="nf">build</span><span class="o">:</span> <span class="c"> # ...</span> <span class="cp">ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))</span> <span class="c"> # Code to run the package test suite.</span> <span class="cp">endif</span> </pre></div> </div> </section> <section id="debian-rules-and-rules-requires-root"> <span id="s-debianrules-gainrootapi"></span><h3><span class="section-number">4.9.2. </span><code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> and <code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code><a class="headerlink" href="#debian-rules-and-rules-requires-root" title="Link to this heading"></a></h3> <p>Depending on the value of the <a class="reference internal" href="ch-controlfields.html#s-f-rules-requires-root"><span class="std std-ref">Rules-Requires-Root</span></a> field, the package builder (e.g. dpkg-buildpackage) may run the <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> target as an unprivileged user and provide a <cite>gain root command</cite>. This command allows the <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> target to run particular subcommands under (fake)root.</p> <p>The <cite>gain root command</cite> is passed to the build script via the <code class="docutils literal notranslate"><span class="pre">DEB_GAIN_ROOT_CMD</span></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.</p> <p>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.</p> <p>The following are examples of valid gain root commands (in syntax of sh), assuming the tools used are available and properly configured:</p> <div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Command "sudo", with arguments "-nE" and "--"</span> <span class="nb">export</span><span class="w"> </span><span class="nv">DEB_GAIN_ROOT_CMD</span><span class="o">=</span><span class="s1">'sudo -nE --'</span> <span class="c1"># Command "fakeroot" with the single argument "--"</span> <span class="nb">export</span><span class="w"> </span><span class="nv">DEB_GAIN_ROOT_CMD</span><span class="o">=</span><span class="s1">'fakeroot --'</span> </pre></div> </div> <p>Examples of valid use of the <cite>gain root command</cite>:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span># sh-syntax (assumes set -e semantics for error handling) $DEB_GAIN_ROOT_CMD some-cmd --which-requires-root # perl my @cmd = ('some-cmd', '--which-requires-root'); unshift(@cmd, split(' ', $ENV{DEB_GAIN_ROOT_CMD})) if $ENV{DEB_GAIN_ROOT_CMD}; system(@cmd) == 0 or die("@cmd failed"); </pre></div> </div> </section> </section> <section id="variable-substitutions-debian-substvars"> <span id="s-substvars"></span><h2><span class="section-number">4.10. </span>Variable substitutions: <code class="docutils literal notranslate"><span class="pre">debian/substvars</span></code><a class="headerlink" href="#variable-substitutions-debian-substvars" title="Link to this heading"></a></h2> <p>When <code class="docutils literal notranslate"><span class="pre">dpkg-gencontrol</span></code> generates <a class="reference internal" href="ch-controlfields.html#s-binarycontrolfiles"><span class="std std-ref">binary package control files</span></a> (<code class="docutils literal notranslate"><span class="pre">DEBIAN/control</span></code>), it performs variable substitutions on its output just before writing it. Variable substitutions have the form <code class="docutils literal notranslate"><span class="pre">${variable}</span></code>. The optional file <code class="docutils literal notranslate"><span class="pre">debian/substvars</span></code> contains variable substitutions to be used; variables can also be set directly from <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> using the <code class="docutils literal notranslate"><span class="pre">-V</span></code> option to the source packaging commands, and certain predefined variables are also available.</p> <p>The <code class="docutils literal notranslate"><span class="pre">debian/substvars</span></code> file is usually generated and modified dynamically by <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> targets, in which case it must be removed by the <code class="docutils literal notranslate"><span class="pre">clean</span></code> target.</p> <p>See <em class="manpage">deb-substvars(5)</em> for full details about source variable substitutions, including the format of <code class="docutils literal notranslate"><span class="pre">debian/substvars</span></code>.</p> </section> <section id="upstream-source-location-debian-watch"> <span id="s-debianwatch"></span><h2><span class="section-number">4.11. </span>Upstream source location: <code class="docutils literal notranslate"><span class="pre">debian/watch</span></code><a class="headerlink" href="#upstream-source-location-debian-watch" title="Link to this heading"></a></h2> <p>This is a configuration file for the <code class="docutils literal notranslate"><span class="pre">uscan</span></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"><span class="pre">uscan</span></code> understands, including this configuration file is recommended.</p> <p>If the upstream maintainer of the software provides OpenPGP signatures for new releases, including the information required for <code class="docutils literal notranslate"><span class="pre">uscan</span></code> to verify signatures for new upstream releases is also recommended. To do this, use the <code class="docutils literal notranslate"><span class="pre">pgpsigurlmangle</span></code> option in <code class="docutils literal notranslate"><span class="pre">debian/watch</span></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"><span class="pre">debian/upstream/signing-key.asc</span></code>.</p> <p>For more information about <code class="docutils literal notranslate"><span class="pre">uscan</span></code> and these options, including how to generate the file containing upstream signing keys, see <em class="manpage">uscan(1)</em>.</p> </section> <section id="generated-files-list-debian-files"> <span id="s-debianfiles"></span><h2><span class="section-number">4.12. </span>Generated files list: <code class="docutils literal notranslate"><span class="pre">debian/files</span></code><a class="headerlink" href="#generated-files-list-debian-files" title="Link to this heading"></a></h2> <p>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"><span class="pre">dpkg-genchanges</span></code> uses it when it generates a <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file.</p> <p>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"><span class="pre">files.new</span></code>) <a class="footnote-reference brackets" href="#id33" id="id15" role="doc-noteref"><span class="fn-bracket">[</span>15<span class="fn-bracket">]</span></a> should be removed by the <code class="docutils literal notranslate"><span class="pre">clean</span></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"><span class="pre">binary</span></code> target.</p> <p>When <code class="docutils literal notranslate"><span class="pre">dpkg-gencontrol</span></code> is run for a binary package, it adds an entry to <code class="docutils literal notranslate"><span class="pre">debian/files</span></code> for the <code class="docutils literal notranslate"><span class="pre">.deb</span></code> file that will be created when <code class="docutils literal notranslate"><span class="pre">dpkg-deb</span> <span class="pre">--build</span></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"><span class="pre">clean</span></code> target.</p> <p>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"><span class="pre">dpkg-gencontrol</span></code> then they should be placed in the parent of the package’s top-level directory and <code class="docutils literal notranslate"><span class="pre">dpkg-distaddfile</span></code> should be called to add the file to the list in <code class="docutils literal notranslate"><span class="pre">debian/files</span></code>.</p> </section> <section id="embedded-code-copies"> <span id="s-embeddedfiles"></span><h2><span class="section-number">4.13. </span>Embedded code copies<a class="headerlink" href="#embedded-code-copies" title="Link to this heading"></a></h2> <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. <a class="footnote-reference brackets" href="#id34" id="id16" role="doc-noteref"><span class="fn-bracket">[</span>16<span class="fn-bracket">]</span></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="#id35" id="id17" role="doc-noteref"><span class="fn-bracket">[</span>17<span class="fn-bracket">]</span></a></p> </section> <section id="source-package-handling-debian-readme-source"> <span id="s-readmesource"></span><h2><span class="section-number">4.14. </span>Source package handling: <code class="docutils literal notranslate"><span class="pre">debian/README.source</span></code><a class="headerlink" href="#source-package-handling-debian-readme-source" title="Link to this heading"></a></h2> <p>If running <code class="docutils literal notranslate"><span class="pre">dpkg-source</span> <span class="pre">-x</span></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"><span class="pre">dpkg-buildpackage</span></code> to produce a modified package without taking any additional steps, creating a <code class="docutils literal notranslate"><span class="pre">debian/README.source</span></code> documentation file is recommended. This file should explain how to do all of the following:</p> <ol class="arabic simple"> <li><p>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"><span class="pre">patch</span></code> target in <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> is recommended; see <a class="reference external" href="#s-debianrules">Main building script: debian/rules</a>.</p></li> <li><p>Modify the source and save those modifications so that they will be applied when building the package.</p></li> <li><p>Remove source modifications that are currently being applied when building the package.</p></li> <li><p>Optionally, document what steps are necessary to upgrade the Debian source package to a new upstream version, if applicable.</p></li> </ol> <p>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><code class="docutils literal notranslate"><span class="pre">debian/README.source</span></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"><span class="pre">debian/README.source</span></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).</p> </section> <section id="reproducibility"> <h2><span class="section-number">4.15. </span>Reproducibility<a class="headerlink" href="#reproducibility" title="Link to this heading"></a></h2> <p>Packages should build reproducibly, which for the purposes of this document <a class="footnote-reference brackets" href="#id36" id="id18" role="doc-noteref"><span class="fn-bracket">[</span>18<span class="fn-bracket">]</span></a> means that given</p> <ul class="simple"> <li><p>a version of a source package unpacked at a given path;</p></li> <li><p>a set of versions of installed build dependencies;</p></li> <li><p>a set of environment variable values;</p></li> <li><p>a build architecture; and</p></li> <li><p>a host architecture,</p></li> </ul> <p>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.</p> <p>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.</p> </section> <section id="missing-sources-debian-missing-sources"> <h2><span class="section-number">4.16. </span>Missing sources: <code class="docutils literal notranslate"><span class="pre">debian/missing-sources</span></code><a class="headerlink" href="#missing-sources-debian-missing-sources" title="Link to this heading"></a></h2> <p>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"><span class="pre">main</span></code> or <code class="docutils literal notranslate"><span class="pre">contrib</span></code>, you should either:</p> <ol class="arabic simple"> <li><p>repack the upstream tarball to include those sources; or</p></li> <li><p>include a copy of the sources in the <code class="docutils literal notranslate"><span class="pre">debian/missing-sources</span></code> directory.</p></li> </ol> <p>Package maintainers may optionally use the following convention to organize the contents of <code class="docutils literal notranslate"><span class="pre">debian/missing-sources</span></code>: for a sourceless file <code class="docutils literal notranslate"><span class="pre">foo</span></code> in the subdirectory <code class="docutils literal notranslate"><span class="pre">bar</span></code> of the upstream tarball, where the source of <code class="docutils literal notranslate"><span class="pre">foo</span></code> has extension <code class="docutils literal notranslate"><span class="pre">baz</span></code>, place the source at <code class="docutils literal notranslate"><span class="pre">debian/missing-sources/bar/foo.baz</span></code>. For example, according to this convention, the C source code of an executable <code class="docutils literal notranslate"><span class="pre">checksum/util</span></code> would be located at <code class="docutils literal notranslate"><span class="pre">debian/missing-sources/checksum/util.c</span></code>.</p> </section> <section id="vendor-specific-patch-series"> <h2><span class="section-number">4.17. </span>Vendor-specific patch series<a class="headerlink" href="#vendor-specific-patch-series" title="Link to this heading"></a></h2> <p>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"><span class="pre">debian/patches/foo.series</span></code> for any <code class="docutils literal notranslate"><span class="pre">foo</span></code>.</p> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id19" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span> <p>Rationale:</p> <ul class="simple"> <li><p>This allows maintaining the list separately from the policy documents (the list does not need the kind of control that the policy documents do).</p></li> <li><p>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.</p></li> <li><p>The separate package allows bug reports against the list to be categorized separately from the policy management process in the BTS.</p></li> </ul> </aside> <aside class="footnote brackets" id="id20" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">2</a><span class="fn-bracket">]</span></span> <p>The reason for this is that dependencies change, and you should list all those packages, and <em>only</em> those packages that <em>you</em> need directly. What others need is their business. For example, if you only link against <code class="docutils literal notranslate"><span class="pre">libimlib</span></code>, you will need to build-depend on libimlib2-dev but not against any <code class="docutils literal notranslate"><span class="pre">libjpeg*</span></code> packages, even though <code class="docutils literal notranslate"><span class="pre">libimlib2-dev</span></code> currently depends on them: installation of libimlib2-dev will automatically ensure that all of its run-time dependencies are satisfied.</p> </aside> <aside class="footnote brackets" id="id21" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">3</a><span class="fn-bracket">]</span></span> <p>Mistakes in changelogs are usually best rectified by making a new changelog entry rather than “rewriting history” by editing old changelog entries.</p> </aside> <aside class="footnote brackets" id="id22" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id4">4</a><span class="fn-bracket">]</span></span> <p>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.</p> </aside> <aside class="footnote brackets" id="id23" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id5">5</a><span class="fn-bracket">]</span></span> <p>To be precise, the string should match the following Perl regular expression:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i </pre></div> </div> <p>That is: The string should consist of the word <code class="docutils literal notranslate"><span class="pre">closes:</span></code> followed by a comma-separated list of bug numbers. Bug numbers may be preceded by the word <code class="docutils literal notranslate"><span class="pre">bug</span></code> and/or a <code class="docutils literal notranslate"><span class="pre">#</span></code> sign, as in <code class="docutils literal notranslate"><span class="pre">Closes:</span> <span class="pre">42,</span> <span class="pre">bug#43,</span> <span class="pre">#44,</span> <span class="pre">bug</span> <span class="pre">45</span></code>.</p> <p>The list of bug numbers may span multiple lines.</p> <p>All of the bug numbers listed will be closed by the archive maintenance software (<code class="docutils literal notranslate"><span class="pre">dak</span></code>) using the version of the changelog entry.</p> <p>The words <code class="docutils literal notranslate"><span class="pre">closes:</span></code> and <code class="docutils literal notranslate"><span class="pre">bug</span></code> are not case sensitive.</p> </aside> <aside class="footnote brackets" id="id24" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id6">6</a><span class="fn-bracket">]</span></span> <p>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"><span class="std std-ref">Maintainer</span></a> or <a class="reference internal" href="ch-controlfields.html#s-f-uploaders"><span class="std std-ref">Uploaders</span></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"><span class="std std-ref">Related documents</span></a>) documents the conventions used.</p> </aside> <aside class="footnote brackets" id="id25" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id7">7</a><span class="fn-bracket">]</span></span> <p>This is the same as the format generated by <code class="docutils literal notranslate"><span class="pre">date</span> <span class="pre">-R</span></code>.</p> </aside> <aside class="footnote brackets" id="id26" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id8">8</a><span class="fn-bracket">]</span></span> <p>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.</p> </aside> <aside class="footnote brackets" id="id27" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id9">9</a><span class="fn-bracket">]</span></span> <p>Setgid directories are allowed.</p> </aside> <aside class="footnote brackets" id="id28" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id10">10</a><span class="fn-bracket">]</span></span> <p>Another common way to do this is for <code class="docutils literal notranslate"><span class="pre">build</span></code> to depend on <code class="docutils literal notranslate"><span class="pre">build-stamp</span></code> and to do nothing else, and for the <code class="docutils literal notranslate"><span class="pre">build-stamp</span></code> target to do the building and to <code class="docutils literal notranslate"><span class="pre">touch</span> <span class="pre">build-stamp</span></code> on completion. This is especially useful if the build routine creates a file or directory called <code class="docutils literal notranslate"><span class="pre">build</span></code>; in such a case, <code class="docutils literal notranslate"><span class="pre">build</span></code> will need to be listed as a phony target (i.e., as a dependency of the <code class="docutils literal notranslate"><span class="pre">.PHONY</span></code> target). See the documentation of <code class="docutils literal notranslate"><span class="pre">make</span></code> for more information on phony targets.</p> </aside> <aside class="footnote brackets" id="id29" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id11">11</a><span class="fn-bracket">]</span></span> <p>This split allows binary-only builds to not install the dependencies required for the <code class="docutils literal notranslate"><span class="pre">build-indep</span></code> target and skip any resource-intensive build tasks that are only required when building architecture-independent binary packages.</p> </aside> <aside class="footnote brackets" id="id30" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id12">12</a><span class="fn-bracket">]</span></span> <p>The <code class="docutils literal notranslate"><span class="pre">fakeroot</span></code> package often allows one to build a package correctly even without being root.</p> </aside> <aside class="footnote brackets" id="id31" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id13">13</a><span class="fn-bracket">]</span></span> <p>Some packages support any delimiter, but whitespace is the easiest to parse inside a makefile and avoids ambiguity with flag values that contain commas.</p> </aside> <aside class="footnote brackets" id="id32" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id14">14</a><span class="fn-bracket">]</span></span> <p>Packages built with <code class="docutils literal notranslate"><span class="pre">make</span></code> can often implement this by passing the <code class="docutils literal notranslate"><span class="pre">-j</span></code>n option to <code class="docutils literal notranslate"><span class="pre">make</span></code>.</p> </aside> <aside class="footnote brackets" id="id33" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id15">15</a><span class="fn-bracket">]</span></span> <p><code class="docutils literal notranslate"><span class="pre">files.new</span></code> is used as a temporary file by <code class="docutils literal notranslate"><span class="pre">dpkg-gencontrol</span></code> and <code class="docutils literal notranslate"><span class="pre">dpkg-distaddfile</span></code> - they write a new version of <code class="docutils literal notranslate"><span class="pre">files</span></code> here before renaming it, to avoid leaving a corrupted copy if an error occurs.</p> </aside> <aside class="footnote brackets" id="id34" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id16">16</a><span class="fn-bracket">]</span></span> <p>For example, parts of the GNU build system work like this.</p> </aside> <aside class="footnote brackets" id="id35" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id17">17</a><span class="fn-bracket">]</span></span> <p>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.</p> </aside> <aside class="footnote brackets" id="id36" role="doc-footnote"> <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id18">18</a><span class="fn-bracket">]</span></span> <p>This is Debian’s precisification of the <a class="reference external" href="https://reproducible-builds.org/docs/definition/">reproducible-builds.org definition</a>.</p> </aside> </aside> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="ch-binary.html" class="btn btn-neutral float-left" title="3. Binary packages" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="ch-controlfields.html" class="btn btn-neutral float-right" title="5. Control files and their fields" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p></p> </div> </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>