Subversion Repositories openrisc

\input texinfo  @c -*-texinfo-*-

@c %**start of header

@setfilename gfc-internals.info

@set copyrights-gfortran 2007, 2008, 2009

@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.2 or

any later version published by the Free Software Foundation; with the

Invariant Sections being ``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

* Object Orientation::     Internals of Fortran 2003 OOP features.

* 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 flavor 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.

A special case of function calls are ``component calls'' to type-bound

procedures; those have the @code{expr_type} @code{EXPR_COMPCALL} with

@code{value.compcall} containing the argument list and the procedure called,

while @code{symtree} and @code{ref} describe the object on which the procedure

was called in the same way as a @code{EXPR_VARIABLE} expression would.

@xref{Type-bound Procedures}.

@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 F2003 OOP

@c ---------------------------------------------------------------------

@node Object Orientation

@chapter Internals of Fortran 2003 OOP Features

@menu

* Type-bound Procedures:: Type-bound procedures.

* Type-bound Operators::  Type-bound operators.

@end menu

@c Type-bound procedures

@c ---------------------

@node Type-bound Procedures

@section Type-bound Procedures

Type-bound procedures are stored in the @code{tb_sym_root} of the namespace

@code{f2k_derived} associated with the derived-type symbol as @code{gfc_symtree}

nodes.  The name and symbol of these symtrees corresponds to the binding-name

of the procedure, i.e. the name that is used to call it from the context of an

object of the derived-type.

In addition, this type of symtrees stores in @code{n.tb} a struct of type

@code{gfc_typebound_proc} containing the additional data needed:  The

binding attributes (like @code{PASS} and @code{NOPASS}, @code{NON_OVERRIDABLE}

or the access-specifier), the binding's target(s) and, if the current binding

overrides or extends an inherited binding of the same name, @code{overridden}

points to this binding's @code{gfc_typebound_proc} structure.

@subsection Specific Bindings

@c --------------------------

For specific bindings (declared with @code{PROCEDURE}), if they have a

passed-object argument, the passed-object dummy argument is first saved by its

name, and later during resolution phase the corresponding argument is looked for

and its position remembered as @code{pass_arg_num} in @code{gfc_typebound_proc}.

The binding's target procedure is pointed-to by @code{u.specific}.

@code{DEFERRED} bindings are just like ordinary specific bindings, except

that their @code{deferred} flag is set of course and that @code{u.specific}

points to their ``interface'' defining symbol (might be an abstract interface)

instead of the target procedure.

At the moment, all type-bound procedure calls are statically dispatched and

transformed into ordinary procedure calls at resolution time; their actual

argument list is updated to include at the right position the passed-object

argument, if applicable, and then a simple procedure call to the binding's

target procedure is built.  To handle dynamic dispatch in the future, this will

be extended to allow special code generation during the trans-phase to dispatch

based on the object's dynamic type.

@subsection Generic Bindings

@c -------------------------

Bindings declared as @code{GENERIC} store the specific bindings they target as

a linked list using nodes of type @code{gfc_tbp_generic} in @code{u.generic}.

For each specific target, the parser records its symtree and during resolution

this symtree is bound to the corresponding @code{gfc_typebound_proc} structure

of the specific target.

Calls to generic bindings are handled entirely in the resolution-phase, where

for the actual argument list present the matching specific binding is found

and the call's target procedure (@code{value.compcall.tbp}) is re-pointed to

the found specific binding and this call is subsequently handled by the logic

for specific binding calls.

@subsection Calls to Type-bound Procedures

@c ---------------------------------------

Calls to type-bound procedures are stored in the parse-tree as @code{gfc_expr}

nodes of type @code{EXPR_COMPCALL}.  Their @code{value.compcall.actual} saves

the actual argument list of the call and @code{value.compcall.tbp} points to the

@code{gfc_typebound_proc} structure of the binding to be called.  The object

in whose context the procedure was called is saved by combination of

@code{symtree} and @code{ref}, as if the expression was of type

@code{EXPR_VARIABLE}.

For code like this:

@smallexample

CALL myobj%procedure (arg1, arg2)

@end smallexample

@noindent

the @code{CALL} is represented in the parse-tree as a @code{gfc_code} node of

type @code{EXEC_COMPCALL}.  The @code{expr} member of this node holds an

expression of type @code{EXPR_COMPCALL} of the same structure as mentioned above

except that its target procedure is of course a @code{SUBROUTINE} and not a

@code{FUNCTION}.

Expressions that are generated internally (as expansion of a type-bound

operator call) may also use additional flags and members.

@code{value.compcall.ignore_pass} signals that even though a @code{PASS}

attribute may be present the actual argument list should not be updated because

it already contains the passed-object.

@code{value.compcall.base_object} overrides, if it is set, the base-object

(that is normally stored in @code{symtree} and @code{ref} as mentioned above);

this is needed because type-bound operators can be called on a base-object that

need not be of type @code{EXPR_VARIABLE} and thus representable in this way.

Finally, if @code{value.compcall.assign} is set, the call was produced in

expansion of a type-bound assignment; this means that proper dependency-checking

needs to be done when relevant.

@c Type-bound operators

@c --------------------

@node Type-bound Operators

@section Type-bound Operators

Type-bound operators are in fact basically just @code{GENERIC} procedure

bindings and are represented much in the same way as those (see

@ref{Type-bound Procedures}).

They come in two flavours:

User-defined operators (like @code{.MYOPERATOR.})

are stored in the @code{f2k_derived} namespace's @code{tb_uop_root}

symtree exactly like ordinary type-bound procedures are stored in

@code{tb_sym_root}; their symtrees' names are the operator-names (e.g.

@samp{myoperator} in the example).

Intrinsic operators on the other hand are stored in the namespace's

array member @code{tb_op} indexed by the intrinsic operator's enum

value.  Those need not be packed into @code{gfc_symtree} structures and are

only @code{gfc_typebound_proc} instances.

When an operator call or assignment is found that can not be handled in

another way (i.e. neither matches an intrinsic nor interface operator

definition) but that contains a derived-type expression, all type-bound

operators defined on that derived-type are checked for a match with

the operator call.  If there's indeed a relevant definition, the

operator call is replaced with an internally generated @code{GENERIC}

type-bound procedure call to the respective definition and that call is

further processed.

@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