| DH_ADA_LIBRARY(1) | Debhelper | DH_ADA_LIBRARY(1) |
dh_ada_library - help packaging Ada libraries for Debian
dh_ada_library [debhelper options]
dh_ada_library is a debhelper program that handles some common tasks in packaging libraries written in the Ada programming language.
The difficult work is to convince the upstream build system to produce both a static and a relocatable library in a row (during the dh_auto_configure and dh_auto_build steps), then to install these under debian/tmp/ with the directory structure described by the Debian Policy for Ada (dh_auto_install). The /usr/share/ada/packaging.mk Makefile snippet, part of the same dh-ada-library package, may help for that. It contains lots of comments describing its usage.
Once the files are installed, dh_ada_library is in charge of dispatching them to the specific package temporary directories. It is enabled by the presence of the dh-sequence-ada-library virtual package in the Build-Depends-Arch field of the debian/control file. For a while, you should in addition depend on the explicit dh-ada-library concrete package and require at least version 9, because this version introduces incompatible changes, and virtual packages cannot receive version restrictions.
At start, it parses debian/control to find Ada libraries: architecture-dependent packages, named libname-dev, depending on ${ada:Depends} and providing ${ada:Provides}.
For each one, there must also be a runtime library package, named from the shared object name as described in section 8 of the Debian Policy (usually libname-SOversion).
For a description of DEB_HOST_MULTIARCH, see dpkg-architecture(1). The installation directories (DEB_ADA_SOURCE_DIR, DEB_LIB_DIR, DEB_ADA_LIB_INFO_DIR and DEB_GNAT_PROJECT_DIR) are defined in the Debian Policy, their current values are available via packaging.mk.
The following files are copied from debian/tmp/ to debian/libname-SOversion/.
dh_link later removes the redundant path components like lib/...
Versions before 8.1 were ignoring the SOname/Library_Version, and guessing it from the SOversion in the Debian package name. Patches caused by this unfortunate decision can now be unapplied.
The following files are copied from debian/tmp/ to debian/libname/.
dh_fixperms later checks that their permissions are 444.
In order to improve build reproducibility, -f*-prefix-map compiler flags are removed from them.
If the library was built with gprbuild and another GNAT project, the gprinstall tool can generate such a standalone project with the correct Languages, Linker_Switches in the Linker package, imports (with), source file renamings... Else, the maintainer must write a new project, or more accurately generate it because DEB_HOST_MULTIARCH cannot be hardcoded. If so, it is recommended to also substitute the path variables set by /usr/share/ada/packaging.mk, in case the directory structure ever has to change (again).
In order to improve build reproducibility, -f*-prefix-map compiler flags are removed (for examples because gprbuild has copied variables like ADAFLAGS from the build project).
dh_link later removes the redundant path components like lib/...
More items are added as described in the next sections in order to reflect the dependencies across Ada library packages.
It only contains libname-dev-HASH, where HASH is a 32 bit XOR of all checksums in the .ali files (8 lowercase hexadecimal digits).
If libdep-dev is built from the same source package, the dependency is libdep-dev (= ${binary:Version}), ensuring that all static libraries are compiled with compatible options. Such a restriction is more specific than a hash suffix.
If libdep-dev is not built from the same source but is installed on the system, in other words if it is listed in Build-Depends, the dependency is on the libdep-dev-hash virtual package provided by the installed concrete libdep-dev. It prevents later installation of an update of libdep-dev modifying its ALI checksums.
Remaining projects trigger a warning, because the maintainer will need to find the right dependency.
Versions before 8.1 were guessing more dependencies from Linker'Linker_Options. This was often wrong, for no benefit since C -dev packages carry no version and can be hard-coded in debian/control.
The following files, if they exist under debian/tmp/, are ignored but marked as installed by dh_ada_library in order to prevent a false alert by dh_missing later, as if the files were listed in debian/not-installed.
It would be easy to fix the directory structure, and versions before 8.1 were doing exactly this, at the cost of generating a project with different paths. Now that gprinstall is almost capable of dealing with stagged installs, duplicating its job seems a waste of energy.
For now, DEB_ADA_SOURCE_DIR and DEB_GNAT_PROJECT_DIR are under /usr/share/ada/. This implies that the -dev package cannot be declared Multi-Arch: same as the content of the project (and maybe of generated sources) will vary across architectures.
The Linker'Linker_Options attribute should rarely be needed. A dependency written in Ada should be described by an imported project, also handling .ali files. A dependency written in C should be listed in Library_Options when building a shared library, and in Linker'Linker_Options when using a static archive, but is not always required in Linker'Linker_Options for shared libraries. Until now, such options have only proved useful to light bindings importing C symbols from a specification or an inlined procedure. In a foo.pc file as read by pkg-config, they are named Libs, excluding -lfoo and Libs.private.
Common debhelper command line options and environment variables are recognized.
This stanza in debian/rules may help debugging.
override_dh_ada_library:
dh_ada_library -v"
The version is composed of two numbers separated by a dot. The second one increases during a normal update, which supposedly fixes bugs, introduces compatible evolutions, or remove stuff unused since oldoldstable. A change in the first one announces an incompatibility requiring some users to modify their source package.
debhelper(7), deb-substvars(5), the Debian Policy at <https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#run-time-shared-libraries>, the Debian Policy for Ada at <http://people.debian.org/~lbrenta/debian-ada-policy.html>, and the documentation of GNAT project tools installed into /usr/share/doc/gprbuild by the gprbuild-doc package.
Nicolas Boulenguez <nicolas@debian.org>
| 2024-03-18 | 9.3 |