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 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 (mode 644) into the package.

       If debian/control mentions a -dbg package (see below), dh_ada_library runs  dh_strip  with
       options storing its debugging information into the -dbg 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.  dh_lintian is run first so that it will not
       overwrite the override file later.

   Debugging symbols (-dbg) package
       Since automatic -dbgsym packages  are  preferred,  there  is  normally  no  -dbg  package.
       Versions >= 6.7 are compatible with this new method.

       However,  if  debian/control  mentions  a  -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 (mode 444) and  sources  (mode  644)  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 (mode 644)  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.

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

                                            2019-12-16                          DH_ADA_LIBRARY(1)