DH_ADA_LIBRARY(1)

NAME
dh_ada_library - help packaging Ada libraries for Debian

SYNOPSIS
dh_ada_library [debhelper options] [[variable=value ...] project.gpr ] ...

DESCRIPTION
dh_ada_library is a debhelper program that handles some common tasks in packaging libraries written in the Ada programming language.

Each project.gpr argument designates a GNAT project file building a shared library provided by the source package. Since using environment variables in such projects is common practice, a list of variable assignments may be provided before each project.

dh_ada_library reads each project file and extracts the following information from it: library name, imported projects, source directories, library directory, object directory (containing ALI files) and linker options (both Leading_Library_Options and Library_Options). Then 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).

  Important change in version 7
Previous versions were deducing linker options for the installed project from Leading_Library_Options and Library_Options attributes in the build project. Next versions, more consistently with other GNAT tools, will read Linker'Linker_Options instead. Unfortunately, integration tests (like autopkgtests) seem to be the only reliable way to detect problems caused by this change.

  Runtime library package
dh_ada_library installs the shared library into this package.

This should not be necessary anymore since shared library declares its stack executable, dh_ada_library generates a lintian override for the runtime library package about GNAT using trampolines for exception handling. If dh-ada-library is called directly, that is neither by the dh sequencer nor by the override_dh_ada_library target, this should be after dh_lintian so that the latter does not overwrite the override.

  Development package (-dev)
First, dh_ada_library installs the usual development symbolic libLIBRARY.so referring to +libLIBRARY.so.soversion.

The ALI files are installed in read-only mode (444), stripped from the lines containing -f*-prefix-map build options are removed (improving build reproducibility, until the proper solution BUILD_PATH_PREFIX_MAP is accepted by GCC). All sources are also installed, from each language in the build project. dh-ada-library then looks for a file named libLIBRARY_NAME.a (the static library) in the current directory or its subdirectories and installs this file into the -dev package.

A second project file, intended for use by programs linking against the library, is generated and installed into the -dev package, copying the renaming exceptions. The Linker package of the new project inherits any -l or -L linker options from Leading_Library_Options and Library_Options attributes of the build project file.

The ada:Depends substitution variable receives a value reflecting that the package depends on gnat, gnat-X and the library package. For each imported library project recognized, either as already processed or installed by one of the Build-Depends, a dependency is added into ada:Depends and the generated project is added the corresponding with line. 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.

DEBHELPER INTEGRATION
Most packages only need to add dh-sequence-ada-library to Build-Depends-Arch in debian/control. Debhelper (>= 12) wild detect the dependency and execute dh_ada_library after dh_lintian as part of binary-arch and binary sequences.

Some packages do not distinguish Build-Depends-Arch, for example because they only build architecture-dependent binaries. It is then convenient to add the dependency to Build-Depends instead. The tool will then also run as part of the binary-indep sequence, though probably not doing anything.

Packages compatible with debhelper (<< 12) should add dh-ada-ada-library to Build-Depends-Arch, and an override like
override_dh_lintian-arch:
        dh_lintian -a
        dh_ada_library
into debian/rules.

Packages compatible with debhelper (<< 12), but not distinguishing Build-Depends-Arch, may just add dh-ada-ada-library to Build-Depends and pass the --with=ada-library option to the dh sequencer in debian/rules.

REMARKS
The Library_Version project attribute is purposedly ignored. Instead, the soname is guessed from the library package name. For projects needing an external variable definition to set this attribute, any arbitrary value may be given. This will often allow the maintainer to use a simple debian/ada_libraries file instead of a debhelper override or an environment variable exportation.

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.

FILES

debian/ada_libraries
    Projects and variables, in addition to those in the command line if called directly from debian/rules. Line breaks are considered as normal spaces. This may change in the future and it is recommended to put exactly one affectation or project on each line. Any line starting with a dash will be ignored.

OPTIONS
Common debhelper command line options and environment variables are recognized.

EXAMPLES
dh_ada_library 'DIRS=src gen' SOVERSION=ignored foo.gpr --verbose --no-act

SEE ALSO
debhelper(7), dh_installdocs(1), dh_lintian(1), deb-substvars(5), the Debian Policy for Ada available at http://people.debian.org/~lbrenta/debian-ada-policy.html.

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