--- name: "dh_ada_library" section: "1" platform: "linux" package: "dh-ada-library" version: "9.9" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/dh_ada_library" --- # dh\_ada\_library(1) help packaging Ada libraries for Debian ## NAME dh\_ada\_library - help packaging Ada libraries for Debian ## SYNOPSIS **dh\_ada\_library** \[*debhelper options*\] ## DESCRIPTION **dh\_ada\_library** is a debhelper program that handles some common tasks in packaging libraries written in the Ada programming language. The difficult work is to convince the upstream build system to produce both a static and a relocatable library in a row (during the **dh\_auto\_configure** and **dh\_auto\_build** steps), then to install these under **debian/tmp/** with the directory structure described by the Debian Policy for Ada (**dh\_auto\_install**). The **/usr/share/ada/packaging.mk** Makefile snippet, part of the same **dh-ada-library** package, may help for that. It contains lots of comments describing its usage. Once the files are installed, **dh\_ada\_library** is in charge of dispatching them to the specific package temporary directories. It is enabled by the presence of the **dh-sequence-ada-library** virtual package in the **Build-Depends-Arch** field of the **debian/control** file. For a while, you should in addition depend on the explicit **dh-ada-library** concrete package and require at least version 9, because this version introduces incompatible changes, and virtual packages cannot receive version restrictions. At start, it parses *debian/control* to find Ada libraries: architecture-dependent packages, named **lib***name***-dev**, depending on **${ada:Depends}** and providing **${ada:Provides}**. For each one, there must also be a runtime library package, named from the shared object name as described in section 8 of the Debian Policy (usually **lib***name***-***SOversion*). For a description of *DEB\_HOST\_MULTIARCH*, see [**dpkg-architecture**(1)](/dpkg-architecture/1.md). The installation directories (*DEB\_ADA\_SOURCE\_DIR*, *DEB\_LIB\_DIR*, *DEB\_ADA\_LIB\_INFO\_DIR* and *DEB\_GNAT\_PROJECT\_DIR*) are defined in the Debian Policy, their current values are available via **packaging.mk**. ### Runtime library package The following files are copied from **debian/tmp/** to **debian/lib***name***-***SOversion***/**. - *DEB\_LIB\_DIR***/***shared library* The concrete file containing the shared library. It is found by following the **debian/tmp/***DEB\_LIB\_DIR***/lib***name***.so** symbolic link. - *DEB\_LIB\_DIR***/***SOname* The shared object name (*SOname*) is extracted from the binary data in the shared library, and may differ from the file name. If so, this symbolic link also refers to the *shared library* and is also installed (for ldconfig, see the Debian Policy for details). **dh\_link** later removes the redundant path components like **lib/..**. Versions before 8.1 were ignoring the SOname/Library\_Version, and guessing it from the SOversion in the Debian package name. Patches caused by this unfortunate decision can now be unapplied. ### Development package (-dev) The following files are copied from **debian/tmp/** to **debian/lib***name***/**. - *DEB\_ADA\_LIB\_INFO\_DIR***/***name***/***\****.ali** The GNAT Ada Library Information files files created along the objects when building the shared library. **dh\_fixperms** later checks that their permissions are 444. In order to improve build reproducibility, *-f\*-prefix-map* compiler flags are removed from them. - *DEB\_ADA\_SOURCE\_DIR***/***name***/***\** The sources, Ada or not, should all be in a single directory. - *DEB\_LIB\_DIR***/lib***name***.a** The static archive. - *DEB\_GNAT\_PROJECT\_DIR***/***name***.gpr** This standalone library GNAT project intended for use after installation. If the library was built with **gprbuild** and another GNAT project, the **gprinstall** tool can generate such a standalone project with the correct **Languages**, **Linker\_Switches** in the **Linker** package, imports (**with**), source file renamings... Else, the maintainer must write a new project, or more accurately generate it because **DEB\_HOST\_MULTIARCH** cannot be hardcoded. If so, it is recommended to also substitute the path variables set by **/usr/share/ada/packaging.mk**, in case the directory structure ever has to change (again). In order to improve build reproducibility, *-f\*-prefix-map* compiler flags are removed (for examples because **gprbuild** has copied variables like **ADAFLAGS** from the build project). - *DEB\_LIB\_DIR***/lib***name***.so** The development symbolic link is installed here, but dangling because the concrete shared library is in the runtime library package. **dh\_link** later removes the redundant path components like **lib/..**. - **ada:Depends** This debhelper substitution variable is created for inclusion in the **Depends** field of the **lib***name***-dev** package in **debian/control**. Its value contains the following dependencies. - **lib***name***-***SOversion* **(= ${binary:Version})** The development package needs the same version of the runtime library package because of the dangling symbolic link. - **gnat (\>=** *DEB\_GNAT\_VERSION***), gnat (\<\<** *DEB\_GNAT\_VERSION + 1***)** The development package requires the default Ada compiler in order to ensure the compatibility with all other Ada packages. - **gnat-***DEB\_GNAT\_VERSION***-***HASH* This virtual package reflects the (host) version of the run-time library used during the build. More items are added as described in the next sections in order to reflect the dependencies across Ada library packages. - **ada:Provides** This debhelper substitution variable is created for inclusion in the **Provides** field of the **lib***name***-dev** package in **debian/control**. It only contains **lib***name***-dev-***HASH*, where *HASH* is a 32 bit XOR of all checksums in the **.ali** files (8 lowercase hexadecimal digits). - Imported projects In addition, **dh\_ada\_library** searches **debian/tmp/***DEB\_GNAT\_PROJECT\_DIR***/***name***.gpr** for imported projects (**with**). For each imported library project *dep***.gpr**, a dependency is added into **ada:Depends**. If **lib***dep***-dev** is built from the same source package, the dependency is **lib***dep***-dev (= ${binary:Version})**, ensuring that all static libraries are compiled with compatible options. Such a restriction is more specific than a hash suffix. If **lib***dep***-dev** is not built from the same source but is installed on the system, in other words if it is listed in **Build-Depends**, the dependency is on the **lib***dep***-dev-***hash* virtual package provided by the installed concrete **lib***dep***-dev**. It prevents later installation of an update of **lib***dep***-dev** modifying its ALI checksums. Remaining projects trigger a warning, because the maintainer will need to find the right dependency. Versions before 8.1 were guessing more dependencies from **Linker'Linker\_Options**. This was often wrong, for no benefit since C -dev packages carry no version and can be hard-coded in **debian/control**. ### Files that are not installed The following files, if they exist under **debian/tmp/**, are ignored but marked as installed by **dh\_ada\_library** in order to prevent a false alert by **dh\_missing** later, as if the files were listed in **debian/not-installed**. - **usr/unwantedly\_gprinstalled/** Please refer to **/usr/share/ada/packaging.mk**. - *DEB\_LIB\_DIR***/lib***name***.la** The Debian Policy recommends not to install libtool **.la** files. ## REMARKS It would be easy to fix the directory structure, and versions before 8.1 were doing exactly this, at the cost of generating a project with different paths. Now that gprinstall is almost capable of dealing with stagged installs, duplicating its job seems a waste of energy. For now, *DEB\_ADA\_SOURCE\_DIR* and *DEB\_GNAT\_PROJECT\_DIR* are under **/usr/share/ada/**. 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*. ## OPTIONS Common debhelper command line options and environment variables are recognized. - **--export-versions** This option is intended for support of **packaging.mk**. Print Makefile definitions for the variables described in it. ## EXAMPLES This stanza in **debian/rules** may help debugging. ``` override_dh_ada_library: dh_ada_library -v" ``` ## 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)](/debhelper/7.md), [**deb-substvars**(5)](/deb-substvars/5.md), the **Debian Policy** at \, the **Debian Policy for Ada** at \, and the documentation of GNAT project tools installed into **/usr/share/doc/gprbuild** by the gprbuild-doc package. ## AUTHOR Nicolas Boulenguez \