2008-07-10 Daniel Kraft <d@domob.eu>

[pf3gnuchains/gcc-fork.git] / gcc / fortran / gfc-internals.texi

\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename gfc-internals.info
@set copyrights-gfortran 2007-2008

@include gcc-common.texi

@synindex tp cp

@settitle GNU Fortran Compiler Internals

@c %**end of header

@c Use with @@smallbook.

@c %** start of document

@c Cause even numbered pages to be printed on the left hand side of
@c the page and odd numbered pages to be printed on the right hand
@c side of the page.  Using this, you can print on both sides of a
@c sheet of paper and have the text on the same part of the sheet.

@c The text on right hand pages is pushed towards the right hand
@c margin and the text on left hand pages is pushed toward the left
@c hand margin.
@c (To provide the reverse effect, set bindingoffset to -0.75in.)

@c @tex
@c \global\bindingoffset=0.75in
@c \global\normaloffset =0.75in
@c @end tex

@copying
Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'' and ``Funding
Free Software'', the Front-Cover
texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
``GNU Free Documentation License''.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@end copying

@ifinfo
@dircategory Software development
@direntry
* gfortran: (gfortran).                  The GNU Fortran Compiler.
@end direntry
This file documents the internals of the GNU Fortran
compiler, (@command{gfortran}).

Published by the Free Software Foundation
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301 USA

@insertcopying
@end ifinfo


@setchapternewpage odd
@titlepage
@title GNU Fortran Internals
@versionsubtitle
@author The @t{gfortran} team
@page
@vskip 0pt plus 1filll
Published by the Free Software Foundation@*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@c Last printed ??ber, 19??.@*
@c Printed copies are available for $? each.@*
@c ISBN ???
@sp 1
@insertcopying
@end titlepage

@summarycontents
@contents

@page

@c ---------------------------------------------------------------------
@c TexInfo table of contents.
@c ---------------------------------------------------------------------

@ifnottex
@node Top
@top Introduction
@cindex Introduction

This manual documents the internals of @command{gfortran}, 
the GNU Fortran compiler.

@ifset DEVELOPMENT
@emph{Warning:} This document, and the compiler it describes, are still
under development.  While efforts are made to keep it up-to-date, it might
not accurately reflect the status of the most recent GNU Fortran compiler.
@end ifset

@comment
@comment  When you add a new menu item, please keep the right hand
@comment  aligned to the same column.  Do not use tabs.  This provides
@comment  better formatting.
@comment
@menu
* Introduction::           About this manual.
* User Interface::         Code that Interacts with the User.
* Frontend Data Structures::
                           Data structures used by the frontend
* LibGFortran::            The LibGFortran Runtime Library.
* GNU Free Documentation License::
                           How you can copy and share this manual.
* Index::                  Index of this documentation.
@end menu
@end ifnottex

@c ---------------------------------------------------------------------
@c Introduction
@c ---------------------------------------------------------------------

@node Introduction
@chapter Introduction

@c The following duplicates the text on the TexInfo table of contents.
@iftex
This manual documents the internals of @command{gfortran}, the GNU Fortran
compiler.

@ifset DEVELOPMENT
@emph{Warning:} This document, and the compiler it describes, are still
under development.  While efforts are made to keep it up-to-date, it
might not accurately reflect the status of the most recent GNU Fortran
compiler.
@end ifset
@end iftex

At present, this manual is very much a work in progress, containing 
miscellaneous notes about the internals of the compiler.  It is hoped
that at some point in the future it will become a reasonably complete
guide; in the interim, GNU Fortran developers are strongly encouraged to
contribute to it as a way of keeping notes while working on the 
compiler.


@c ---------------------------------------------------------------------
@c Code that Interacts with the User
@c ---------------------------------------------------------------------

@node User Interface
@chapter Code that Interacts with the User

@menu
* Command-Line Options::    Command-Line Options.
* Error Handling::          Error Handling.
@end menu


@c ---------------------------------------------------------------------
@c Command-Line Options
@c ---------------------------------------------------------------------

@node Command-Line Options
@section Command-Line Options

Command-line options for @command{gfortran} involve four interrelated
pieces within the Fortran compiler code.

The relevant command-line flag is defined in @file{lang.opt}, according
to the documentation in @ref{Options,, Options, gccint, GNU Compiler
Collection Internals}.  This is then processed by the overall GCC
machinery to create the code that enables @command{gfortran} and
@command{gcc} to recognize the option in the command-line arguments and
call the relevant handler function.

This generated code calls the @code{gfc_handle_option} code in
@file{options.c} with an enumerator variable indicating which option is
to be processed, and the relevant integer or string values associated
with that option flag.  Typically, @code{gfc_handle_option} uses these
arguments to set global flags which record the option states.

The global flags that record the option states are stored in the
@code{gfc_option_t} struct, which is defined in @file{gfortran.h}.
Before the options are processed, initial values for these flags are set
in @code{gfc_init_option} in @file{options.c}; these become the default
values for the options.



@c ---------------------------------------------------------------------
@c Error Handling
@c ---------------------------------------------------------------------

@node Error Handling
@section Error Handling

The GNU Fortran compiler's parser operates by testing each piece of
source code against a variety of matchers.  In some cases, if these
matchers do not match the source code, they will store an error message
in a buffer.  If the parser later finds a matcher that does correctly
match the source code, then the buffered error is discarded.  However,
if the parser cannot find a match, then the buffered error message is
reported to the user.  This enables the compiler to provide more
meaningful error messages even in the many cases where (erroneous)
Fortran syntax is ambiguous due to things like the absence of reserved
keywords.

As an example of how this works, consider the following line:
@smallexample
IF = 3
@end smallexample
Hypothetically, this may get passed to the matcher for an @code{IF}
statement.  Since this could plausibly be an erroneous @code{IF}
statement, the matcher will buffer an error message reporting the
absence of an expected @samp{(} following an @code{IF}.  Since no
matchers reported an error-free match, however, the parser will also try
matching this against a variable assignment.  When @code{IF} is a valid
variable, this will be parsed as an assignment statement, and the error
discarded.  However, when @code{IF} is not a valid variable, this
buffered error message will be reported to the user.

The error handling code is implemented in @file{error.c}.  Errors are
normally entered into the buffer with the @code{gfc_error} function.
Warnings go through a similar buffering process, and are entered into
the buffer with @code{gfc_warning}.  There is also a special-purpose
function, @code{gfc_notify_std}, for things which have an error/warning
status that depends on the currently-selected language standard.

The @code{gfc_error_check} function checks the buffer for errors,
reports the error message to the user if one exists, clears the buffer,
and returns a flag to the user indicating whether or not an error
existed.  To check the state of the buffer without changing its state or
reporting the errors, the @code{gfc_error_flag_test} function can be
used.  The @code{gfc_clear_error} function will clear out any errors in
the buffer, without reporting them.  The @code{gfc_warning_check} and
@code{gfc_clear_warning} functions provide equivalent functionality for
the warning buffer.

Only one error and one warning can be in the buffers at a time, and
buffering another will overwrite the existing one.  In cases where one
may wish to work on a smaller piece of source code without disturbing an
existing error state, the @code{gfc_push_error}, @code{gfc_pop_error},
and @code{gfc_free_error} mechanism exists to implement a stack for the
error buffer.

For cases where an error or warning should be reported immediately
rather than buffered, the @code{gfc_error_now} and
@code{gfc_warning_now} functions can be used.  Normally, the compiler
will continue attempting to parse the program after an error has
occurred, but if this is not appropriate, the @code{gfc_fatal_error}
function should be used instead.  For errors that are always the result
of a bug somewhere in the compiler, the @code{gfc_internal_error}
function should be used.

The syntax for the strings used to produce the error/warning message in
the various error and warning functions is similar to the @code{printf}
syntax, with @samp{%}-escapes to insert variable values.  The details,
and the allowable codes, are documented in the @code{error_print}
function in @file{error.c}.

@c ---------------------------------------------------------------------
@c Frontend Data Structures
@c ---------------------------------------------------------------------

@node Frontend Data Structures
@chapter Frontend Data Structures
@cindex data structures

This chapter should describe the details necessary to understand how
the various @code{gfc_*} data are used and interact.  In general it is
advisable to read the code in @file{dump-parse-tree.c} as its routines
should exhaust all possible valid combinations of content for these
structures.

@menu
* gfc_code:: Representation of Executable Statements.
* gfc_expr:: Representation of Values and Expressions.
@end menu


@c gfc_code
@c --------

@node gfc_code
@section @code{gfc_code}
@cindex statement chaining
@tindex @code{gfc_code}
@tindex @code{struct gfc_code}

The executable statements in a program unit are represented by a
nested chain of @code{gfc_code} structures.  The type of statement is
identified by the @code{op} member of the structure, the different
possible values are enumerated in @code{gfc_exec_op}.  A special
member of this @code{enum} is @code{EXEC_NOP} which is used to
represent the various @code{END} statements if they carry a label.
Depending on the type of statement some of the other fields will be
filled in.  Fields that are generally applicable are the @code{next}
and @code{here} fields.  The former points to the next statement in
the current block or is @code{NULL} if the current statement is the
last in a block, @code{here} points to the statement label of the
current statement.

If the current statement is one of @code{IF}, @code{DO}, @code{SELECT}
it starts a block, i.e.@: a nested level in the program.  In order to
represent this, the @code{block} member is set to point to a
@code{gfc_code} structure whose @code{next} member starts the chain of
statements inside the block; this structure's @code{op} member should be set to
the same value as the parent structure's @code{op} member.  The @code{SELECT}
and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF}
and @code{ELSE} blocks or the various @code{CASE}s, respectively).  These chains
are linked-lists formed by the @code{block} members.

Consider the following example code:

@example
IF (foo < 20) THEN
  PRINT *, "Too small"
  foo = 20
ELSEIF (foo > 50) THEN
  PRINT *, "Too large"
  foo = 50
ELSE
  PRINT *, "Good"
END IF
@end example

This statement-block will be represented in the internal gfortran tree as
follows, were the horizontal link-chains are those induced by the @code{next}
members and vertical links down are those of @code{block}. @samp{==|} and
@samp{--|} mean @code{NULL} pointers to mark the end of a chain:

@example
... ==> IF ==> ...
        |
        +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==|
             |
             +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==|
                  |
                  +--> ELSE ==> PRINT *, "Good" ==|
                       |
                       +--|
@end example


@subsection IF Blocks

Conditionals are represented by @code{gfc_code} structures with their
@code{op} member set to @code{EXEC_IF}.  This structure's @code{block}
member must point to another @code{gfc_code} node that is the header of the
if-block.  This header's @code{op} member must be set to @code{EXEC_IF}, too,
its @code{expr} member holds the condition to check for, and its @code{next}
should point to the code-chain of the statements to execute if the condition is
true.

If in addition an @code{ELSEIF} or @code{ELSE} block is present, the
@code{block} member of the if-block-header node points to yet another
@code{gfc_code} structure that is the header of the elseif- or else-block.  Its
structure is identical to that of the if-block-header, except that in case of an
@code{ELSE} block without a new condition the @code{expr} member should be
@code{NULL}.  This block can itself have its @code{block} member point to the
next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.


@subsection Loops

@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their
@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and
to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks.
Their @code{block} member should point to a @code{gfc_code} structure heading
the code-chain of the loop body; its @code{op} member should be set to
@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively.

For @code{DO WHILE} loops, the loop condition is stored on the top
@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are
simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in
the internal representation.

Similarly, @code{DO} loops with an iterator have instead of the condition their
@code{ext.iterator} member set to the correct values for the loop iterator
variable and its range.


@subsection @code{SELECT} Statements

A @code{SELECT} block is introduced by a @code{gfc_code} structure with an
@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression
to evaluate and test.  Its @code{block} member starts a list of @code{gfc_code}
structures linked together by their @code{block} members that stores the various
@code{CASE} parts.

Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too,
its @code{next} member points to the code-chain to be executed in the current
case-block, and @code{extx.case_list} contains the case-values this block
corresponds to.  The @code{block} member links to the next case in the list.


@c gfc_expr
@c --------

@node gfc_expr
@section @code{gfc_expr}
@tindex @code{gfc_expr}
@tindex @code{struct gfc_expr}

Expressions and ``values'', including constants, variable-, array- and
component-references as well as complex expressions consisting of operators and
function calls are internally represented as one or a whole tree of
@code{gfc_expr} objects.  The member @code{expr_type} specifies the overall
type of an expression (for instance, @code{EXPR_CONSTANT} for constants or
@code{EXPR_VARIABLE} for variable references).  The members @code{ts} and
@code{rank} as well as @code{shape}, which can be @code{NULL}, specify
the type, rank and, if applicable, shape of the whole expression or expression
tree of which the current structure is the root.  @code{where} is the locus of
this expression in the source code.

Depending on the flavour of the expression being described by the object
(that is, the value of its @code{expr_type} member), the corresponding structure
in the @code{value} union will usually contain additional data describing the
expression's value in a type-specific manner.  The @code{ref} member is used to
build chains of (array-, component- and substring-) references if the expression
in question contains such references, see below for details.


@subsection Constants

Scalar constants are represented by @code{gfc_expr} nodes with their
@code{expr_type} set to @code{EXPR_CONSTANT}.  The constant's value shall
already be known at compile-time and is stored in the @code{logical},
@code{integer}, @code{real}, @code{complex} or @code{character} struct inside
@code{value}, depending on the constant's type specification.


@subsection Operators

Operator-expressions are expressions that are the result of the execution of
some operator on one or two operands.  The expressions have an @code{expr_type}
of @code{EXPR_OP}.  Their @code{value.op} structure contains additional data.

@code{op1} and optionally @code{op2} if the operator is binary point to the
two operands, and @code{operator} or @code{uop} describe the operator that
should be evaluated on these operands, where @code{uop} describes a user-defined
operator.


@subsection Function Calls

If the expression is the return value of a function-call, its @code{expr_type}
is set to @code{EXPR_FUNCTION}, and @code{symtree} must point to the symtree
identifying the function to be called.  @code{value.function.actual} holds the
actual arguments given to the function as a linked list of
@code{gfc_actual_arglist} nodes.

The other members of @code{value.function} describe the function being called
in more detail, containing a link to the intrinsic symbol or user-defined
function symbol if the call is to an intrinsic or external function,
respectively.  These values are determined during resolution-phase from the
structure's @code{symtree} member.


@subsection Array- and Structure-Constructors

Array- and structure-constructors (one could probably call them ``array-'' and
``derived-type constants'') are @code{gfc_expr} structures with their
@code{expr_type} member set to @code{EXPR_ARRAY} or @code{EXPR_STRUCTURE},
respectively.  For structure constructors, @code{symtree} points to the
derived-type symbol for the type being constructed.

The values for initializing each array element or structure component are
stored as linked-list of @code{gfc_constructor} nodes in the
@code{value.constructor} member.


@subsection Null

@code{NULL} is a special value for pointers; it can be of different base types.
Such a @code{NULL} value is represented in the internal tree by a
@code{gfc_expr} node with @code{expr_type} @code{EXPR_NULL}.  If the base type
of the @code{NULL} expression is known, it is stored in @code{ts} (that's for
instance the case for default-initializers of @code{ALLOCATABLE} components),
but this member can also be set to @code{BT_UNKNOWN} if the information is not
available (for instance, when the expression is a pointer-initializer
@code{NULL()}).


@subsection Variables and Reference Expressions

Variable references are @code{gfc_expr} structures with their @code{expr_type}
set to @code{EXPR_VARIABLE}; their @code{symtree} should point to the variable
that is referenced.

For this type of expression, it's also possible to chain array-, component-
or substring-references to the original expression to get something like
@samp{struct%component(2:5)}, where @code{component} is either an array or
a @code{CHARACTER} member of @code{struct} that is of some derived-type.  Such a
chain of references is achieved by a linked list headed by @code{ref} of the
@code{gfc_expr} node.  For the example above it would be (@samp{==|} is the
last @code{NULL} pointer):

@smallexample
EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==|
@end smallexample

If @code{component} is a string rather than an array, the last element would be
a @code{REF_SUBSTRING} reference, of course.  If the variable itself or some
component referenced is an array and the expression should reference the whole
array rather than being followed by an array-element or -section reference, a
@code{REF_ARRAY} reference must be built as the last element in the chain with
an array-reference type of @code{AR_FULL}. Consider this example code:

@smallexample
TYPE :: mytype
  INTEGER :: array(42)
END TYPE mytype

TYPE(mytype) :: variable
INTEGER :: local_array(5)

CALL do_something (variable%array, local_array)
@end smallexample

The @code{gfc_expr} nodes representing the arguments to the @samp{do_something}
call will have a reference-chain like this:

@smallexample
EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==|
EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==|
@end smallexample


@subsection Constant Substring References

@code{EXPR_SUBSTRING} is a special type of expression that encodes a substring
reference of a constant string, as in the following code snippet:

@smallexample
x = "abcde"(1:2)
@end smallexample

In this case, @code{value.character} contains the full string's data as if it
was a string constant, but the @code{ref} member is also set and points to a
substring reference as described in the subsection above.


@c ---------------------------------------------------------------------
@c LibGFortran
@c ---------------------------------------------------------------------

@node LibGFortran
@chapter The LibGFortran Runtime Library

@menu
* Symbol Versioning::    Symbol Versioning.
@end menu


@c ---------------------------------------------------------------------
@c Symbol Versioning
@c ---------------------------------------------------------------------

@node Symbol Versioning
@section Symbol Versioning
@comment Based on http://gcc.gnu.org/wiki/SymbolVersioning,
@comment as of 2006-11-05, written by Janne Blomqvist.

In general, this capability exists only on a few platforms, thus there
is a need for configure magic so that it is used only on those targets
where it is supported. 

The central concept in symbol versioning is the so-called map file,
which specifies the version node(s) exported symbols are labeled with.
Also, the map file is used to hide local symbols. 

Some relevant references:
@itemize @bullet
@item
@uref{http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html,
GNU @command{ld} manual}

@item
@uref{http://people.redhat.com/drepper/symbol-versioning, ELF Symbol
Versioning - Ulrich Depper}

@item
@uref{http://people.redhat.com/drepper/dsohowto.pdf, How to Write Shared
Libraries - Ulrich Drepper (see Chapter 3)}

@end itemize

If one adds a new symbol to a library that should be exported, the new
symbol should be mentioned in the map file and a new version node
defined, e.g., if one adds a new symbols @code{foo} and @code{bar} to
libgfortran for the next GCC release, the following should be added to
the map file: 
@smallexample
GFORTRAN_1.1 @{
    global:
        foo;
        bar;
@} GFORTRAN_1.0;
@end smallexample
@noindent
where @code{GFORTRAN_1.0} is the version node of the current release,
and @code{GFORTRAN_1.1} is the version node of the next release where
foo and bar are made available. 

If one wants to change an existing interface, it is possible by using
some asm trickery (from the @command{ld} manual referenced above): 

@smallexample
__asm__(".symver original_foo,foo@@");
__asm__(".symver old_foo,foo@@VERS_1.1");
__asm__(".symver old_foo1,foo@@VERS_1.2");
__asm__(".symver new_foo,foo@@VERS_2.0");
@end smallexample

In this example, @code{foo@@} represents the symbol @code{foo} bound to
the unspecified base version of the symbol. The source file that
contains this example would define 4 C functions: @code{original_foo},
@code{old_foo}, @code{old_foo1}, and @code{new_foo}. 

In this case the map file must contain @code{foo} in @code{VERS_1.1}
and @code{VERS_1.2} as well as in @code{VERS_2.0}.


@c ---------------------------------------------------------------------
@c GNU Free Documentation License
@c ---------------------------------------------------------------------

@include fdl.texi


@c ---------------------------------------------------------------------
@c Index
@c ---------------------------------------------------------------------

@node Index
@unnumbered Index

@printindex cp

@bye