What are the versioning/dev rules of stdlib?

[davidpfister]

IMO, to your first comment I would say yes. Minor and patch updates do not change the API (at least) and you should be able to swap the files (or binaries). I cannot answer for the ABI stability since I do not have that constraint.
Regarding the second point, I am not sure you will find a general answer. The point is more to clearly state that a function is obsolete and have clear rules about the removal of deprecated features. Since it is a breaking change, then, the function could be maintained until the current+n major releases. Hence, it become important to notify the end-user about this (in the doc, in the code and ideally in the compiler output) and give it enough time to make the change.

[ivanpribec]

@davidpfister

The point is more to clearly state that a function is obsolete and have clear rules about the removal of deprecated features. Since it is a breaking change, then, the function could be maintained until the current+n major releases. Hence, it become important to notify the end-user about this (in the doc, in the code and ideally in the compiler output) and give it enough time to make the change.

GCC offers a deprecated attribute:

module a
contains
subroutine foo
!GCC$ ATTRIBUTES DEPRECATED :: FOO
print *, "Don't call me."
end subroutine
end module

use a, only: foo
call foo
end

that shows a message when compiled

/app/example.f90:10:8:

   10 | call foo
      |        1
Warning: Using subroutine 'foo' at (1) is deprecated [-Wdeprecated-declarations]
Compiler returned: 0

I never checked if other Fortran compilers also support this.

[davidpfister]

Intel has the MESSAGE directive:

!DIR$ MESSAGE:'OBSOLETE(foo). The function is superseded by "bar": in file __FILE__, line __LINE__ '
subroutine foo
print *, "Don't call me."
end subroutine

That gives the following

OBSOLETE(foo). The function is superseded by "bar": in file "RunFile.f90", line 52

But the message can be adapted to give the same as gfortran

[PierU]

@FedericoPerini

Thank you for sharing all these pieces of information, it’s very interesting to understand how libraries (and their versions) are handled in an industrial environment and I would like to summarize more.

I can’t speak for everyone, not all “industrial” environments are the same. Our have specific constraints, that should not to be taken as a general case.

@FedericoPerini

do you assume that whatever minor or patch updates do not change either ABI or API (and Fortran module files, I would say)? So that you can basically just hot swap the library file?

Essentially, yes.

@FedericoPerini

when a function changes signature (i.e. getline → get_line), for how long is the old version expected to be maintained, before it can actually be removed from the library?

In our case the answer is quite simple : “indefinitely”. Eventually, the old function may no longer be used at a point, and it could be then removed. But it can take 10 years, 20 years… We still have 40 years old pieces of code that are still used.

Assuming that stdlib (or any other external library) is integrated and has breaking changes at a major version, the new major version has to be integrated as if it was a new and different library, and the previous major version has to be kept as is. This also means that the public names must differ (for a library with fortran modules, a solution is to append the major version number to the global prefix: stdlib1, stdlib2…).

@ivanpribec

Unless you want to limit yourself to the Fortran subset (or shall I say FORTRAN subset) included in the System V ABI (https://refspecs.linuxbase.org/elf/x86_64-abi-0.99.pdf), ABI stability is not very practical. Essentially it prevents you from using any of the advanced array features (assumed-shape arguments, assumed-rank arguments, elemental functions, …). When you do use these things, the ABI is vendor-specific (each use a different dope vector struct for instance).

Right. We have major versions of our software every 4 years. Each major version is supported up to 10 years, with corrective + evolutive maintenance. A given major version has a tighly fixed environment: fixed OS version, and fixed compiler version, which are used during the entire lifetime of the major sofware version (we are still supporting a version using Debian 7 and ifort 14… although it receives only corrective patches now).

Thanks to the fixed compiler version, we assume that the ABI doesn’t change as long as the definitions of the public objects don’t change in the source code.

[certik]

@PierU

In our case the answer is quite simple : “indefinitely”. Eventually, the old function may no longer be used at a point, and it could be then removed. But it can take 10 years, 20 years… We still have 40 years old pieces of code that are still used.

Assuming that stdlib (or any other external library) is integrated and has breaking changes at a major version, the new major version has to be integrated as if it was a new and different library, and the previous major version has to be kept as is. This also means that the public names must differ (for a library with fortran modules, a solution is to append the major version number to the global prefix: stdlib1, stdlib2…).

I think we should never change the API once we declare it “stable”, in other words, we should never increase the major version of stdlib.

Regarding patch part of the version, the API should not change at all (just some function bodies change, or some new functions are added that are private to a module).

Regarding the minor part of the version: I think adding an optional argument (that if not present will not change current behavior) should be ok. Or adding more methods to a class, or adding more members to a struct (derived type). So the user code does not need to be changed, so the API is backwards compatible. But the ABI changes (a struct got bigger, or a function has more optional arguments), so things have to be recompiled. @PierU what do you think?

[PierU]

@certik

Regarding the minor part of the version: I think adding an optional argument (that if not present will not change current behavior) should be ok. Or adding more methods to a class, or adding more members to a struct (derived type). So the user code does not need to be changed, so the API is backwards compatible. But the ABI changes (a struct got bigger, or a function has more optional arguments), so things have to be recompiled. @PierU what do you think?

If you ask me, I would be much more conservative : within a major version, no modification at all of the existing public derived types (that means the components AND the type-bound functions, be they public or private) and of the argument lists of the existing public functions/subroutines, even if it does not break the API.

But I’m pretty sure it’s a “lost battle”, as most of users are probably OK with the approach you are describing. Obviously, libraries exposing modules are not meant to be distributed in binary form…

[septc]

Though only a workaround, is it possibly an option to write some wrapper (intermediate layer) API code for in-house use and use an external library such as stdlib as an internal implementation for that wrapper API (to keep ABI stable)?

[PierU]

@septc

Though only a workaround, is it possibly an option to write some wrapper (intermediate layer) API code for in-house use and use an external library such as stdlib as an internal implementation for that wrapper API (to keep ABI stable)?

Yes… It would be tedious for a large library, though.

The other workaround is to not update it once integrated, and do the maintenance by ourselves.