Bug 42607 - add information about how to compile a module
Summary: add information about how to compile a module
Status: WAITING
Alias: None
Product: gcc
Classification: Unclassified
Component: fortran (show other bugs)
Version: 4.4.3
: P3 enhancement
Target Milestone: ---
Assignee: Not yet assigned to anyone
URL:
Keywords: documentation
Depends on:
Blocks:
 
Reported: 2010-01-04 13:30 UTC by Debian GCC Maintainers
Modified: 2013-06-25 18:31 UTC (History)
6 users (show)

See Also:
Host:
Target:
Build:
Known to work:
Known to fail:
Last reconfirmed: 2013-06-24 00:00:00


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Debian GCC Maintainers 2010-01-04 13:30:38 UTC
[forwarded from http://bugs.debian.org/501560]

"gfortran documentation lacks any kind of info about how to create a module .mod file. It should be quite easy to indicate that the standard gcc option -c when applied to the to-be-compiled file creates the .mod file along with the .o file."

should -c explain how a .mod file is created?

  Matthias
Comment 1 kargl 2010-01-05 05:49:04 UTC
(In reply to comment #0)
> [forwarded from http://bugs.debian.org/501560]
> 
> "gfortran documentation lacks any kind of info about how to create a module
> .mod file. It should be quite easy to indicate that the standard gcc option -c
> when applied to the to-be-compiled file creates the .mod file along with the .o
> file."
> 
> should -c explain how a .mod file is created?

IMHO, the answer is a resounding 'no.'  Adding such information
would simply add unneeded clutter to the manual, and should be
an insult to anyone that uses Fortran.

Also, the Fortran standard does not require that a .mod be created,
and with -fwhole-file it is entirely possible that gfortran 
can keep the module information in memory while compiling a
program and never emit anything.  In fact, the intrinsic
modules specified in the standard (that gfortran has implemented)
do not exist as files.  These are built on the fly.

Should we also explain to the user that 'fire is hot and water
at room temperature is wet.'?
Comment 2 Tobias Burnus 2010-01-06 14:16:13 UTC
I think a description does not belong into "man gfortran" (invoke.texi), but maybe into the general text of gfortran.texi.

I think .mod files are not obvious; the standard does not say anything about them, though (almost?) all compilers use them. On the other hand, few people seem to have problems with .mod files.

Intel has for instance the following in their manual:
http://software.intel.com/sites/products/documentation/hpc/compilerpro/en-us/fortran/lin/compiler_f/index.htm
 - and mentions it short as output files:
http://software.intel.com/sites/products/documentation/hpc/compilerpro/en-us/fortran/lin/compiler_f/bldaps_for/common/bldaps_produce_outfiles.htm

IBM mentions them shortly at
http://publib.boulder.ibm.com/infocenter/lnxpcomp/v8v101/index.jsp?topic=/com.ibm.xlf101l.doc/xlfcr/compilgpgms.htm
Comment 3 Noel Torres 2010-03-29 09:31:30 UTC
IMHO there is no need to add this to the -c section of the man page, but I think it should be added as a section in the gfortran info maual, named "Module Files". There it can be stated how -J and related flags work, and how module files are created.
Comment 4 Joost VandeVondele 2010-04-02 05:29:09 UTC
(In reply to comment #2)
> I think .mod files are not obvious; the standard does not say anything about
> them, though (almost?) all compilers use them. On the other hand, few people
> seem to have problems with .mod files.

the current Cray compiler (from cce) does not have modules, the mod info ends up in the .o files.

one thing that could be documented about the gfortran mod files is that they are left untouched if possible. We use that in our makefile to avoid recompilation cascades. This is actually an important feature for developers, since it makes gfortran much faster for development than many of the other compilers.

Furthermore, the fact that left-over mod files from older/newer gfortran compilers leads to user-visible error messages could also be worth documenting (At least state that even though .o, .a and .so files might be 'ABI-compatible' over several versions of the compiler, .mod files a specific to even a minor version of the compiler). 
Comment 5 Ralf Wildenhues 2010-04-04 08:40:23 UTC
(In reply to comment #1)
> > should -c explain how a .mod file is created?
> 
> IMHO, the answer is a resounding 'no.'  Adding such information
> would simply add unneeded clutter to the manual, and should be
> an insult to anyone that uses Fortran.

Not documenting the semantics of module files anywhere is a sure way for build tools like Automake to never get decent support for building Fortran.  As it is now, the user needs to fake dependencies manually to make up for this missing information.  (Where to put the information is another question altogether.)

> Also, the Fortran standard does not require that a .mod be created,

The Fortran standard is irrelevant for this question.  Users want 'make clean' to remove cruft that 'make' created, and you don't provide a 'gfortran --clean' to keep information about .mod files under the hood either.
Comment 6 Jerry DeLisle 2010-04-04 15:02:07 UTC
That idea of a --clean is interesting.  I can see where it would be useful to force a recompile of module files.  I am not sure what the actual flag should be. Of course one could use make to do all of this.
Comment 7 kargl 2010-04-04 20:28:20 UTC
(In reply to comment #5)
> (In reply to comment #1)
> > > should -c explain how a .mod file is created?
> > 
> > IMHO, the answer is a resounding 'no.'  Adding such information
> > would simply add unneeded clutter to the manual, and should be
> > an insult to anyone that uses Fortran.
> 
> Not documenting the semantics of module files anywhere is a sure way for build
> tools like Automake to never get decent support for building Fortran.  As it is
> now, the user needs to fake dependencies manually to make up for this missing
> information.  (Where to put the information is another question altogether.)

I don't use automake, so I really don't care what it does or does
not do.

> > Also, the Fortran standard does not require that a .mod be created,
> 
> The Fortran standard is irrelevant for this question.  Users want 'make clean'
> to remove cruft that 'make' created, and you don't provide a 'gfortran --clean'
> to keep information about .mod files under the hood either.
> 

The Fortran standard is the only thing that matters.

'make clean' does the right thing for me.  Of course,
I know how to write a Makefile without depending on
the whim (yes, I wrote whim) of the automake developers.
Comment 8 Noel Torres 2010-04-05 10:00:44 UTC
I do not care particularly about automake and such, but precisely because the Fortran standard does not say a word about module files the user expects to get info about them _for his compiler_ in _his compiler documentation_.

That's why I think we must (yes, I included myself, because I've spent so much time trying to figure out how gfortran module files work) create a documentation section for them. User has the right to know what module files are (not necessarily the internals), when they're created, where they're stored and searched for, and whether they're changed if source code change does not change the module interface.
Comment 9 nightstrike 2011-03-05 17:33:05 UTC
Any chance of this happening?
Comment 10 kargl 2011-03-05 17:57:47 UTC
(In reply to comment #9)
> Any chance of this happening?

No one who seemed to care about the issue has
stepped up with a patch.  One may then draw
the conclusion of 'no'.
Comment 11 Dominique d'Humieres 2013-06-24 20:46:22 UTC
What should we do with this PR?
Comment 12 kargl 2013-06-25 03:12:50 UTC
(In reply to Dominique d'Humieres from comment #11)
> What should we do with this PR?

See my comment #1 and #10.  I think that the PR
should be closed with WONTFIX (because gcc does not
have INDIFFERENCE).

Contributing documentation for gfortran is the
easiest way to get involved with its development.
Yet, none of the individuals, who seem to think
that .mod file creation needs to be document,
have step forward to write the doc.
Comment 13 Harald Anlauf 2013-06-25 18:31:47 UTC
Since Cray was mentioned, the Cray online documentation says:

[...]
The following files are produced by or accepted by the Cray Fortran compiler:
[...]

modulename.mod
            If the -em option is specified, the compiler writes a
            modulename.mod file for each module; modulename is created by
            taking the name of the module and, if necessary, converting it to
            uppercase. This file contains module information, including any
            contained module procedures.


I consider that an example of a reasonable documentation.

Gfortran generated module files (modulename.mod) are always lower case.
Gfortran creates a .mod file not only for -c, but also for -fsyntax-only,
and apparently always when it is presented a source file which contains
a module statement.  It should not be that difficult to put that into the
documentation.