.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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_FORTRAN_LIB 1"
.TH DH_FORTRAN_LIB 1 2024-02-05 "dh_fortran_lib v0.39" dh-fortran-lib
.\" 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_fortran_lib \- Fortran library installation support
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBdh_fortran_lib\fR
[\fIdebhelper\ options\fR]
\&\fB\-\-flavor=\fR\fIflavor\fR
[\fB\-\-sourcedir=\fR\fIdir\fR]
[\fB\-\-no\-orig\-library\fR]
[\fB\-\-no\-create\-in\-sourcedir\fR] 
[\fIlibname\fR\ \fIdestination\fR\ ...]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBdh_fortran_lib\fR is a debhelper program that enables multiple compiler flavous of a Fortran library
to be installed in parallel by mangling the library filename and SONAME.
.PP
Fortran libraries compiled by different compilers are not expected to be ABI-compatible, and hence
for multiple compilers to be supported simultaneously the libraries must be named differently,
and shared libraries need to include the  compiler flavor in the SONAME.
.PP
\&\fBdh_fortran_lib\fR makes this possible without changes being necessary to the upstream library code.
.PP
It does this by renaming a library, for example:
.PP
.Vb 2
\&        $(LIBDIR)/libfiat.so.1.2 => $(LIBDIR)/libfiat\-gfortran.so.1.2
\&=back
.Ve
.PP
Symlinks also get renamed:
.PP
.Vb 1
\&        $(LIBDIR)/libfiat.so.1 => $(LIBDIR)/libfiat\-gfortran.so.1
.Ve
.PP
A per-flavor compilation link is added:
 	$(LIBDIR)/fortran/gfortran/libfiat.so \-> $(LIBDIR)/libfiat\-gfortran.so.1.2
.PP
and the SONAME in the ELF file is changed:
.PP
.Vb 4
\&        $ readelf \-a $(LIBDIR)/libfiat.so.1.2 | grep SONAME
\&                0x000000000000000e (SONAME)             Library soname: [libfiat.so.1]
\&        $ readelf \-a $(LIBDIR)/libfiat\-gfortran.so.1.2 | grep SONAME
\&                0x000000000000000e (SONAME)             Library soname: [libfiat\-gfortran.so.1]
.Ve
.PP
For static files, we  just rename and add symlinks:
.PP
.Vb 1
\&        $(LIBDIR)/libfiat.a => $(LIBDIR)/libfiat\-gfortran.a
\&
\&        $(LIBDIR)/fortran/gfortran/libfiat.a => $(LIBDIR)/libfiat\-gfortran.a
.Ve
.PP
The consequence of this is that any library that builds against \fIlibfiat\fR with appropriate search paths
set will use \fIlibfiat-gfortran\fR instead. This enables parallel builds with multiple compiler flavors to
be installed simultaneously.
.SH USAGE
.IX Header "USAGE"
The expected usage is that this will be called in debian/rules as:
.PP
.Vb 1
\&        dh_fortran_lib \-\-flavor=$(FLAVOR) $(BUILDDIR)/XXX/libfiat\-gfortran.so.1
.Ve
.PP
The files are installed in the sourcedir (usually debian/tmp) by default.
.SH OPTIONS
.IX Header "OPTIONS"
.IP "\fB\-\-flavor=\fRdir =item \fB\-\-sourcedir=\fR\fIdir\fR =item \fB\-n\fR, \fB\-\-no\-orig\-library\fR" 4
.IX Item "--flavor=dir =item --sourcedir=dir =item -n, --no-orig-library"
Look in the specified directory for files to be installed.
.Sp
\&\fB\-\-no\-orig\-library\fR adds the library name (with default path) to the list of files not to be installed
by debhelper.
.SH TODO
.IX Header "TODO"
(1) Do we really want to support \-\-no\-orig\-library, blocking install of unmangled library ?
(2) 2 install variants;
   dh_fortran_lib \-\-flavor=F LIBBDIR/libfiat.so.4.1
   # installs in debian/tmp ; simplest
   dh_fortran_lib \-p libfiat-dev LIBBDIR/libfiat.so.4.1
(3) what about reading .fortran\-lib files? ugly build-paths messy to include in these
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdebhelper\fR\|(7)
.SH AUTHORS
.IX Header "AUTHORS"
Alastair McKinstry <mckinstry@debian.org>
.PP
Lots of code stolen shamelessly from dh_install (Joey Hess <joeyh@debian.org> and Sébastien Villemot <sebastien@debian.org>).