- </sect1>
-
- <sect1 id="symbols">
- <heading>The <file>symbols</file> File Format</heading>
-
- <p>
- The following documents the format of the <file>symbols</file>
- control file as included in binary packages. These files are
- built from template <file>symbols</file> files in the source
- package by <prgn>dpkg-gensymbols</prgn>. The template files
- support a richer syntax that
- allows <prgn>dpkg-gensymbols</prgn> to do some of the tedious
- work involved in maintaining <file>symbols</file> files, such
- as handling C++ symbols or optional symbols that may not exist
- on particular architectures. When
- writing <file>symbols</file> files for a shared library
- package, refer to <manref name="dpkg-gensymbols" section="1">
- for the richer syntax.
- </p>
-
- <p>
- A <file>symbols</file> may contain one or more entries, one
- for each shared library contained in the package corresponding
- to that <file>symbols</file>. Each entry has the following
- format:
- </p>
-
- <p>
- <example>
-<var>library-soname</var> <var>main-dependency-template</var>
-[ | <var>alternative-dependency-template</var> ]
-[ ... ]
-[ * <var>field-name</var>: <var>field-value</var> ]
-[ ... ]
- <var>symbol</var> <var>minimal-version</var>[ <var>id-of-dependency-template</var> ]
- </example>
- </p>
-
- <p>
- To explain this format, we'll use the the <tt>zlib1g</tt>
- package as an example, which (at the time of writing) installs
- the shared library <file>/usr/lib/libz.so.1.2.3.4</file>.
- Mandatory lines will be described first, followed by optional
- lines.
- </p>
-
- <p>
- <var>library-soname</var> must contain exactly the value of
- the ELF <tt>SONAME</tt> attribute of the shared library. In
- our example, this is <tt>libz.so.1</tt>.<footnote>
- This can be determined by using the command
- <example compact="compact">
-readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME
- </example>
- </footnote>
- </p>
-
- <p>
- <var>main-dependency-template</var> has the same syntax as a
- dependency field in a binary package control file, except that
- the string <tt>#MINVER#</tt> is replaced by a version
- restriction like <tt>(>= <var>version</var>)</tt> 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, <var>main-dependency-template</var> will
- be <tt><var>package</var> #MINVER#</tt>,
- where <var>package</var> 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.
- </p>
-
- <p>
- In our example, the first line of
- the <tt>zlib1g</tt> <file>symbols</file> file would be:
- <example compact="compact">
-libz.so.1 zlib1g #MINVER#
- </example>
- </p>
-
- <p>
- Each public symbol exported by the shared library must have a
- corresponding symbol line, indented by one
- space. <var>symbol</var> is the exported symbol (which, for
- C++, means the mangled symbol) followed by <tt>@</tt> and the
- symbol version, or the string <tt>Base</tt> if there is no
- symbol version. <var>minimal-version</var> 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 its behavior in a way that is visible to a
- caller. <var>id-of-dependency-template</var> is an optional
- field that references
- an <var>alternative-dependency-template</var>; see below for a
- full description.
- </p>
-
- <p>
- For example, <tt>libz.so.1</tt> contains the
- symbols <tt>compress</tt>
- and <tt>compressBound</tt>. <tt>compress</tt> has no symbol
- version and last changed its behavior in upstream
- version <tt>1:1.1.4</tt>. <tt>compressBound</tt> has the
- symbol version <tt>ZLIB_1.2.0</tt>, was introduced in upstream
- version <tt>1:1.2.0</tt>, and has not changed its behavior.
- Its <file>symbols</file> file therefore contains the lines:
- <example compact="compact">
- compress@Base 1:1.1.4
- compressBound@ZLIB_1.2.0 1:1.2.0
- </example>
- Packages using only <tt>compress</tt> would then get a
- dependency of <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
- using <tt>compressBound</tt> would get a dependency
- of <tt>zlib1g (>= 1:1.2.0)</tt>.
- </p>
-
- <p>
- One or more <var>alternative-dependency-template</var> 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 <var>id-of-dependency-template</var> field. The first
- alternative dependency template is numbered 1, the second 2,
- and so forth.<footnote>
- 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 <file>symbols</file> file:
- <example>
-libGL.so.1 libgl1
- | libgl1-mesa-glx #MINVER#
- publicGlSymbol@Base 6.3-1
- [...]
- implementationSpecificSymbol@Base 6.5.2-7 1
- [...]
- </example>
- Binaries or shared libraries using
- only <tt>publicGlSymbol</tt> would depend only
- on <tt>libgl1</tt> (which may be provided by multiple
- packages), but ones
- using <tt>implementationSpecificSymbol</tt> would get a
- dependency on <tt>libgl1-mesa-glx (>= 6.5.2-7)</tt>
- </footnote>
- </p>