(debian-policy.info)Libraries

---

Next: Shared libraries<2> Prev: Binaries Up: Files<2>

---

Enter node , (file) or (file)node

10.2 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.  (1) 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.  (2)

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’.  (3)

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 Note:
symbols. and Note: shlibs. 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.  (4)

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.  (5)

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.  (6) 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.

   ---------- Footnotes ----------

   (1) If you are using GCC, ‘-fPIC’ 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.

Position independent code may have a performance penalty, especially on
‘i386’.  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.

   (2) 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.

   (3) Some of the reasons for linking static libraries with the ‘-fPIC’
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 ‘mklibs’ does in the Debian installer project.

   (4) You might want to replace ‘--strip-unneeded’ with ‘--strip-debug’
for static libraries, as dh_strip does.  When stripping static
libraries, you should also pass ‘--enable-deterministic-archives’ to
ensure that your package build is reproducible.

   (5) A common example are the so-called “plug-ins”, internal shared
objects that are dynamically loaded by programs using dlopen(3).

   (6) These files store, among other things, all libraries on which
that shared library depends.  Unfortunately, if the ‘.la’ file is
present and contains that dependency information, using ‘libtool’ 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.