path: root/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.
@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 ---------------------------------------------------------------------
@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