Intel® Fortran Compiler Module .mod Files Version Compatibility, Part 1 of 2

Fortran Modules and Versioning

A Fortran module is a type of program unit that contains specifications of entities such as data objects, parameters, structures, procedures, and user-defined operators. These precompiled specifications and definitions can be used by one or more program units. Partial or complete access to the module entities is provided to programs by the Fortran USE statement. Typical applications of modules are the specification of global data or the specification of a derived type and its associated operations.

Modules are excellent ways to organize programs. You can set up separate modules for:

• Commonly used routines.
• Data definitions specific to certain operating systems.
• System-dependent language extensions.

In modern Fortran 2008 there is also a construct called a SUBMODULE. We will discuss SUBMODULEs in a subsequent blog (Part II).  First let us consider a module construct.  Modules can be in their own Fortran source files or can be included with other program units in a source file.  When a source file containing a module is compiled, two binary objects are created.  One binary created by the compiler when it processes a module in a source file is a module file, commonly referred to as a “.mod” file due to the file extension “.mod” used to name the created .mod file.  This module file contains binary descriptions of the public entities in the module.  There are only descriptions in .mod files. There is no executable code contained in a .mod file. In addition to the .mod file, the compiler also creates an object file.  The object file will contain any procedures contained within the module, along with any other code from procedures and data objects in that source file.

The Intel Fortran Compiler creates .mod files in an unpublished proprietary binary format. The .mod binary format used by the Intel® Fortran Compiler has had to change over time.  The binary format has had to evolve to follow changes in the Fortran language. There is no common .mod file format agreed upon by all compiler vendors and open-source projects.  This is unfortunate, as module files and objects cannot be shared across different compiler implementations.

To keep track of changes in the .mod format as it has evolved over time, the .mod file contains a version number.  This module file version refers to the version of the internal format supported in the .mod file and is in no way related to the version of the compiler.  The version number identifies what binary format was used to create the .mod file. 

As in all things related to versioning, newer compilers can use the current .mod version along with older .mod file versions (backwards compatibility).  This makes sense, as we want newer compilers to still accept .mod files created by older compilers.  However, the opposite is NOT true – you cannot take a newer .mod file and expect an old compiler to recognize the binary format. The older compiler may support an older Fortran Standard and does not have a way to process more modern data objects or abstractions contained in the newer .mod file.

How can you determine the version of an Intel Fortran created module file?  This version information is  stored in the first 2-byte integer in the first 2 bytes in an Intel Fortran created .mod file in little-endian format.  This 2-byte integer holds the module file version number.   This number is stored in the correct endian-ness of the target platform.  Currently Intel only supports little endian.  The next 2-byte integer in the .mod file is a minor version number, however, this has never been used and is set to the value "1" by default.

The Intel Fortran compiler will check the first 2-byte integer, the version of the .mod file format, and determine if it can accept and use the data contained in that .mod file.  As of this writing in May of 2024, the .mod file format created and used by Intel Fortran version 2024 is format version 13 ( 0x000d ).  This value is stored in the first byte of the .mod file.  Version 13 of the .mod file format first appeared with the Intel® Fortran Compiler version 2023.2.0.  Prior to this, the older version 12 ( 0x000c ) module file format existed in Intel Fortran 2023.1.0 and older compilers starting with Intel Fortran version 18.0.0.  As a result of the version change in compiler version 2023.2.0, any .mod files created by Intel Fortran version 2023.2 or 2024.x and newer will not be accepted and usable by any older Intel Fortran compilers.  The oldest version accepted as of this writing is version 0x0009 which was used in ifort compiler version 11.0.  No older versions are supported. 

As an example, consider the following example module contained in a source file named “sourcefile_of_module.f90” which is a Fortran source file containing a module named "name_of_actual_module":

module name_of_actual_module 
  !...this simple module has no data or contained procedures
end module name_of_actual_module

Compiling this source file produces 2 binaries:

$ ifx -c sourcefile_of_module.f90 
$ ls -1tr
sourcefile_of_module.f90
name_of_actual_module.mod
sourcefile_of_module.o

We see that the file name of the created .mod file uses the name of the module itself “name_of_actual_module”  with file extension “.mod”.  However, the object file name adopts the name of the source file, not the module file(s) contained therein.  In this example, the object file name is “name_of_source_file.o”. One other distinction between the module file and the object file is that there is one module file (.mod) created for each module in the source file whereas there is only one object file for each source file.  We can see this by adding another module to the source file "sourcefile_of_module.f90" and recompiling:

$ cat sourcefile_of_module.f90
module name_of_actual_module 
  !...this simple module has no data or contained procedures
end module name_of_actual_module
module name_of_another_module
  !...this simple module has no data or contained procedures
end module name_of_another_module


$ ifx -c sourcefile_of_module.f90 
$ ls -1tr
sourcefile_of_module.f90
name_of_actual_module.mod
name_of_another_module.mod
sourcefile_of_module.o

Notice that we only have 1 object file ( .o ) named after the source file "sourcefile_of_module" but we have 2 module files ( .mod ), one for each module in the source file.

Since the .mod file is binary, we cannot directly view the first byte of this module file.  There are many methods to view the contents of binary files.  On Windows, you can use PowerShell's Format-Hex Cmdlet or a command-line utility named 'certutil'.  On linux, the 'od' utility can be used.  As an example, we can use the ‘od’ utility on linux to view the contents of the example name_of_actual_module.mod file:

od -t x2 name_of_actual_module.mod

0000000 000d 0001 00d7 0000 0001 0000 386b 3032

0000020 3033 0039 000b 0000 05c0 0000 0000 0000

...etc...

We show only the first 32 bytes of output above, the first 32 bytes in the .mod file printed in hexadecimal.  We see '000d' as the first 2-bytes in the .mod file (in little-endian order).  This is a hexadecimal representation of decimal 13.  Thus, we know this .mod was built with an Intel Fortran compiler using module file format version 13.  In fact, this example was built with version 2024.1.0 which uses that module file format version 13.  The second 2-byte integer is '0001', the update number, which as was said has been fixed at 1 and is not used.

What happens if we use this .mod file and try to use it in a subroutine, for example?  Let's take the easy case where we use the same 2024.1.0 compiler with this modulefile (or any other compiler version that recognizes module file format 13):

$ cat use_the_module.f90
subroutine use_the_module()
 use name_of_actual_module
end subroutine use_the_module

$ ifx -c use_the_module.f90 -V
Intel(R) Fortran Compiler for applications running on Intel(R) 64, Version 2024.1.0 Build 20240308
Copyright (C) 1985-2024 Intel Corporation. All rights reserved.

 Intel(R) Fortran 24.0-1472.3
$ 

We expected this example to compile without issue.  But what happens if we use this version 13 module file with an older compiler?  As we said, Intel Fortran compilers 2023.1.0 and older only understand version 12 (or older) module file formats.  We try the 2023.1.0 compiler with this same example:

$ ifx -c use_the_module.f90 -V
Intel(R) Fortran Compiler for applications running on Intel(R) 64, Version 2023.1.0 Build 20230320
Copyright (C) 1985-2023 Intel Corporation. All rights reserved.

 Intel(R) Fortran 23.0-1474.2
use_the_module.f90(2): error #7012: The module file cannot be read.  Its format requires a more recent F90 compiler.   [NAME_OF_ACTUAL_MODULE]
 use name_of_actual_module
-----^
compilation aborted for use_the_module.f90 (code 1)

This is the error you can expect if your .mod file is too new for the older compiler you are using.

The backwards compatibility is why software developers often distribute .mod files and objects from older compiler versions. This way their users with newer compilers are able to use backwards compatibility to utilize these older binaries.  And of course their users with older compiler versions can use the files as well.

Module version history

When will Intel Fortran move to the next module file format?  As of the date of this writing, May 2024, the Intel Fortran team is actively at work implementing the Fortran 2023 standard.  It is possible there could be a need to store new information in the .mod file.  Even a small change will make the new .mod file format unreadable by older compilers and force a new version for the module file format.  And looking a few years ahead to Fortran 202y, the Standards Committee work on generics that will most likely require changes to the .mod file format.  

Author! Author!

Keep up with all the latest from the Intel Fortran team by following me on X @iCompilersRon

Ron Green #IAmIntel

 

Ron Green is manager for the Intel® Fortran Compiler development team. He is a customer advocate for Intel® Fortran and the larger Software and Advanced Technology Group (SATG) at Intel Corporation.  Ron is a moderator of the Intel Fortran Community Forum and is an Intel Developer Zone Black Belt Developer.  He has extensive experience as a Fortran developer and consultant in HPC for the past 31+ years and has been with Intel’s developer tools and compiler team for 16+ years.