Provided by: dh-ada-library_8.6_all 
NAME
dh_ada_library - help packaging Ada libraries for Debian
SYNOPSIS
dh_ada_library [debhelper options]
DESCRIPTION
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.
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 (>= 8.1), because this version introduces incompatible changes, and virtual
packages cannot receive version restrictions.
At start, it parses debian/control to check that package names exist conforming to the
Coexistence Not Allowed naming scheme described in the Debian Policy for Ada and extracts
the ALI files version (aliversion)) and the shared library version (soversion). More
accurately, each library needs two packages, ibname-ALIversion-dev/ and ibname-SOversionR.
The dash is required when name ends with a digit, used here for readability, but rare in
practice.
Runtime library package
The following files are copied from debian/tmp to debian/libname-SOversion.
debian/tmp/usr/lib/DEB_HOST_MULTIARCH/shared library
The concrete file containing the shared library. This file is found by following
the debian/tmp/usr/lib/DEB_HOST_MULTIARCH/libname.so symbolic link.
debian/tmp/usr/lib/DEB_HOST_MULTIARCH/SOname
The shared object name (SOname) is extracted from the binary data in the shared
library, and may differ from the file name. In that case, both are installed
(ldconfig requires the symbolic link, see the Debian Policy for details).
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.
Development package (-dev)
The following files are copied from debian/tmp to debian/libname-LIversion.
ali_install_dir/name/*.ali
The GNAT Ada Library Information files files created along the objects when
building the shared library.
dh_fixperms later checks that their permissions are 444.
In order to improve build reproducibility, -f*-prefix-map compiler flags are
removed from them.
ada_install_dir/name/*
The sources, Ada or not, should all be in a single directory.
/usr/lib/DEB_HOST_MULTIARCH/libname.a
The static archive.
gpr_install_dir/name.gpr
This standalone library GNAT project intended for use after installation.
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).
usr/lib/DEB_HOST_MULTIARCH/libname.so
The development symbolic link is installed here, but dangling because the concrete
shared library is in the runtime library package.
dh_link later removes the redundant path components like lib/...
ada:Depends
This debhelper substitution variable is created for inclusion in the Depends field
of the libname-ALIversion-dev package in debian/control. The value means that the
development package needs the same version of the runtime library package (because
of the dangling symbolic link), and the default Ada compiler. For technical
reasons (https://bugs.debian.org/bug=975589#24), the compiler version is not
described gnat-V but as gnat (>= V), gnat (<< V+1).
In addition, dh_ada_library searches debian/tmp/gpr_install_dir/name.gpr for
imported projects (with). For each imported library project recognized, either as
built from this source package or installed by one of the Build-Depends, a
dependency is added into ada:Depends. For already processed project within the
same source package, the dependency mandates an exact binary:Version, ensuring that
all static libraries are compiled with compatible options. 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.
Files that are not installed
The following files, if they exist, 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.
debian/tmp/usr/unwantedly_gprinstalled
Please refer to /usr/share/ada/packaging.mk.
debian/tmp/usr/lib/DEB_HOST_MULTIARCH/libname.la
The Debian Policy recommends not to install libtool .la files.
REMARKS
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.
Both libraries and ALI files are installed into /usr/lib/DEB_HOST_MULTIARCH, the project
and sources into /usr/share/ada/adainclude. 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.
OPTIONS
Common debhelper command line options and environment variables are recognized.
EXAMPLES
This stanza in debian/rules may help debugging.
override_dh_ada_library:
dh_ada_library -v
VERSIONS
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.
SEE ALSO
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.
AUTHOR
dh_ada_library and this manpage were written by Nicolas Boulenguez <nicolas@debian.org>
for the Debian project (and may be used by others).
2022-08-16 DH_ADA_LIBRARY(1)