From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- gcc/fortran/gfc-internals.texi | 826 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 826 insertions(+) create mode 100644 gcc/fortran/gfc-internals.texi (limited to 'gcc/fortran/gfc-internals.texi') diff --git a/gcc/fortran/gfc-internals.texi b/gcc/fortran/gfc-internals.texi new file mode 100644 index 000000000..ed4c5ed3d --- /dev/null +++ b/gcc/fortran/gfc-internals.texi @@ -0,0 +1,826 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename gfc-internals.info +@set copyrights-gfortran 2007, 2008, 2009, 2010 + +@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.3 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. + + +@subsection @code{BLOCK} and @code{ASSOCIATE} + +The code related to a @code{BLOCK} statement is stored inside an +@code{gfc_code} structure (say @var{c}) +with @code{c.op} set to @code{EXEC_BLOCK}. The +@code{gfc_namespace} holding the locally defined variables of the +@code{BLOCK} is stored in @code{c.ext.block.ns}. The code inside the +construct is in @code{c.code}. + +@code{ASSOCIATE} constructs are based on @code{BLOCK} and thus also have +the internal storage structure described above (including @code{EXEC_BLOCK}). +However, for them @code{c.ext.block.assoc} is set additionally and points +to a linked list of @code{gfc_association_list} structures. Those +structures basically store a link of associate-names to target expressions. +The associate-names themselves are still also added to the @code{BLOCK}'s +namespace as ordinary symbols, but they have their @code{gfc_symbol}'s +member @code{assoc} set also pointing to the association-list structure. +This way associate-names can be distinguished from ordinary variables +and their target expressions identified. + +For association to expressions (as opposed to variables), at the very beginning +of the @code{BLOCK} construct assignments are automatically generated to +set the corresponding variables to their target expressions' values, and +later on the compiler simply disallows using such associate-names in contexts +that may change the value. + + +@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 -- cgit v1.2.3