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 (Linker'Linker_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).

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

       This should not be necessary anymore since 0 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 and Linker'Linker_Options attribute of
       the original project (see below).

       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.   For  each  option  like -lFOO in Linker'Linker_Options, a matching
       libFOO.so is searched in the default  library  directory,  and  the  -dev  package  responsible  for  its
       installation is added to ada:Depends.

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.

       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.

       Versions   prior   to   7   were   reading   Leading_Library_Options   and   Library_Options  instead  of
       Linker'Linker_Options.  Unfortunately, integration tests (like autopkgtests) seem to be the only  way  to
       detect packages relying on this behaviour.

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

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

                                                   2020-04-21                                  DH_ADA_LIBRARY(1)