File: //usr/share/doc/debian-policy/policy.html/ch-files.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>10. Files — Debian Policy Manual v4.6.0.1</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/nature.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="11. Customized programs" href="ch-customized-programs.html" />
<link rel="prev" title="9. The Operating System" href="ch-opersys.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="ch-customized-programs.html" title="11. Customized programs"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="ch-opersys.html" title="9. The Operating System"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> »</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">10. </span>Files</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="files">
<h1><span class="section-number">10. </span>Files<a class="headerlink" href="#files" title="Permalink to this headline">¶</a></h1>
<section id="binaries">
<span id="s-binaries"></span><h2><span class="section-number">10.1. </span>Binaries<a class="headerlink" href="#binaries" title="Permalink to this headline">¶</a></h2>
<p>Two different packages must not install programs with different
functionality but with the same filenames. (The case of two programs
having the same functionality but different implementations is handled
via “alternatives” or the “Conflicts” mechanism. See
<a class="reference internal" href="ch-binary.html#s-maintscripts"><span class="std std-ref">Maintainer Scripts</span></a> and
<a class="reference internal" href="ch-relationships.html#s-conflicts"><span class="std std-ref">Conflicting binary packages - Conflicts</span></a> respectively.) If this case happens,
one of the programs must be renamed. The maintainers should report this
to the <code class="docutils literal notranslate"><span class="pre">debian-devel</span></code> mailing list and try to find a consensus about
which program will have to be renamed. If a consensus cannot be reached,
<em>both</em> programs must be renamed.</p>
<p>To support merged-<code class="docutils literal notranslate"><span class="pre">/usr</span></code> systems, packages must not install files in
both <code class="docutils literal notranslate"><span class="pre">/path</span></code> and <code class="docutils literal notranslate"><span class="pre">/usr/path</span></code>. For example, a package must not install
both <code class="docutils literal notranslate"><span class="pre">/bin/example</span></code> and <code class="docutils literal notranslate"><span class="pre">/usr/bin/example</span></code>.</p>
<p>If a file is moved between <code class="docutils literal notranslate"><span class="pre">/path</span></code> and <code class="docutils literal notranslate"><span class="pre">/usr/path</span></code> in revisions of a
Debian package, and a compatibility symlink at the old path is needed,
the symlink must be managed in a way that will not break when <code class="docutils literal notranslate"><span class="pre">/path</span></code>
and <code class="docutils literal notranslate"><span class="pre">/usr/path</span></code> are the same underlying directory due to symlinks or
other mechanisms.</p>
<p>Binary executables must not be statically linked with the GNU C library,
since this prevents the binary from benefiting from fixes and
improvements to the C library without being rebuilt and complicates
security updates. This requirement may be relaxed for binary executables
whose intended purpose is to diagnose and fix the system in situations
where the GNU C library may not be usable (such as system recovery
shells or utilities like ldconfig) or for binary executables where the
security benefits of static linking outweigh the drawbacks.</p>
<p>By default, when a package is being built, any binaries created should
include debugging information, as well as being compiled with
optimization. You should also turn on as many reasonable compilation
warnings as possible (see <a class="reference internal" href="ch-source.html#s-debianrules"><span class="std std-ref">Main building script: debian/rules</span></a>). For the C programming
language, this means the following compilation parameters should be
used:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">CC</span> <span class="o">=</span> <span class="n">gcc</span>
<span class="n">CFLAGS</span> <span class="o">=</span> <span class="o">-</span><span class="n">O2</span> <span class="o">-</span><span class="n">g</span> <span class="o">-</span><span class="n">Wall</span> <span class="c1"># sane warning options vary between programs</span>
<span class="n">LDFLAGS</span> <span class="o">=</span> <span class="c1"># none</span>
</pre></div>
</div>
<p>By default all installed binaries should be stripped by calling</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">strip</span> <span class="o">--</span><span class="n">strip</span><span class="o">-</span><span class="n">unneeded</span> <span class="o">--</span><span class="n">remove</span><span class="o">-</span><span class="n">section</span><span class="o">=.</span><span class="n">comment</span> <span class="o">--</span><span class="n">remove</span><span class="o">-</span><span class="n">section</span><span class="o">=.</span><span class="n">note</span> <span class="n">binaries</span>
</pre></div>
</div>
<p>on the binaries after they have been copied into <code class="docutils literal notranslate"><span class="pre">debian/tmp</span></code> but
before the tree is made into a package.</p>
<p>It is not recommended to strip binaries by passing the <code class="docutils literal notranslate"><span class="pre">-s</span></code> flag to
<code class="docutils literal notranslate"><span class="pre">install</span></code>, because this fails to remove .comment and .note sections,
and also prevents the automatic creation of dbgsym binary packages by
tools like <code class="docutils literal notranslate"><span class="pre">dh_strip</span></code>.</p>
<p>Although binaries in the build tree should be compiled with debugging
information by default, it can often be difficult to debug programs if
they are also subjected to compiler optimization. For this reason, it is
recommended to support the standardized environment variable
<code class="docutils literal notranslate"><span class="pre">DEB_BUILD_OPTIONS</span></code> (see <a class="reference internal" href="ch-source.html#s-debianrules-options"><span class="std std-ref">debian/rules and DEB_BUILD_OPTIONS</span></a>).
This variable can contain several flags to change how a package is
compiled and built.</p>
<p>It is up to the package maintainer to decide what compilation options
are best for the package. Certain binaries (such as
computationally-intensive programs) will function better with certain
flags (<code class="docutils literal notranslate"><span class="pre">-O3</span></code>, for example); feel free to use them. Please use good
judgment here. Don’t use flags for the sake of it; only use them if
there is good reason to do so. Feel free to override the upstream
author’s ideas about which compilation options are best: they are often
inappropriate for our environment.</p>
</section>
<section id="libraries">
<span id="s-libraries"></span><h2><span class="section-number">10.2. </span>Libraries<a class="headerlink" href="#libraries" title="Permalink to this headline">¶</a></h2>
<p>If the package is <strong>architecture: any</strong>, then the shared library
compilation and linking flags must have <code class="docutils literal notranslate"><span class="pre">-fPIC</span></code>, or the package shall
not build on some of the supported architectures. <a class="footnote-reference brackets" href="#id16" id="id1">1</a> Any exception
to this rule must be discussed on the mailing list
<em>debian-devel@lists.debian.org</em>, and a rough consensus obtained. The
reasons for not compiling with <code class="docutils literal notranslate"><span class="pre">-fPIC</span></code> flag must be recorded in the
file <code class="docutils literal notranslate"><span class="pre">README.Debian</span></code>, and care must be taken to either restrict the
architecture or arrange for <code class="docutils literal notranslate"><span class="pre">-fPIC</span></code> to be used on architectures where
it is required. <a class="footnote-reference brackets" href="#id17" id="id2">2</a></p>
<p>As to the static libraries, the common case is not to have relocatable
code, since there is no benefit, unless in specific cases; therefore the
static version must not be compiled with the <code class="docutils literal notranslate"><span class="pre">-fPIC</span></code> flag. Any
exception to this rule should be discussed on the mailing list
<em>debian-devel@lists.debian.org</em>, and the reasons for compiling with the
<code class="docutils literal notranslate"><span class="pre">-fPIC</span></code> flag must be recorded in the file <code class="docutils literal notranslate"><span class="pre">README.Debian</span></code>. <a class="footnote-reference brackets" href="#id18" id="id3">3</a></p>
<p>In other words, if both a shared and a static library is being built,
each source unit (<code class="docutils literal notranslate"><span class="pre">*.c</span></code>, for example, for C files) will need to be
compiled twice, for the normal case.</p>
<p>Libraries should be built with threading support and to be thread-safe
if the library supports this.</p>
<p>Although not enforced by the build tools, shared libraries must be
linked against all libraries that they use symbols from in the same way
that binaries are. This ensures the correct functioning of the
<a class="reference internal" href="ch-sharedlibs.html#s-sharedlibs-symbols"><span class="std std-ref">symbols</span></a> and <a class="reference internal" href="ch-sharedlibs.html#s-sharedlibs-shlibdeps"><span class="std std-ref">shlibs</span></a> systems and guarantees that all
libraries can be safely opened with <code class="docutils literal notranslate"><span class="pre">dlopen()</span></code>. Packagers may wish to
use the gcc option <code class="docutils literal notranslate"><span class="pre">-Wl,-z,defs</span></code> when building a shared library. Since
this option enforces symbol resolution at build time, a missing library
reference will be caught early as a fatal build error.</p>
<p>All installed shared libraries should be stripped with</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">strip</span> <span class="o">--</span><span class="n">strip</span><span class="o">-</span><span class="n">unneeded</span> <span class="o">--</span><span class="n">remove</span><span class="o">-</span><span class="n">section</span><span class="o">=.</span><span class="n">comment</span> <span class="o">--</span><span class="n">remove</span><span class="o">-</span><span class="n">section</span><span class="o">=.</span><span class="n">note</span> <span class="n">your</span><span class="o">-</span><span class="n">lib</span>
</pre></div>
</div>
<p>(The option <code class="docutils literal notranslate"><span class="pre">--strip-unneeded</span></code> makes <code class="docutils literal notranslate"><span class="pre">strip</span></code> remove only the symbols
which aren’t needed for relocation processing.) Shared libraries can
function perfectly well when stripped, since the symbols for dynamic
linking are in a separate part of the ELF object file. <a class="footnote-reference brackets" href="#id19" id="id4">4</a></p>
<p>Note that under some circumstances it may be useful to install a shared
library unstripped, for example when building a separate package to
support debugging. The debhelper <cite>dh_strip`</cite> tool can create such
packages automatically.</p>
<p>Shared object files (often <code class="docutils literal notranslate"><span class="pre">.so</span></code> files) that are not public
libraries, that is, they are not meant to be linked to by third party
executables (binaries of other packages), should be installed in
subdirectories of the <code class="docutils literal notranslate"><span class="pre">/usr/lib</span></code> or <code class="docutils literal notranslate"><span class="pre">/usr/lib/triplet</span></code> directories
(see the FHS for a definition). Such files are exempt from the rules
that govern ordinary shared libraries, except that they must not be
installed executable and should be stripped. <a class="footnote-reference brackets" href="#id20" id="id5">5</a></p>
<p>Packages that use <code class="docutils literal notranslate"><span class="pre">libtool</span></code> to create and install their shared
libraries install a file containing additional metadata (ending in
<code class="docutils literal notranslate"><span class="pre">.la</span></code>) alongside the library. For public libraries intended for use by
other packages, these files normally should not be included in the
Debian package, since the information they include is not necessary to
link with the shared library on Debian and can add unnecessary
additional dependencies to other programs or libraries. <a class="footnote-reference brackets" href="#id21" id="id6">6</a> If the
<code class="docutils literal notranslate"><span class="pre">.la</span></code> file is required for that library (if, for instance, it’s loaded
via <code class="docutils literal notranslate"><span class="pre">libltdl</span></code> in a way that requires that meta-information), the
<code class="docutils literal notranslate"><span class="pre">dependency_libs</span></code> setting in the <code class="docutils literal notranslate"><span class="pre">.la</span></code> file should normally be set
to the empty string. If the shared library development package has
historically included the <code class="docutils literal notranslate"><span class="pre">.la</span></code>, it must be retained in the
development package (with <code class="docutils literal notranslate"><span class="pre">dependency_libs</span></code> emptied) until all
libraries that depend on it have removed or emptied <code class="docutils literal notranslate"><span class="pre">dependency_libs</span></code>
in their <code class="docutils literal notranslate"><span class="pre">.la</span></code> files to prevent linking with those other libraries
using <code class="docutils literal notranslate"><span class="pre">libtool</span></code> from failing.</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">.la</span></code> must be included, it should be included in the
development (<code class="docutils literal notranslate"><span class="pre">-dev</span></code>) package, unless the library will be loaded by
<code class="docutils literal notranslate"><span class="pre">libtool</span></code>’s <code class="docutils literal notranslate"><span class="pre">libltdl</span></code> library. If it is intended for use with
<code class="docutils literal notranslate"><span class="pre">libltdl</span></code>, the <code class="docutils literal notranslate"><span class="pre">.la</span></code> files must go in the run-time library package.</p>
<p>These requirements for handling of <code class="docutils literal notranslate"><span class="pre">.la</span></code> files do not apply to
loadable modules or libraries not installed in directories searched by
default by the dynamic linker. Packages installing loadable modules will
frequently need to install the <code class="docutils literal notranslate"><span class="pre">.la</span></code> files alongside the modules so
that they can be loaded by <code class="docutils literal notranslate"><span class="pre">libltdl</span></code>. <code class="docutils literal notranslate"><span class="pre">dependency_libs</span></code> does not
need to be modified for libraries or modules that are not installed in
directories searched by the dynamic linker by default and not intended
for use by other packages.</p>
<p>You must make sure that you use only released versions of shared
libraries to build your packages; otherwise other users will not be able
to run your binaries properly. Producing source packages that depend on
unreleased compilers is also usually a bad idea.</p>
</section>
<section id="shared-libraries">
<span id="s10-3"></span><h2><span class="section-number">10.3. </span>Shared libraries<a class="headerlink" href="#shared-libraries" title="Permalink to this headline">¶</a></h2>
<p>This section has moved to <a class="reference internal" href="ch-sharedlibs.html"><span class="doc">Shared libraries</span></a>.</p>
</section>
<section id="scripts">
<span id="s-scripts"></span><h2><span class="section-number">10.4. </span>Scripts<a class="headerlink" href="#scripts" title="Permalink to this headline">¶</a></h2>
<p>All command scripts, including the package maintainer scripts inside the
package and used by <code class="docutils literal notranslate"><span class="pre">dpkg</span></code>, should have a <code class="docutils literal notranslate"><span class="pre">#!</span></code> line naming the shell
to be used to interpret them.</p>
<p>In the case of Perl scripts this should be <code class="docutils literal notranslate"><span class="pre">#!/usr/bin/perl</span></code>.</p>
<p>When scripts are installed into a directory in the system PATH, the
script name should not include an extension such as <code class="docutils literal notranslate"><span class="pre">.sh</span></code> or <code class="docutils literal notranslate"><span class="pre">.pl</span></code>
that denotes the scripting language currently used to implement it.</p>
<p>Shell scripts (<code class="docutils literal notranslate"><span class="pre">sh</span></code> and <code class="docutils literal notranslate"><span class="pre">bash</span></code>) other than <code class="docutils literal notranslate"><span class="pre">init.d</span></code> scripts should
almost certainly start with <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">-e</span></code> so that errors are detected.
<code class="docutils literal notranslate"><span class="pre">init.d</span></code> scripts are something of a special case, due to how
frequently they need to call commands that are allowed to fail, and it
may instead be easier to check the exit status of commands directly. See
<a class="reference internal" href="ch-opersys.html#s-writing-init"><span class="std std-ref">Writing the scripts</span></a> for more information about writing
<code class="docutils literal notranslate"><span class="pre">init.d</span></code> scripts.</p>
<p>Every script should use <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">-e</span></code> or check the exit status of <em>every</em>
command.</p>
<p>Scripts may assume that <code class="docutils literal notranslate"><span class="pre">/bin/sh</span></code> implements the POSIX.1-2017 Shell Command
Language <a class="footnote-reference brackets" href="#id22" id="id7">7</a> plus the following additional features not mandated by
POSIX.1-2017.. <a class="footnote-reference brackets" href="#id23" id="id8">8</a></p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">-n</span></code>, if implemented as a shell built-in, must not generate a
newline.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">test</span></code>, if implemented as a shell built-in, must support <code class="docutils literal notranslate"><span class="pre">-a</span></code> and
<code class="docutils literal notranslate"><span class="pre">-o</span></code> as binary logical operators.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">local</span></code> to create a scoped variable must be supported, including
listing multiple variables in a single local command and assigning a
value to a variable at the same time as localizing it. <code class="docutils literal notranslate"><span class="pre">local</span></code> may
or may not preserve the variable value from an outer scope if no
assignment is present. Uses such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fname</span> <span class="p">()</span> <span class="p">{</span>
<span class="n">local</span> <span class="n">a</span> <span class="n">b</span> <span class="n">c</span><span class="o">=</span><span class="n">delta</span> <span class="n">d</span>
<span class="c1"># ... use a, b, c, d ...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>must be supported and must set the value of <code class="docutils literal notranslate"><span class="pre">c</span></code> to <code class="docutils literal notranslate"><span class="pre">delta</span></code>.</p>
</li>
<li><p>The XSI extension to <code class="docutils literal notranslate"><span class="pre">kill</span></code> allowing <code class="docutils literal notranslate"><span class="pre">kill</span> <span class="pre">-signal</span></code>, where signal
is either the name of a signal or one of the numeric signals listed
in the XSI extension (0, 1, 2, 3, 6, 9, 14, and 15), must be
supported if <code class="docutils literal notranslate"><span class="pre">kill</span></code> is implemented as a shell built-in.</p></li>
<li><p>The XSI extension to <code class="docutils literal notranslate"><span class="pre">trap</span></code> allowing numeric signals must be
supported. In addition to the signal numbers listed in the extension,
which are the same as for <code class="docutils literal notranslate"><span class="pre">kill</span></code> above, 13 (SIGPIPE) must be
allowed.</p></li>
</ul>
<p>If a shell script requires non-POSIX.1-2017 features from the shell interpreter
other than those listed above, the appropriate shell must be specified
in the first line of the script (e.g., <code class="docutils literal notranslate"><span class="pre">#!/bin/bash</span></code>) and the package
must depend on the package providing the shell (unless the shell package
is marked “Essential”, as in the case of <code class="docutils literal notranslate"><span class="pre">bash</span></code>).</p>
<p>You may wish to restrict your script to POSIX.1-2017 features plus the above
set when possible so that it may use <code class="docutils literal notranslate"><span class="pre">/bin/sh</span></code> as its interpreter.
Checking your script with <code class="docutils literal notranslate"><span class="pre">checkbashisms</span></code> from the devscripts package
or running your script with an alternate shell such as <code class="docutils literal notranslate"><span class="pre">posh</span></code> may help
uncover violations of the above requirements. If in doubt whether a
script complies with these requirements, use <code class="docutils literal notranslate"><span class="pre">/bin/bash</span></code>.</p>
<p>Perl scripts should check for errors when making any system calls,
including <code class="docutils literal notranslate"><span class="pre">open</span></code>, <code class="docutils literal notranslate"><span class="pre">print</span></code>, <code class="docutils literal notranslate"><span class="pre">close</span></code>, <code class="docutils literal notranslate"><span class="pre">rename</span></code> and <code class="docutils literal notranslate"><span class="pre">system</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">csh</span></code> and <code class="docutils literal notranslate"><span class="pre">tcsh</span></code> should be avoided as scripting languages. See <em>Csh
Programming Considered Harmful</em>, one of the <code class="docutils literal notranslate"><span class="pre">comp.unix.*</span></code> FAQs, which
can be found at <a class="reference external" href="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/">http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/</a>. If
an upstream package comes with <code class="docutils literal notranslate"><span class="pre">csh</span></code> scripts then you must make sure
that they start with <code class="docutils literal notranslate"><span class="pre">#!/bin/csh</span></code> and make your package depend on the
<code class="docutils literal notranslate"><span class="pre">c-shell</span></code> virtual package.</p>
<p>Any scripts which create files in world-writeable directories (e.g., in
<code class="docutils literal notranslate"><span class="pre">/tmp</span></code>) must use a mechanism which will fail atomically if a file with
the same name already exists.</p>
<p>The Debian base system provides the <code class="docutils literal notranslate"><span class="pre">tempfile</span></code> and <code class="docutils literal notranslate"><span class="pre">mktemp</span></code>
utilities for use by scripts for this purpose.</p>
</section>
<section id="symbolic-links">
<span id="s10-5"></span><h2><span class="section-number">10.5. </span>Symbolic links<a class="headerlink" href="#symbolic-links" title="Permalink to this headline">¶</a></h2>
<p>In general, symbolic links within a top-level directory should be
relative, and symbolic links pointing from one top-level directory to or
into another should be absolute. (A top-level directory is a
sub-directory of the root directory <code class="docutils literal notranslate"><span class="pre">/</span></code>.) For example, a symbolic link
from <code class="docutils literal notranslate"><span class="pre">/usr/lib/foo</span></code> to <code class="docutils literal notranslate"><span class="pre">/usr/share/bar</span></code> should be relative
(<code class="docutils literal notranslate"><span class="pre">../share/bar</span></code>), but a symbolic link from <code class="docutils literal notranslate"><span class="pre">/var/run</span></code> to <code class="docutils literal notranslate"><span class="pre">/run</span></code>
should be absolute. <a class="footnote-reference brackets" href="#id24" id="id9">9</a> Symbolic links must not traverse above the
root directory.</p>
<p>In addition, symbolic links should be specified as short as possible,
i.e., link targets like <code class="docutils literal notranslate"><span class="pre">foo/../bar</span></code> are deprecated.</p>
<p>Note that when creating a relative link using <code class="docutils literal notranslate"><span class="pre">ln</span></code> it is not necessary
for the target of the link to exist relative to the working directory
you’re running <code class="docutils literal notranslate"><span class="pre">ln</span></code> from, nor is it necessary to change directory to
the directory where the link is to be made. Simply include the string
that should appear as the target of the link (this will be a pathname
relative to the directory in which the link resides) as the first
argument to <code class="docutils literal notranslate"><span class="pre">ln</span></code>.</p>
<p>For example, in your <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> or <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code>, you can do things
like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>ln -fs gcc $(prefix)/bin/cc
ln -fs gcc debian/tmp/usr/bin/cc
ln -fs ../sbin/sendmail $(prefix)/bin/runq
ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
</pre></div>
</div>
<p>A symbolic link pointing to a compressed file (in the sense that it is
meant to be uncompressed with <code class="docutils literal notranslate"><span class="pre">unzip</span></code> or <code class="docutils literal notranslate"><span class="pre">zless</span></code> etc.) should always
have the same file extension as the referenced file. (For example, if a
file <code class="docutils literal notranslate"><span class="pre">foo.gz</span></code> is referenced by a symbolic link, the filename of the
link has to end with “<code class="docutils literal notranslate"><span class="pre">.gz</span></code>” too, as in <code class="docutils literal notranslate"><span class="pre">bar.gz</span></code>.)</p>
</section>
<section id="device-files">
<span id="s10-6"></span><h2><span class="section-number">10.6. </span>Device files<a class="headerlink" href="#device-files" title="Permalink to this headline">¶</a></h2>
<p>Packages must not include device files or named pipes in the package
file tree.</p>
<p>Debian packages should assume that device files in <code class="docutils literal notranslate"><span class="pre">/dev</span></code> are
dynamically managed by the kernel or some other system facility and do
not have to be explicitly created or managed by the package. Debian
packages other than those whose purpose is to manage the <code class="docutils literal notranslate"><span class="pre">/dev</span></code> device
file tree must not attempt to create or remove device files in <code class="docutils literal notranslate"><span class="pre">/dev</span></code>
when a dynamic device management facility is in use.</p>
<p>If named pipes or device files outside of <code class="docutils literal notranslate"><span class="pre">/dev</span></code> are required by a
package, they should normally be created when necessary by the programs
in the package, by init scripts or systemd unit files, or by similar
on-demand mechanisms. If such files need to be created during package
installation, they must be created in the <code class="docutils literal notranslate"><span class="pre">postinst</span></code> maintainer script
<a class="footnote-reference brackets" href="#id25" id="id10">10</a> and removed in either the <code class="docutils literal notranslate"><span class="pre">prerm</span></code> or the <code class="docutils literal notranslate"><span class="pre">postrm</span></code> maintainer
script.</p>
</section>
<section id="configuration-files">
<span id="s-config-files"></span><h2><span class="section-number">10.7. </span>Configuration files<a class="headerlink" href="#configuration-files" title="Permalink to this headline">¶</a></h2>
<section id="definitions">
<span id="s10-7-1"></span><h3><span class="section-number">10.7.1. </span>Definitions<a class="headerlink" href="#definitions" title="Permalink to this headline">¶</a></h3>
<dl class="simple">
<dt>configuration file</dt><dd><p>A file that affects the operation of a program, or provides site- or
host-specific information, or otherwise customizes the behavior of a
program. Typically, configuration files are intended to be modified
by the system administrator (if needed or desired) to conform to
local policy or to provide more useful site-specific behavior.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">conffile</span></code></dt><dd><p>A file listed in a package’s <code class="docutils literal notranslate"><span class="pre">conffiles</span></code> file, and is treated
specially by <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> (see <a class="reference internal" href="ch-maintainerscripts.html#s-configdetails"><span class="std std-ref">Details of configuration</span></a>).</p>
</dd>
</dl>
<p>The distinction between these two is important; they are not
interchangeable concepts. Almost all <code class="docutils literal notranslate"><span class="pre">conffile</span></code>s are configuration
files, but many configuration files are not <code class="docutils literal notranslate"><span class="pre">conffiles</span></code>.</p>
<p>As noted elsewhere, <code class="docutils literal notranslate"><span class="pre">/etc/init.d</span></code> scripts, <code class="docutils literal notranslate"><span class="pre">/etc/default</span></code> files,
scripts installed in <code class="docutils literal notranslate"><span class="pre">/etc/cron.{hourly,daily,weekly,monthly}</span></code>, and
cron configuration installed in <code class="docutils literal notranslate"><span class="pre">/etc/cron.d</span></code> must be treated as
configuration files. In general, any script that embeds configuration
information is de-facto a configuration file and should be treated as
such.</p>
</section>
<section id="location">
<span id="s10-7-2"></span><h3><span class="section-number">10.7.2. </span>Location<a class="headerlink" href="#location" title="Permalink to this headline">¶</a></h3>
<p>Any configuration files created or used by your package must reside in
<code class="docutils literal notranslate"><span class="pre">/etc</span></code>. If there are several, consider creating a subdirectory of
<code class="docutils literal notranslate"><span class="pre">/etc</span></code> named after your package.</p>
<p>If your package creates or uses configuration files outside of <code class="docutils literal notranslate"><span class="pre">/etc</span></code>,
and it is not feasible to modify the package to use <code class="docutils literal notranslate"><span class="pre">/etc</span></code> directly,
put the files in <code class="docutils literal notranslate"><span class="pre">/etc</span></code> and create symbolic links to those files from
the location that the package requires.</p>
</section>
<section id="behavior">
<span id="s10-7-3"></span><h3><span class="section-number">10.7.3. </span>Behavior<a class="headerlink" href="#behavior" title="Permalink to this headline">¶</a></h3>
<p>Configuration file handling must conform to the following behavior:</p>
<ul class="simple">
<li><p>local changes must be preserved during a package upgrade, and</p></li>
<li><p>configuration files must be preserved when the package is removed,
and only deleted when the package is purged.</p></li>
</ul>
<p>Obsolete configuration files without local changes should be removed by
the package during upgrade. <a class="footnote-reference brackets" href="#id26" id="id11">11</a></p>
<p>The easy way to achieve this behavior is to make the configuration file
a <code class="docutils literal notranslate"><span class="pre">conffile</span></code>. This is appropriate only if it is possible to distribute
a default version that will work for most installations, although some
system administrators may choose to modify it. This implies that the
default version will be part of the package distribution, and must not
be modified by the maintainer scripts during installation (or at any
other time).</p>
<p>In order to ensure that local changes are preserved correctly, packages
must not contain or make hard links to conffiles. <a class="footnote-reference brackets" href="#id27" id="id12">12</a></p>
<p>The other way to do it is via the maintainer scripts. In this case, the
configuration file must not be listed as a <code class="docutils literal notranslate"><span class="pre">conffile</span></code> and must not be
part of the package distribution. If the existence of a file is required
for the package to be sensibly configured it is the responsibility of
the package maintainer to provide maintainer scripts which correctly
create, update and maintain the file and remove it on purge. (See
<a class="reference internal" href="ch-maintainerscripts.html"><span class="doc">Package maintainer scripts and installation procedure</span></a>
for more information.) These scripts must be idempotent (i.e., must work
correctly if <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> needs to re-run them due to errors during
installation or removal), must cope with all the variety of ways
<code class="docutils literal notranslate"><span class="pre">dpkg</span></code> can call maintainer scripts, must not overwrite or otherwise
mangle the user’s configuration without asking, must not ask unnecessary
questions (particularly during upgrades), and must otherwise be good
citizens.</p>
<p>The scripts are not required to configure every possible option for the
package, but only those necessary to get the package running on a given
system. Ideally the sysadmin should not have to do any configuration
other than that done (semi-)automatically by the <code class="docutils literal notranslate"><span class="pre">postinst</span></code> script.</p>
<p>A common practice is to create a script called <code class="docutils literal notranslate"><span class="pre">package-configure</span></code> and
have the package’s <code class="docutils literal notranslate"><span class="pre">postinst</span></code> call it if and only if the configuration
file does not already exist. In certain cases it is useful for there to
be an example or template file which the maintainer scripts use. Such
files should be in <code class="docutils literal notranslate"><span class="pre">/usr/share/package</span></code> or <code class="docutils literal notranslate"><span class="pre">/usr/lib/package</span></code>
(depending on whether they are architecture-independent or not). There
should be symbolic links to them from
<code class="docutils literal notranslate"><span class="pre">/usr/share/doc/package/examples</span></code> if they are examples, and should be
perfectly ordinary <code class="docutils literal notranslate"><span class="pre">dpkg</span></code>-handled files (<em>not</em> configuration files).</p>
<p>These two styles of configuration file handling must not be mixed, for
that way lies madness: <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> will ask about overwriting the file
every time the package is upgraded.</p>
</section>
<section id="sharing-configuration-files">
<span id="s10-7-4"></span><h3><span class="section-number">10.7.4. </span>Sharing configuration files<a class="headerlink" href="#sharing-configuration-files" title="Permalink to this headline">¶</a></h3>
<p>If two or more packages use the same configuration file and it is
reasonable for both to be installed at the same time, one of these
packages must be defined as <em>owner</em> of the configuration file, i.e., it
will be the package which handles that file as a configuration file.
Other packages that use the configuration file must depend on the owning
package if they require the configuration file to operate. If the other
package will use the configuration file if present, but is capable of
operating without it, no dependency need be declared.</p>
<p>If it is desirable for two or more related packages to share a
configuration file <em>and</em> for all of the related packages to be able to
modify that configuration file, then the following should be done:</p>
<ol class="arabic simple">
<li><p>One of the related packages (the “owning” package) will manage the
configuration file with maintainer scripts as described in the
previous section.</p></li>
<li><p>The owning package should also provide a program that the other
packages may use to modify the configuration file.</p></li>
<li><p>The related packages must use the provided program to make any
desired modifications to the configuration file. They should either
depend on the core package to guarantee that the configuration
modifier program is available or accept gracefully that they cannot
modify the configuration file if it is not. (This is in addition to
the fact that the configuration file may not even be present in the
latter scenario.)</p></li>
</ol>
<p>Sometimes it’s appropriate to create a new package which provides the
basic infrastructure for the other packages and which manages the shared
configuration files. (The <code class="docutils literal notranslate"><span class="pre">sgml-base</span></code> package is a good example.)</p>
<p>If the configuration file cannot be shared as described above, the
packages must be marked as conflicting with each other. Two packages
that specify the same file as a <code class="docutils literal notranslate"><span class="pre">conffile</span></code> must conflict. This is an
instance of the general rule about not sharing files. Neither
alternatives nor diversions are likely to be appropriate in this case;
in particular, <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> does not handle diverted <code class="docutils literal notranslate"><span class="pre">conffile</span></code>s well.</p>
<p>When two packages both declare the same <code class="docutils literal notranslate"><span class="pre">conffile</span></code>, they may see
left-over configuration files from each other even though they conflict
with each other. If a user removes (without purging) one of the packages
and installs the other, the new package will take over the <code class="docutils literal notranslate"><span class="pre">conffile</span></code>
from the old package. If the file was modified by the user, it will be
treated the same as any other locally modified <code class="docutils literal notranslate"><span class="pre">conffile</span></code> during an
upgrade.</p>
<p>The maintainer scripts must not alter a <code class="docutils literal notranslate"><span class="pre">conffile</span></code> of <em>any</em> package,
including the one the scripts belong to.</p>
</section>
<section id="user-configuration-files-dotfiles">
<span id="s10-7-5"></span><h3><span class="section-number">10.7.5. </span>User configuration files (“dotfiles”)<a class="headerlink" href="#user-configuration-files-dotfiles" title="Permalink to this headline">¶</a></h3>
<p>The files in <code class="docutils literal notranslate"><span class="pre">/etc/skel</span></code> will automatically be copied into new user
accounts by <code class="docutils literal notranslate"><span class="pre">adduser</span></code>. No other program should reference the files in
<code class="docutils literal notranslate"><span class="pre">/etc/skel</span></code>.</p>
<p>Therefore, if a program needs a dotfile to exist in advance in <code class="docutils literal notranslate"><span class="pre">$HOME</span></code>
to work sensibly, that dotfile should be installed in <code class="docutils literal notranslate"><span class="pre">/etc/skel</span></code> and
treated as a configuration file.</p>
<p>However, programs that require dotfiles in order to operate sensibly are
a bad thing, unless they do create the dotfiles themselves
automatically.</p>
<p>Furthermore, programs should be configured by the Debian default
installation to behave as closely to the upstream default behavior as
possible.</p>
<p>Therefore, if a program in a Debian package needs to be configured in
some way in order to operate sensibly, that should be done using a
site-wide configuration file placed in <code class="docutils literal notranslate"><span class="pre">/etc</span></code>. Only if the program
doesn’t support a site-wide default configuration and the package
maintainer doesn’t have time to add it may a default per-user file be
placed in <code class="docutils literal notranslate"><span class="pre">/etc/skel</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">/etc/skel</span></code> should be as empty as we can make it. This is particularly
true because there is no easy (or necessarily desirable) mechanism for
ensuring that the appropriate dotfiles are copied into the accounts of
existing users when a package is installed.</p>
</section>
</section>
<section id="log-files">
<span id="s10-8"></span><h2><span class="section-number">10.8. </span>Log files<a class="headerlink" href="#log-files" title="Permalink to this headline">¶</a></h2>
<p>Log files should usually be named <code class="docutils literal notranslate"><span class="pre">/var/log/package.log</span></code>. If you have
many log files, or need a separate directory for permission reasons
(<code class="docutils literal notranslate"><span class="pre">/var/log</span></code> is writable only by <code class="docutils literal notranslate"><span class="pre">root</span></code>), you should usually create a
directory named <code class="docutils literal notranslate"><span class="pre">/var/log/package</span></code> and place your log files there.</p>
<p>Log files must be rotated occasionally so that they don’t grow
indefinitely. The best way to do this is to install a log rotation
configuration file in the directory <code class="docutils literal notranslate"><span class="pre">/etc/logrotate.d</span></code>, normally named
<code class="docutils literal notranslate"><span class="pre">/etc/logrotate.d/package</span></code>, and use the facilities provided by
<code class="docutils literal notranslate"><span class="pre">logrotate</span></code>. <a class="footnote-reference brackets" href="#id28" id="id13">13</a> Here is a good example for a logrotate config file
(for more information see <em class="manpage">logrotate(8)</em>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">log</span><span class="o">/</span><span class="n">foo</span><span class="o">/*.</span><span class="n">log</span> <span class="p">{</span>
<span class="n">rotate</span> <span class="mi">12</span>
<span class="n">weekly</span>
<span class="n">compress</span>
<span class="n">missingok</span>
<span class="n">postrotate</span>
<span class="n">start</span><span class="o">-</span><span class="n">stop</span><span class="o">-</span><span class="n">daemon</span> <span class="o">-</span><span class="n">K</span> <span class="o">-</span><span class="n">p</span> <span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">foo</span><span class="o">.</span><span class="n">pid</span> <span class="o">-</span><span class="n">s</span> <span class="n">HUP</span> <span class="o">-</span><span class="n">x</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">sbin</span><span class="o">/</span><span class="n">foo</span> <span class="o">-</span><span class="n">q</span>
<span class="n">endscript</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This rotates all files under <code class="docutils literal notranslate"><span class="pre">/var/log/foo</span></code>, saves 12 compressed
generations, and tells the daemon to reopen its log files after the log
rotation. It skips this log rotation (via <code class="docutils literal notranslate"><span class="pre">missingok</span></code>) if no such log
file is present, which avoids errors if the package is removed but not
purged.</p>
<p>Log files should be removed when the package is purged (but not when it
is only removed). This should be done by the <code class="docutils literal notranslate"><span class="pre">postrm</span></code> script when it
is called with the argument <code class="docutils literal notranslate"><span class="pre">purge</span></code> (see
<a class="reference internal" href="ch-maintainerscripts.html#s-removedetails"><span class="std std-ref">Details of removal and/or configuration purging</span></a>).</p>
</section>
<section id="permissions-and-owners">
<span id="s-permissions-owners"></span><h2><span class="section-number">10.9. </span>Permissions and owners<a class="headerlink" href="#permissions-and-owners" title="Permalink to this headline">¶</a></h2>
<p>The rules in this section are guidelines for general use. If necessary
you may deviate from the details below. However, if you do so you must
make sure that what is done is secure and you should try to be as
consistent as possible with the rest of the system. You are also
encouraged to discuss it on <code class="docutils literal notranslate"><span class="pre">debian-devel</span></code> first.</p>
<p>Files should be owned by <code class="docutils literal notranslate"><span class="pre">root:root</span></code>, and made writable only by the
owner and universally readable (and executable, if appropriate), that is
mode 644 or 755.</p>
<p>Directories should be mode 755 or (for group-writability) mode 2775. The
ownership of the directory should be consistent with its mode: if a
directory is mode 2775, it should be owned by the group that needs write
access to it. <a class="footnote-reference brackets" href="#id29" id="id14">14</a></p>
<p>Control information files should be owned by <code class="docutils literal notranslate"><span class="pre">root:root</span></code> and either
mode 644 (for most files) or mode 755 (for executables such as
<a class="reference internal" href="ch-binary.html#s-maintscripts"><span class="std std-ref">maintainer scripts</span></a>).</p>
<p>Setuid and setgid executables should be mode 4755 or 2755 respectively,
and owned by the appropriate user or group. They should not be made
unreadable (modes like 4711 or 2711 or even 4111); doing so achieves no
extra security, because anyone can find the binary in the freely
available Debian package; it is merely inconvenient. For the same reason
you should not restrict read or execute permissions on non-set-id
executables.</p>
<p>Some setuid programs need to be restricted to particular sets of users,
using file permissions. In this case they should be owned by the uid to
which they are set-id, and by the group which should be allowed to
execute them. They should have mode 4754; again there is no point in
making them unreadable to those users who must not be allowed to execute
them.</p>
<p>It is possible to arrange that the system administrator can reconfigure
the package to correspond to their local security policy by changing the
permissions on a binary: they can do this by using
<code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code>, as described below. <a class="footnote-reference brackets" href="#id30" id="id15">15</a> Another method you
should consider is to create a group for people allowed to use the
program(s) and make any setuid executables executable only by that
group.</p>
<p>If you need to create a new user or group for your package there are two
possibilities. Firstly, you may need to make some files in the binary
package be owned by this user or group, or you may need to compile the
user or group id (rather than just the name) into the binary (though
this latter should be avoided if possible, as in this case you need a
statically allocated id).</p>
<p>If you need a statically allocated id, you must ask for a user or group
id from the <code class="docutils literal notranslate"><span class="pre">base-passwd</span></code> maintainer, and must not release the package
until you have been allocated one. Once you have been allocated one you
must either make the package depend on a version of the <code class="docutils literal notranslate"><span class="pre">base-passwd</span></code>
package with the id present in <code class="docutils literal notranslate"><span class="pre">/etc/passwd</span></code> or <code class="docutils literal notranslate"><span class="pre">/etc/group</span></code>, or
arrange for your package to create the user or group itself with the
correct id (using <code class="docutils literal notranslate"><span class="pre">adduser</span></code>) in its <code class="docutils literal notranslate"><span class="pre">preinst</span></code> or <code class="docutils literal notranslate"><span class="pre">postinst</span></code>.
(Doing it in the <code class="docutils literal notranslate"><span class="pre">postinst</span></code> is to be preferred if it is possible,
otherwise a pre-dependency will be needed on the <code class="docutils literal notranslate"><span class="pre">adduser</span></code> package.)</p>
<p>On the other hand, the program might be able to determine the uid or gid
from the user or group name at runtime, so that a dynamically allocated
id can be used. In this case you should choose an appropriate user or
group name, discussing this on <code class="docutils literal notranslate"><span class="pre">debian-devel</span></code> and checking that it is
unique. When this has been checked you must arrange for your package to
create the user or group if necessary using <code class="docutils literal notranslate"><span class="pre">adduser</span></code> in the
<code class="docutils literal notranslate"><span class="pre">preinst</span></code> or <code class="docutils literal notranslate"><span class="pre">postinst</span></code> script (again, the latter is to be preferred
if it is possible).</p>
<p>Note that changing the numeric value of an id associated with a name is
very difficult, and involves searching the file system for all
appropriate files. You need to think carefully whether a static or
dynamic id is required, since changing your mind later will cause
problems.</p>
<section id="the-use-of-dpkg-statoverride">
<span id="s10-9-1"></span><h3><span class="section-number">10.9.1. </span>The use of <code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code><a class="headerlink" href="#the-use-of-dpkg-statoverride" title="Permalink to this headline">¶</a></h3>
<p>This section is not intended as policy, but as a description of the use
of <code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code>.</p>
<p>If a system administrator wishes to have a file (or directory or other
such thing) installed with owner and permissions different from those in
the distributed Debian package, they can use the <code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code>
program to instruct <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> to use the different settings every time
the file is installed. Thus the package maintainer should distribute the
files with their normal permissions, and leave it for the system
administrator to make any desired changes. For example, a daemon which
is normally required to be setuid root, but in certain situations could
be used without being setuid, should be installed setuid in the
<code class="docutils literal notranslate"><span class="pre">.deb</span></code>. Then the local system administrator can change this if they
wish. If there are two standard ways of doing it, the package maintainer
can use <code class="docutils literal notranslate"><span class="pre">debconf</span></code> to find out the preference, and call
<code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code> in the maintainer script if necessary to
accommodate the system administrator’s choice. Care must be taken during
upgrades to not override an existing setting.</p>
<p>Given the above, <code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code> is essentially a tool for system
administrators and would not normally be needed in the maintainer
scripts. There is one type of situation, though, where calls to
<code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code> would be needed in the maintainer scripts, and
that involves packages which use dynamically allocated user or group
ids. In such a situation, something like the following idiom can be very
helpful in the package’s <code class="docutils literal notranslate"><span class="pre">postinst</span></code>, where <code class="docutils literal notranslate"><span class="pre">sysuser</span></code> is a
dynamically allocated id:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>for i in /usr/bin/foo /usr/sbin/bar; do
# only do something when no setting exists
if ! dpkg-statoverride --list $i >/dev/null 2>&1; then
#include: debconf processing, question about foo and bar
if [ "$RET" = "true" ] ; then
dpkg-statoverride --update --add sysuser root 4755 $i
fi
fi
done
</pre></div>
</div>
<p>The corresponding code to remove the override when the package is purged
would be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>for i in /usr/bin/foo /usr/sbin/bar; do
if dpkg-statoverride --list $i >/dev/null 2>&1; then
dpkg-statoverride --remove $i
fi
done
</pre></div>
</div>
</section>
</section>
<section id="file-names">
<span id="s-filenames"></span><h2><span class="section-number">10.10. </span>File names<a class="headerlink" href="#file-names" title="Permalink to this headline">¶</a></h2>
<p>The name of the files installed by binary packages in the system PATH
(namely <code class="docutils literal notranslate"><span class="pre">/bin</span></code>, <code class="docutils literal notranslate"><span class="pre">/sbin</span></code>, <code class="docutils literal notranslate"><span class="pre">/usr/bin</span></code>, <code class="docutils literal notranslate"><span class="pre">/usr/sbin</span></code> and
<code class="docutils literal notranslate"><span class="pre">/usr/games</span></code>) must be encoded in ASCII.</p>
<p>The name of the files and directories installed by binary packages
outside the system PATH must be encoded in UTF-8 and should be
restricted to ASCII when it is possible to do so.</p>
<dl class="footnote brackets">
<dt class="label" id="id16"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
<dd><p>If you are using GCC, <code class="docutils literal notranslate"><span class="pre">-fPIC</span></code> produces code with relocatable
position independent code, which is required for most architectures
to create a shared library, with i386 and perhaps some others where
non position independent code is permitted in a shared library.</p>
<p>Position independent code may have a performance penalty, especially
on <code class="docutils literal notranslate"><span class="pre">i386</span></code>. However, in most cases the speed penalty must be
measured against the memory wasted on the few architectures where non
position independent code is even possible.</p>
</dd>
<dt class="label" id="id17"><span class="brackets"><a class="fn-backref" href="#id2">2</a></span></dt>
<dd><p>Some of the reasons why this might be required is if the library
contains hand crafted assembly code that is not relocatable, the
speed penalty is excessive for compute intensive libs, and similar
reasons.</p>
</dd>
<dt class="label" id="id18"><span class="brackets"><a class="fn-backref" href="#id3">3</a></span></dt>
<dd><p>Some of the reasons for linking static libraries with the <code class="docutils literal notranslate"><span class="pre">-fPIC</span></code>
flag are if, for example, one needs a Perl API for a library that is
under rapid development, and has an unstable API, so shared libraries
are pointless at this phase of the library’s development. In that
case, since Perl needs a library with relocatable code, it may make
sense to create a static library with relocatable code. Another
reason cited is if you are distilling various libraries into a common
shared library, like <code class="docutils literal notranslate"><span class="pre">mklibs</span></code> does in the Debian installer project.</p>
</dd>
<dt class="label" id="id19"><span class="brackets"><a class="fn-backref" href="#id4">4</a></span></dt>
<dd><p>You might want to replace <code class="docutils literal notranslate"><span class="pre">--strip-unneeded</span></code> with
<code class="docutils literal notranslate"><span class="pre">--strip-debug</span></code> for static libraries, as dh_strip does. When
stripping static libraries, you should also pass
<code class="docutils literal notranslate"><span class="pre">--enable-deterministic-archives</span></code> to ensure that your package
build is reproducible.</p>
</dd>
<dt class="label" id="id20"><span class="brackets"><a class="fn-backref" href="#id5">5</a></span></dt>
<dd><p>A common example are the so-called “plug-ins”, internal shared objects
that are dynamically loaded by programs using <em class="manpage">dlopen(3)</em>.</p>
</dd>
<dt class="label" id="id21"><span class="brackets"><a class="fn-backref" href="#id6">6</a></span></dt>
<dd><p>These files store, among other things, all libraries on which that
shared library depends. Unfortunately, if the <code class="docutils literal notranslate"><span class="pre">.la</span></code> file is present
and contains that dependency information, using <code class="docutils literal notranslate"><span class="pre">libtool</span></code> when
linking against that library will cause the resulting program or
library to be linked against those dependencies as well, even if this
is unnecessary. This can create unneeded dependencies on shared
library packages that would otherwise be hidden behind the library
ABI, and can make library transitions to new SONAMEs unnecessarily
complicated and difficult to manage.</p>
</dd>
<dt class="label" id="id22"><span class="brackets"><a class="fn-backref" href="#id7">7</a></span></dt>
<dd><p>The Open Group Base Specifications Issue 7, 2018 Edition, which is
also known as POSIX.1-2017 and as IEEE Std 1003.1-2017 and is
available on the World Wide Web from <a class="reference external" href="http://pubs.opengroup.org/onlinepubs/9699919799/download/">The Open Group</a>.</p>
</dd>
<dt class="label" id="id23"><span class="brackets"><a class="fn-backref" href="#id8">8</a></span></dt>
<dd><p>These features are in widespread use in the Linux community and are
implemented in all of bash, dash, and ksh, the most common shells
users may wish to use as <code class="docutils literal notranslate"><span class="pre">/bin/sh</span></code>.</p>
</dd>
<dt class="label" id="id24"><span class="brackets"><a class="fn-backref" href="#id9">9</a></span></dt>
<dd><p>This is necessary to allow top-level directories to be symlinks. If
linking <code class="docutils literal notranslate"><span class="pre">/var/run</span></code> to <code class="docutils literal notranslate"><span class="pre">/run</span></code> were done with the relative symbolic
link <code class="docutils literal notranslate"><span class="pre">../run</span></code>, but <code class="docutils literal notranslate"><span class="pre">/var</span></code> were a symbolic link to <code class="docutils literal notranslate"><span class="pre">/srv/disk1</span></code>,
the symbolic link would point to <code class="docutils literal notranslate"><span class="pre">/srv/run</span></code> rather than the
intended target.</p>
</dd>
<dt class="label" id="id25"><span class="brackets"><a class="fn-backref" href="#id10">10</a></span></dt>
<dd><p>It’s better to use <code class="docutils literal notranslate"><span class="pre">mkfifo</span></code> rather than <code class="docutils literal notranslate"><span class="pre">mknod</span></code> to create named
pipes to avoid false positives from automated checks for packages
incorrectly creating device files.</p>
</dd>
<dt class="label" id="id26"><span class="brackets"><a class="fn-backref" href="#id11">11</a></span></dt>
<dd><p>The <code class="docutils literal notranslate"><span class="pre">dpkg-maintscript-helper</span></code> tool, available from the dpkg
package, can help for this task.</p>
</dd>
<dt class="label" id="id27"><span class="brackets"><a class="fn-backref" href="#id12">12</a></span></dt>
<dd><p>Rationale: There are two problems with hard links. The first is that
some editors break the link while editing one of the files, so that
the two files may unwittingly become unlinked and different. The
second is that <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> might break the hard link while upgrading
<code class="docutils literal notranslate"><span class="pre">conffile</span></code>s.</p>
</dd>
<dt class="label" id="id28"><span class="brackets"><a class="fn-backref" href="#id13">13</a></span></dt>
<dd><p>The traditional approach to log files has been to set up <em>ad hoc</em> log
rotation schemes using simple shell scripts and cron. While this
approach is highly customizable, it requires quite a lot of sysadmin
work. Even though the original Debian system helped a little by
automatically installing a system which can be used as a template,
this was deemed not enough.</p>
<p>The use of <code class="docutils literal notranslate"><span class="pre">logrotate</span></code>, a program developed by Red Hat, is better,
as it centralizes log management. It has both a configuration file
(<code class="docutils literal notranslate"><span class="pre">/etc/logrotate.conf</span></code>) and a directory where packages can drop
their individual log rotation configurations (<code class="docutils literal notranslate"><span class="pre">/etc/logrotate.d</span></code>).</p>
</dd>
<dt class="label" id="id29"><span class="brackets"><a class="fn-backref" href="#id14">14</a></span></dt>
<dd><p>When a package is upgraded, and the owner or permissions of a file
included in the package has changed, dpkg arranges for the ownership
and permissions to be correctly set upon installation. However, this
does not extend to directories; the permissions and ownership of
directories already on the system does not change on install or
upgrade of packages. This makes sense, since otherwise common
directories like <code class="docutils literal notranslate"><span class="pre">/usr</span></code> would always be in flux. To correctly
change permissions of a directory the package owns, explicit action
is required, usually in the <code class="docutils literal notranslate"><span class="pre">postinst</span></code> script. Care must be taken
to handle downgrades as well, in that case.</p>
</dd>
<dt class="label" id="id30"><span class="brackets"><a class="fn-backref" href="#id15">15</a></span></dt>
<dd><p>Ordinary files installed by <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> (as opposed to <code class="docutils literal notranslate"><span class="pre">conffile</span></code>s
and other similar objects) normally have their permissions reset to
the distributed permissions when the package is reinstalled. However,
the use of <code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code> overrides this default behavior.</p>
</dd>
</dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">10. Files</a><ul>
<li><a class="reference internal" href="#binaries">10.1. Binaries</a></li>
<li><a class="reference internal" href="#libraries">10.2. Libraries</a></li>
<li><a class="reference internal" href="#shared-libraries">10.3. Shared libraries</a></li>
<li><a class="reference internal" href="#scripts">10.4. Scripts</a></li>
<li><a class="reference internal" href="#symbolic-links">10.5. Symbolic links</a></li>
<li><a class="reference internal" href="#device-files">10.6. Device files</a></li>
<li><a class="reference internal" href="#configuration-files">10.7. Configuration files</a><ul>
<li><a class="reference internal" href="#definitions">10.7.1. Definitions</a></li>
<li><a class="reference internal" href="#location">10.7.2. Location</a></li>
<li><a class="reference internal" href="#behavior">10.7.3. Behavior</a></li>
<li><a class="reference internal" href="#sharing-configuration-files">10.7.4. Sharing configuration files</a></li>
<li><a class="reference internal" href="#user-configuration-files-dotfiles">10.7.5. User configuration files (“dotfiles”)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#log-files">10.8. Log files</a></li>
<li><a class="reference internal" href="#permissions-and-owners">10.9. Permissions and owners</a><ul>
<li><a class="reference internal" href="#the-use-of-dpkg-statoverride">10.9.1. The use of <code class="docutils literal notranslate"><span class="pre">dpkg-statoverride</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#file-names">10.10. File names</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="ch-opersys.html"
title="previous chapter"><span class="section-number">9. </span>The Operating System</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="ch-customized-programs.html"
title="next chapter"><span class="section-number">11. </span>Customized programs</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/ch-files.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="ch-customized-programs.html" title="11. Customized programs"
>next</a> |</li>
<li class="right" >
<a href="ch-opersys.html" title="9. The Operating System"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> »</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">10. </span>Files</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.2.0.
</div>
</body>
</html>