Module "header" in Fortran

Question

I have a module containing API of a library, for example

module external_api
   public :: func1
   private
   ...
contains 
   function func1(arg1, arg2) result (r)
   type(api_type1), intent(in) :: arg1
   integer, intent(out) :: arg2
   type(api_type2) :: r
   ...
   end function func1
   ...
end module

The API functions will be called from 3rd party code, but I do not want to show/expose source code of the library.

In C language I would simply provide a header file with the declarations plus compiled library. In Fortran I provide compiled .mod file and compiled library. But the .mod file is a binary format, so one cannot "read" declarations of functions.

What is the best practice for API function declarations from a closed-source Fortran library?

Answer 1

Fortran language does not have a concept of header files with declarations. Problem with shipping compiled modules is that they are binary and (frequently) compiler-specific. Moreover the individual function signatures are not visible from the .mod file and need to be documented

Most portable way for libraries is to use modules only internally and create the entry points as external functions for which interface blocks are available.

Another possibility is to supply source code of module containing external API.

Answer 2

Expanding on my comment, in case you want to accept it.

I am a big fan of

• documenting the code
• creating man pages

So I am going to suggest you use some tool like doxygen or ROBODoc where you can write your API within the source code then automatically create a man-page.

I stress documenting the API within the code, as having to document it in another file/location never works out in practice. As people are lazy and won't be bothered (even if they do initially, over time laziness creeps in). If it is in the source right where the routines are, you'll have a greater chance that it's kept up to date.

Doxygen can create all different types of output. HTML is it's most supported and refined. The man-pages are ok, but brilliant (just be warned). So you should figure out how you are going to present the API to users.

Another thing that is relevant, doxygen has a \internal keyword, to indicate that it is part of an internal use only, which is helpful if you do not want to expose everything in your library. Yet keeping one style/processing method to create all your documentation.

Answer 3

It's a problem... we have module libquadmath0 in fortran for fork with 16 byte floating point format values. It's a float128 type. So I want to use it in C programs. But can't... I have no other modules like that only fortran. If i want to work in fortran i needn't this module because of if fortran presents support of this type any you needn't this module. So you may use it without problems. Calculations we may do immediately no other needn't. But if you want read|write string you may call fortran read write command. It's supported. So fortran string like pascal it's not the same C-string. You need convert. The deal is that... So there is many functions with float128 type. here are no support but in fortran are. Another way to write this module manually in assembler. Set flags co-processor you get desired behavior. But you don't get convert to string functions. Unfortunatelly not all OS Linux has this module in C support. It's OpenSuse Leap 15.0 no support. May be thumblrweed too. I don't test x586 architecture but x86_64 no. Fedora and some others is. But in version OS Linux is some dolphin dsiadvantages. You may use gmp lib. There are no problems. But is bad solution so no reason use special lib for co-processor supported type.