.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "DH_ADA_LIBRARY 1" .TH DH_ADA_LIBRARY 1 "2023-12-17" "9.1" "Debhelper" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" dh_ada_library \- help packaging Ada libraries for Debian .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBdh_ada_library\fR [\fIdebhelper options\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBdh_ada_library\fR is a debhelper program that handles some common tasks in packaging libraries written in the Ada programming language. .PP The difficult work is to convince the upstream build system to produce both a static and a relocatable library in a row (during the \&\fBdh_auto_configure\fR and \fBdh_auto_build\fR steps), then to install these under \fBdebian/tmp/\fR with the directory structure described by the Debian Policy for Ada (\fBdh_auto_install\fR). The \fB/usr/share/ada/packaging.mk\fR Makefile snippet, part of the same \&\fBdh-ada-library\fR package, may help for that. It contains lots of comments describing its usage. .PP Once the files are installed, \fBdh_ada_library\fR is in charge of dispatching them to the specific package temporary directories. It is enabled by the presence of the \fBdh-sequence-ada-library\fR virtual package in the \fBBuild-Depends-Arch\fR field of the \&\fBdebian/control\fR file. For a while, you should in addition depend on the explicit \&\fBdh-ada-library\fR concrete package and require at least version 9, because this version introduces incompatible changes, and virtual packages cannot receive version restrictions. .PP At start, it parses \&\fIdebian/control\fR to find Ada libraries: architecture-dependent packages, named \fBlib\fR\fIname\fR\fB\-dev\fR, depending on \fB${ada:Depends}\fR and providing \fB${ada:Provides}\fR. .PP 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 \fBlib\fR\fIname\fR\fB\-\fR\fISOversion\fR). .PP For a description of \fI\s-1DEB_HOST_MULTIARCH\s0\fR, see \&\fBdpkg\-architecture\fR\|(1). The installation directories (\fI\s-1DEB_ADA_SOURCE_DIR\s0\fR, \fI\s-1DEB_LIB_DIR\s0\fR, \fI\s-1DEB_ADA_LIB_INFO_DIR\s0\fR and \&\fI\s-1DEB_GNAT_PROJECT_DIR\s0\fR) are defined in the Debian Policy, their current values are available via \fBpackaging.mk\fR. .SS "Runtime library package" .IX Subsection "Runtime library package" The following files are copied from \fBdebian/tmp/\fR to \&\fBdebian/lib\fR\fIname\fR\fB\-\fR\fISOversion\fR\fB/\fR. .IP "\fI\s-1DEB_LIB_DIR\s0\fR\fB/\fR\fIshared library\fR" 4 .IX Item "DEB_LIB_DIR/shared library" The concrete file containing the shared library. It is found by following the \&\fBdebian/tmp/\fR\fI\s-1DEB_LIB_DIR\s0\fR\fB/lib\fR\fIname\fR\fB.so\fR symbolic link. .IP "\fI\s-1DEB_LIB_DIR\s0\fR\fB/\fR\fISOname\fR" 4 .IX Item "DEB_LIB_DIR/SOname" The shared object name (\fISOname\fR) 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 \fIshared library\fR and is also installed (for ldconfig, see the Debian Policy for details). .Sp \&\fBdh_link\fR later removes the redundant path components like \&\fBlib/..\fR. .PP 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. .SS "Development package (\-dev)" .IX Subsection "Development package (-dev)" The following files are copied from \fBdebian/tmp/\fR to \&\fBdebian/lib\fR\fIname\fR\fB/\fR. .IP "\fI\s-1DEB_ADA_LIB_INFO_DIR\s0\fR\fB/\fR\fIname\fR\fB/\fR\fI*\fR\fB.ali\fR" 4 .IX Item "DEB_ADA_LIB_INFO_DIR/name/*.ali" The \s-1GNAT\s0 Ada Library Information files files created along the objects when building the shared library. .Sp \&\fBdh_fixperms\fR later checks that their permissions are 444. .Sp In order to improve build reproducibility, \fI\-f*\-prefix\-map\fR compiler flags are removed from them. .IP "\fI\s-1DEB_ADA_SOURCE_DIR\s0\fR\fB/\fR\fIname\fR\fB/\fR\fI*\fR" 4 .IX Item "DEB_ADA_SOURCE_DIR/name/*" The sources, Ada or not, should all be in a single directory. .IP "\fI\s-1DEB_LIB_DIR\s0\fR>\fB/lib\fR\fIname\fR\fB.a\fR" 4 .IX Item "DEB_LIB_DIR>/libname.a" The static archive. .IP "\fI\s-1DEB_GNAT_PROJECT_DIR\s0\fR\fB/\fR\fIname\fR\fB.gpr\fR" 4 .IX Item "DEB_GNAT_PROJECT_DIR/name.gpr" This standalone library \s-1GNAT\s0 project intended for use after installation. .Sp If the library was built with \fBgprbuild\fR and another \s-1GNAT\s0 project, the \fBgprinstall\fR tool can generate such a standalone project with the correct \fBLanguages\fR, \fBLinker_Switches\fR in the \fBLinker\fR package, imports (\fBwith\fR), source file renamings... Else, the maintainer must write a new project, or more accurately generate it because \fB\s-1DEB_HOST_MULTIARCH\s0\fR cannot be hardcoded. If so, it is recommended to also substitute the path variables set by \&\fB/usr/share/ada/packaging.mk\fR, in case the directory structure ever has to change (again). .IP "\fI\s-1DEB_LIB_DIR\s0\fR\fB/lib\fR\fIname\fR\fB.so\fR" 4 .IX Item "DEB_LIB_DIR/libname.so" The development symbolic link is installed here, but dangling because the concrete shared library is in the runtime library package. .Sp \&\fBdh_link\fR later removes the redundant path components like \&\fBlib/..\fR. .IP "\fBada:Depends\fR" 4 .IX Item "ada:Depends" This debhelper substitution variable is created for inclusion in the \&\fBDepends\fR field of the \fBlib\fR\fIname\fR\fB\-dev\fR package in \fBdebian/control\fR. Its value contains the following dependencies. .RS 4 .IP "\fBlib\fR\fIname\fR\fB\-\fR\fISOversion\fR\fB (= ${binary:Version})\fR" 4 .IX Item "libname-SOversion (= ${binary:Version})" The development package needs the same version of the runtime library package because of the dangling symbolic link. .IP "\fBgnat\fR (>= \fI\s-1DEB_GNAT_VERSION\s0\fR, \fBgnat\fR (<< \fI\s-1DEB_GNAT_VERSION + 1\s0\fR)" 4 .IX Item "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. .IP "\fBgnat\-\fR\fI\s-1DEB_GNAT_VERSION\s0\fR\fB\-\fR\fI\s-1HASH\s0\fR" 4 .IX Item "gnat-DEB_GNAT_VERSION-HASH" This virtual package reflects the (host) version of the run-time library used during the build. .RE .RS 4 .Sp More items are added as described in the next sections in order to reflect the dependencies across Ada library packages. .RE .IP "\fBada:Provides\fR" 4 .IX Item "ada:Provides" This debhelper substitution variable is created for inclusion in the \&\fBProvides\fR field of the \fBlib\fR\fIname\fR\fB\-dev\fR package in \fBdebian/control\fR. .Sp It only contains \fBlib\fR\fIname\fR\fB\-dev\-\fR\fI\s-1HASH\s0\fR, where \fI\s-1HASH\s0\fR is a 32 bit \s-1XOR\s0 of all checksums in the \fB.ali\fR files (8 lowercase hexadecimal digits). .IP "Imported projects" 4 .IX Item "Imported projects" In addition, \fBdh_ada_library\fR searches \&\fBdebian/tmp/\fR\fI\s-1DEB_GNAT_PROJECT_DIR\s0\fR\fB/\fR\fIname\fR\fB.gpr\fR for imported projects (\fBwith\fR). For each imported library project \fIdep\fR\fB.gpr\fR, a dependency is added into \fBada:Depends\fR. .Sp If \fBlib\fR\fIdep\fR\fB\-dev\fR is built from the same source package, the dependency is \fBlib\fR\fIdep\fR\fB\-dev (= ${binary:Version})\fR, ensuring that all static libraries are compiled with compatible options. Such a restriction is more specific than a hash suffix. .Sp If \fBlib\fR\fIdep\fR\fB\-dev\fR is not built from the same source but is installed on the system, in other words if it is listed in \&\fBBuild-Depends\fR, the dependency is on the \&\fBlib\fR\fIdep\fR\fB\-dev\-\fR\fIhash\fR virtual package provided by the installed concrete \fBlib\fR\fIdep\fR\fB\-dev\fR. It prevents later installation of an update of \fBlib\fR\fIdep\fR\fB\-dev\fR modifying its \s-1ALI\s0 checksums. .Sp Remaining projects trigger a warning, because the maintainer will need to find the right dependency. .PP Versions before 8.1 were guessing more dependencies from \&\fBLinker'Linker_Options\fR. This was often wrong, for no benefit since C \-dev packages carry no version and can be hard-coded in \fBdebian/control\fR. .SS "Files that are not installed" .IX Subsection "Files that are not installed" The following files, if they exist under \fBdebian/tmp/\fR, are ignored but marked as installed by \fBdh_ada_library\fR in order to prevent a false alert by \fBdh_missing\fR later, as if the files were listed in \&\fBdebian/not\-installed\fR. .IP "\fBusr/unwantedly_gprinstalled/\fR" 4 .IX Item "usr/unwantedly_gprinstalled/" Please refer to \fB/usr/share/ada/packaging.mk\fR. .IP "\fI\s-1DEB_LIB_DIR\s0\fR\fB/lib\fR\fIname\fR\fB.la\fR" 4 .IX Item "DEB_LIB_DIR/libname.la" The Debian Policy recommends not to install libtool \fB.la\fR files. .SH "REMARKS" .IX Header "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. .PP For now, \fI\s-1DEB_ADA_SOURCE_DIR\s0\fR and \fI\s-1DEB_GNAT_PROJECT_DIR\s0\fR are under \&\fB/usr/share/ada/\fR. This implies that the \-dev package cannot be declared \&\fBMulti-Arch: same\fR as the content of the project (and maybe of generated sources) will vary across architectures. .PP The \fILinker'Linker_Options\fR attribute should rarely be needed. A dependency written in Ada should be described by an imported project, also handling \fI.ali\fR files. A dependency written in C should be listed in \fILibrary_Options\fR when building a shared library, and in \fILinker'Linker_Options\fR when using a static archive, but is not always required in \&\fILinker'Linker_Options\fR 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 \fIfoo.pc\fR file as read by \fBpkg-config\fR, they are named \&\fILibs\fR, excluding \fI\-lfoo\fR and \fILibs.private\fR. .SH "OPTIONS" .IX Header "OPTIONS" Common debhelper command line options and environment variables are recognized. .IP "\fB\-\-export\-versions\fR" 4 .IX Item "--export-versions" This option is intended for support of \fBpackaging.mk\fR. Print Makefile definitions for the variables described in it. .SH "EXAMPLES" .IX Header "EXAMPLES" This stanza in \fBdebian/rules\fR may help debugging. .PP .Vb 2 \& override_dh_ada_library: \& dh_ada_library \-v" .Ve .SH "VERSIONS" .IX Header "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 \fIoldoldstable\fR. A change in the first one announces an incompatibility requiring some users to modify their source package. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBdebhelper\fR\|(7), \&\fBdeb\-substvars\fR\|(5), the \fBDebian Policy\fR at , the \fBDebian Policy for Ada\fR at , and the documentation of \s-1GNAT\s0 project tools installed into \&\fB/usr/share/doc/gprbuild\fR by the gprbuild-doc package. .SH "AUTHOR" .IX Header "AUTHOR" Nicolas Boulenguez