Files
=====

.. _s-binaries:

Binaries
--------

Two different packages must not install programs with different
functionality but with the same filenames. This also applies when they
are installed into different directories on the default (user or root)
``PATH``. (The case of two programs
having the same functionality but different implementations is handled
via "alternatives" or the "Conflicts" mechanism. See
:ref:`s-maintscripts` and
:ref:`s-conflicts` respectively.) If this case happens,
one of the programs must be renamed. The maintainers should report this
to the ``debian-devel`` mailing list and try to find a consensus about
which program will have to be renamed. If a consensus cannot be reached,
*both* programs must be renamed.

There is an exception to the above rules for ``/usr/games``: packages that
already install programs to ``/usr/games``, where another package installs a
program of the same with different functionality to a different directory on
the default ``PATH``, may continue to do so.  However, packages must not
install any newly conflicting programs to ``/usr/games``, and packages already
doing so are encouraged to move these programs to non-conflicting names.

Packages must not install files to paths whose first component is a name
directly under the file system root and which is a symbolic link to a
directory of the same name under ``/usr``.  That is, packages must not install
files to paths matching the glob patterns ``/bin/*``, ``/lib/*``, ``/lib*/*``
and ``/sbin/*``.  The base-files package is an exception, for it installs
aliasing symbolic links from ``/bin`` to ``/usr/bin``, ``/lib`` to
``/usr/lib``, et cetera.  This restriction is necessary to avoid triggering
undefined behaviour in ``dpkg``.

Packages may assume that ``/bin``, ``/lib`` and ``/sbin`` are always symbolic
links such that files under ``/usr/bin``, ``/usr/lib`` and ``/usr/sbin`` are
always accessible via these aliases.

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.

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 :ref:`s-debianrules`). For the C programming
language, this means the following compilation parameters should be
used:

::

    CC = gcc
    CFLAGS = -O2 -g -Wall # sane warning options vary between programs
    LDFLAGS = # none

By default all installed binaries should be stripped by calling

::

    strip --strip-unneeded --remove-section=.comment --remove-section=.note binaries

on the binaries after they have been copied into ``debian/tmp`` but
before the tree is made into a package.

It is not recommended to strip binaries by passing the ``-s`` flag to
``install``, because this fails to remove .comment and .note sections,
and also prevents the automatic creation of dbgsym binary packages by
tools like ``dh_strip``.

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
``DEB_BUILD_OPTIONS`` (see :ref:`s-debianrules-options`).
This variable can contain several flags to change how a package is
compiled and built.

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 (``-O3``, 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.

.. _s-libraries:

Libraries
---------

If the package is **architecture: any**, then the shared library
compilation and linking flags must have ``-fPIC``, or the package shall
not build on some of the supported architectures.  [#]_ Any exception
to this rule must be discussed on the mailing list
*debian-devel@lists.debian.org*, and a rough consensus obtained. The
reasons for not compiling with ``-fPIC`` flag must be recorded in the
file ``README.Debian``, and care must be taken to either restrict the
architecture or arrange for ``-fPIC`` to be used on architectures where
it is required.  [#]_

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 ``-fPIC`` flag. Any
exception to this rule should be discussed on the mailing list
*debian-devel@lists.debian.org*, and the reasons for compiling with the
``-fPIC`` flag must be recorded in the file ``README.Debian``.  [#]_

In other words, if both a shared and a static library is being built,
each source unit (``*.c``, for example, for C files) will need to be
compiled twice, for the normal case.

Libraries should be built with threading support and to be thread-safe
if the library supports this.

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
:ref:`symbols <s-sharedlibs-symbols>` and :ref:`shlibs <s-sharedlibs-shlibdeps>` systems and guarantees that all
libraries can be safely opened with ``dlopen()``. Packagers may wish to
use the gcc option ``-Wl,-z,defs`` 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.

All installed shared libraries should be stripped with

::

    strip --strip-unneeded --remove-section=.comment --remove-section=.note your-lib

(The option ``--strip-unneeded`` makes ``strip`` 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.  [#]_

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 ``dh_strip`` tool can create such
packages automatically.

Shared object files (often ``.so`` 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 ``/usr/lib`` or ``/usr/lib/triplet`` 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. [#]_

Packages that use ``libtool`` to create and install their shared
libraries install a file containing additional metadata (ending in
``.la``) 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.  [#]_ If the
``.la`` file is required for that library (if, for instance, it's loaded
via ``libltdl`` in a way that requires that meta-information), the
``dependency_libs`` setting in the ``.la`` file should normally be set
to the empty string. If the shared library development package has
historically included the ``.la``, it must be retained in the
development package (with ``dependency_libs`` emptied) until all
libraries that depend on it have removed or emptied ``dependency_libs``
in their ``.la`` files to prevent linking with those other libraries
using ``libtool`` from failing.

If the ``.la`` must be included, it should be included in the
development (``-dev``) package, unless the library will be loaded by
``libtool``'s ``libltdl`` library. If it is intended for use with
``libltdl``, the ``.la`` files must go in the run-time library package.

These requirements for handling of ``.la`` 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 ``.la`` files alongside the modules so
that they can be loaded by ``libltdl``. ``dependency_libs`` 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.

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.

.. _s10.3:

Shared libraries
----------------

This section has moved to :doc:`Shared libraries <ch-sharedlibs>`.

.. _s-scripts:

Scripts
-------

All command scripts, including the package maintainer scripts inside the
package and used by ``dpkg``, should have a ``#!`` line naming the shell
to be used to interpret them.

In the case of Perl scripts this should be ``#!/usr/bin/perl``.

When scripts are installed into a directory in the system PATH, the
script name should not include an extension such as ``.sh`` or ``.pl``
that denotes the scripting language currently used to implement it.

Shell scripts (``sh`` and ``bash``) other than ``init.d`` scripts should
almost certainly start with ``set -e`` so that errors are detected.
``init.d`` 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
:ref:`s-writing-init` for more information about writing
``init.d`` scripts.

Every script should use ``set -e`` or check the exit status of *every*
command.

Scripts may assume that ``/bin/sh`` implements the POSIX.1-2017 Shell Command
Language  [#]_ plus the following additional features not mandated by
POSIX.1-2017.. [#]_

-  ``echo -n``, if implemented as a shell built-in, must not generate a
   newline.

-  ``test``, if implemented as a shell built-in, must support ``-a`` and
   ``-o`` as binary logical operators.

-  ``local`` 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. ``local`` may
   or may not preserve the variable value from an outer scope if no
   assignment is present. Uses such as:

   ::

       fname () {
           local a b c=delta d
           # ... use a, b, c, d ...
       }

   must be supported and must set the value of ``c`` to ``delta``.

-  The XSI extension to ``kill`` allowing ``kill -signal``, 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 ``kill`` is implemented as a shell built-in.

-  The XSI extension to ``trap`` allowing numeric signals must be
   supported. In addition to the signal numbers listed in the extension,
   which are the same as for ``kill`` above, 13 (SIGPIPE) must be
   allowed.

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., ``#!/bin/bash``) and the package
must depend on the package providing the shell (unless the shell package
is marked "Essential", as in the case of ``bash``).

You may wish to restrict your script to POSIX.1-2017 features plus the above
set when possible so that it may use ``/bin/sh`` as its interpreter.
Checking your script with ``checkbashisms`` from the devscripts package
or running your script with an alternate shell such as ``posh`` may help
uncover violations of the above requirements. If in doubt whether a
script complies with these requirements, use ``/bin/bash``.

Perl scripts should check for errors when making any system calls,
including ``open``, ``print``, ``close``, ``rename`` and ``system``.

``csh`` and ``tcsh`` should be avoided as scripting languages. See *Csh
Programming Considered Harmful*, one of the ``comp.unix.*`` FAQs, which
can be found at http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/. If
an upstream package comes with ``csh`` scripts then you must make sure
that they start with ``#!/bin/csh`` and make your package depend on the
``c-shell`` virtual package.

Any scripts which create files in world-writeable directories (e.g., in
``/tmp``) must use a mechanism which will fail atomically if a file with
the same name already exists.

The Debian base system provides the ``tempfile`` and ``mktemp``
utilities for use by scripts for this purpose.

.. _s10.5:

Symbolic links
--------------

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 ``/``.) For example, a symbolic link
from ``/usr/lib/foo`` to ``/usr/share/bar`` should be relative
(``../share/bar``), but a symbolic link from ``/var/run`` to ``/run``
should be absolute.  [#]_ Symbolic links must not traverse above the
root directory.

In addition, symbolic links should be specified as short as possible,
i.e., link targets like ``foo/../bar`` are deprecated.

Note that when creating a relative link using ``ln`` it is not necessary
for the target of the link to exist relative to the working directory
you're running ``ln`` from, n                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  