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,  ALI  files directory and linker
       options.  Then it parses debian/control to check that three 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).
       Then, dh_ada_library processes each of the three packages as follows:

   Runtime library package
       dh_ada_library  installs  the  shared  library  into  the  package then runs dh_strip with
       options storing its debugging information into the -dbg package.

       If the 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.  dh_lintian is run first so that it will not overwrite the override file later.

   Debugging symbols (-dbg) package
       The  ada:Depends,  ada:Recommends,  ada:Suggests  substitution  variables  receive  values
       reflecting  that  the  -dbg  package  depends  on the library package, recommends the -dev
       package and suggests the gnat package.

       Versions <= 5.3 used to replace the documentation directory with a symbolic  link  to  the
       one  in  the  runtime library package, but usage has shown that linking directories caused
       upgrade problems.  If a binary package built with such a version has  been  released,  the
       source     package     should     add     maintainer     scripts     as    described    in
       https://wiki.debian.org/MissingCopyrightFile.

   Development package (-dev)
       First,  dh_ada_library  installs  the   usual   development   symbolic   link   (*.so   ->
       *.so.soversion),  ALI  files  and sources into the -dev package.  Languages other than Ada
       listed in the project file are taken into account, whether they have been previously dealt
       with  by  gprbuild,  or  ignored by gnatmake and compiled separately.  Then it 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.  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.

       Each renaming exception is transmitted to the generated project.

       dh_ada_library runs dh_strip before installing the static library so that the latter keeps
       its debugging information.

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

REMARKS

       This  program  does  not belong to the debhelper suite.  To activate it, please run the dh
       sequencer with the --with ada-library option.

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

                                            2013-03-21                          DH_ADA_LIBRARY(1)