1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename gfc-internals.info 4@set copyrights-gfortran 2007-2021 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* Translating to GENERIC:: 123 Generating the intermediate language for later stages. 124* LibGFortran:: The LibGFortran Runtime Library. 125* GNU Free Documentation License:: 126 How you can copy and share this manual. 127* Index:: Index of this documentation. 128@end menu 129@end ifnottex 130 131@c --------------------------------------------------------------------- 132@c Introduction 133@c --------------------------------------------------------------------- 134 135@node Introduction 136@chapter Introduction 137 138@c The following duplicates the text on the TexInfo table of contents. 139@iftex 140This manual documents the internals of @command{gfortran}, the GNU Fortran 141compiler. 142 143@ifset DEVELOPMENT 144@emph{Warning:} This document, and the compiler it describes, are still 145under development. While efforts are made to keep it up-to-date, it 146might not accurately reflect the status of the most recent GNU Fortran 147compiler. 148@end ifset 149@end iftex 150 151At present, this manual is very much a work in progress, containing 152miscellaneous notes about the internals of the compiler. It is hoped 153that at some point in the future it will become a reasonably complete 154guide; in the interim, GNU Fortran developers are strongly encouraged to 155contribute to it as a way of keeping notes while working on the 156compiler. 157 158 159@c --------------------------------------------------------------------- 160@c Code that Interacts with the User 161@c --------------------------------------------------------------------- 162 163@node User Interface 164@chapter Code that Interacts with the User 165 166@menu 167* Command-Line Options:: Command-Line Options. 168* Error Handling:: Error Handling. 169@end menu 170 171 172@c --------------------------------------------------------------------- 173@c Command-Line Options 174@c --------------------------------------------------------------------- 175 176@node Command-Line Options 177@section Command-Line Options 178 179Command-line options for @command{gfortran} involve four interrelated 180pieces within the Fortran compiler code. 181 182The relevant command-line flag is defined in @file{lang.opt}, according 183to the documentation in @ref{Options,, Options, gccint, GNU Compiler 184Collection Internals}. This is then processed by the overall GCC 185machinery to create the code that enables @command{gfortran} and 186@command{gcc} to recognize the option in the command-line arguments and 187call the relevant handler function. 188 189This generated code calls the @code{gfc_handle_option} code in 190@file{options.c} with an enumerator variable indicating which option is 191to be processed, and the relevant integer or string values associated 192with that option flag. Typically, @code{gfc_handle_option} uses these 193arguments to set global flags which record the option states. 194 195The global flags that record the option states are stored in the 196@code{gfc_option_t} struct, which is defined in @file{gfortran.h}. 197Before the options are processed, initial values for these flags are set 198in @code{gfc_init_option} in @file{options.c}; these become the default 199values for the options. 200 201 202 203@c --------------------------------------------------------------------- 204@c Error Handling 205@c --------------------------------------------------------------------- 206 207@node Error Handling 208@section Error Handling 209 210The GNU Fortran compiler's parser operates by testing each piece of 211source code against a variety of matchers. In some cases, if these 212matchers do not match the source code, they will store an error message 213in a buffer. If the parser later finds a matcher that does correctly 214match the source code, then the buffered error is discarded. However, 215if the parser cannot find a match, then the buffered error message is 216reported to the user. This enables the compiler to provide more 217meaningful error messages even in the many cases where (erroneous) 218Fortran syntax is ambiguous due to things like the absence of reserved 219keywords. 220 221As an example of how this works, consider the following line: 222@smallexample 223IF = 3 224@end smallexample 225Hypothetically, this may get passed to the matcher for an @code{IF} 226statement. Since this could plausibly be an erroneous @code{IF} 227statement, the matcher will buffer an error message reporting the 228absence of an expected @samp{(} following an @code{IF}. Since no 229matchers reported an error-free match, however, the parser will also try 230matching this against a variable assignment. When @code{IF} is a valid 231variable, this will be parsed as an assignment statement, and the error 232discarded. However, when @code{IF} is not a valid variable, this 233buffered error message will be reported to the user. 234 235The error handling code is implemented in @file{error.c}. Errors are 236normally entered into the buffer with the @code{gfc_error} function. 237Warnings go through a similar buffering process, and are entered into 238the buffer with @code{gfc_warning}. There is also a special-purpose 239function, @code{gfc_notify_std}, for things which have an error/warning 240status that depends on the currently-selected language standard. 241 242The @code{gfc_error_check} function checks the buffer for errors, 243reports the error message to the user if one exists, clears the buffer, 244and returns a flag to the user indicating whether or not an error 245existed. To check the state of the buffer without changing its state or 246reporting the errors, the @code{gfc_error_flag_test} function can be 247used. The @code{gfc_clear_error} function will clear out any errors in 248the buffer, without reporting them. The @code{gfc_warning_check} and 249@code{gfc_clear_warning} functions provide equivalent functionality for 250the warning buffer. 251 252Only one error and one warning can be in the buffers at a time, and 253buffering another will overwrite the existing one. In cases where one 254may wish to work on a smaller piece of source code without disturbing an 255existing error state, the @code{gfc_push_error}, @code{gfc_pop_error}, 256and @code{gfc_free_error} mechanism exists to implement a stack for the 257error buffer. 258 259For cases where an error or warning should be reported immediately 260rather than buffered, the @code{gfc_error_now} and 261@code{gfc_warning_now} functions can be used. Normally, the compiler 262will continue attempting to parse the program after an error has 263occurred, but if this is not appropriate, the @code{gfc_fatal_error} 264function should be used instead. For errors that are always the result 265of a bug somewhere in the compiler, the @code{gfc_internal_error} 266function should be used. 267 268The syntax for the strings used to produce the error/warning message in 269the various error and warning functions is similar to the @code{printf} 270syntax, with @samp{%}-escapes to insert variable values. The details, 271and the allowable codes, are documented in the @code{error_print} 272function in @file{error.c}. 273 274@c --------------------------------------------------------------------- 275@c Frontend Data Structures 276@c --------------------------------------------------------------------- 277 278@node Frontend Data Structures 279@chapter Frontend Data Structures 280@cindex data structures 281 282This chapter should describe the details necessary to understand how 283the various @code{gfc_*} data are used and interact. In general it is 284advisable to read the code in @file{dump-parse-tree.c} as its routines 285should exhaust all possible valid combinations of content for these 286structures. 287 288@menu 289* gfc_code:: Representation of Executable Statements. 290* gfc_expr:: Representation of Values and Expressions. 291@end menu 292 293 294@c gfc_code 295@c -------- 296 297@node gfc_code 298@section @code{gfc_code} 299@cindex statement chaining 300@tindex @code{gfc_code} 301@tindex @code{struct gfc_code} 302 303The executable statements in a program unit are represented by a 304nested chain of @code{gfc_code} structures. The type of statement is 305identified by the @code{op} member of the structure, the different 306possible values are enumerated in @code{gfc_exec_op}. A special 307member of this @code{enum} is @code{EXEC_NOP} which is used to 308represent the various @code{END} statements if they carry a label. 309Depending on the type of statement some of the other fields will be 310filled in. Fields that are generally applicable are the @code{next} 311and @code{here} fields. The former points to the next statement in 312the current block or is @code{NULL} if the current statement is the 313last in a block, @code{here} points to the statement label of the 314current statement. 315 316If the current statement is one of @code{IF}, @code{DO}, @code{SELECT} 317it starts a block, i.e.@: a nested level in the program. In order to 318represent this, the @code{block} member is set to point to a 319@code{gfc_code} structure whose @code{next} member starts the chain of 320statements inside the block; this structure's @code{op} member should be set to 321the same value as the parent structure's @code{op} member. The @code{SELECT} 322and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF} 323and @code{ELSE} blocks or the various @code{CASE}s, respectively). These chains 324are linked-lists formed by the @code{block} members. 325 326Consider the following example code: 327 328@example 329IF (foo < 20) THEN 330 PRINT *, "Too small" 331 foo = 20 332ELSEIF (foo > 50) THEN 333 PRINT *, "Too large" 334 foo = 50 335ELSE 336 PRINT *, "Good" 337END IF 338@end example 339 340This statement-block will be represented in the internal gfortran tree as 341follows, were the horizontal link-chains are those induced by the @code{next} 342members and vertical links down are those of @code{block}. @samp{==|} and 343@samp{--|} mean @code{NULL} pointers to mark the end of a chain: 344 345@example 346... ==> IF ==> ... 347 | 348 +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==| 349 | 350 +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==| 351 | 352 +--> ELSE ==> PRINT *, "Good" ==| 353 | 354 +--| 355@end example 356 357 358@subsection IF Blocks 359 360Conditionals are represented by @code{gfc_code} structures with their 361@code{op} member set to @code{EXEC_IF}. This structure's @code{block} 362member must point to another @code{gfc_code} node that is the header of the 363if-block. This header's @code{op} member must be set to @code{EXEC_IF}, too, 364its @code{expr} member holds the condition to check for, and its @code{next} 365should point to the code-chain of the statements to execute if the condition is 366true. 367 368If in addition an @code{ELSEIF} or @code{ELSE} block is present, the 369@code{block} member of the if-block-header node points to yet another 370@code{gfc_code} structure that is the header of the elseif- or else-block. Its 371structure is identical to that of the if-block-header, except that in case of an 372@code{ELSE} block without a new condition the @code{expr} member should be 373@code{NULL}. This block can itself have its @code{block} member point to the 374next @code{ELSEIF} or @code{ELSE} block if there's a chain of them. 375 376 377@subsection Loops 378 379@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their 380@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and 381to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks. 382Their @code{block} member should point to a @code{gfc_code} structure heading 383the code-chain of the loop body; its @code{op} member should be set to 384@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively. 385 386For @code{DO WHILE} loops, the loop condition is stored on the top 387@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are 388simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in 389the internal representation. 390 391Similarly, @code{DO} loops with an iterator have instead of the condition their 392@code{ext.iterator} member set to the correct values for the loop iterator 393variable and its range. 394 395 396@subsection @code{SELECT} Statements 397 398A @code{SELECT} block is introduced by a @code{gfc_code} structure with an 399@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression 400to evaluate and test. Its @code{block} member starts a list of @code{gfc_code} 401structures linked together by their @code{block} members that stores the various 402@code{CASE} parts. 403 404Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too, 405its @code{next} member points to the code-chain to be executed in the current 406case-block, and @code{extx.case_list} contains the case-values this block 407corresponds to. The @code{block} member links to the next case in the list. 408 409 410@subsection @code{BLOCK} and @code{ASSOCIATE} 411 412The code related to a @code{BLOCK} statement is stored inside an 413@code{gfc_code} structure (say @var{c}) 414with @code{c.op} set to @code{EXEC_BLOCK}. The 415@code{gfc_namespace} holding the locally defined variables of the 416@code{BLOCK} is stored in @code{c.ext.block.ns}. The code inside the 417construct is in @code{c.code}. 418 419@code{ASSOCIATE} constructs are based on @code{BLOCK} and thus also have 420the internal storage structure described above (including @code{EXEC_BLOCK}). 421However, for them @code{c.ext.block.assoc} is set additionally and points 422to a linked list of @code{gfc_association_list} structures. Those 423structures basically store a link of associate-names to target expressions. 424The associate-names themselves are still also added to the @code{BLOCK}'s 425namespace as ordinary symbols, but they have their @code{gfc_symbol}'s 426member @code{assoc} set also pointing to the association-list structure. 427This way associate-names can be distinguished from ordinary variables 428and their target expressions identified. 429 430For association to expressions (as opposed to variables), at the very beginning 431of the @code{BLOCK} construct assignments are automatically generated to 432set the corresponding variables to their target expressions' values, and 433later on the compiler simply disallows using such associate-names in contexts 434that may change the value. 435 436 437@c gfc_expr 438@c -------- 439 440@node gfc_expr 441@section @code{gfc_expr} 442@tindex @code{gfc_expr} 443@tindex @code{struct gfc_expr} 444 445Expressions and ``values'', including constants, variable-, array- and 446component-references as well as complex expressions consisting of operators and 447function calls are internally represented as one or a whole tree of 448@code{gfc_expr} objects. The member @code{expr_type} specifies the overall 449type of an expression (for instance, @code{EXPR_CONSTANT} for constants or 450@code{EXPR_VARIABLE} for variable references). The members @code{ts} and 451@code{rank} as well as @code{shape}, which can be @code{NULL}, specify 452the type, rank and, if applicable, shape of the whole expression or expression 453tree of which the current structure is the root. @code{where} is the locus of 454this expression in the source code. 455 456Depending on the flavor of the expression being described by the object 457(that is, the value of its @code{expr_type} member), the corresponding structure 458in the @code{value} union will usually contain additional data describing the 459expression's value in a type-specific manner. The @code{ref} member is used to 460build chains of (array-, component- and substring-) references if the expression 461in question contains such references, see below for details. 462 463 464@subsection Constants 465 466Scalar constants are represented by @code{gfc_expr} nodes with their 467@code{expr_type} set to @code{EXPR_CONSTANT}. The constant's value shall 468already be known at compile-time and is stored in the @code{logical}, 469@code{integer}, @code{real}, @code{complex} or @code{character} struct inside 470@code{value}, depending on the constant's type specification. 471 472 473@subsection Operators 474 475Operator-expressions are expressions that are the result of the execution of 476some operator on one or two operands. The expressions have an @code{expr_type} 477of @code{EXPR_OP}. Their @code{value.op} structure contains additional data. 478 479@code{op1} and optionally @code{op2} if the operator is binary point to the 480two operands, and @code{operator} or @code{uop} describe the operator that 481should be evaluated on these operands, where @code{uop} describes a user-defined 482operator. 483 484 485@subsection Function Calls 486 487If the expression is the return value of a function-call, its @code{expr_type} 488is set to @code{EXPR_FUNCTION}, and @code{symtree} must point to the symtree 489identifying the function to be called. @code{value.function.actual} holds the 490actual arguments given to the function as a linked list of 491@code{gfc_actual_arglist} nodes. 492 493The other members of @code{value.function} describe the function being called 494in more detail, containing a link to the intrinsic symbol or user-defined 495function symbol if the call is to an intrinsic or external function, 496respectively. These values are determined during resolution-phase from the 497structure's @code{symtree} member. 498 499A special case of function calls are ``component calls'' to type-bound 500procedures; those have the @code{expr_type} @code{EXPR_COMPCALL} with 501@code{value.compcall} containing the argument list and the procedure called, 502while @code{symtree} and @code{ref} describe the object on which the procedure 503was called in the same way as a @code{EXPR_VARIABLE} expression would. 504@xref{Type-bound Procedures}. 505 506 507@subsection Array- and Structure-Constructors 508 509Array- and structure-constructors (one could probably call them ``array-'' and 510``derived-type constants'') are @code{gfc_expr} structures with their 511@code{expr_type} member set to @code{EXPR_ARRAY} or @code{EXPR_STRUCTURE}, 512respectively. For structure constructors, @code{symtree} points to the 513derived-type symbol for the type being constructed. 514 515The values for initializing each array element or structure component are 516stored as linked-list of @code{gfc_constructor} nodes in the 517@code{value.constructor} member. 518 519 520@subsection Null 521 522@code{NULL} is a special value for pointers; it can be of different base types. 523Such a @code{NULL} value is represented in the internal tree by a 524@code{gfc_expr} node with @code{expr_type} @code{EXPR_NULL}. If the base type 525of the @code{NULL} expression is known, it is stored in @code{ts} (that's for 526instance the case for default-initializers of @code{ALLOCATABLE} components), 527but this member can also be set to @code{BT_UNKNOWN} if the information is not 528available (for instance, when the expression is a pointer-initializer 529@code{NULL()}). 530 531 532@subsection Variables and Reference Expressions 533 534Variable references are @code{gfc_expr} structures with their @code{expr_type} 535set to @code{EXPR_VARIABLE}; their @code{symtree} should point to the variable 536that is referenced. 537 538For this type of expression, it's also possible to chain array-, component- 539or substring-references to the original expression to get something like 540@samp{struct%component(2:5)}, where @code{component} is either an array or 541a @code{CHARACTER} member of @code{struct} that is of some derived-type. Such a 542chain of references is achieved by a linked list headed by @code{ref} of the 543@code{gfc_expr} node. For the example above it would be (@samp{==|} is the 544last @code{NULL} pointer): 545 546@smallexample 547EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==| 548@end smallexample 549 550If @code{component} is a string rather than an array, the last element would be 551a @code{REF_SUBSTRING} reference, of course. If the variable itself or some 552component referenced is an array and the expression should reference the whole 553array rather than being followed by an array-element or -section reference, a 554@code{REF_ARRAY} reference must be built as the last element in the chain with 555an array-reference type of @code{AR_FULL}. Consider this example code: 556 557@smallexample 558TYPE :: mytype 559 INTEGER :: array(42) 560END TYPE mytype 561 562TYPE(mytype) :: variable 563INTEGER :: local_array(5) 564 565CALL do_something (variable%array, local_array) 566@end smallexample 567 568The @code{gfc_expr} nodes representing the arguments to the @samp{do_something} 569call will have a reference-chain like this: 570 571@smallexample 572EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==| 573EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==| 574@end smallexample 575 576 577@subsection Constant Substring References 578 579@code{EXPR_SUBSTRING} is a special type of expression that encodes a substring 580reference of a constant string, as in the following code snippet: 581 582@smallexample 583x = "abcde"(1:2) 584@end smallexample 585 586In this case, @code{value.character} contains the full string's data as if it 587was a string constant, but the @code{ref} member is also set and points to a 588substring reference as described in the subsection above. 589 590 591@c --------------------------------------------------------------------- 592@c F2003 OOP 593@c --------------------------------------------------------------------- 594 595@node Object Orientation 596@chapter Internals of Fortran 2003 OOP Features 597 598@menu 599* Type-bound Procedures:: Type-bound procedures. 600* Type-bound Operators:: Type-bound operators. 601@end menu 602 603 604@c Type-bound procedures 605@c --------------------- 606 607@node Type-bound Procedures 608@section Type-bound Procedures 609 610Type-bound procedures are stored in the @code{tb_sym_root} of the namespace 611@code{f2k_derived} associated with the derived-type symbol as @code{gfc_symtree} 612nodes. The name and symbol of these symtrees corresponds to the binding-name 613of the procedure, i.e. the name that is used to call it from the context of an 614object of the derived-type. 615 616In addition, this type of symtrees stores in @code{n.tb} a struct of type 617@code{gfc_typebound_proc} containing the additional data needed: The 618binding attributes (like @code{PASS} and @code{NOPASS}, @code{NON_OVERRIDABLE} 619or the access-specifier), the binding's target(s) and, if the current binding 620overrides or extends an inherited binding of the same name, @code{overridden} 621points to this binding's @code{gfc_typebound_proc} structure. 622 623 624@subsection Specific Bindings 625@c -------------------------- 626 627For specific bindings (declared with @code{PROCEDURE}), if they have a 628passed-object argument, the passed-object dummy argument is first saved by its 629name, and later during resolution phase the corresponding argument is looked for 630and its position remembered as @code{pass_arg_num} in @code{gfc_typebound_proc}. 631The binding's target procedure is pointed-to by @code{u.specific}. 632 633@code{DEFERRED} bindings are just like ordinary specific bindings, except 634that their @code{deferred} flag is set of course and that @code{u.specific} 635points to their ``interface'' defining symbol (might be an abstract interface) 636instead of the target procedure. 637 638At the moment, all type-bound procedure calls are statically dispatched and 639transformed into ordinary procedure calls at resolution time; their actual 640argument list is updated to include at the right position the passed-object 641argument, if applicable, and then a simple procedure call to the binding's 642target procedure is built. To handle dynamic dispatch in the future, this will 643be extended to allow special code generation during the trans-phase to dispatch 644based on the object's dynamic type. 645 646 647@subsection Generic Bindings 648@c ------------------------- 649 650Bindings declared as @code{GENERIC} store the specific bindings they target as 651a linked list using nodes of type @code{gfc_tbp_generic} in @code{u.generic}. 652For each specific target, the parser records its symtree and during resolution 653this symtree is bound to the corresponding @code{gfc_typebound_proc} structure 654of the specific target. 655 656Calls to generic bindings are handled entirely in the resolution-phase, where 657for the actual argument list present the matching specific binding is found 658and the call's target procedure (@code{value.compcall.tbp}) is re-pointed to 659the found specific binding and this call is subsequently handled by the logic 660for specific binding calls. 661 662 663@subsection Calls to Type-bound Procedures 664@c --------------------------------------- 665 666Calls to type-bound procedures are stored in the parse-tree as @code{gfc_expr} 667nodes of type @code{EXPR_COMPCALL}. Their @code{value.compcall.actual} saves 668the actual argument list of the call and @code{value.compcall.tbp} points to the 669@code{gfc_typebound_proc} structure of the binding to be called. The object 670in whose context the procedure was called is saved by combination of 671@code{symtree} and @code{ref}, as if the expression was of type 672@code{EXPR_VARIABLE}. 673 674For code like this: 675@smallexample 676CALL myobj%procedure (arg1, arg2) 677@end smallexample 678@noindent 679the @code{CALL} is represented in the parse-tree as a @code{gfc_code} node of 680type @code{EXEC_COMPCALL}. The @code{expr} member of this node holds an 681expression of type @code{EXPR_COMPCALL} of the same structure as mentioned above 682except that its target procedure is of course a @code{SUBROUTINE} and not a 683@code{FUNCTION}. 684 685Expressions that are generated internally (as expansion of a type-bound 686operator call) may also use additional flags and members. 687@code{value.compcall.ignore_pass} signals that even though a @code{PASS} 688attribute may be present the actual argument list should not be updated because 689it already contains the passed-object. 690@code{value.compcall.base_object} overrides, if it is set, the base-object 691(that is normally stored in @code{symtree} and @code{ref} as mentioned above); 692this is needed because type-bound operators can be called on a base-object that 693need not be of type @code{EXPR_VARIABLE} and thus representable in this way. 694Finally, if @code{value.compcall.assign} is set, the call was produced in 695expansion of a type-bound assignment; this means that proper dependency-checking 696needs to be done when relevant. 697 698 699@c Type-bound operators 700@c -------------------- 701 702@node Type-bound Operators 703@section Type-bound Operators 704 705Type-bound operators are in fact basically just @code{GENERIC} procedure 706bindings and are represented much in the same way as those (see 707@ref{Type-bound Procedures}). 708 709They come in two flavours: 710User-defined operators (like @code{.MYOPERATOR.}) 711are stored in the @code{f2k_derived} namespace's @code{tb_uop_root} 712symtree exactly like ordinary type-bound procedures are stored in 713@code{tb_sym_root}; their symtrees' names are the operator-names (e.g. 714@samp{myoperator} in the example). 715Intrinsic operators on the other hand are stored in the namespace's 716array member @code{tb_op} indexed by the intrinsic operator's enum 717value. Those need not be packed into @code{gfc_symtree} structures and are 718only @code{gfc_typebound_proc} instances. 719 720When an operator call or assignment is found that cannot be handled in 721another way (i.e. neither matches an intrinsic nor interface operator 722definition) but that contains a derived-type expression, all type-bound 723operators defined on that derived-type are checked for a match with 724the operator call. If there's indeed a relevant definition, the 725operator call is replaced with an internally generated @code{GENERIC} 726type-bound procedure call to the respective definition and that call is 727further processed. 728 729@c --------------------------------------------------------------------- 730@c - Translating to GENERIC 731@c --------------------------------------------------------------------- 732 733@node Translating to GENERIC 734@chapter Generating the intermediate language for later stages. 735 736This chapter deals with the transformation of gfortran's frontend data 737structures to the intermediate language used by the later stages of 738the compiler, the so-called middle end. 739 740Data structures relating to this are found in the source files 741@file{trans*.h} and @file{trans-*.c}. 742 743@menu 744* Basic Data Structures:: Basic data structures. 745* Converting Expressions:: Converting expressions to tree. 746* Translating Statements:: Translating statements. 747* Accessing Declarations:: Accessing declarations. 748@end menu 749 750@node Basic Data Structures 751@section Basic data structures 752 753Gfortran creates GENERIC as an intermediate language for the 754middle-end. Details about GENERIC can be found in the GCC manual. 755 756The basic data structure of GENERIC is a @code{tree}. Everything in 757GENERIC is a @code{tree}, including types and statements. Fortunately 758for the gfortran programmer, @code{tree} variables are 759garbage-collected, so doing memory management for them is not 760necessary. 761 762@code{tree} expressions are built using functions such as, for 763example, @code{fold_build2_loc}. For two tree variables @code{a} and 764@code{b}, both of which have the type @code{gfc_arry_index_type}, 765calculation @code{c = a * b} would be done by 766 767@smallexample 768c = fold_build2_loc (input_location, MULT_EXPR, 769 gfc_array_index_type, a, b); 770@end smallexample 771 772The types have to agree, otherwise internal compiler errors will occur 773at a later stage. Expressions can be converted to a different type 774using @code{fold_convert}. 775 776Accessing individual members in the @code{tree} structures should not 777be done. Rather, access should be done via macros. 778 779One basic data structure is the @code{stmtblock_t} struct. This is 780used for holding a list of statements, expressed as @code{tree} 781expressions. If a block is created using @code{gfc_start_block}, it 782has its own scope for variables; if it is created using 783@code{gfc_init_block}, it does not have its own scope. 784 785It is possible to 786@itemize @bullet 787@item Add an expression to the end of a block using 788 @code{gfc_add_expr_to_block} 789@item Add an expression to the beginning of a block using 790 @code{void gfc_prepend_expr_to_block} 791@item Make a block into a single @code{tree} using 792 @code{gfc_finish_block}. For example, this is needed to put the 793 contents of a block into the @code{if} or @code{else} branch of 794 a @code{COND_EXPR}. 795@end itemize 796 797Variables are also @code{tree} expressions, they can be created using 798@code{gfc_create_var}. Assigning to a variable can be done with 799@code{gfc_add_modify}. 800 801An example: Creating a default integer type variable in the current 802scope with the prefix ``everything'' in the @code{stmt_block} 803@code{block} and assigning the value 42 would be 804 805@smallexample 806tree var, *block; 807/* Initialize block somewhere here. */ 808var = gfc_create_var (integer_type_node, "everything"); 809gfc_add_modify (block, var, build_int_cst (integer_type_node, 42)); 810@end smallexample 811 812@node Converting Expressions 813@section Converting Expressions to tree 814 815Converting expressions to @code{tree} is done by functions called 816@code{gfc_conv_*}. 817 818The central data structure for a GENERIC expression is the 819@code{gfc_se} structure. Its @code{expr} member is a @code{tree} that 820holds the value of the expression. A @code{gfc_se} structure is 821initialized using @code{gfc_init_se}; it needs to be embedded in an 822outer @code{gfc_se}. 823 824Evaluating Fortran expressions often require things to be done before 825and after evaluation of the expression, for example code for the 826allocation of a temporary variable and its subsequent deallocation. 827Therefore, @code{gfc_se} contains the members @code{pre} and 828@code{post}, which point to @code{stmt_block} blocks for code that 829needs to be executed before and after evaluation of the expression. 830 831When using a local @code{gfc_se} to convert some expression, it is 832often necessary to add the generated @code{pre} and @code{post} blocks 833to the @code{pre} or @code{post} blocks of the outer @code{gfc_se}. 834Code like this (lifted from @file{trans-expr.c}) is fairly common: 835 836@smallexample 837gfc_se cont_se; 838tree cont_var; 839 840/* cont_var = is_contiguous (expr); . */ 841gfc_init_se (&cont_se, parmse); 842gfc_conv_is_contiguous_expr (&cont_se, expr); 843gfc_add_block_to_block (&se->pre, &(&cont_se)->pre); 844gfc_add_modify (&se->pre, cont_var, cont_se.expr); 845gfc_add_block_to_block (&se->pre, &(&cont_se)->post); 846@end smallexample 847 848Conversion functions which need a @code{gfc_se} structure will have a 849corresponding argument. 850 851@code{gfc_se} also contains pointers to a @code{gfc_ss} and a 852@code{gfc_loopinfo} structure. These are needed by the scalarizer. 853 854@node Translating Statements 855@section Translating statements 856Translating statements to @code{tree} is done by functions called 857@code{gfc_trans_*}. These functions usually get passed a 858@code{gfc_code} structure, evaluate any expressions and then 859return a @code{tree} structure. 860 861@node Accessing Declarations 862@section Accessing declarations 863 864@code{gfc_symbol}, @code{gfc_charlen} and other front-end structures 865contain a @code{backend_decl} variable, which contains the @code{tree} 866used for accessing that entity in the middle-end. 867 868Accessing declarations is usually done by functions called 869@code{gfc_get*}. 870 871@c --------------------------------------------------------------------- 872@c LibGFortran 873@c --------------------------------------------------------------------- 874 875@node LibGFortran 876@chapter The LibGFortran Runtime Library 877 878@menu 879* Symbol Versioning:: Symbol Versioning. 880@end menu 881 882 883@c --------------------------------------------------------------------- 884@c Symbol Versioning 885@c --------------------------------------------------------------------- 886 887@node Symbol Versioning 888@section Symbol Versioning 889@comment Based on https://gcc.gnu.org/wiki/SymbolVersioning, 890@comment as of 2006-11-05, written by Janne Blomqvist. 891 892In general, this capability exists only on a few platforms, thus there 893is a need for configure magic so that it is used only on those targets 894where it is supported. 895 896The central concept in symbol versioning is the so-called map file, 897which specifies the version node(s) exported symbols are labeled with. 898Also, the map file is used to hide local symbols. 899 900Some relevant references: 901@itemize @bullet 902@item 903@uref{https://sourceware.org/binutils/docs/ld/VERSION.html, 904GNU @command{ld} manual} 905 906@item 907@uref{https://www.akkadia.org/drepper/symbol-versioning, ELF Symbol 908Versioning - Ulrich Depper} 909 910@item 911@uref{https://www.akkadia.org/drepper/dsohowto.pdf, How to Write Shared 912Libraries - Ulrich Drepper (see Chapter 3)} 913 914@end itemize 915 916If one adds a new symbol to a library that should be exported, the new 917symbol should be mentioned in the map file and a new version node 918defined, e.g., if one adds a new symbols @code{foo} and @code{bar} to 919libgfortran for the next GCC release, the following should be added to 920the map file: 921@smallexample 922GFORTRAN_1.1 @{ 923 global: 924 foo; 925 bar; 926@} GFORTRAN_1.0; 927@end smallexample 928@noindent 929where @code{GFORTRAN_1.0} is the version node of the current release, 930and @code{GFORTRAN_1.1} is the version node of the next release where 931foo and bar are made available. 932 933If one wants to change an existing interface, it is possible by using 934some asm trickery (from the @command{ld} manual referenced above): 935 936@smallexample 937__asm__(".symver original_foo,foo@@"); 938__asm__(".symver old_foo,foo@@VERS_1.1"); 939__asm__(".symver old_foo1,foo@@VERS_1.2"); 940__asm__(".symver new_foo,foo@@VERS_2.0"); 941@end smallexample 942 943In this example, @code{foo@@} represents the symbol @code{foo} bound to 944the unspecified base version of the symbol. The source file that 945contains this example would define 4 C functions: @code{original_foo}, 946@code{old_foo}, @code{old_foo1}, and @code{new_foo}. 947 948In this case the map file must contain @code{foo} in @code{VERS_1.1} 949and @code{VERS_1.2} as well as in @code{VERS_2.0}. 950 951 952@c --------------------------------------------------------------------- 953@c GNU Free Documentation License 954@c --------------------------------------------------------------------- 955 956@include fdl.texi 957 958 959@c --------------------------------------------------------------------- 960@c Index 961@c --------------------------------------------------------------------- 962 963@node Index 964@unnumbered Index 965 966@printindex cp 967 968@bye 969