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

   Runtime library package
       The following files are copied from debian/tmp/ to debian/libname-SOversion/.

       DEB_LIB_DIR/shared library
           The concrete file containing the shared library.  It is found by following the
           debian/tmp/DEB_LIB_DIR/libname.so symbolic link.

       DEB_LIB_DIR/SOname
           The shared object name (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 shared library and is also installed (for ldconfig, 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/.

       DEB_ADA_LIB_INFO_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.

       DEB_ADA_SOURCE_DIR/name/*
           The sources, Ada or not, should all be in a single directory.

       DEB_LIB_DIR/libname.a
           The static archive.

       DEB_GNAT_PROJECT_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).

           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).

       DEB_LIB_DIR/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-dev package in debian/control.  Its value contains the following
           dependencies.

           libname-SOversion (= ${binary:Version})
               The development package needs the same version of the runtime library package
               because of the dangling symbolic link.

           gnat (>= DEB_GNAT_VERSION), gnat (<< DEB_GNAT_VERSION + 1)
               The development package requires the default Ada compiler in order to ensure the
               compatibility with all other Ada packages.

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

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

       ada:Provides
           This debhelper substitution variable is created for inclusion in the Provides field of
           the libname-dev package in debian/control.

           It only contains libname-dev-HASH, where HASH is a 32 bit XOR of all checksums in the
           .ali files (8 lowercase hexadecimal digits).

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

           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.

   Files that are not installed
       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.

       usr/unwantedly_gprinstalled/
           Please refer to /usr/share/ada/packaging.mk.

       DEB_LIB_DIR/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.

       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.

OPTIONS

       Common debhelper command line options and environment variables are recognized.

       --export-versions
           This option is intended for support of packaging.mk.  Print Makefile definitions for
           the variables described in it.

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

       Nicolas Boulenguez <nicolas@debian.org>