DWARF V2 (and V2.1 Draft 4) is marginally adequate to support Fortran modules
as defined in the 1990 and 1995 standards. After reviewing the requirements,
I make a proposal for improving support.


Background
----------

Following is a somewhat abbreviated description of modules and module
references (use statements) taken from 11.3 of the 1995 Fortran standard
(which appears to be word for word identical with the 1990 standard):

    11.3 Modules

    A module contains specifications and definitions that are to be accessible
    to other program units.

        module ::= MODULE module-name
                        [ specification-part ]
                        [ module-subprogram-part ]
                   END [ MODULE [ module-name ]]

    The module name is global to the executable program.

    11.3.1 Module reference

    A USE statement specifying a module name is a module reference. At the
    time a module reference is processed, the public portions of the specified
    module must be available.

    The accessibility, public or private, of specifications and definitions
    to a scoping unit making reference to the module may be controlled in
    both the module and the scoping unit making the reference.

    11.3.2 The USE statement and use association

    The USE statement provides the means by which a scoping unit accesses
    named data objects, derived types, interface blocks, procedures, generic
    identifiers, and namelist groups in a module. The accessed entities
    have the attributes specified in the module.

    use-stmt ::=     USE module-name [ , rename-list ]
             |        USE module-name , ONLY : [ only-list ]

    rename-list ::=  local-name => use-name ,...

    only-list ::=    [ local-name => ] use-name ,...

    If a local-name appears in a rename-list or an only-list, it is the
    local name for the entity specified in the use-name; otherwise, the
    local name is the use-name.

    The USE statement without the ONLY option provides access to all the
    public entities in the specified module.

    The USE statement with the ONLY option provides access only to those
    entities that appear as use-names in the only-list.

    More than one USE statement for a given module may appear in a scoping
    unit. If one of the USE statements is without an ONLY qualifier, all
    public entities are accessible and the rename-lists and only-lists are
    interpreted as a single concatenated rename-list. If all of the USE
    statements have ONLY qualifiers, only those entities named in one or
    more of the only-lists are accessible, that is, all of the only-lists
    are treated as a single concatenated only-list.

    Note that an entity may be accessed by more than one local name.

    Examples:

        USE STATS_LIB

    provides access to all public entities in the module STATS_LIB.

        USE MATH_LIB; USE STATS_LIB, SPROD => PROD

    makes all public entities in both MATH_LIB and STATS_LIB accessible.
    If MATH_LIB contains an entity called PROD, it is accessible by its own
    name while the entity PROD of STATS_LIB is accessible by the name SPROD.

        USE STATS_LIB, ONLY: YPROD; USE STATS_LIB, ONLY: PROD

    makes entities YPROD and PROD in STATS_LIB accessible.

        USE DATA_MODULE, RENAME_A => A

    makes all entities of DATA_MODULE accessible by their declared names
    except that RENAME_A is the local name for A (A as such is not accessible).

        USE DATA_MODULE, ONLY: RENAME_A => A

    makes only the entity A of DATA_MODULE accessible using the local name
    RENAME_A.


Notes and Discussion
--------------------

Module declaration:
So far as I can determine, the existing DWARF V2 module DIE (DW_TAG_module)
is suitable for representing Fortran 90/95 modules. Moreover, I am not
aware of any DWARF limitations that would restrict the representation of
an entity within a module differently than elsewhere. (For example, the
fact that you can't specify the SAVE attribute or TARGET attribute is
equally true both inside and outside of a module declaration and therefore
not a limitation of the module entry as such.)

I intentionally skipped stating rules that determine accessibility outside
of a module. I believe that an implementation can include in a module entry
description

  - only those entities that are accessible outside, or
  - all entities, without indication of which are accessible, or
  - all entities with appropriate accessibilty attributes to indicate
    accessibility

The choice is a quality of implementation issue and not dictated by DWARF.
(This issue is no different than the corresponding issue found in C++ classes
and the same considerations apply.)

In short, I see no need for additional DWARF mechanisms to handle the
description of F90/F95 modules.

USE statements:
There appear to be three kinds of USE statement that need to be accomodated:

  1) USE-with-only-list
  2) USE-all-entities-as-is
  3) USE-all-entities-with-some-renamed (possibly all)

Let us consider each in turn:

1) The USE-with-only-list form of USE statement can be represented using
DW_TAG_imported_declaration with a DW_AT_import attribute that refers to the
imported entity, and

  - if renamed, then a DW_AT_name attribute whose value specifies the
    local name

  - otherwise, no DW_AT_name attribute (in which case the local name is
    the same as the name in the module)

(The former has no C++ equivalent, while the latter is equivalent to a C++
using declaration.)

In general, the USE statements of a module will require multiple such
imported declaration entries to represent, one for each use-name that is
made accessible.

2) The USE-all-entities-as-is form of USE statement can be represented
using DW_TAG_imported_module with a DW_AT_import attribute that refers
to the module entry and no DW_AT_name attribute.

(This is equivalent to the C++ using directive.)

(Note that the C++ namespace alias definition has no equivalent in FORTRAN
90/95.)

3) The USE-all-entities-with-some-renamed form remains. I can think of two
ways this might be handled.

  a) One is to represent this the same as a USE-with-only-list, that is, as
     a series of imported declaration entries, at least one of which does
     a renaming (if not, then case 2 would be preferred) and the rest that do
     not.

  b) Extend the DW_TAG_imported_module DIE to allow it to optionally own
     children. The cases where it has no children are already covered above.
     If there are children, they are limited only to imported declaration
     entries that do renaming.

     The conceptual model here is that DW_TAG_imported_module means "import
     everything as is" while the children, if any, provide a list of exceptions
     to that general case.

The advantage of a) is that it requires no new DWARF mechanism. The disadvantage
is that the list of imported declarations is potentially large. When a user
writes a USE-with-only-list, the list is likely to be very specific to exactly
the set of imported entities required and no more, tending to make it short.
When a user writes a USE-all-entities-with-some-renaming, the list is
potentially very large--depending on the author and/or purpose of the module
rather than the author of the unit that makes use of the module.

Note that the USE-all-entities form can also be implemented as a series of
imported declarations just as could a C++ using directive. We (the DWARF
working group) chose (in 991110.1) to introduce the DW_TAG_imported_module
entry for namespaces in large part for compactness I think and in part also
because it follows the form of the user expression in an obvious way.

These same considerations suggest that we should extend the
DW_TAG_imported_module just a bit further to allow it to express the notion
of importing everything but with some names changed.

This leads to the following

PROPOSAL
--------

Extend the DW_TAG_imported_module DIE to allow it to optionally own
children. If there are children, they are limited only to imported declaration
entries that do renaming. The owned renamings are interpreted as exceptions
to the importation of all names of a module specified by the owning
imported module entry.


EDITORIAL CONSIDERATIONS
------------------------

Regardless of the outcome of the proposal...

At present, we have a brief generic description of imported declarations
in Section 4.3 (historically motivated by Modula I suppose) and a separate
description in Section 3.2.2 that is very specific to C++. The placement
of the generic description in Chapter 4 also tends to suggest that the
import declarations are more closely related to data than to subprograms
(though this is never stated, of course).

What I would like to do is create a new Section 3.2.3 entitled "Using and
Importing Declarations" and collect all of the DW_TAG_imported_declaration,
DW_TAG_imported_module and DW_AT_import material in that one place. The
*application* of these to the representation of C++ using clauses and
Fortran USE statements can then be covered in associated italics text, more
like is characteristic of the rest of the manual.

Accepted.