See /usr/share/doc/debhelper/PROGRAMMING.md on general design of debhelper.
This follows that design.

For convenience of Python code, dhfortran/debhelper.py implements Python equivalents of any Perl debhelper routines we use.

The scripts are written in Python for ease of development and testing. The package provides:
  * dh_fortran_mod: Move Fortran-module files to per-compiler directories
  * dh_fortan_lib: Ditto for libraries, but also change SONAMES
  * dh_fortran_pkgconf: rewrite pkgconfig files to match the above
  * dh_fortran: overall builder script

See manual pages for each.

TODO:
  * Clean up buildsystem/fortran.pm. Mostly unused
  * What if buildsystem == meson, cmake, ecbuild ?
    --buildsystem=fortran means using fpm.
       automatically enables --with fortran
    --with fortran will use fpm if buildsystem is not set.
 * dh_fortran_lib:
    Install ar archives correctly with multifortran, keep_orig
 * dh_fortran_mod: silence 'missing files' when running without specified pkg, path
 * Missing files handling in general: track missing files and error on failure


Targets are called with FC, FCFLAGS, FMODDIR, FC_DEFAULT, FLIBDIR set as appropriate

Set 0.80 release as having full multifortran and cross-compilation support
 * With fpm 0.13+ for multiple builddirs; meson overrides

Set 1.0 as release to remove --flavor flags. Full deprecation warnings in 0.80


DESIGN:

   dh-fortran does two things:
   1. Enable a fortran build system, using 'fpm', if --buildsystem=fortran is set
   2. Build for multiple compilers. This can be as simple as setting
   ```
	export FC_REQUIRED:= gfortran-15 flang-21
	export FC_OPTIONAL:= lfortran
   ```
   in the debian/rules. This causes multiple builds to be done in $BUILDDIR-${COMPILER_FLAVOUR}
   directory, install into their own tmpdirs and then install the additional
   libraries and module files.
   
   
HOW IT WORKS:

   In the Perl sequence/fortran.pm, the path is altered to divert to /usr/share/dh-fortran
   first. This enable dh_auto_{clean,configure,build,install,test} to be intercepted.
   In fortran-buildsystem calls, these then call "fpm" rules with appropriate
   environments set.
   For other build systems, the environment is set (eg FC=flang-21, FCFLAGS accordingly, etc)
   and builddir, tmpdir rewritten to Fortran-subdirectories as required.
   

FPM Integration:
 * dh-fortran executes fpm where fpm.toml is present and buildsystem=fortran
 *  check fortran-fpm in environment
 *  fpm search plugin for Apt/dpkg integration (?)
    fpm will use / install modules if they exist in Debian; alert missing modules
-DONE

Multicompiler builds will be triggered by:
* Presence of FC_DEFAULT, FC_OPTIONAL in the environment

* presence of *.fortran-mod or *fortran-lib files in debian

ISSUES:
 * fpm only works with one builddirectory ./build
   This will be fixed in the next release
   fpm-current works ok
 * TODO: chrpath -d * automatically for libs?


Multi-fortran decision process:
* DO a make -P | grep FC_DEFAULT, FC_OPTIONAL check. If they're defined in d/rules, then thats what sets their values
  store flags env in .debhelper/fc_env. len(FC_OPTIONAL)>=1 means multifortran build
* For the moment, FC_DEFAULT allows a single flavor
* Set BUILDDIR. TMPDIR. Will need a different TMPDIR for each of the other Fortran builds.
* for FC_DEFAULT, BUILDDIR=$(BUILDDIR), for all compilers define $(BUILDDIR)-$(FLAVOR) and for default its a  symlink to $(BUILDDIR)
* ditto $TMPDIR.
* 

Check dh-fortrans' use of source,dest etc terms correct.

* Allow FC= to be a cross-compiler, deprecate --flavor in favour of use --fc and accept aliases, but use flavor internally
  for the "canonical"

Notes:
	Dropped get_flavor(), get_fc() in favour of get_fc_flavor() which does all checking.
	Use  FC as the external API, flavor as Internal, but we should track the FC for cross-compiling:
	when --fc = other-arch-gfortran-15 , flavor=gfortran-15, but we've lost the arch.
	How about flavor, arch = get_fc_flavor_arch() ?

TODO:	
	drop get_abi_() fn internally
      * bug: 'get_env' --fc lfortran gives wrong results if lfortran not installed

TEST CASES:
	fortran-shlex:	"pure" fpm build
	fortran-cli2: fpm or meson build 
	odc:	ecbuild/cmake+makefile
	netcdf-fortran: autoconf

Issue: what if binaries in a package use the pre-adjusted sonames?
       Best if we can set the SONAME pattern at build-time


FPM Integration
export FPM_FFLAGS="-I/usr/lib/aarch64-linux-gnu/fortran/gfortran-mod-16/ -I/usr/include -cpp"

FPM notes:
From fortran-julienne: 'bin/scaffold' linked against libjulienne.so of the same build. We really need it to be built
against libjulienne-flang.so.0 from the flang build, for example: so hack the build order

