Enable FVS executables and shared libraries to return the version and optional additional build info

[d-diaz]

Version information for each FVS variant is currently hardcoded with strings in vbase/revise.f. Each time a version is updated, these strings must be manually updated or find-replaced. The version strings also differ from the pattern for release tags used in this repo, raising potential for confusion about which version pattern is authoritative or what it refers to.

I wanted to see if you would consider a submission of a PR (to the dev branch, following the posted contribution guidelines) that would allow for the population of Fortran parameters related to versioning that could be specified as build-time arguments such as -DFVS_VERSIONTAG=FS2026.2 and -DFVS_VERSIONDATE=20260401. The desired end-state would allow for FVS to report its version and related info in a couple ways, and for these input parameters to be easily generated in an automated build workflow (e.g., results of git ... commands)

1. As a command-line tool:
   Update main.f to check if version or build-info args are passed and provide these outputs based on control flow to return early and not ask for a keyfile to run.

$ FVSpn --version
FS2025.4c (USDAForestService)

and a more detailed option

$ FVSpn --build-info
Version: FS2025.4c
Org:     USDAForestService
Remote:  https://github.com/USDAForestService/ForestVegetationSimulator
Branch:  main
Commit:  abd132
Date:    20250930

2. As new subroutines following the pattern of the FVS API which could be picked up by rFVS, fvs2py, and pyfvs wrappers.
   This could be placed in a new base/version.f which would include an FVSVERSION module that would establish all the placeholders for these build-time attributes (version, org name, repo, branch, commit hash, and date), define subroutines for fvsGetVersion and fvsGetBuildInfo and C wrappers as needed for rFVS like fvsGetVersionC and fvsGetBuildInfoC.

To minimize disruption to existing patterns that call revise.f, we could just update that file to USE FVSVERSION so that it depends on the new module, and then to retrieve the FVS_VERSIONDATE parameter if you wanted to retain the existing pattern in outfiles, etc. It would also be an option to incorporate additional or different build info into these plain text outputs if desired. The revise.f would be simplified significantly (no more SELECT CASE block).

I'd expect the PR to demonstrate a successful build on Windows and Linux with updates as necessary to the bin/makefile and the input file lists for each variant, and that CLI and wrapper API could also be demonstrated to work as expected.

[wagnerds]

Hi David,

I really like idea of adding --version and --build-info as command line options and will bring the topic to the staff.

For clarification, would the compile time flags for the version and data replace the current defining processes or would it supplement them? Would we then need to include the version and date flags every time we did a build for testing?

[d-diaz]

This shouldn't need to change any existing compile flags, it would just add new ones. However, those new compile flags would each map to parameters defined in version.f and populate their values at build-time. version.f would look something like this:

C----------
C BASE version.f
C
C Provides the FVSVERSION module, which exposes build provenance metadata
C injected at compile time via -D flags.
C
C Subroutines:
C   fvsGetVersion(version, nch)   Short version string for --version flag
C   fvsGetBuildInfo(info, nch)    Full provenance block for --build-info flag
C
C Both subroutines are also callable via the shared library API from R,
C Python, or any language with a Fortran or C FFI.
C
C All metadata can be derived from the FVS source repo.
C----------

      MODULE FVSVERSION
      IMPLICIT NONE

C     Preprocessor fallbacks for direct compilation 
C     (e.g. plain gfortran invocation or source archive builds).
C     When specified in the build script, these are overridden by -D flags.

#ifndef FVS_GIT_VERSION
#define FVS_GIT_VERSION "unknown"
#endif
#ifndef FVS_GIT_ORG
#define FVS_GIT_ORG     "unknown"
#endif
#ifndef FVS_GIT_HASH
#define FVS_GIT_HASH    "unknown"
#endif
#ifndef FVS_GIT_DATE
#define FVS_GIT_DATE    "unknown"
#endif
#ifndef FVS_GIT_BRANCH
#define FVS_GIT_BRANCH  "unknown"
#endif
#ifndef FVS_GIT_REMOTE
#define FVS_GIT_REMOTE  "unknown"
#endif

C     Named constants. CHARACTER(LEN=*) with PARAMETER lets the compiler
C     infer the exact length from the string literal — no padding, no
C     fixed-width declarations, no TRIM() required at call sites.

      CHARACTER(LEN=*), PARAMETER :: FVSVER_VERSION = FVS_GIT_VERSION
      CHARACTER(LEN=*), PARAMETER :: FVSVER_ORG     = FVS_GIT_ORG
      CHARACTER(LEN=*), PARAMETER :: FVSVER_HASH    = FVS_GIT_HASH
      CHARACTER(LEN=*), PARAMETER :: FVSVER_DATE    = FVS_GIT_DATE
      CHARACTER(LEN=*), PARAMETER :: FVSVER_BRANCH  = FVS_GIT_BRANCH
      CHARACTER(LEN=*), PARAMETER :: FVSVER_REMOTE  = FVS_GIT_REMOTE

      CONTAINS

C----------
C FVSGETVERSION -- Return the short version string.
C
C   version  (OUT) Allocatable character: "<tag> (<org>)"
C            e.g. "FS2025.4c (USDAForestService)"
C                 "FS2025.4c-4-ga4f3c12 (USDAForestService)"
C                 "FS2025.4c-dirty (USDAForestService)"
C   nch      (OUT) Length of the returned string
C
C Called by main.f for --version and by downstream API callers.
C----------

      SUBROUTINE fvsGetVersion(version, nch)
      CHARACTER(LEN=:), ALLOCATABLE, INTENT(OUT) :: version
      INTEGER,                       INTENT(OUT) :: nch

      version = FVSVER_VERSION // ' (' // FVSVER_ORG // ')'
      nch     = LEN(version)

      END SUBROUTINE fvsGetVersion

C----------
C FVSGETBUILDINFO -- Return the full provenance block.
C
C   info  (OUT) Allocatable character, newline-delimited key: value pairs:
C
C               Version: FS2025.4c
C               Org:     USDAForestService
C               Remote:  https://github.com/...
C               Branch:  main
C               Commit:  a4f3c12
C               Date:    20250930
C
C   nch   (OUT) Length of the returned string
C
C Called by main.f for --build-info and by downstream API callers.
C The field label width is padded to align values — same convention
C as `git version --build-options` and `python -VV`.
C----------

      SUBROUTINE fvsGetBuildInfo(info, nch)
      CHARACTER(LEN=:), ALLOCATABLE, INTENT(OUT) :: info
      INTEGER,                       INTENT(OUT) :: nch

      info =
     &  'Version: ' // FVSVER_VERSION // CHAR(10) //
     &  'Org:     ' // FVSVER_ORG     // CHAR(10) //
     &  'Remote:  ' // FVSVER_REMOTE  // CHAR(10) //
     &  'Branch:  ' // FVSVER_BRANCH  // CHAR(10) //
     &  'Commit:  ' // FVSVER_HASH    // CHAR(10) //
     &  'Date:    ' // FVSVER_DATE
      nch = LEN(info)

      END SUBROUTINE fvsGetBuildInfo

      END MODULE FVSVERSION

We can figure out a shell script that collects these parameters from the build environment (e.g., calling several git ... commands to identify the build context and figure out the best way to integrate that into the build process whether using makefile or Cmake.

I have a new Meson-based build process running here that I would also like to incorporate this functionality for injecting compile flags based on the code environment at build-time. Those fvs-build workflows can be called from any GH user or repo to compile binaries or make a Docker container with the Linux binaries, so could be used as an automated way y'all could trigger builds and potentially create GH releases from this repo as well (e.g., automated upon merge to main), but I would like to have a build process that could also still work by augmenting the existing makefile and potentially Cmake workflows in this repo if possible to not constrain build options further.

Then in revise.f by adding USE FVSVERSION we could then just fetch whatever metadata fields are desired to be injected into plain text files and other places where revise.f gets applied. Right now the hard-coded date string is used, but you could use one or some combination of these new fields for a more comprehensive and authoritative response.

[wagnerds]

Thanks for the additional information. I will bring it to the staff next week for discussion.

[wagnerds]

After discussing with our staff, we are amenable to the idea and would be interested in testing it in our workflow for potential incorporation. Thanks!