# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2018, 1997, 1998 Ian Jackson, Christian Schwarz, 1998-2017,
# The Debian Policy Mailing List
# This file is distributed under the same license as the Debian Policy
# Manual package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2018.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Debian Policy Manual 4.1.6.0\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2018-07-10 16:09+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.4.0\n"

#: ../../ch-sharedlibs.rst:2
msgid "Shared libraries"
msgstr ""

#: ../../ch-sharedlibs.rst:4
msgid ""
"Packages containing shared libraries must be constructed with a little "
"care to make sure that the shared library is always available. This is "
"especially important for packages whose shared libraries are vitally "
"important, such as the C library (currently ``libc6``)."
msgstr ""

#: ../../ch-sharedlibs.rst:9
msgid ""
"This section deals only with public shared libraries: shared libraries "
"that are placed in directories searched by the dynamic linker by default "
"or which are intended to be linked against normally and possibly used by "
"other, independent packages. Shared libraries that are internal to a "
"particular package or that are only loaded as dynamic modules are not "
"covered by this section and are not subject to its requirements."
msgstr ""

#: ../../ch-sharedlibs.rst:16
msgid ""
"A shared library is identified by the ``SONAME`` attribute stored in its "
"dynamic section. When a binary is linked against a shared library, the "
"``SONAME`` of the shared library is recorded in the binary's ``NEEDED`` "
"section so that the dynamic linker knows that library must be loaded at "
"runtime. The shared library file's full name (which usually contains "
"additional version information not needed in the ``SONAME``) is therefore"
" normally not referenced directly. Instead, the shared library is loaded "
"by its ``SONAME``, which exists on the file system as a symlink pointing "
"to the full name of the shared library. This symlink must be provided by "
"the package.  :ref:`s-sharedlibs-runtime` describes how to do this.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:27
msgid ""
"When linking a binary or another shared library against a shared library,"
" the ``SONAME`` for that shared library is not yet known. Instead, the "
"shared library is found by looking for a file matching the library name "
"with ``.so`` appended. This file exists on the file system as a symlink "
"pointing to the shared library."
msgstr ""

#: ../../ch-sharedlibs.rst:33
msgid ""
"Shared libraries are normally split into several binary packages. The "
"``SONAME`` symlink is installed by the runtime shared library package, "
"and the bare ``.so`` symlink is installed in the development package "
"since it's only used when linking binaries or shared libraries. However, "
"there are some exceptions for unusual shared libraries or for shared "
"libraries that are also loaded as dynamic modules by other programs."
msgstr ""

#: ../../ch-sharedlibs.rst:40
msgid ""
"This section is primarily concerned with how the separation of shared "
"libraries into multiple packages should be done and how dependencies on "
"and between shared library binary packages are managed in Debian. "
":ref:`s-libraries` should be read in conjunction with this section and "
"contains additional rules for the files contained in the shared library "
"packages."
msgstr ""

#: ../../ch-sharedlibs.rst:47
msgid ""
"This is a convention of shared library versioning, but not a requirement."
" Some libraries use the ``SONAME`` as the full library file name instead "
"and therefore do not need a symlink. Most, however, encode additional "
"information about backwards-compatible revisions as a minor version "
"number in the file name. The ``SONAME`` itself only changes when binaries"
" linked with the earlier version of the shared library may no longer "
"work, but the filename may change with each release of the library. See "
":ref:`s-sharedlibs-runtime` for more information."
msgstr ""

#: ../../ch-sharedlibs.rst:60
msgid "Run-time shared libraries"
msgstr ""

#: ../../ch-sharedlibs.rst:62
msgid ""
"The run-time shared library must be placed in a package whose name "
"changes whenever the ``SONAME`` of the shared library changes. This "
"allows several versions of the shared library to be installed at the same"
" time, allowing installation of the new version of the shared library "
"without immediately breaking binaries that depend on the old version. "
"Normally, the run-time shared library and its ``SONAME`` symlink should "
"be placed in a package named libraryname\\ *soversion*, where *soversion*"
" is the version number in the ``SONAME`` of the shared library.  "
"Alternatively, if it would be confusing to directly append *soversion* to"
" libraryname (if, for example, libraryname itself ends in a number), you "
"should use libraryname-\\ *soversion* instead. [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:74
msgid ""
"To determine the *soversion*, look at the ``SONAME`` of the library, "
"stored in the ELF ``SONAME`` attribute. It is usually of the form "
"``name.so.major-version`` (for example, ``libz.so.1``). The version part "
"is the part which comes after ``.so.``, so in that example it is ``1``. "
"The soname may instead be of the form ``name-major-version.so``, such as "
"``libdb-5.1.so``, in which case the name would be ``libdb`` and the "
"version would be ``5.1``."
msgstr ""

#: ../../ch-sharedlibs.rst:82
msgid ""
"If you have several shared libraries built from the same source tree, you"
" may lump them all together into a single shared library package provided"
" that all of their ``SONAME``\\ s will always change together. Be aware "
"that this is not normally the case, and if the ``SONAME``\\ s do not "
"change together, upgrading such a merged shared library package will be "
"unnecessarily difficult because of file conflicts with the old version of"
" the package. When in doubt, always split shared library packages so that"
" each binary package installs a single shared library."
msgstr ""

#: ../../ch-sharedlibs.rst:91
msgid ""
"Every time the shared library ABI changes in a way that may break "
"binaries linked against older versions of the shared library, the "
"``SONAME`` of the library and the corresponding name for the binary "
"package containing the runtime shared library should change. Normally, "
"this means the ``SONAME`` should change any time an interface is removed "
"from the shared library or the signature of an interface (the number of "
"parameters or the types of parameters that it takes, for example) is "
"changed. This practice is vital to allowing clean upgrades from older "
"versions of the package and clean transitions between the old ABI and new"
" ABI without having to upgrade every affected package simultaneously."
msgstr ""

#: ../../ch-sharedlibs.rst:102
msgid ""
"The ``SONAME`` and binary package name need not, and indeed normally "
"should not, change if new interfaces are added but none are removed or "
"changed, since this will not break binaries linked against the old shared"
" library. Correct versioning of dependencies on the newer shared library "
"by binaries that use the new interfaces is handled via the ``symbols`` or"
" ``shlibs`` system (see :ref:`s-sharedlibs-depends`)."
msgstr ""

#: ../../ch-sharedlibs.rst:109
msgid ""
"The package should install the shared libraries under their normal names."
" For example, the libgdbm3 package should install ``libgdbm.so.3.0.0`` as"
" ``/usr/lib/libgdbm.so.3.0.0``. The files should not be renamed or re-"
"linked by any ``prerm`` or ``postrm`` scripts; ``dpkg`` will take care of"
" renaming things safely without affecting running programs, and attempts "
"to interfere with this are likely to lead to problems."
msgstr ""

#: ../../ch-sharedlibs.rst:117
msgid ""
"Shared libraries should not be installed executable, since the dynamic "
"linker does not require this and trying to execute a shared library "
"usually results in a core dump."
msgstr ""

#: ../../ch-sharedlibs.rst:121
msgid ""
"The run-time library package should include the symbolic link for the "
"``SONAME`` that ``ldconfig`` would create for the shared libraries. For "
"example, the libgdbm3 package should include a symbolic link from "
"``/usr/lib/libgdbm.so.3`` to ``libgdbm.so.3.0.0``. This is needed so that"
" the dynamic linker (for example ``ld.so`` or ``ld-linux.so.*``) can find"
" the library between the time that ``dpkg`` installs it and the time that"
" ``ldconfig`` is run in the ``postinst`` script.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:129
msgid ""
"The following command, when run on a shared library, will output the name"
" to be used for the Debian package containing that shared library::"
msgstr ""

#: ../../ch-sharedlibs.rst:137
msgid ""
"The package management system requires the library to be placed before "
"the symbolic link pointing to it in the ``.deb`` file. This is so that "
"when ``dpkg`` comes to install the symlink (overwriting the previous "
"symlink pointing at an older version of the library), the new shared "
"library is already in place. In the past, this was achieved by creating "
"the library in the temporary packaging directory before creating the "
"symlink. Unfortunately, this was not always effective, since the building"
" of the tar file in the ``.deb`` depended on the behavior of the "
"underlying file system. Some file systems (such as reiserfs) reorder the "
"files so that the order of creation is forgotten. Since version 1.7.0, "
"``dpkg`` reorders the files itself as necessary when building a package. "
"Thus it is no longer important to concern oneself with the order of file "
"creation."
msgstr ""

#: ../../ch-sharedlibs.rst:155
msgid "``ldconfig``"
msgstr ""

#: ../../ch-sharedlibs.rst:157
msgid ""
"Any package installing shared libraries in one of the default library "
"directories of the dynamic linker (which are currently ``/usr/lib`` and "
"``/lib``) or a directory that is listed in ``/etc/ld.so.conf`` [#]_ must "
"use ``ldconfig`` to update the shared library system."
msgstr ""

#: ../../ch-sharedlibs.rst:162
msgid ""
"Any such package must have the line ``activate-noawait ldconfig`` in its "
"``triggers`` control file (i.e. ``DEBIAN/triggers``)."
msgstr ""

#: ../../ch-sharedlibs.rst:165
msgid ""
"These are currently ``/usr/local/lib`` plus directories under ``/lib`` "
"and ``/usr/lib`` matching the multiarch triplet for the system "
"architecture."
msgstr ""

#: ../../ch-sharedlibs.rst:172
msgid "Shared library support files"
msgstr ""

#: ../../ch-sharedlibs.rst:174
msgid ""
"If your package contains files whose names do not change with each change"
" in the library shared object version, you must not put them in the "
"shared library package. Otherwise, several versions of the shared library"
" cannot be installed at the same time without filename clashes, making "
"upgrades and transitions unnecessarily difficult."
msgstr ""

#: ../../ch-sharedlibs.rst:180
msgid ""
"It is recommended that supporting files and run-time support programs "
"that do not need to be invoked manually by users, but are nevertheless "
"required for the package to function, be placed (if they are binary) in a"
" subdirectory of ``/usr/lib``, preferably under ``/usr/lib/``\\ package-"
"name. If the program or file is architecture independent, the "
"recommendation is for it to be placed in a subdirectory of ``/usr/share``"
" instead, preferably under ``/usr/share/``\\ package-name. Following the "
"package-name naming convention ensures that the file names change when "
"the shared object version changes."
msgstr ""

#: ../../ch-sharedlibs.rst:191
msgid ""
"Run-time support programs that use the shared library but are not "
"required for the library to function or files used by the shared library "
"that can be used by any version of the shared library package should "
"instead be put in a separate package. This package might typically be "
"named libraryname-tools; note the absence of the soversion in the package"
" name."
msgstr ""

#: ../../ch-sharedlibs.rst:198
msgid ""
"Files and support programs only useful when compiling software against "
"the library should be included in the development package for the "
"library.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:202
msgid ""
"For example, a ``package-name-config`` script or pkg-config configuration"
" files."
msgstr ""

#: ../../ch-sharedlibs.rst:208
msgid "Static libraries"
msgstr ""

#: ../../ch-sharedlibs.rst:210
msgid ""
"The static library (``libraryname.a``) is usually provided in addition to"
" the shared version. It is placed into the development package (see "
"below)."
msgstr ""

#: ../../ch-sharedlibs.rst:214
msgid ""
"In some cases, it is acceptable for a library to be available in static "
"form only; these cases include:"
msgstr ""

#: ../../ch-sharedlibs.rst:217
msgid ""
"libraries for languages whose shared library support is immature or "
"unstable"
msgstr ""

#: ../../ch-sharedlibs.rst:220
msgid ""
"libraries whose interfaces are in flux or under development (commonly the"
" case when the library's major version number is zero, or where the ABI "
"breaks across patchlevels)"
msgstr ""

#: ../../ch-sharedlibs.rst:224
msgid ""
"libraries which are explicitly intended to be available only in static "
"form by their upstream author(s)"
msgstr ""

#: ../../ch-sharedlibs.rst:230
msgid "Development files"
msgstr ""

#: ../../ch-sharedlibs.rst:232
msgid ""
"If there are development files associated with a shared library, the "
"source package needs to generate a binary development package named "
"libraryname-dev, or if you need to support multiple development versions "
"at a time, librarynameapiversion-dev. Installing the development package "
"must result in installation of all the development files necessary for "
"compiling programs against that shared library.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:239
msgid ""
"In case several development versions of a library exist, you may need to "
"use ``dpkg``'s Conflicts mechanism (see :ref:`s-conflicts`) to ensure "
"that the user only installs one development version at a time (as "
"different development versions are likely to have the same header files "
"in them, which would cause a filename clash if both were unpacked)."
msgstr ""

#: ../../ch-sharedlibs.rst:245
msgid ""
"The development package should contain a symlink for the associated "
"shared library without a version number. For example, the libgdbm-dev "
"package should include a symlink from ``/usr/lib/libgdbm.so`` to "
"``libgdbm.so.3.0.0``. This symlink is needed by the linker (``ld``) when "
"compiling packages, as it will only look for ``libgdbm.so`` when "
"compiling dynamically."
msgstr ""

#: ../../ch-sharedlibs.rst:252
msgid ""
"If the package provides Ada Library Information (``*.ali``) files for use"
" with GNAT, these files must be installed read-only (mode 0444) so that "
"GNAT will not attempt to recompile them. This overrides the normal file "
"mode requirements given in :ref:`s-permissions-owners`."
msgstr ""

#: ../../ch-sharedlibs.rst:257
msgid ""
"This wording allows the development files to be split into several "
"packages, such as a separate architecture-independent libraryname-"
"headers, provided that the development package depends on all the "
"required additional packages."
msgstr ""

#: ../../ch-sharedlibs.rst:265
msgid "Dependencies between the packages of the same library"
msgstr ""

#: ../../ch-sharedlibs.rst:267
msgid ""
"Typically the development version should have an exact version dependency"
" on the runtime library, to make sure that compilation and linking "
"happens correctly. The ``${binary:Version}`` substitution variable can be"
" useful for this purpose.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:272
msgid ""
"Previously, ``${Source-Version}`` was used, but its name was confusing "
"and it has been deprecated since dpkg 1.13.19."
msgstr ""

#: ../../ch-sharedlibs.rst:278
msgid "Dependencies between the library and other packages"
msgstr ""

#: ../../ch-sharedlibs.rst:280
msgid ""
"If a package contains a binary or library which links to a shared "
"library, we must ensure that, when the package is installed on the "
"system, all of the libraries needed are also installed. These "
"dependencies must be added to the binary package when it is built, since "
"they may change based on which version of a shared library the binary or "
"library was linked with even if there are no changes to the source of the"
" binary (for example, symbol versions change, macros become functions or "
"vice versa, or the binary package may determine at compile-time whether "
"new library interfaces are available and can be called). To allow these "
"dependencies to be constructed, shared libraries must provide either a "
"``symbols`` file or a ``shlibs`` file. These provide information on the "
"package dependencies required to ensure the presence of interfaces "
"provided by this library. Any package with binaries or libraries linking "
"to a shared library must use these files to determine the required "
"dependencies when it is built. Other packages which use a shared library "
"(for example using ``dlopen()``) should compute appropriate dependencies "
"using these files at build time as well."
msgstr ""

#: ../../ch-sharedlibs.rst:298
msgid ""
"The two mechanisms differ in the degree of detail that they provide. A "
"``symbols`` file documents, for each symbol exported by a library, the "
"minimal version of the package any binary using this symbol will need. "
"This is typically the version of the package in which the symbol was "
"introduced. This information permits detailed analysis of the symbols "
"used by a particular package and construction of an accurate dependency, "
"but it requires the package maintainer to track more information about "
"the shared library."
msgstr ""

#: ../../ch-sharedlibs.rst:307
msgid ""
"A ``shlibs`` file, in contrast, only documents the last time the library "
"ABI changed in any way. It only provides information about the library as"
" a whole, not individual symbols. When a package is built using a shared "
"library with only a ``shlibs`` file, the generated dependency will "
"require a version of the shared library equal to or newer than the "
"version of the last ABI change. This generates unnecessarily restrictive "
"dependencies compared to ``symbols`` files if none of the symbols used by"
" the package have changed. This, in turn, may make upgrades needlessly "
"complex and unnecessarily restrict use of the package on systems with "
"older versions of the shared libraries."
msgstr ""

#: ../../ch-sharedlibs.rst:318
msgid ""
"``shlibs`` files also only support a limited range of library SONAMEs, "
"making it difficult to use ``shlibs`` files in some unusual corner cases."
"  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:322
msgid ""
"``symbols`` files are therefore recommended for most shared library "
"packages since they provide more accurate dependencies. For most C "
"libraries, the additional detail required by ``symbols`` files is not too"
" difficult to maintain. However, maintaining exhaustive symbols "
"information for a C++ library can be quite onerous, so ``shlibs`` files "
"may be more appropriate for most C++ libraries. Libraries with a "
"corresponding udeb must also provide a ``shlibs`` file, since the udeb "
"infrastructure does not use ``symbols`` files."
msgstr ""

#: ../../ch-sharedlibs.rst:331
msgid ""
"A ``shlibs`` file represents an SONAME as a library name and version "
"number, such as ``libfoo VERSION``, instead of recording the actual "
"SONAME. If the SONAME doesn't match one of the two expected formats "
"(``libfoo-VERSION.so`` or ``libfoo.so.VERSION``), it cannot be "
"represented."
msgstr ""

#: ../../ch-sharedlibs.rst:340
msgid "Generating dependencies on shared libraries"
msgstr ""

#: ../../ch-sharedlibs.rst:342
msgid ""
"When a package that contains any shared libraries or compiled binaries is"
" built, it must run ``dpkg-shlibdeps`` on each shared library and "
"compiled binary to determine the libraries used and hence the "
"dependencies needed by the package. [#]_ To do this, put a call to "
"``dpkg-shlibdeps`` into your ``debian/rules`` file in the source package."
" List all of the compiled binaries, libraries, or loadable modules in "
"your package. [#]_ ``dpkg-shlibdeps`` will use the ``symbols`` or "
"``shlibs`` files installed by the shared libraries to generate dependency"
" information. The package must then provide a substitution variable into "
"which the discovered dependency information can be placed."
msgstr ""

#: ../../ch-sharedlibs.rst:353
msgid ""
"If you are creating a udeb for use in the Debian Installer, you will need"
" to specify that ``dpkg-shlibdeps`` should use the dependency line of "
"type ``udeb`` by adding the ``-tudeb`` option.  [#]_ If there is no "
"dependency line of type ``udeb`` in the ``shlibs`` file, ``dpkg-"
"shlibdeps`` will fall back to the regular dependency line."
msgstr ""

#: ../../ch-sharedlibs.rst:359
msgid ""
"``dpkg-shlibdeps`` puts the dependency information into the "
"``debian/substvars`` file by default, which is then used by ``dpkg-"
"gencontrol``. You will need to place a ``${shlibs:Depends}`` variable in "
"the ``Depends`` field in the control file of every binary package built "
"by this source package that contains compiled binaries, libraries, or "
"loadable modules. If you have multiple binary packages, you will need to "
"call ``dpkg-shlibdeps`` on each one which contains compiled libraries or "
"binaries. For example, you could use the ``-T`` option to the ``dpkg`` "
"utilities to specify a different ``substvars`` file for each binary "
"package.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:370
msgid "For more details on ``dpkg-shlibdeps``, see its manual page."
msgstr ""

#: ../../ch-sharedlibs.rst:372
msgid ""
"We say that a binary ``foo`` *directly* uses a library ``libbar`` if it "
"is explicitly linked with that library (that is, the library is listed in"
" the ELF ``NEEDED`` attribute, caused by adding ``-lbar`` to the link "
"line when the binary is created). Other libraries that are needed by "
"``libbar`` are linked *indirectly* to ``foo``, and the dynamic linker "
"will load them automatically when it loads ``libbar``. A package should "
"depend on the libraries it directly uses, but not the libraries it only "
"uses indirectly. The dependencies for the libraries used directly will "
"automatically pull in the indirectly-used libraries. ``dpkg-shlibdeps`` "
"will handle this logic automatically, but package maintainers need to be "
"aware of this distinction between directly and indirectly using a library"
" if they have to override its results for some reason.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:385
msgid ""
"``dpkg-shlibdeps`` will use a program like ``objdump`` or ``readelf`` to "
"find the libraries and the symbols in those libraries directly needed by "
"the binaries or shared libraries in the package."
msgstr ""

#: ../../ch-sharedlibs.rst:390
msgid ""
"The easiest way to call ``dpkg-shlibdeps`` correctly is to use a package "
"helper framework such as debhelper. If you are using debhelper, the "
"``dh_shlibdeps`` program will do this work for you. It will also "
"correctly handle multi-binary packages."
msgstr ""

#: ../../ch-sharedlibs.rst:395
msgid ""
"``dh_shlibdeps`` from the ``debhelper`` suite will automatically add this"
" option if it knows it is processing a udeb."
msgstr ""

#: ../../ch-sharedlibs.rst:398
msgid ""
"Again, ``dh_shlibdeps`` and ``dh_gencontrol`` will handle everything "
"except the addition of the variable to the control file for you if you're"
" using debhelper, including generating separate ``substvars`` files for "
"each binary package and calling ``dpkg-gencontrol`` with the appropriate "
"flags."
msgstr ""

#: ../../ch-sharedlibs.rst:404
msgid ""
"A good example of where this helps is the following: We could update "
"``libimlib`` with a new version that supports a new revision of a "
"graphics format called dgf (but retaining the same major version number) "
"and depends on a new library package libdgf4 instead of the older "
"libdgf3. If we used ``ldd`` to add dependencies for every library "
"directly or indirectly linked with a binary, every package that uses "
"``libimlib`` would need to be recompiled so it would also depend on "
"libdgf4 in order to retire the older libdgf3 package. Since dependencies "
"are only added based on ELF ``NEEDED`` attribute, packages using "
"``libimlib`` can rely on ``libimlib`` itself having the dependency on an "
"appropriate version of ``libdgf`` and do not need rebuilding."
msgstr ""

#: ../../ch-sharedlibs.rst:420
msgid "Shared library ABI changes"
msgstr ""

#: ../../ch-sharedlibs.rst:422
msgid ""
"Maintaining a shared library package using either ``symbols`` or "
"``shlibs`` files requires being aware of the exposed ABI of the shared "
"library and any changes to it. Both ``symbols`` and ``shlibs`` files "
"record every change to the ABI of the shared library; ``symbols`` files "
"do so per public symbol, whereas ``shlibs`` files record only the last "
"change for the entire library."
msgstr ""

#: ../../ch-sharedlibs.rst:429
msgid ""
"There are two types of ABI changes: ones that are backward-compatible and"
" ones that are not. An ABI change is backward-compatible if any "
"reasonable program or library that was linked with the previous version "
"of the shared library will still work correctly with the new version of "
"the shared library.  [#]_ Adding new symbols to the shared library is a "
"backward-compatible change. Removing symbols from the shared library is "
"not. Changing the behavior of a symbol may or may not be backward-"
"compatible depending on the change; for example, changing a function to "
"accept a new enum constant not previously used by the library is "
"generally backward-compatible, but changing the members of a struct that "
"is passed into library functions is generally not unless the library "
"takes special precautions to accept old versions of the data structure."
msgstr ""

#: ../../ch-sharedlibs.rst:443
msgid ""
"ABI changes that are not backward-compatible normally require changing "
"the ``SONAME`` of the library and therefore the shared library package "
"name, which forces rebuilding all packages using that shared library to "
"update their dependencies and allow them to use the new version of the "
"shared library. For more information, see :ref:`s-sharedlibs-runtime`. "
"The remainder of this section will deal with backward-compatible changes."
msgstr ""

#: ../../ch-sharedlibs.rst:450
msgid ""
"Backward-compatible changes require either updating or recording the "
"minimal-version for that symbol in ``symbols`` files or updating the "
"version in the dependencies in ``shlibs`` files. For more information on "
"how to do this in the two formats, see :ref:`s-symbols` and "
":ref:`s-shlibs`. Below are general rules that apply to both files."
msgstr ""

#: ../../ch-sharedlibs.rst:456
msgid ""
"The easy case is when a public symbol is added. Simply add the version at"
" which the symbol was introduced (for ``symbols`` files) or update the "
"dependency version (for ``shlibs``) files. But special care should be "
"taken to update dependency versions when the behavior of a public symbol "
"changes. This is easy to neglect, since there is no automated method of "
"determining such changes, but failing to update versions in this case may"
" result in binary packages with too-weak dependencies that will fail at "
"runtime, possibly in ways that can cause security vulnerabilities. If the"
" package maintainer believes that a symbol behavior change may have "
"occurred but isn't sure, it's safer to update the version rather than "
"leave it unmodified. This may result in unnecessarily strict "
"dependencies, but it ensures that packages whose dependencies are "
"satisfied will work properly."
msgstr ""

#: ../../ch-sharedlibs.rst:470
msgid ""
"A common example of when a change to the dependency version is required "
"is a function that takes an enum or struct argument that controls what "
"the function does. For example::"
msgstr ""

#: ../../ch-sharedlibs.rst:477
msgid ""
"If a new operation, ``OP_BAZ``, is added, the minimal-version of "
"``library_do_operation`` (for ``symbols`` files) or the version in the "
"dependency for the shared library (for ``shlibs`` files) must be "
"increased to the version at which ``OP_BAZ`` was introduced. Otherwise, a"
" binary built against the new version of the library (having detected at "
"compile-time that the library supports ``OP_BAZ``) may be installed with "
"a shared library that doesn't support ``OP_BAZ`` and will fail at runtime"
" when it tries to pass ``OP_BAZ`` into this function."
msgstr ""

#: ../../ch-sharedlibs.rst:486
msgid ""
"Dependency versions in either ``symbols`` or ``shlibs`` files normally "
"should not contain the Debian revision of the package, since the library "
"behavior is normally fixed for a particular upstream version and any "
"Debian packaging of that upstream version will have the same behavior. In"
" the rare case that the library behavior was changed in a particular "
"Debian revision, appending ``~`` to the end of the version that includes "
"the Debian revision is recommended, since this allows backports of the "
"shared library package using the normal backport versioning convention to"
" satisfy the dependency."
msgstr ""

#: ../../ch-sharedlibs.rst:496
msgid ""
"An example of an \"unreasonable\" program is one that uses library "
"interfaces that are documented as internal and unsupported. If the only "
"programs or libraries affected by a change are \"unreasonable\" ones, "
"other techniques, such as declaring ``Breaks`` relationships with "
"affected packages or treating their usage of the library as bugs in those"
" packages, may be appropriate instead of changing the SONAME.  However, "
"the default approach is to change the SONAME for any change to the ABI "
"that could break a program."
msgstr ""

#: ../../ch-sharedlibs.rst:508
msgid "The ``symbols`` system"
msgstr ""

#: ../../ch-sharedlibs.rst:510
msgid ""
"In the following sections, we will first describe where the various "
"``symbols`` files are to be found, then the ``symbols`` file format, and "
"finally how to create ``symbols`` files if your package contains a shared"
" library."
msgstr ""

#: ../../ch-sharedlibs.rst:518
msgid "The ``symbols`` files present on the system"
msgstr ""

#: ../../ch-sharedlibs.rst:520
msgid ""
"``symbols`` files for a shared library are normally provided by the "
"shared library package as a control file, but there are several override "
"paths that are checked first in case that information is wrong or "
"missing. The following list gives them in the order in which they are "
"read by ``dpkg-shlibdeps``. The first one that contains the required "
"information is used."
msgstr ""

#: ../../ch-sharedlibs.rst:539
msgid "``debian/*/DEBIAN/symbols``"
msgstr ""

#: ../../ch-sharedlibs.rst:528
msgid ""
"During the package build, if the package itself contains shared libraries"
" with ``symbols`` files, they will be generated in these staging "
"directories by ``dpkg-gensymbols`` (see `Providing a symbols file <#s"
"-providing-symbols>`__). ``symbols`` files found in the build tree take "
"precedence over ``symbols`` files from other binary packages."
msgstr ""

#: ../../ch-sharedlibs.rst:535
msgid ""
"These files must exist before ``dpkg-shlibdeps`` is run or the "
"dependencies of binaries and libraries from a source package on other "
"libraries from that same source package will not be correct. In practice,"
" this means that ``dpkg-gensymbols`` must be run before ``dpkg-"
"shlibdeps`` during the package build.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:544
msgid ""
"``/etc/dpkg/symbols/package.symbols.arch`` and "
"``/etc/dpkg/symbols/package.symbols``"
msgstr ""

#: ../../ch-sharedlibs.rst:542
msgid ""
"Per-system overrides of shared library dependencies. These files normally"
" do not exist. They are maintained by the local system administrator and "
"must not be created by any Debian package."
msgstr ""

#: ../../ch-sharedlibs.rst:550
msgid "``symbols`` control files for packages installed on the system"
msgstr ""

#: ../../ch-sharedlibs.rst:547
msgid ""
"The ``symbols`` control files for all the packages currently installed on"
" the system are searched last. This will be the most common source of "
"shared library dependency information. These files can be read with "
"``dpkg-query --control-show package symbols``."
msgstr ""

#: ../../ch-sharedlibs.rst:552
msgid ""
"Be aware that if a ``debian/shlibs.local`` exists in the source package, "
"it will override any ``symbols`` files. This is the only case where a "
"``shlibs`` is used despite ``symbols`` files being present. See :ref:`s"
"-shlibs-paths` and :ref:`s-sharedlibs-shlibdeps` for more information."
msgstr ""

#: ../../ch-sharedlibs.rst:558
msgid ""
"An example may clarify. Suppose the source package ``foo`` generates two "
"binary packages, ``libfoo2`` and ``foo-runtime``. When building the "
"binary packages, the contents of the packages are staged in the "
"directories ``debian/libfoo2`` and ``debian/foo-runtime`` respectively. "
"(``debian/tmp`` could be used instead of one of these.)  Since "
"``libfoo2`` provides the ``libfoo`` shared library, it will contain a "
"``symbols`` file, which will be installed in "
"``debian/libfoo2/DEBIAN/symbols``, eventually to be included as a control"
" file in that package. When ``dpkg-shlibdeps`` is run on the executable "
"``debian/foo-runtime/usr/bin/foo-prog``, it will examine the "
"``debian/libfoo2/DEBIAN/symbols`` file to determine whether ``foo-"
"prog``'s library dependencies are satisfied by any of the libraries "
"provided by ``libfoo2``. Since those binaries were linked against the "
"just-built shared library as part of the build process, the ``symbols`` "
"file for the newly-built ``libfoo2`` must take precedence over a "
"``symbols`` file for any other ``libfoo2`` package already installed on "
"the system."
msgstr ""

#: ../../ch-sharedlibs.rst:580
msgid "The ``symbols`` File Format"
msgstr ""

#: ../../ch-sharedlibs.rst:582
msgid ""
"The following documents the format of the ``symbols`` control file as "
"included in binary packages. These files are built from template "
"``symbols`` files in the source package by ``dpkg-gensymbols``. The "
"template files support a richer syntax that allows ``dpkg-gensymbols`` to"
" do some of the tedious work involved in maintaining ``symbols`` files, "
"such as handling C++ symbols or optional symbols that may not exist on "
"particular architectures. When writing ``symbols`` files for a shared "
"library package, refer to dpkg-gensymbols(1) for the richer syntax."
msgstr ""

#: ../../ch-sharedlibs.rst:591
msgid ""
"A ``symbols`` may contain one or more entries, one for each shared "
"library contained in the package corresponding to that ``symbols``. Each "
"entry has the following format::"
msgstr ""

#: ../../ch-sharedlibs.rst:602
msgid ""
"To explain this format, we'll use the ``zlib1g`` package as an example, "
"which (at the time of writing) installs the shared library "
"``/usr/lib/libz.so.1.2.3.4``. Mandatory lines will be described first, "
"followed by optional lines."
msgstr ""

#: ../../ch-sharedlibs.rst:607
msgid ""
"``library-soname`` must contain exactly the value of the ELF ``SONAME`` "
"attribute of the shared library. In our example, this is ``libz.so.1``. "
"[#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:611
msgid ""
"``main-dependency-template`` has the same syntax as a dependency field in"
" a binary package control file, except that the string ``#MINVER#`` is "
"replaced by a version restriction like ``(>= version)`` or by nothing if "
"an unversioned dependency is deemed sufficient. The version restriction "
"will be based on which symbols from the shared library are referenced and"
" the version at which they were introduced (see below). In nearly all "
"cases, ``main-dependency-template`` will be ``package #MINVER#``, where "
"package is the name of the binary package containing the shared library. "
"This adds a simple, possibly-versioned dependency on the shared library "
"package. In some rare cases, such as when multiple packages provide the "
"same shared library ABI, the dependency template may need to be more "
"complex."
msgstr ""

#: ../../ch-sharedlibs.rst:624
msgid ""
"In our example, the first line of the ``zlib1g`` ``symbols`` file would "
"be::"
msgstr ""

#: ../../ch-sharedlibs.rst:629
msgid ""
"Each public symbol exported by the shared library must have a "
"corresponding symbol line, indented by one space. symbol is the exported "
"symbol (which, for C++, means the mangled symbol) followed by ``@`` and "
"the symbol version, or the string ``Base`` if there is no symbol version."
" ``minimal-version`` is the most recent version of the shared library "
"that changed the behavior of that symbol, whether by adding it, changing "
"its function signature (the parameters, their types, or the return type),"
" or changing its behavior in a way that is visible to a caller. ``id-of-"
"dependency-template`` is an optional field that references an "
"``alternative-dependency-template``; see below for a full description."
msgstr ""

#: ../../ch-sharedlibs.rst:641
msgid ""
"For example, ``libz.so.1`` contains the symbols ``compress`` and "
"``compressBound``. ``compress`` has no symbol version and last changed "
"its behavior in upstream version ``1:1.1.4``. ``compressBound`` has the "
"symbol version ``ZLIB_1.2.0``, was introduced in upstream version "
"``1:1.2.0``, and has not changed its behavior. Its ``symbols`` file "
"therefore contains the lines::"
msgstr ""

#: ../../ch-sharedlibs.rst:651
msgid ""
"Packages using only ``compress`` would then get a dependency on ``zlib1g "
"(>= 1:1.1.4)``, but packages using ``compressBound`` would get a "
"dependency on ``zlib1g (>= 1:1.2.0)``."
msgstr ""

#: ../../ch-sharedlibs.rst:655
msgid ""
"One or more ``alternative-dependency-template`` lines may be provided. "
"These are used in cases where some symbols in the shared library should "
"use one dependency template while others should use a different template."
"  The alternative dependency templates are used only if a symbol line "
"contains the ``id-of-dependency-template`` field. The first alternative "
"dependency template is numbered 1, the second 2, and so forth.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:663
msgid ""
"Finally, the entry for the library may contain one or more metadata "
"fields. Currently, the only supported field-name is ``Build-Depends-"
"Package``, whose value lists the `library development package <#s"
"-sharedlibs-dev>`_ on which packages using this shared library declare a "
"build dependency. If this field is present, ``dpkg-shlibdeps`` uses it to"
" ensure that the resulting binary package dependency on the shared "
"library is at least as strict as the source package dependency on the "
"shared library development package.  [#]_ For our example, the ``zlib1g``"
" ``symbols`` file would contain::"
msgstr ""

#: ../../ch-sharedlibs.rst:675
msgid "Also see ``deb-symbols(5)``."
msgstr ""

#: ../../ch-sharedlibs.rst:677
msgid "This can be determined by using the command"
msgstr ""

#: ../../ch-sharedlibs.rst:683
msgid ""
"An example of where this may be needed is with a library that implements "
"the libGL interface. All GL implementations provide the same set of base "
"interfaces, and then may provide some additional interfaces only used by "
"programs that require that specific GL implementation. So, for example, "
"libgl1-mesa-glx may use the following ``symbols`` file::"
msgstr ""

#: ../../ch-sharedlibs.rst:696
msgid ""
"Binaries or shared libraries using only ``publicGlSymbol`` would depend "
"only on ``libgl1`` (which may be provided by multiple packages), but ones"
" using ``implementationSpecificSymbol`` would get a dependency on "
"``libgl1-mesa-glx (>= 6.5.2-7)``."
msgstr ""

#: ../../ch-sharedlibs.rst:701
msgid ""
"This field should normally not be necessary, since if the behavior of any"
" symbol has changed, the corresponding symbol minimal-version should have"
" been increased. But including it makes the ``symbols`` system more "
"robust by tightening the dependency in cases where the package using the "
"shared library specifically requires at least a particular version of the"
" shared library development package for some reason."
msgstr ""

#: ../../ch-sharedlibs.rst:712
msgid "Providing a ``symbols`` file"
msgstr ""

#: ../../ch-sharedlibs.rst:714
msgid ""
"If your package provides a shared library, you should arrange to include "
"a ``symbols`` control file following the format described above in that "
"package. You must include either a ``symbols`` control file or a "
"``shlibs`` control file."
msgstr ""

#: ../../ch-sharedlibs.rst:719
msgid ""
"Normally, this is done by creating a ``symbols`` in the source package "
"named ``debian/package.symbols`` or ``debian/symbols``, possibly with "
"``.arch`` appended if the symbols information varies by architecture. "
"This file may use the extended syntax documented in dpkg-gensymbols(1). "
"Then, call ``dpkg-gensymbols`` as part of the package build process. It "
"will create ``symbols`` files in the package staging area based on the "
"binaries and libraries in the package staging area and the ``symbols`` "
"files in the source package. [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:728
msgid ""
"Packages that provide ``symbols`` files must keep them up-to-date to "
"ensure correct dependencies in packages that use the shared libraries. "
"This means updating the ``symbols`` file whenever a new public symbol is "
"added, changing the minimal-version field whenever a symbol changes "
"behavior or signature in a backward-compatible way (see :ref:`s"
"-sharedlibs-updates`), and changing the library-soname and main-"
"dependency-template, and probably all of the minimal-version fields, when"
" the library changes ``SONAME``. Removing a public symbol from the "
"``symbols`` file because it's no longer provided by the library normally "
"requires changing the ``SONAME`` of the library.  See :ref:`s-sharedlibs-"
"runtime` for more information on ``SONAME``\\ s."
msgstr ""

#: ../../ch-sharedlibs.rst:740
msgid ""
"If you are using ``debhelper``, ``dh_makeshlibs`` will take care of "
"calling either ``dpkg-gensymbols`` or generating a ``shlibs`` file as "
"appropriate."
msgstr ""

#: ../../ch-sharedlibs.rst:747
msgid "The ``shlibs`` system"
msgstr ""

#: ../../ch-sharedlibs.rst:749
msgid ""
"The ``shlibs`` system is a simpler alternative to the ``symbols`` system "
"for declaring dependencies for shared libraries. It may be more "
"appropriate for C++ libraries and other cases where tracking individual "
"symbols is too difficult. It predated the ``symbols`` system and is "
"therefore frequently seen in older packages. It is also required for "
"udebs, which do not support ``symbols``."
msgstr ""

#: ../../ch-sharedlibs.rst:756
msgid ""
"In the following sections, we will first describe where the various "
"``shlibs`` files are to be found, then how to use ``dpkg-shlibdeps``, and"
" finally the ``shlibs`` file format and how to create them."
msgstr ""

#: ../../ch-sharedlibs.rst:763
msgid "The ``shlibs`` files present on the system"
msgstr ""

#: ../../ch-sharedlibs.rst:765
msgid ""
"There are several places where ``shlibs`` files are found. The following "
"list gives them in the order in which they are read by ``dpkg-"
"shlibdeps``. (The first one which gives the required information is "
"used.)"
msgstr ""

#: ../../ch-sharedlibs.rst:776
msgid "``debian/shlibs.local``"
msgstr ""

#: ../../ch-sharedlibs.rst:771
msgid ""
"This lists overrides for this package. This file should normally not be "
"used, but may be needed temporarily in unusual situations to work around "
"bugs in other packages, or in unusual cases where the normally declared "
"dependency information in the installed ``shlibs`` file for a library "
"cannot be used. This file overrides information obtained from any other "
"source."
msgstr ""

#: ../../ch-sharedlibs.rst:780
msgid "``/etc/dpkg/shlibs.override``"
msgstr ""

#: ../../ch-sharedlibs.rst:779
msgid ""
"This lists global overrides. This list is normally empty. It is "
"maintained by the local system administrator."
msgstr ""

#: ../../ch-sharedlibs.rst:786
msgid "``DEBIAN/shlibs`` files in the \"build directory\""
msgstr ""

#: ../../ch-sharedlibs.rst:783
msgid ""
"These files are generated as part of the package build process and staged"
" for inclusion as control files in the binary packages being built. They "
"provide details of any shared libraries included in the same package."
msgstr ""

#: ../../ch-sharedlibs.rst:791
msgid "``shlibs`` control files for packages installed on the system"
msgstr ""

#: ../../ch-sharedlibs.rst:789
msgid ""
"The ``shlibs`` control files for all the packages currently installed on "
"the system. These files can be read using ``dpkg-query --control-show "
"package shlibs``."
msgstr ""

#: ../../ch-sharedlibs.rst:797
msgid "``/etc/dpkg/shlibs.default``"
msgstr ""

#: ../../ch-sharedlibs.rst:794
msgid ""
"This file lists any shared libraries whose packages have failed to "
"provide correct ``shlibs`` files. It was used when the ``shlibs`` setup "
"was first introduced, but it is now normally empty. It is maintained by "
"the ``dpkg`` maintainer."
msgstr ""

#: ../../ch-sharedlibs.rst:799
msgid ""
"If a ``symbols`` file for a shared library package is available, ``dpkg-"
"shlibdeps`` will always use it in preference to a ``shlibs``, with the "
"exception of ``debian/shlibs.local``. The latter overrides any other "
"``shlibs`` or ``symbols`` files."
msgstr ""

#: ../../ch-sharedlibs.rst:807
msgid "The ``shlibs`` File Format"
msgstr ""

#: ../../ch-sharedlibs.rst:809
msgid ""
"Each ``shlibs`` file has the same format. Lines beginning with ``#`` are "
"considered to be comments and are ignored. Each line is of the form::"
msgstr ""

#: ../../ch-sharedlibs.rst:814
msgid ""
"We will explain this by reference to the example of the ``zlib1g`` "
"package, which (at the time of writing) installs the shared library "
"``/usr/lib/libz.so.1.2.3.4``."
msgstr ""

#: ../../ch-sharedlibs.rst:818
msgid ""
"``type`` is an optional element that indicates the type of package for "
"which the line is valid. The only type currently in use is ``udeb``. The "
"colon and space after the type are required."
msgstr ""

#: ../../ch-sharedlibs.rst:822
msgid ""
"``library-name`` is the name of the shared library, in this case "
"``libz``. (This must match the name part of the soname, see below.)"
msgstr ""

#: ../../ch-sharedlibs.rst:825
msgid ""
"``soname-version`` is the version part of the ELF ``SONAME`` attribute of"
" the library, determined the same way that the soversion component of the"
" recommended shared library package name is determined. See :ref:`s"
"-sharedlibs-runtime` for the details."
msgstr ""

#: ../../ch-sharedlibs.rst:830
msgid ""
"``dependencies`` has the same syntax as a dependency field in a binary "
"package control file. It should give details of which packages are "
"required to satisfy a binary built against the version of the library "
"contained in the package. See :ref:`s-depsyntax` for details on the "
"syntax, and :ref:`s-sharedlibs-updates` for details on how to maintain "
"the dependency version constraint."
msgstr ""

#: ../../ch-sharedlibs.rst:837
msgid ""
"In our example, if the last change to the ``zlib1g`` package that could "
"change behavior for a client of that library was in version "
"``1:1.2.3.3.dfsg-1``, then the ``shlibs`` entry for this library could "
"say::"
msgstr ""

#: ../../ch-sharedlibs.rst:844
msgid ""
"This version restriction must be new enough that any binary built against"
" the current version of the library will work with any version of the "
"shared library that satisfies that dependency."
msgstr ""

#: ../../ch-sharedlibs.rst:848
msgid ""
"As zlib1g also provides a udeb containing the shared library, there would"
" also be a second line::"
msgstr ""

#: ../../ch-sharedlibs.rst:856
msgid "Providing a ``shlibs`` file"
msgstr ""

#: ../../ch-sharedlibs.rst:858
msgid ""
"To provide a ``shlibs`` file for a shared library binary package, create "
"a ``shlibs`` file following the format described above and place it in "
"the ``DEBIAN`` directory for that package during the build. It will then "
"be included as a control file for that package.  [#]_"
msgstr ""

#: ../../ch-sharedlibs.rst:863
msgid ""
"Since ``dpkg-shlibdeps`` reads the ``DEBIAN/shlibs`` files in all of the "
"binary packages being built from this source package, all of the "
"``DEBIAN/shlibs`` files should be installed before ``dpkg-shlibdeps`` is "
"called on any of the binary packages."
msgstr ""

#: ../../ch-sharedlibs.rst:868
msgid ""
"This is what ``dh_makeshlibs`` in the debhelper suite does. If your "
"package also has a udeb that provides a shared library, ``dh_makeshlibs``"
" can automatically generate the ``udeb:`` lines if you specify the name "
"of the udeb with the ``--add-udeb`` option."
msgstr ""

