debian man page for dh_ada_library

DH_ADA_LIBRARY(1)					      General Commands Manual						 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: the library name, imported projects, source directo-
       ries, ALI files directory and linker options.  Then it parses debian/control to check that three package names exist conforming to the nam-
       ing scheme described in the Debian Policy for Ada and extracts 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
       dh_ada_library  runs  dh_installdocs  with  options  replacing  the  documentation directory with a symbolic link to the one in the runtime
       library package.  If additionnal files are ever needed in it, please list them in the debian/libLIBRARY_NAME-dbg.docs file instead of  run-
       ning dh_installdocs again, as this tool is not intended to be run twice.

       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.

   Development package (-dev)
       First, dh_ada_library installs the usual development symbolic link (*.so -> *.so.soversion), ALI files and sources into the  -dev  package.
       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.

       dh_ada_library then reads and parses the project file passed on the command line, which is normally used to build  the  static  and  shared
       libraries,  and	uses it as a template to generate another project file, which it installs into the -dev package.  This second project file
       is intended for use by programs that use the library.  It inherits any -l or -L linker options from the build project file  but	omits  the
       Compiler switches, replacing this with Externally_Built and Library_ALI_Dir.

       dh_ada_library runs dh_strip with options avoiding that the static library is stripped.

       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, a corresponding -dev package name is searched in debian/control or else with dpkg-query and a dependency	is
       added.

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 the simple debian/ada_libraries file instead of a debhelper override or an environment variable exportation.

       A symbolic link for the -dev package documentation directory only has advantages and is recommended, but cannot be created by this program.
       There is good chance that the maintainer will later have to execute dh_installdocs from debian/rules, and the tool fails when it encounters
       a  dangling  symbolic  link  or	if  it	has  already  been  executed.	For  the  -dbg package, it is easy to list arguments in one of the
       debian/*.docs files, but for the -dev package this solution would require a manual renaming whenever the ALIVERSION changes.

       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.  Line breaks are considered as normal spaces.  Any  line  starting
	      with a dash will be ignored.

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

EXAMPLES
       dh_ada_library KIND=dynamic 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://peo-
       ple.debian.org/~lbrenta/debian-ada-policy.html, http://wiki.debian.org/Multiarch/Implementation.

AUTHOR
       dh_ada_library and this manpage were written by Nicolas Boulenguez <nicolas.boulenguez@free.fr>, for the Debian project (and may be used by
       others).

								    2012-03-19							 DH_ADA_LIBRARY(1)