Provided by: dh-ada-library_7.8_amd64 bug

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).   In  order  to  improve  build
       reproducibility,  -f*-prefix-map  compiler  flags  are removed from them.  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  the  library package and gnat (>= X), gnat (<< X+1), where X is the GNAT major version
       available at build time.  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)