dh_fortran_lib - Fortran library installation support

Authors

       Alastair McKinstry <mckinstry@debian.org>

       Lots of code stolen shamelessly from dh_install (Joey  Hess  <joeyh@debian.org>  and  Sébastien  Villemot
       <sebastien@debian.org>).

dh_fortran_lib v0.43                               2025-02-24                                  DH_FORTRAN_LIB(1)

Description

dh_fortran_lib 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.

       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.

       dh_fortran_lib makes this possible without changes being necessary to the upstream library code.

       It does this by renaming a library, for example:

               $(LIBDIR)/libfiat.so.1.2 => $(LIBDIR)/libfiat-gfortran.so.1.2
       =back

       Symlinks also get renamed:

               $(LIBDIR)/libfiat.so.1 => $(LIBDIR)/libfiat-gfortran.so.1

       A per-flavor compilation link is added:
             $(LIBDIR)/fortran/gfortran/libfiat.so -> $(LIBDIR)/libfiat-gfortran.so.1.2

       and the SONAME in the ELF file is changed:

               $ 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]

       For static files, we  just rename and add symlinks:

               $(LIBDIR)/libfiat.a => $(LIBDIR)/libfiat-gfortran.a

               $(LIBDIR)/fortran/gfortran/libfiat.a => $(LIBDIR)/libfiat-gfortran.a

       The consequence of this is that any library that builds against libfiat with appropriate search paths set
       will use libfiat-gfortran instead. This enables parallel builds with multiple compiler flavors to be
       installed simultaneously.

Name

       dh_fortran_lib - Fortran library installation support

Options

--flavor=dir =item --sourcedir=dir =item -n, --no-orig-library
           Look in the specified directory for files to be installed.

           --no-orig-library  adds the library name (with default path) to the list of files not to be installed
           by debhelper.

Synopsis

dh_fortran_lib [debhelperoptions] --flavor=flavor [--sourcedir=dir] [--no-orig-library]
       [--no-create-in-sourcedir] [libnamedestination ...]

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

Usage

       The expected usage is that this will be called in debian/rules as:

               dh_fortran_lib --flavor=$(FLAVOR) $(BUILDDIR)/XXX/libfiat-gfortran.so.1

       The files are installed in the sourcedir (usually debian/tmp) by default.