1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename gfc-internals.info 4@set copyrights-gfortran 2007-2013 5 6@include gcc-common.texi 7 8@synindex tp cp 9 10@settitle GNU Fortran Compiler Internals 11 12@c %**end of header 13 14@c Use with @@smallbook. 15 16@c %** start of document 17 18@c Cause even numbered pages to be printed on the left hand side of 19@c the page and odd numbered pages to be printed on the right hand 20@c side of the page. Using this, you can print on both sides of a 21@c sheet of paper and have the text on the same part of the sheet. 22 23@c The text on right hand pages is pushed towards the right hand 24@c margin and the text on left hand pages is pushed toward the left 25@c hand margin. 26@c (To provide the reverse effect, set bindingoffset to -0.75in.) 27 28@c @tex 29@c \global\bindingoffset=0.75in 30@c \global\normaloffset =0.75in 31@c @end tex 32 33@copying 34Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc. 35 36Permission is granted to copy, distribute and/or modify this document 37under the terms of the GNU Free Documentation License, Version 1.3 or 38any later version published by the Free Software Foundation; with the 39Invariant Sections being ``Funding Free Software'', the Front-Cover 40Texts being (a) (see below), and with the Back-Cover Texts being (b) 41(see below). A copy of the license is included in the section entitled 42``GNU Free Documentation License''. 43 44(a) The FSF's Front-Cover Text is: 45 46 A GNU Manual 47 48(b) The FSF's Back-Cover Text is: 49 50 You have freedom to copy and modify this GNU Manual, like GNU 51 software. Copies published by the Free Software Foundation raise 52 funds for GNU development. 53@end copying 54 55@ifinfo 56@dircategory Software development 57@direntry 58* gfortran: (gfortran). The GNU Fortran Compiler. 59@end direntry 60This file documents the internals of the GNU Fortran 61compiler, (@command{gfortran}). 62 63Published by the Free Software Foundation 6451 Franklin Street, Fifth Floor 65Boston, MA 02110-1301 USA 66 67@insertcopying 68@end ifinfo 69 70 71@setchapternewpage odd 72@titlepage 73@title GNU Fortran Internals 74@versionsubtitle 75@author The @t{gfortran} team 76@page 77@vskip 0pt plus 1filll 78Published by the Free Software Foundation@* 7951 Franklin Street, Fifth Floor@* 80Boston, MA 02110-1301, USA@* 81@c Last printed ??ber, 19??.@* 82@c Printed copies are available for $? each.@* 83@c ISBN ??? 84@sp 1 85@insertcopying 86@end titlepage 87 88@summarycontents 89@contents 90 91@page 92 93@c --------------------------------------------------------------------- 94@c TexInfo table of contents. 95@c --------------------------------------------------------------------- 96 97@ifnottex 98@node Top 99@top Introduction 100@cindex Introduction 101 102This manual documents the internals of @command{gfortran}, 103the GNU Fortran compiler. 104 105@ifset DEVELOPMENT 106@emph{Warning:} This document, and the compiler it describes, are still 107under development. While efforts are made to keep it up-to-date, it might 108not accurately reflect the status of the most recent GNU Fortran compiler. 109@end ifset 110 111@comment 112@comment When you add a new menu item, please keep the right hand 113@comment aligned to the same column. Do not use tabs. This provides 114@comment better formatting. 115@comment 116@menu 117* Introduction:: About this manual. 118* User Interface:: Code that Interacts with the User. 119* Frontend Data Structures:: 120 Data structures used by the frontend 121* Object Orientation:: Internals of Fortran 2003 OOP features. 122* LibGFortran:: The LibGFortran Runtime Library. 123* GNU Free Documentation License:: 124 How you can copy and share this manual. 125* Index:: Index of this documentation. 126@end menu 127@end ifnottex 128 129@c --------------------------------------------------------------------- 130@c Introduction 131@c --------------------------------------------------------------------- 132 133@node Introduction 134@chapter Introduction 135 136@c The following duplicates the text on the TexInfo table of contents. 137@iftex 138This manual documents the internals of @command{gfortran}, the GNU Fortran 139compiler. 140 141@ifset DEVELOPMENT 142@emph{Warning:} This document, and the compiler it describes, are still 143under development. While efforts are made to keep it up-to-date, it 144might not accurately reflect the status of the most recent GNU Fortran 145compiler. 146@end ifset 147@end iftex 148 149At present, this manual is very much a work in progress, containing 150miscellaneous notes about the internals of the compiler. It is hoped 151that at some point in the future it will become a reasonably complete 152guide; in the interim, GNU Fortran developers are strongly encouraged to 153contribute to it as a way of keeping notes while working on the 154compiler. 155 156 157@c --------------------------------------------------------------------- 158@c Code that Interacts with the User 159@c --------------------------------------------------------------------- 160 161@node User Interface 162@chapter Code that Interacts with the User 163 164@menu 165* Command-Line Options:: Command-Line Options. 166* Error Handling:: Error Handling. 167@end menu 168 169 170@c --------------------------------------------------------------------- 171@c Command-Line Options 172@c --------------------------------------------------------------------- 173 174@node Command-Line Options 175@section Command-Line Options 176 177Command-line options for @command{gfortran} involve four interrelated 178pieces within the Fortran compiler code. 179 180The relevant command-line flag is defined in @file{lang.opt}, according 181to the documentation in @ref{Options,, Options, gccint, GNU Compiler 182Collection Internals}. This is then processed by the overall GCC 183machinery to create the code that enables @command{gfortran} and 184@command{gcc} to recognize the option in the command-line arguments and 185call the relevant handler function. 186 187This generated code calls the @code{gfc_handle_option} code in 188@file{options.c} with an enumerator variable indicating which option is 189to be processed, and the relevant integer or string values associated 190with that option flag. Typically, @code{gfc_handle_option} uses these 191arguments to set global flags which record the option states. 192 193The global flags that record the option states are stored in the 194@code{gfc_option_t} struct, which is defined in @file{gfortran.h}. 195Before the options are processed, initial values for these flags are set 196in @code{gfc_init_option} in @file{options.c}; these become the default 197values for the options. 198 199 200 201@c --------------------------------------------------------------------- 202@c Error Handling 203@c --------------------------------------------------------------------- 204 205@node Error Handling 206@section Error Handling 207 208The GNU Fortran compiler's parser operates by testing each piece of 209source code against a variety of matchers. In some cases, if these 210matchers do not match the source code, they will store an error message 211in a buffer. If the parser later finds a matcher that does correctly 212match the source code, then the buffered error is discarded. However, 213if the parser cannot find a match, then the buffered error message is 214reported to the user. This enables the compiler to provide more 215meaningful error messages even in the many cases where (erroneous) 216Fortran syntax is ambiguous due to things like the absence of reserved 217keywords. 218 219As an example of how this works, consider the following line: 220@smallexample 221IF = 3 222@end smallexample 223Hypothetically, this may get passed to the matcher for an @code{IF} 224statement. Since this could plausibly be an erroneous @code{IF} 225statement, the matcher will buffer an error message reporting the 226absence of an expected @samp{(} following an @code{IF}. Since no 227matchers reported an error-free match, however, the parser will also try 228matching this against a variable assignment. When @code{IF} is a valid 229variable, this will be parsed as an assignment statement, and the error 230discarded. However, when @code{IF} is not a valid variable, this 231buffered error message will be reported to the user. 232 233The error handling code is implemented in @file{error.c}. Errors are 234normally entered into the buffer with the @code{gfc_error} function. 235Warnings go through a similar buffering process, and are entered into 236the buffer with @code{gfc_warning}. There is also a special-purpose 237function, @code{gfc_notify_std}, for things which have an error/warning 238status that depends on the currently-selected language standard. 239 240The @code{gfc_error_check} function checks the buffer for errors, 241reports the error message to the user if one exists, clears the buffer, 242and returns a flag to the user indicating whether or not an error 243existed. To check the state of the buffer without changing its state or 244reporting the errors, the @code{gfc_error_flag_test} function can be 245used. The @code{gfc_clear_error} function will clear out any errors in 246the buffer, without reporting them. The @code{gfc_warning_check} and 247@code{gfc_clear_warning} functions provide equivalent functionality for 248the warning buffer. 249 250Only one error and one warning can be in the buffers at a time, and 251buffering another will overwrite the existing one. In cases where one 252may wish to work on a smaller piece of source code without disturbing an 253existing error state, the @code{gfc_push_error}, @code{gfc_pop_error}, 254and @code{gfc_free_error} mechanism exists to implement a stack for the 255error buffer. 256 257For cases where an error or warning should be reported immediately 258rather than buffered, the @code{gfc_error_now} and 259@code{gfc_warning_now} functions can be used. Normally, the compiler 260will continue attempting to parse the program after an error has 261occurred, but if this is not appropriate, the @code{gfc_fatal_error} 262function should be used instead. For errors that are always the result 263of a bug somewhere in the compiler, the @code{gfc_internal_error} 264function should be used. 265 266The syntax for the strings used to produce the error/warning message in 267the various error and warning functions is similar to the @code{printf} 268syntax, with @samp{%}-escapes to insert variable values. The details, 269and the allowable codes, are documented in the @code{error_print} 270function in @file{error.c}. 271 272@c --------------------------------------------------------------------- 273@c Frontend Data Structures 274@c --------------------------------------------------------------------- 275 276@node Frontend Data Structures 277@chapter Frontend Data Structures 278@cindex data structures 279 280This chapter should describe the details necessary to understand how 281the various @code{gfc_*} data are used and interact. In general it is 282advisable to read the code in @file{dump-parse-tree.c} as its routines 283should exhaust all possible valid combinations of content for these 284structures. 285 286@menu 287* gfc_code:: Representation of Executable Statements. 288* gfc_expr:: Representation of Values and Expressions. 289@end menu 290 291 292@c gfc_code 293@c -------- 294 295@node gfc_code 296@section @code{gfc_code} 297@cindex statement chaining 298@tindex @code{gfc_code} 299@tindex @code{struct gfc_code} 300 301The executable statements in a program unit are represented by a 302nested chain of @code{gfc_code} structures. The type of statement is 303identified by the @code{op} member of the structure, the different 304possible values are enumerated in @code{gfc_exec_op}. A special 305member of this @code{enum} is @code{EXEC_NOP} which is used to 306represent the various @code{END} statements if they carry a label. 307Depending on the type of statement some of the other fields will be 308filled in. Fields that are generally applicable are the @code{next} 309and @code{here} fields. The former points to the next statement in 310the current block or is @code{NULL} if the current statement is the 311last in a block, @code{here} points to the statement label of the 312current statement. 313 314If the current statement is one of @code{IF}, @code{DO}, @code{SELECT} 315it starts a block, i.e.@: a nested level in the program. In order to 316represent this, the @code{block} member is set to point to a 317@code{gfc_code} structure whose @code{next} member starts the chain of 318statements inside the block; this structure's @code{op} member should be set to 319the same value as the parent structure's @code{op} member. The @code{SELECT} 320and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF} 321and @code{ELSE} blocks or the various @code{CASE}s, respectively). These chains 322are linked-lists formed by the @code{block} members. 323 324Consider the following example code: 325 326@example 327IF (foo < 20) THEN 328 PRINT *, "Too small" 329 foo = 20 330ELSEIF (foo > 50) THEN 331 PRINT *, "Too large" 332 foo = 50 333ELSE 334 PRINT *, "Good" 335END IF 336@end example 337 338This statement-block will be represented in the internal gfortran tree as 339follows, were the horizontal link-chains are those induced by the @code{next} 340members and vertical links down are those of @code{block}. @samp{==|} and 341@samp{--|} mean @code{NULL} pointers to mark the end of a chain: 342 343@example 344... ==> IF ==> ... 345 | 346 +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==| 347 | 348 +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==| 349 | 350 +--> ELSE ==> PRINT *, "Good" ==| 351 | 352 +--| 353@end example 354 355 356@subsection IF Blocks 357 358Conditionals are represented by @code{gfc_code} structures with their 359@code{op} member set to @code{EXEC_IF}. This structure's @code{block} 360member must point to another @code{gfc_code} node that is the header of the 361if-block. This header's @code{op} member must be set to @code{EXEC_IF}, too, 362its @code{expr} member holds the condition to check for, and its @code{next} 363should point to the code-chain of the statements to execute if the condition is 364true. 365 366If in addition an @code{ELSEIF} or @code{ELSE} block is present, the 367@code{block} member of the if-block-header node points to yet another 368@code{gfc_code} structure that is the header of the elseif- or else-block. Its 369structure is identical to that of the if-block-header, except that in case of an 370@code{ELSE} block without a new condition the @code{expr} member should be 371@code{NULL}. This block can itself have its @code{block} member point to the 372next @code{ELSEIF} or @code{ELSE} block if there's a chain of them. 373 374 375@subsection Loops 376 377@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their 378@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and 379to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks. 380Their @code{block} member should point to a @code{gfc_code} structure heading 381the code-chain of the loop body; its @code{op} member should be set to 382@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively. 383 384For @code{DO WHILE} loops, the loop condition is stored on the top 385@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are 386simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in 387the internal representation. 388 389Similarly, @code{DO} loops with an iterator have instead of the condition their 390@code{ext.iterator} member set to the correct values for the loop iterator 391variable and its range. 392 393 394@subsection @code{SELECT} Statements 395 396A @code{SELECT} block is introduced by a @code{gfc_code} structure with an 397@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression 398to evaluate and test. Its @code{block} member starts a list of @code{gfc_code} 399structures linked together by their @code{block} members that stores the various 400@code{CASE} parts. 401 402Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too, 403its @code{next} member points to the code-chain to be executed in the current 404case-block, and @code{extx.case_list} contains the case-values this block 405corresponds to. The @code{block} member links to the next case in the list. 406 407 408@subsection @code{BLOCK} and @code{ASSOCIATE} 409 410The code related to a @code{BLOCK} statement is stored inside an 411@code{gfc_code} structure (say @var{c}) 412with @code{c.op} set to @code{EXEC_BLOCK}. The 413@code{gfc_namespace} holding the locally defined variables of the 414@code{BLOCK} is stored in @code{c.ext.block.ns}. The code inside the 415construct is in @code{c.code}. 416 417@code{ASSOCIATE} constructs are based on @code{BLOCK} and thus also have 418the internal storage structure described above (including @code{EXEC_BLOCK}). 419However, for them @code{c.ext.block.assoc} is set additionally and points 420to a linked list of @code{gfc_association_list} structures. Those 421structures basically store a link of associate-names to target expressions. 422The associate-names themselves are still also added to the @code{BLOCK}'s 423namespace as ordinary symbols, but they have their @code{gfc_symbol}'s 424member @code{assoc} set also pointing to the association-list structure. 425This way associate-names can be distinguished from ordinary variables 426and their target expressions identified. 427 428For association to expressions (as opposed to variables), at the very beginning 429of the @code{BLOCK} construct assignments are automatically generated to 430set the corresponding variables to their target expressions' values, and 431later on the compiler simply disallows using such associate-names in contexts 432that may change the value. 433 434 435@c gfc_expr 436@c -------- 437 438@node gfc_expr 439@section @code{gfc_expr} 440@tindex @code{gfc_expr} 441@tindex @code{struct gfc_expr} 442 443Expressions and ``values'', including constants, variable-, array- and 444component-references as well as complex expressions consisting of operators and 445function calls are internally represented as one or a whole tree of 446@code{gfc_expr} objects. The member @code{expr_type} specifies the overall 447type of an expression (for instance, @code{EXPR_CONSTANT} for constants or 448@code{EXPR_VARIABLE} for variable references). The members @code{ts} and 449@code{rank} as well as @code{shape}, which can be @code{NULL}, specify 450the type, rank and, if applicable, shape of the whole expression or expression 451tree of which the current structure is the root. @code{where} is the locus of 452this expression in the source code. 453 454Depending on the flavor of the expression being described by the object 455(that is, the value of its @code{expr_type} member), the corresponding structure 456in the @code{value} union will usually contain additional data describing the 457expression's value in a type-specific manner. The @code{ref} member is used to 458build chains of (array-, component- and substring-) references if the expression 459in question contains such references, see below for details. 460 461 462@subsection Constants 463 464Scalar constants are represented by @code{gfc_expr} nodes with their 465@code{expr_type} set to @code{EXPR_CONSTANT}. The constant's value shall 466already be known at compile-time and is stored in the @code{logical}, 467@code{integer}, @code{real}, @code{complex} or @code{character} struct inside 468@code{value}, depending on the constant's type specification. 469 470 471@subsection Operators 472 473Operator-expressions are expressions that are the result of the execution of 474some operator on one or two operands. The expressions have an @code{expr_type} 475of @code{EXPR_OP}. Their @code{value.op} structure contains additional data. 476 477@code{op1} and optionally @code{op2} if the operator is binary point to the 478two operands, and @code{operator} or @code{uop} describe the operator that 479should be evaluated on these operands, where @code{uop} describes a user-defined 480operator. 481 482 483@subsection Function Calls 484 485If the expression is the return value of a function-call, its @code{expr_type} 486is set to @code{EXPR_FUNCTION}, and @code{symtree} must point to the symtree 487identifying the function to be called. @code{value.function.actual} holds the 488actual arguments given to the function as a linked list of 489@code{gfc_actual_arglist} nodes. 490 491The other members of @code{value.function} describe the function being called 492in more detail, containing a link to the intrinsic symbol or user-defined 493function symbol if the call is to an intrinsic or external function, 494respectively. These values are determined during resolution-phase from the 495structure's @code{symtree} member. 496 497A special case of function calls are ``component calls'' to type-bound 498procedures; those have the @code{expr_type} @code{EXPR_COMPCALL} with 499@code{value.compcall} containing the argument list and the procedure called, 500while @code{symtree} and @code{ref} describe the object on which the procedure 501was called in the same way as a @code{EXPR_VARIABLE} expression would. 502@xref{Type-bound Procedures}. 503 504 505@subsection Array- and Structure-Constructors 506 507Array- and structure-constructors (one could probably call them ``array-'' and 508``derived-type constants'') are @code{gfc_expr} structures with their 509@code{expr_type} member set to @code{EXPR_ARRAY} or @code{EXPR_STRUCTURE}, 510respectively. For structure constructors, @code{symtree} points to the 511derived-type symbol for the type being constructed. 512 513The values for initializing each array element or structure component are 514stored as linked-list of @code{gfc_constructor} nodes in the 515@code{value.constructor} member. 516 517 518@subsection Null 519 520@code{NULL} is a special value for pointers; it can be of different base types. 521Such a @code{NULL} value is represented in the internal tree by a 522@code{gfc_expr} node with @code{expr_type} @code{EXPR_NULL}. If the base type 523of the @code{NULL} expression is known, it is stored in @code{ts} (that's for 524instance the case for default-initializers of @code{ALLOCATABLE} components), 525but this member can also be set to @code{BT_UNKNOWN} if the information is not 526available (for instance, when the expression is a pointer-initializer 527@code{NULL()}). 528 529 530@subsection Variables and Reference Expressions 531 532Variable references are @code{gfc_expr} structures with their @code{expr_type} 533set to @code{EXPR_VARIABLE}; their @code{symtree} should point to the variable 534that is referenced. 535 536For this type of expression, it's also possible to chain array-, component- 537or substring-references to the original expression to get something like 538@samp{struct%component(2:5)}, where @code{component} is either an array or 539a @code{CHARACTER} member of @code{struct} that is of some derived-type. Such a 540chain of references is achieved by a linked list headed by @code{ref} of the 541@code{gfc_expr} node. For the example above it would be (@samp{==|} is the 542last @code{NULL} pointer): 543 544@smallexample 545EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==| 546@end smallexample 547 548If @code{component} is a string rather than an array, the last element would be 549a @code{REF_SUBSTRING} reference, of course. If the variable itself or some 550component referenced is an array and the expression should reference the whole 551array rather than being followed by an array-element or -section reference, a 552@code{REF_ARRAY} reference must be built as the last element in the chain with 553an array-reference type of @code{AR_FULL}. Consider this example code: 554 555@smallexample 556TYPE :: mytype 557 INTEGER :: array(42) 558END TYPE mytype 559 560TYPE(mytype) :: variable 561INTEGER :: local_array(5) 562 563CALL do_something (variable%array, local_array) 564@end smallexample 565 566The @code{gfc_expr} nodes representing the arguments to the @samp{do_something} 567call will have a reference-chain like this: 568 569@smallexample 570EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==| 571EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==| 572@end smallexample 573 574 575@subsection Constant Substring References 576 577@code{EXPR_SUBSTRING} is a special type of expression that encodes a substring 578reference of a constant string, as in the following code snippet: 579 580@smallexample 581x = "abcde"(1:2) 582@end smallexample 583 584In this case, @code{value.character} contains the full string's data as if it 585was a string constant, but the @code{ref} member is also set and points to a 586substring reference as described in the subsection above. 587 588 589@c --------------------------------------------------------------------- 590@c F2003 OOP 591@c --------------------------------------------------------------------- 592 593@node Object Orientation 594@chapter Internals of Fortran 2003 OOP Features 595 596@menu 597* Type-bound Procedures:: Type-bound procedures. 598* Type-bound Operators:: Type-bound operators. 599@end menu 600 601 602@c Type-bound procedures 603@c --------------------- 604 605@node Type-bound Procedures 606@section Type-bound Procedures 607 608Type-bound procedures are stored in the @code{tb_sym_root} of the namespace 609@code{f2k_derived} associated with the derived-type symbol as @code{gfc_symtree} 610nodes. The name and symbol of these symtrees corresponds to the binding-name 611of the procedure, i.e. the name that is used to call it from the context of an 612object of the derived-type. 613 614In addition, this type of symtrees stores in @code{n.tb} a struct of type 615@code{gfc_typebound_proc} containing the additional data needed: The 616binding attributes (like @code{PASS} and @code{NOPASS}, @code{NON_OVERRIDABLE} 617or the access-specifier), the binding's target(s) and, if the current binding 618overrides or extends an inherited binding of the same name, @code{overridden} 619points to this binding's @code{gfc_typebound_proc} structure. 620 621 622@subsection Specific Bindings 623@c -------------------------- 624 625For specific bindings (declared with @code{PROCEDURE}), if they have a 626passed-object argument, the passed-object dummy argument is first saved by its 627name, and later during resolution phase the corresponding argument is looked for 628and its position remembered as @code{pass_arg_num} in @code{gfc_typebound_proc}. 629The binding's target procedure is pointed-to by @code{u.specific}. 630 631@code{DEFERRED} bindings are just like ordinary specific bindings, except 632that their @code{deferred} flag is set of course and that @code{u.specific} 633points to their ``interface'' defining symbol (might be an abstract interface) 634instead of the target procedure. 635 636At the moment, all type-bound procedure calls are statically dispatched and 637transformed into ordinary procedure calls at resolution time; their actual 638argument list is updated to include at the right position the passed-object 639argument, if applicable, and then a simple procedure call to the binding's 640target procedure is built. To handle dynamic dispatch in the future, this will 641be extended to allow special code generation during the trans-phase to dispatch 642based on the object's dynamic type. 643 644 645@subsection Generic Bindings 646@c ------------------------- 647 648Bindings declared as @code{GENERIC} store the specific bindings they target as 649a linked list using nodes of type @code{gfc_tbp_generic} in @code{u.generic}. 650For each specific target, the parser records its symtree and during resolution 651this symtree is bound to the corresponding @code{gfc_typebound_proc} structure 652of the specific target. 653 654Calls to generic bindings are handled entirely in the resolution-phase, where 655for the actual argument list present the matching specific binding is found 656and the call's target procedure (@code{value.compcall.tbp}) is re-pointed to 657the found specific binding and this call is subsequently handled by the logic 658for specific binding calls. 659 660 661@subsection Calls to Type-bound Procedures 662@c --------------------------------------- 663 664Calls to type-bound procedures are stored in the parse-tree as @code{gfc_expr} 665nodes of type @code{EXPR_COMPCALL}. Their @code{value.compcall.actual} saves 666the actual argument list of the call and @code{value.compcall.tbp} points to the 667@code{gfc_typebound_proc} structure of the binding to be called. The object 668in whose context the procedure was called is saved by combination of 669@code{symtree} and @code{ref}, as if the expression was of type 670@code{EXPR_VARIABLE}. 671 672For code like this: 673@smallexample 674CALL myobj%procedure (arg1, arg2) 675@end smallexample 676@noindent 677the @code{CALL} is represented in the parse-tree as a @code{gfc_code} node of 678type @code{EXEC_COMPCALL}. The @code{expr} member of this node holds an 679expression of type @code{EXPR_COMPCALL} of the same structure as mentioned above 680except that its target procedure is of course a @code{SUBROUTINE} and not a 681@code{FUNCTION}. 682 683Expressions that are generated internally (as expansion of a type-bound 684operator call) may also use additional flags and members. 685@code{value.compcall.ignore_pass} signals that even though a @code{PASS} 686attribute may be present the actual argument list should not be updated because 687it already contains the passed-object. 688@code{value.compcall.base_object} overrides, if it is set, the base-object 689(that is normally stored in @code{symtree} and @code{ref} as mentioned above); 690this is needed because type-bound operators can be called on a base-object that 691need not be of type @code{EXPR_VARIABLE} and thus representable in this way. 692Finally, if @code{value.compcall.assign} is set, the call was produced in 693expansion of a type-bound assignment; this means that proper dependency-checking 694needs to be done when relevant. 695 696 697@c Type-bound operators 698@c -------------------- 699 700@node Type-bound Operators 701@section Type-bound Operators 702 703Type-bound operators are in fact basically just @code{GENERIC} procedure 704bindings and are represented much in the same way as those (see 705@ref{Type-bound Procedures}). 706 707They come in two flavours: 708User-defined operators (like @code{.MYOPERATOR.}) 709are stored in the @code{f2k_derived} namespace's @code{tb_uop_root} 710symtree exactly like ordinary type-bound procedures are stored in 711@code{tb_sym_root}; their symtrees' names are the operator-names (e.g. 712@samp{myoperator} in the example). 713Intrinsic operators on the other hand are stored in the namespace's 714array member @code{tb_op} indexed by the intrinsic operator's enum 715value. Those need not be packed into @code{gfc_symtree} structures and are 716only @code{gfc_typebound_proc} instances. 717 718When an operator call or assignment is found that can not be handled in 719another way (i.e. neither matches an intrinsic nor interface operator 720definition) but that contains a derived-type expression, all type-bound 721operators defined on that derived-type are checked for a match with 722the operator call. If there's indeed a relevant definition, the 723operator call is replaced with an internally generated @code{GENERIC} 724type-bound procedure call to the respective definition and that call is 725further processed. 726 727 728@c --------------------------------------------------------------------- 729@c LibGFortran 730@c --------------------------------------------------------------------- 731 732@node LibGFortran 733@chapter The LibGFortran Runtime Library 734 735@menu 736* Symbol Versioning:: Symbol Versioning. 737@end menu 738 739 740@c --------------------------------------------------------------------- 741@c Symbol Versioning 742@c --------------------------------------------------------------------- 743 744@node Symbol Versioning 745@section Symbol Versioning 746@comment Based on http://gcc.gnu.org/wiki/SymbolVersioning, 747@comment as of 2006-11-05, written by Janne Blomqvist. 748 749In general, this capability exists only on a few platforms, thus there 750is a need for configure magic so that it is used only on those targets 751where it is supported. 752 753The central concept in symbol versioning is the so-called map file, 754which specifies the version node(s) exported symbols are labeled with. 755Also, the map file is used to hide local symbols. 756 757Some relevant references: 758@itemize @bullet 759@item 760@uref{http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html, 761GNU @command{ld} manual} 762 763@item 764@uref{http://people.redhat.com/drepper/symbol-versioning, ELF Symbol 765Versioning - Ulrich Depper} 766 767@item 768@uref{http://people.redhat.com/drepper/dsohowto.pdf, How to Write Shared 769Libraries - Ulrich Drepper (see Chapter 3)} 770 771@end itemize 772 773If one adds a new symbol to a library that should be exported, the new 774symbol should be mentioned in the map file and a new version node 775defined, e.g., if one adds a new symbols @code{foo} and @code{bar} to 776libgfortran for the next GCC release, the following should be added to 777the map file: 778@smallexample 779GFORTRAN_1.1 @{ 780 global: 781 foo; 782 bar; 783@} GFORTRAN_1.0; 784@end smallexample 785@noindent 786where @code{GFORTRAN_1.0} is the version node of the current release, 787and @code{GFORTRAN_1.1} is the version node of the next release where 788foo and bar are made available. 789 790If one wants to change an existing interface, it is possible by using 791some asm trickery (from the @command{ld} manual referenced above): 792 793@smallexample 794__asm__(".symver original_foo,foo@@"); 795__asm__(".symver old_foo,foo@@VERS_1.1"); 796__asm__(".symver old_foo1,foo@@VERS_1.2"); 797__asm__(".symver new_foo,foo@@VERS_2.0"); 798@end smallexample 799 800In this example, @code{foo@@} represents the symbol @code{foo} bound to 801the unspecified base version of the symbol. The source file that 802contains this example would define 4 C functions: @code{original_foo}, 803@code{old_foo}, @code{old_foo1}, and @code{new_foo}. 804 805In this case the map file must contain @code{foo} in @code{VERS_1.1} 806and @code{VERS_1.2} as well as in @code{VERS_2.0}. 807 808 809@c --------------------------------------------------------------------- 810@c GNU Free Documentation License 811@c --------------------------------------------------------------------- 812 813@include fdl.texi 814 815 816@c --------------------------------------------------------------------- 817@c Index 818@c --------------------------------------------------------------------- 819 820@node Index 821@unnumbered Index 822 823@printindex cp 824 825@bye 826