=head1 NAME

dh_ada_library - help packaging Ada libraries for Debian

=head1 SYNOPSIS

B<dh_ada_library> [S<I<debhelper options>>]

=head1 DESCRIPTION

B<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
B<dh_auto_configure> and B<dh_auto_build> steps), then to install
these under B<debian/tmp/> with the directory structure described by
the Debian Policy for Ada (B<dh_auto_install>).
The B</usr/share/ada/packaging.mk> Makefile snippet, part of the same
B<dh-ada-library> package, may help for that.
It contains lots of comments describing its usage.

Once the files are installed, B<dh_ada_library> is in charge of
dispatching them to the specific package temporary directories.
It is enabled by the presence of the B<dh-sequence-ada-library>
virtual package in the B<Build-Depends-Arch> field of the
B<debian/control> file.
For a while, you should in addition depend on the explicit
B<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
I<debian/control>
to find Ada libraries:
architecture-dependent packages,
named B<lib>I<name>B<-dev>,
depending on B<${ada:Depends}> and
providing B<${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 B<lib>I<name>B<->I<SOversion>).

For a description of I<DEB_HOST_MULTIARCH>, see
L<dpkg-architecture(1)>.  The installation directories
(I<DEB_ADA_SOURCE_DIR>, I<DEB_LIB_DIR>, I<DEB_ADA_LIB_INFO_DIR> and
I<DEB_GNAT_PROJECT_DIR>) are defined in the Debian Policy, their
current values are available via B<packaging.mk>.

=head2 Runtime library package

The following files are copied from B<debian/tmp/> to
B<debian/lib>I<name>B<->I<SOversion>B</>.

=over 4

=item I<DEB_LIB_DIR>B</>I<shared library>

The concrete file containing the shared library.
It is found by following the
B<debian/tmp/>I<DEB_LIB_DIR>B</lib>I<name>B<.so> symbolic link.

=item I<DEB_LIB_DIR>B</>I<SOname>

The shared object name (I<SOname>) is extracted from the binary
data in the shared library, and may differ from the file name.
If so, this symbolic link also refers to the I<shared library> and is
also installed (for ldconfig, see the Debian Policy for details).

B<dh_link> later removes the redundant path components like
B<lib/..>.

=back

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.

=head2 Development package (-dev)

The following files are copied from B<debian/tmp/> to
B<debian/lib>I<name>B</>.

=over 4

=item I<DEB_ADA_LIB_INFO_DIR>B</>I<name>B</>I<*>B<.ali>

The GNAT Ada Library Information files files created along the objects
when building the shared library.

B<dh_fixperms> later checks that their permissions are 444.

In order to improve build reproducibility, I<-f*-prefix-map>
compiler flags are removed from them.

=item I<DEB_ADA_SOURCE_DIR>B</>I<name>B</>I<*>

The sources, Ada or not, should all be in a single directory.

=item I<DEB_LIB_DIR>B</lib>I<name>B<.a>

The static archive.

=item I<DEB_GNAT_PROJECT_DIR>B</>I<name>B<.gpr>

This standalone library GNAT project intended for use after
installation.

If the library was built with B<gprbuild> and another GNAT project,
the B<gprinstall> tool can generate such a standalone project with
the correct B<Languages>, B<Linker_Switches> in the B<Linker>
package, imports (B<with>), source file renamings...
Else, the maintainer must write a new project, or more accurately
generate it because B<DEB_HOST_MULTIARCH> cannot be hardcoded.
If so, it is recommended to also substitute the path variables set by
B</usr/share/ada/packaging.mk>, in case the directory structure
ever has to change (again).

In order to improve build reproducibility, I<-f*-prefix-map> compiler
flags are removed (for examples because B<gprbuild> has copied
variables like B<ADAFLAGS> from the build project).

=item I<DEB_LIB_DIR>B</lib>I<name>B<.so>

The development symbolic link is installed here, but dangling because
the concrete shared library is in the runtime library package.

B<dh_link> later removes the redundant path components like
B<lib/..>.

=item B<ada:Depends>

This debhelper substitution variable is created for inclusion in the
B<Depends> field of the B<lib>I<name>B<-dev>
package in B<debian/control>.
Its value contains the following dependencies.

=over 4

=item B<lib>I<name>B<->I<SOversion>B< (= ${binary:Version})>

The development package needs the same version of the runtime library
package because of the dangling symbolic link.

=item B<gnat (E<gt>= >I<DEB_GNAT_VERSION>B<), gnat (<< >I<DEB_GNAT_VERSION + 1>B<)>

The development package requires the default Ada compiler in order to
ensure the compatibility with all other Ada packages.

=item B<gnat->I<DEB_GNAT_VERSION>B<->I<HASH>

This virtual package reflects the (host) version of the run-time
library used during the build.

=back

More items are added as described in the next sections in order to
reflect the dependencies across Ada library packages.

=item B<ada:Provides>

This debhelper substitution variable is created for inclusion in the
B<Provides> field of the B<lib>I<name>B<-dev>
package in B<debian/control>.

It only contains B<lib>I<name>B<-dev->I<HASH>, where I<HASH> is a 32
bit XOR of all checksums in the B<.ali> files (8 lowercase hexadecimal
digits).

=item Imported projects

In addition, B<dh_ada_library> searches
B<debian/tmp/>I<DEB_GNAT_PROJECT_DIR>B</>I<name>B<.gpr> for imported
projects (B<with>).
For each imported library project I<dep>B<.gpr>,
a dependency is added into B<ada:Depends>.

If B<lib>I<dep>B<-dev> is built from the same source package,
the dependency is B<lib>I<dep>B<-dev (= ${binary:Version})>,
ensuring that all static libraries are compiled with compatible options.
Such a restriction is more specific than a hash suffix.

If B<lib>I<dep>B<-dev> is not built from the same source but is
installed on the system, in other words if it is listed in
B<Build-Depends>, the dependency is on the
B<lib>I<dep>B<-dev->I<hash> virtual package provided by
the installed concrete B<lib>I<dep>B<-dev>.
It prevents later installation of an update of B<lib>I<dep>B<-dev>
modifying its ALI checksums.

Remaining projects trigger a warning, because the maintainer will need
to find the right dependency.

=back

Versions before 8.1 were guessing more dependencies from
B<Linker'Linker_Options>.
This was often wrong, for no benefit since C -dev packages carry no
version and can be hard-coded in B<debian/control>.

=head2 Files that are not installed

The following files, if they exist under B<debian/tmp/>, are ignored
but marked as installed by B<dh_ada_library> in order to prevent a
false alert by B<dh_missing> later, as if the files were listed in
B<debian/not-installed>.

=over 4

=item B<usr/unwantedly_gprinstalled/>

Please refer to B</usr/share/ada/packaging.mk>.

=item I<DEB_LIB_DIR>B</lib>I<name>B<.la>

The Debian Policy recommends not to install libtool B<.la> files.

=back

=head1 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.

For now, I<DEB_ADA_SOURCE_DIR> and I<DEB_GNAT_PROJECT_DIR> are under
B</usr/share/ada/>.
This implies that the -dev package cannot be declared
B<Multi-Arch: same>
as the content of the project (and maybe of generated sources) will
vary across architectures.

The I<Linker'Linker_Options> attribute should rarely be needed.
A dependency written in Ada should be described by an imported
project, also handling I<.ali> files.
A dependency written in C should be listed in I<Library_Options>
when building a shared library, and in I<Linker'Linker_Options>
when using a static archive, but is not always required in
I<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 I<foo.pc> file as read by B<pkg-config>, they are named
I<Libs>, excluding I<-lfoo> and I<Libs.private>.

=head1 OPTIONS

Common debhelper command line options and environment variables are
recognized.

=over 4

=item B<--export-versions>

This option is intended for support of B<packaging.mk>.
Print Makefile definitions for the variables described in it.

=back

=head1 EXAMPLES

This stanza in B<debian/rules> may help debugging.

  override_dh_ada_library:
  	dh_ada_library -v"

=head1 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 I<oldoldstable>.
A change in the first one announces an incompatibility requiring some
users to modify their source package.

=head1 SEE ALSO

L<debhelper(7)>,
L<deb-substvars(5)>,
the B<Debian Policy> at
L<https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#run-time-shared-libraries>,
the B<Debian Policy for Ada> at
L<http://people.debian.org/~lbrenta/debian-ada-policy.html>,
and the documentation of GNAT project tools installed into
B</usr/share/doc/gprbuild> by the gprbuild-doc package.

=head1 AUTHOR

Nicolas Boulenguez <nicolas@debian.org>
