NAME

       dh_fortran_lib - Fortran library installation support

SYNOPSIS

       dh_fortran_lib [debhelper options] --flavor=flavor [--sourcedir=dir] [--no-orig-library]
       [--no-create-in-sourcedir] [libname destination ...]

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.

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.

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.

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

SEE ALSO

       debhelper(7)

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