This page documents why and how Debian maintainers for packages written in enlightened programming languages include a version or hash in the -dev package name for each library, similar to the Shared Object version in the library package name.
Even if no one-size-fits-all solution ever emerges, sharing good ideas will be beneficial.
Languages
Ada
The Debian Policy for Ada documents the existing process. Inspired by this page, the packaging style will probably change for gnat-13.
The dh_ada_library tool implements some parts of the policy.
https://wiki.debian.org/Ada adds some details.
Problem
The language requires that an object is recompiled when a source changes in its recursive dependencies. The compiler maintains a .ali file for each compilation unit in order to detect such changes (ignoring comments and spaces). When a library is updated, the .ali file in its -dev package change, all its recursive, reverse dependencies must be recompiled in a correct order. Meanwhile, they FTBFS with sometimes cryptic error messages, or worst may produce buggy executables.
Dependencies
The name of an Ada -dev package describes the state of all sources of all recursive dependencies.
The dependencies between -dev packages are accurate enough for dpkg to prevent the installation of two package directly or indirectly using two versions of the same source.
For example, when several packages are uploaded at once, the build daemons figure a correct build order on each architecture because a (direct) build-dependency can only be installed once all its (recursive, versioned) dependencies can.
- currently The maintainer has to manually edit the Break/Replace/Package fields.
Source: foo
Build-Depends-Arch: libbar1.2-dev
Package: libfoo3.4-dev
Breaks: libfoo3.1-dev, libfoo3.2-dev, libfoo3.3-dev
Replaces: libfoo3.1-dev, libfoo3.2-dev, libfoo3.3-dev
Depends: ${ada:Depends} # libbar1.2-dev, concrete package- planned for gnat-13:
Source: foo`
Build-Depends-Arch: ada-bar-dev
Package: ada-foo-dev
Provides: ${ada:Provides} # ada-foo-dev-1a2b3c4d
Depends: ${ada:Depends} # ada-bar-dev-5e6f7a8b the one available at build time
Transitions
- currently
During an update, either of the library or of a direct or indirect build-dependency, the maintainer must (but sometimes forgets to) rename the -dev package, then upload to the NEW queue. The standard library cannot afford a passage through NEW and is handled specially (with error-prone manual work). Removing the exception is one of the motivation for the planned change.
- planned for gnat-13
Each ada-*-dev package provides a virtual packaged named after the state of the sources of the library and all its recursive dependencies. In practice, the name is computed from the .ali checksums for the library and the name of the ada-*-dev-* virtual packages for each ada-*-dev build-dependency.
An update of a library automatically renames the -dev package, breaking all reverse dependencies. The reverse dependencies are fixed by a simple rebuild. This is similar to the +b1 rebuilds during SO transitions.
Transitions require no migration script (at least for libraries),
Recursive reverse dependencies fail to build from source (with an explicit message instead of either a cryptic message or a buggy result) during the transition.
Guidelines for any language
Language-specific conventions or tools should take care not assume that a given source package only deals with one programming language (see plplot for an example).
Naming scheme for the dev packages
In the absence of other constraints (like existing practice), please name the packages LANGUAGE-LIBRARY-dev and LANGUAGE-LIBRARY-dev-VERSION. This improves the consistency across the archive and automatic detection of -dev build dependencies or built binary packages for a specific language.