]>
Commit | Line | Data |
---|---|---|
a191dd08 | 1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
39bc0e0c | 3 | @setfilename gfc-internals.info |
3d8932fd | 4 | @set copyrights-gfortran 2007-2019 |
a191dd08 | 5 | |
6 | @include gcc-common.texi | |
7 | ||
39bc0e0c | 8 | @synindex tp cp |
9 | ||
a191dd08 | 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 | |
711789cc | 34 | Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc. |
a191dd08 | 35 | |
36 | Permission is granted to copy, distribute and/or modify this document | |
2d0c81dc | 37 | under the terms of the GNU Free Documentation License, Version 1.3 or |
a191dd08 | 38 | any later version published by the Free Software Foundation; with the |
a4cb9727 | 39 | Invariant Sections being ``Funding Free Software'', the Front-Cover |
40 | Texts being (a) (see below), and with the Back-Cover Texts being (b) | |
a191dd08 | 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 | |
60 | This file documents the internals of the GNU Fortran | |
61 | compiler, (@command{gfortran}). | |
62 | ||
63 | Published by the Free Software Foundation | |
64 | 51 Franklin Street, Fifth Floor | |
65 | Boston, 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 | |
78 | Published by the Free Software Foundation@* | |
79 | 51 Franklin Street, Fifth Floor@* | |
80 | Boston, 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 | ||
102 | This manual documents the internals of @command{gfortran}, | |
103 | the GNU Fortran compiler. | |
104 | ||
105 | @ifset DEVELOPMENT | |
106 | @emph{Warning:} This document, and the compiler it describes, are still | |
107 | under development. While efforts are made to keep it up-to-date, it might | |
108 | not 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. | |
39bc0e0c | 119 | * Frontend Data Structures:: |
120 | Data structures used by the frontend | |
12347af6 | 121 | * Object Orientation:: Internals of Fortran 2003 OOP features. |
215235d7 | 122 | * Translating to GENERIC:: |
123 | Generating the intermediate language for later stages. | |
a191dd08 | 124 | * LibGFortran:: The LibGFortran Runtime Library. |
125 | * GNU Free Documentation License:: | |
c24c5fac | 126 | How you can copy and share this manual. |
a191dd08 | 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 | |
140 | This manual documents the internals of @command{gfortran}, the GNU Fortran | |
141 | compiler. | |
142 | ||
143 | @ifset DEVELOPMENT | |
144 | @emph{Warning:} This document, and the compiler it describes, are still | |
145 | under development. While efforts are made to keep it up-to-date, it | |
146 | might not accurately reflect the status of the most recent GNU Fortran | |
147 | compiler. | |
148 | @end ifset | |
149 | @end iftex | |
150 | ||
151 | At present, this manual is very much a work in progress, containing | |
152 | miscellaneous notes about the internals of the compiler. It is hoped | |
153 | that at some point in the future it will become a reasonably complete | |
154 | guide; in the interim, GNU Fortran developers are strongly encouraged to | |
155 | contribute to it as a way of keeping notes while working on the | |
156 | compiler. | |
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 | ||
179 | Command-line options for @command{gfortran} involve four interrelated | |
180 | pieces within the Fortran compiler code. | |
181 | ||
182 | The relevant command-line flag is defined in @file{lang.opt}, according | |
183 | to the documentation in @ref{Options,, Options, gccint, GNU Compiler | |
184 | Collection Internals}. This is then processed by the overall GCC | |
185 | machinery to create the code that enables @command{gfortran} and | |
186 | @command{gcc} to recognize the option in the command-line arguments and | |
187 | call the relevant handler function. | |
188 | ||
189 | This generated code calls the @code{gfc_handle_option} code in | |
190 | @file{options.c} with an enumerator variable indicating which option is | |
191 | to be processed, and the relevant integer or string values associated | |
192 | with that option flag. Typically, @code{gfc_handle_option} uses these | |
193 | arguments to set global flags which record the option states. | |
194 | ||
195 | The global flags that record the option states are stored in the | |
196 | @code{gfc_option_t} struct, which is defined in @file{gfortran.h}. | |
197 | Before the options are processed, initial values for these flags are set | |
198 | in @code{gfc_init_option} in @file{options.c}; these become the default | |
199 | values for the options. | |
200 | ||
201 | ||
202 | ||
203 | @c --------------------------------------------------------------------- | |
204 | @c Error Handling | |
205 | @c --------------------------------------------------------------------- | |
206 | ||
207 | @node Error Handling | |
208 | @section Error Handling | |
209 | ||
210 | The GNU Fortran compiler's parser operates by testing each piece of | |
211 | source code against a variety of matchers. In some cases, if these | |
212 | matchers do not match the source code, they will store an error message | |
213 | in a buffer. If the parser later finds a matcher that does correctly | |
214 | match the source code, then the buffered error is discarded. However, | |
215 | if the parser cannot find a match, then the buffered error message is | |
216 | reported to the user. This enables the compiler to provide more | |
217 | meaningful error messages even in the many cases where (erroneous) | |
218 | Fortran syntax is ambiguous due to things like the absence of reserved | |
219 | keywords. | |
220 | ||
221 | As an example of how this works, consider the following line: | |
222 | @smallexample | |
223 | IF = 3 | |
224 | @end smallexample | |
225 | Hypothetically, this may get passed to the matcher for an @code{IF} | |
226 | statement. Since this could plausibly be an erroneous @code{IF} | |
227 | statement, the matcher will buffer an error message reporting the | |
228 | absence of an expected @samp{(} following an @code{IF}. Since no | |
229 | matchers reported an error-free match, however, the parser will also try | |
230 | matching this against a variable assignment. When @code{IF} is a valid | |
231 | variable, this will be parsed as an assignment statement, and the error | |
232 | discarded. However, when @code{IF} is not a valid variable, this | |
233 | buffered error message will be reported to the user. | |
234 | ||
235 | The error handling code is implemented in @file{error.c}. Errors are | |
236 | normally entered into the buffer with the @code{gfc_error} function. | |
237 | Warnings go through a similar buffering process, and are entered into | |
238 | the buffer with @code{gfc_warning}. There is also a special-purpose | |
239 | function, @code{gfc_notify_std}, for things which have an error/warning | |
240 | status that depends on the currently-selected language standard. | |
241 | ||
242 | The @code{gfc_error_check} function checks the buffer for errors, | |
243 | reports the error message to the user if one exists, clears the buffer, | |
244 | and returns a flag to the user indicating whether or not an error | |
245 | existed. To check the state of the buffer without changing its state or | |
246 | reporting the errors, the @code{gfc_error_flag_test} function can be | |
247 | used. The @code{gfc_clear_error} function will clear out any errors in | |
248 | the buffer, without reporting them. The @code{gfc_warning_check} and | |
249 | @code{gfc_clear_warning} functions provide equivalent functionality for | |
250 | the warning buffer. | |
251 | ||
252 | Only one error and one warning can be in the buffers at a time, and | |
253 | buffering another will overwrite the existing one. In cases where one | |
254 | may wish to work on a smaller piece of source code without disturbing an | |
255 | existing error state, the @code{gfc_push_error}, @code{gfc_pop_error}, | |
256 | and @code{gfc_free_error} mechanism exists to implement a stack for the | |
257 | error buffer. | |
258 | ||
259 | For cases where an error or warning should be reported immediately | |
260 | rather than buffered, the @code{gfc_error_now} and | |
261 | @code{gfc_warning_now} functions can be used. Normally, the compiler | |
262 | will continue attempting to parse the program after an error has | |
263 | occurred, but if this is not appropriate, the @code{gfc_fatal_error} | |
264 | function should be used instead. For errors that are always the result | |
265 | of a bug somewhere in the compiler, the @code{gfc_internal_error} | |
266 | function should be used. | |
267 | ||
268 | The syntax for the strings used to produce the error/warning message in | |
269 | the various error and warning functions is similar to the @code{printf} | |
270 | syntax, with @samp{%}-escapes to insert variable values. The details, | |
271 | and the allowable codes, are documented in the @code{error_print} | |
272 | function in @file{error.c}. | |
273 | ||
39bc0e0c | 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 | ||
282 | This chapter should describe the details necessary to understand how | |
283 | the various @code{gfc_*} data are used and interact. In general it is | |
284 | advisable to read the code in @file{dump-parse-tree.c} as its routines | |
285 | should exhaust all possible valid combinations of content for these | |
286 | structures. | |
287 | ||
288 | @menu | |
15bb490a | 289 | * gfc_code:: Representation of Executable Statements. |
f397ca89 | 290 | * gfc_expr:: Representation of Values and Expressions. |
39bc0e0c | 291 | @end menu |
292 | ||
f397ca89 | 293 | |
15bb490a | 294 | @c gfc_code |
295 | @c -------- | |
296 | ||
39bc0e0c | 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 | ||
303 | The executable statements in a program unit are represented by a | |
304 | nested chain of @code{gfc_code} structures. The type of statement is | |
305 | identified by the @code{op} member of the structure, the different | |
306 | possible values are enumerated in @code{gfc_exec_op}. A special | |
307 | member of this @code{enum} is @code{EXEC_NOP} which is used to | |
22a3a209 | 308 | represent the various @code{END} statements if they carry a label. |
39bc0e0c | 309 | Depending on the type of statement some of the other fields will be |
310 | filled in. Fields that are generally applicable are the @code{next} | |
311 | and @code{here} fields. The former points to the next statement in | |
312 | the current block or is @code{NULL} if the current statement is the | |
313 | last in a block, @code{here} points to the statement label of the | |
314 | current statement. | |
315 | ||
316 | If the current statement is one of @code{IF}, @code{DO}, @code{SELECT} | |
2dd2bcbd | 317 | it starts a block, i.e.@: a nested level in the program. In order to |
39bc0e0c | 318 | represent this, the @code{block} member is set to point to a |
15bb490a | 319 | @code{gfc_code} structure whose @code{next} member starts the chain of |
320 | statements inside the block; this structure's @code{op} member should be set to | |
321 | the same value as the parent structure's @code{op} member. The @code{SELECT} | |
322 | and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF} | |
323 | and @code{ELSE} blocks or the various @code{CASE}s, respectively). These chains | |
324 | are linked-lists formed by the @code{block} members. | |
325 | ||
326 | Consider the following example code: | |
327 | ||
328 | @example | |
329 | IF (foo < 20) THEN | |
330 | PRINT *, "Too small" | |
331 | foo = 20 | |
332 | ELSEIF (foo > 50) THEN | |
333 | PRINT *, "Too large" | |
334 | foo = 50 | |
335 | ELSE | |
336 | PRINT *, "Good" | |
337 | END IF | |
338 | @end example | |
339 | ||
340 | This statement-block will be represented in the internal gfortran tree as | |
341 | follows, were the horizontal link-chains are those induced by the @code{next} | |
342 | members 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 | ||
360 | Conditionals are represented by @code{gfc_code} structures with their | |
361 | @code{op} member set to @code{EXEC_IF}. This structure's @code{block} | |
362 | member must point to another @code{gfc_code} node that is the header of the | |
363 | if-block. This header's @code{op} member must be set to @code{EXEC_IF}, too, | |
364 | its @code{expr} member holds the condition to check for, and its @code{next} | |
365 | should point to the code-chain of the statements to execute if the condition is | |
366 | true. | |
367 | ||
368 | If 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 | |
371 | structure 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 | |
374 | next @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 | |
381 | to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks. | |
382 | Their @code{block} member should point to a @code{gfc_code} structure heading | |
383 | the 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 | ||
386 | For @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 | |
388 | simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in | |
389 | the internal representation. | |
390 | ||
391 | Similarly, @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 | |
393 | variable and its range. | |
394 | ||
395 | ||
396 | @subsection @code{SELECT} Statements | |
397 | ||
398 | A @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 | |
400 | to evaluate and test. Its @code{block} member starts a list of @code{gfc_code} | |
401 | structures linked together by their @code{block} members that stores the various | |
402 | @code{CASE} parts. | |
403 | ||
404 | Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too, | |
405 | its @code{next} member points to the code-chain to be executed in the current | |
406 | case-block, and @code{extx.case_list} contains the case-values this block | |
407 | corresponds to. The @code{block} member links to the next case in the list. | |
a191dd08 | 408 | |
409 | ||
a8088e82 | 410 | @subsection @code{BLOCK} and @code{ASSOCIATE} |
411 | ||
412 | The code related to a @code{BLOCK} statement is stored inside an | |
413 | @code{gfc_code} structure (say @var{c}) | |
414 | with @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 | |
417 | construct is in @code{c.code}. | |
418 | ||
419 | @code{ASSOCIATE} constructs are based on @code{BLOCK} and thus also have | |
420 | the internal storage structure described above (including @code{EXEC_BLOCK}). | |
421 | However, for them @code{c.ext.block.assoc} is set additionally and points | |
422 | to a linked list of @code{gfc_association_list} structures. Those | |
423 | structures basically store a link of associate-names to target expressions. | |
424 | The associate-names themselves are still also added to the @code{BLOCK}'s | |
425 | namespace as ordinary symbols, but they have their @code{gfc_symbol}'s | |
426 | member @code{assoc} set also pointing to the association-list structure. | |
427 | This way associate-names can be distinguished from ordinary variables | |
428 | and their target expressions identified. | |
429 | ||
430 | For association to expressions (as opposed to variables), at the very beginning | |
431 | of the @code{BLOCK} construct assignments are automatically generated to | |
432 | set the corresponding variables to their target expressions' values, and | |
433 | later on the compiler simply disallows using such associate-names in contexts | |
434 | that may change the value. | |
435 | ||
436 | ||
f397ca89 | 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 | ||
445 | Expressions and ``values'', including constants, variable-, array- and | |
446 | component-references as well as complex expressions consisting of operators and | |
447 | function calls are internally represented as one or a whole tree of | |
448 | @code{gfc_expr} objects. The member @code{expr_type} specifies the overall | |
449 | type 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 | |
452 | the type, rank and, if applicable, shape of the whole expression or expression | |
453 | tree of which the current structure is the root. @code{where} is the locus of | |
454 | this expression in the source code. | |
455 | ||
671f48a4 | 456 | Depending on the flavor of the expression being described by the object |
f397ca89 | 457 | (that is, the value of its @code{expr_type} member), the corresponding structure |
458 | in the @code{value} union will usually contain additional data describing the | |
459 | expression's value in a type-specific manner. The @code{ref} member is used to | |
460 | build chains of (array-, component- and substring-) references if the expression | |
461 | in question contains such references, see below for details. | |
462 | ||
463 | ||
464 | @subsection Constants | |
465 | ||
466 | Scalar constants are represented by @code{gfc_expr} nodes with their | |
467 | @code{expr_type} set to @code{EXPR_CONSTANT}. The constant's value shall | |
468 | already 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 | ||
475 | Operator-expressions are expressions that are the result of the execution of | |
476 | some operator on one or two operands. The expressions have an @code{expr_type} | |
477 | of @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 | |
480 | two operands, and @code{operator} or @code{uop} describe the operator that | |
481 | should be evaluated on these operands, where @code{uop} describes a user-defined | |
482 | operator. | |
483 | ||
484 | ||
485 | @subsection Function Calls | |
486 | ||
487 | If the expression is the return value of a function-call, its @code{expr_type} | |
488 | is set to @code{EXPR_FUNCTION}, and @code{symtree} must point to the symtree | |
489 | identifying the function to be called. @code{value.function.actual} holds the | |
490 | actual arguments given to the function as a linked list of | |
491 | @code{gfc_actual_arglist} nodes. | |
492 | ||
493 | The other members of @code{value.function} describe the function being called | |
494 | in more detail, containing a link to the intrinsic symbol or user-defined | |
495 | function symbol if the call is to an intrinsic or external function, | |
496 | respectively. These values are determined during resolution-phase from the | |
497 | structure's @code{symtree} member. | |
498 | ||
12347af6 | 499 | A special case of function calls are ``component calls'' to type-bound |
500 | procedures; those have the @code{expr_type} @code{EXPR_COMPCALL} with | |
501 | @code{value.compcall} containing the argument list and the procedure called, | |
502 | while @code{symtree} and @code{ref} describe the object on which the procedure | |
503 | was called in the same way as a @code{EXPR_VARIABLE} expression would. | |
504 | @xref{Type-bound Procedures}. | |
505 | ||
f397ca89 | 506 | |
507 | @subsection Array- and Structure-Constructors | |
508 | ||
509 | Array- 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}, | |
512 | respectively. For structure constructors, @code{symtree} points to the | |
513 | derived-type symbol for the type being constructed. | |
514 | ||
515 | The values for initializing each array element or structure component are | |
516 | stored 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. | |
523 | Such 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 | |
525 | of the @code{NULL} expression is known, it is stored in @code{ts} (that's for | |
526 | instance the case for default-initializers of @code{ALLOCATABLE} components), | |
527 | but this member can also be set to @code{BT_UNKNOWN} if the information is not | |
528 | available (for instance, when the expression is a pointer-initializer | |
529 | @code{NULL()}). | |
530 | ||
531 | ||
532 | @subsection Variables and Reference Expressions | |
533 | ||
534 | Variable references are @code{gfc_expr} structures with their @code{expr_type} | |
535 | set to @code{EXPR_VARIABLE}; their @code{symtree} should point to the variable | |
536 | that is referenced. | |
537 | ||
538 | For this type of expression, it's also possible to chain array-, component- | |
539 | or substring-references to the original expression to get something like | |
540 | @samp{struct%component(2:5)}, where @code{component} is either an array or | |
541 | a @code{CHARACTER} member of @code{struct} that is of some derived-type. Such a | |
542 | chain 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 | |
544 | last @code{NULL} pointer): | |
545 | ||
546 | @smallexample | |
547 | EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==| | |
548 | @end smallexample | |
549 | ||
550 | If @code{component} is a string rather than an array, the last element would be | |
551 | a @code{REF_SUBSTRING} reference, of course. If the variable itself or some | |
552 | component referenced is an array and the expression should reference the whole | |
553 | array 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 | |
555 | an array-reference type of @code{AR_FULL}. Consider this example code: | |
556 | ||
557 | @smallexample | |
558 | TYPE :: mytype | |
559 | INTEGER :: array(42) | |
560 | END TYPE mytype | |
561 | ||
562 | TYPE(mytype) :: variable | |
563 | INTEGER :: local_array(5) | |
564 | ||
565 | CALL do_something (variable%array, local_array) | |
566 | @end smallexample | |
567 | ||
568 | The @code{gfc_expr} nodes representing the arguments to the @samp{do_something} | |
569 | call will have a reference-chain like this: | |
570 | ||
571 | @smallexample | |
572 | EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==| | |
573 | EXPR_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 | |
580 | reference of a constant string, as in the following code snippet: | |
581 | ||
582 | @smallexample | |
583 | x = "abcde"(1:2) | |
584 | @end smallexample | |
585 | ||
586 | In this case, @code{value.character} contains the full string's data as if it | |
587 | was a string constant, but the @code{ref} member is also set and points to a | |
588 | substring reference as described in the subsection above. | |
589 | ||
590 | ||
12347af6 | 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. | |
c557b81e | 600 | * Type-bound Operators:: Type-bound operators. |
12347af6 | 601 | @end menu |
602 | ||
603 | ||
604 | @c Type-bound procedures | |
605 | @c --------------------- | |
606 | ||
607 | @node Type-bound Procedures | |
608 | @section Type-bound Procedures | |
609 | ||
3323e9b1 | 610 | Type-bound procedures are stored in the @code{tb_sym_root} of the namespace |
12347af6 | 611 | @code{f2k_derived} associated with the derived-type symbol as @code{gfc_symtree} |
612 | nodes. The name and symbol of these symtrees corresponds to the binding-name | |
613 | of the procedure, i.e. the name that is used to call it from the context of an | |
614 | object of the derived-type. | |
615 | ||
3323e9b1 | 616 | In 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 | |
12347af6 | 618 | binding attributes (like @code{PASS} and @code{NOPASS}, @code{NON_OVERRIDABLE} |
619 | or the access-specifier), the binding's target(s) and, if the current binding | |
620 | overrides or extends an inherited binding of the same name, @code{overridden} | |
621 | points to this binding's @code{gfc_typebound_proc} structure. | |
622 | ||
623 | ||
624 | @subsection Specific Bindings | |
625 | @c -------------------------- | |
626 | ||
627 | For specific bindings (declared with @code{PROCEDURE}), if they have a | |
628 | passed-object argument, the passed-object dummy argument is first saved by its | |
629 | name, and later during resolution phase the corresponding argument is looked for | |
630 | and its position remembered as @code{pass_arg_num} in @code{gfc_typebound_proc}. | |
631 | The binding's target procedure is pointed-to by @code{u.specific}. | |
632 | ||
61c3b81d | 633 | @code{DEFERRED} bindings are just like ordinary specific bindings, except |
634 | that their @code{deferred} flag is set of course and that @code{u.specific} | |
635 | points to their ``interface'' defining symbol (might be an abstract interface) | |
636 | instead of the target procedure. | |
637 | ||
12347af6 | 638 | At the moment, all type-bound procedure calls are statically dispatched and |
639 | transformed into ordinary procedure calls at resolution time; their actual | |
640 | argument list is updated to include at the right position the passed-object | |
641 | argument, if applicable, and then a simple procedure call to the binding's | |
642 | target procedure is built. To handle dynamic dispatch in the future, this will | |
643 | be extended to allow special code generation during the trans-phase to dispatch | |
644 | based on the object's dynamic type. | |
645 | ||
646 | ||
647 | @subsection Generic Bindings | |
648 | @c ------------------------- | |
649 | ||
650 | Bindings declared as @code{GENERIC} store the specific bindings they target as | |
651 | a linked list using nodes of type @code{gfc_tbp_generic} in @code{u.generic}. | |
652 | For each specific target, the parser records its symtree and during resolution | |
653 | this symtree is bound to the corresponding @code{gfc_typebound_proc} structure | |
654 | of the specific target. | |
655 | ||
656 | Calls to generic bindings are handled entirely in the resolution-phase, where | |
657 | for the actual argument list present the matching specific binding is found | |
658 | and the call's target procedure (@code{value.compcall.tbp}) is re-pointed to | |
659 | the found specific binding and this call is subsequently handled by the logic | |
660 | for specific binding calls. | |
661 | ||
662 | ||
663 | @subsection Calls to Type-bound Procedures | |
664 | @c --------------------------------------- | |
665 | ||
666 | Calls to type-bound procedures are stored in the parse-tree as @code{gfc_expr} | |
667 | nodes of type @code{EXPR_COMPCALL}. Their @code{value.compcall.actual} saves | |
668 | the 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 | |
670 | in 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 | ||
674 | For code like this: | |
675 | @smallexample | |
676 | CALL myobj%procedure (arg1, arg2) | |
677 | @end smallexample | |
678 | @noindent | |
679 | the @code{CALL} is represented in the parse-tree as a @code{gfc_code} node of | |
680 | type @code{EXEC_COMPCALL}. The @code{expr} member of this node holds an | |
681 | expression of type @code{EXPR_COMPCALL} of the same structure as mentioned above | |
682 | except that its target procedure is of course a @code{SUBROUTINE} and not a | |
683 | @code{FUNCTION}. | |
684 | ||
c557b81e | 685 | Expressions that are generated internally (as expansion of a type-bound |
686 | operator call) may also use additional flags and members. | |
687 | @code{value.compcall.ignore_pass} signals that even though a @code{PASS} | |
688 | attribute may be present the actual argument list should not be updated because | |
689 | it 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); | |
692 | this is needed because type-bound operators can be called on a base-object that | |
693 | need not be of type @code{EXPR_VARIABLE} and thus representable in this way. | |
694 | Finally, if @code{value.compcall.assign} is set, the call was produced in | |
695 | expansion of a type-bound assignment; this means that proper dependency-checking | |
696 | needs 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 | ||
705 | Type-bound operators are in fact basically just @code{GENERIC} procedure | |
706 | bindings and are represented much in the same way as those (see | |
707 | @ref{Type-bound Procedures}). | |
708 | ||
709 | They come in two flavours: | |
710 | User-defined operators (like @code{.MYOPERATOR.}) | |
711 | are stored in the @code{f2k_derived} namespace's @code{tb_uop_root} | |
712 | symtree 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). | |
715 | Intrinsic operators on the other hand are stored in the namespace's | |
716 | array member @code{tb_op} indexed by the intrinsic operator's enum | |
717 | value. Those need not be packed into @code{gfc_symtree} structures and are | |
718 | only @code{gfc_typebound_proc} instances. | |
719 | ||
f4d3c071 | 720 | When an operator call or assignment is found that cannot be handled in |
c557b81e | 721 | another way (i.e. neither matches an intrinsic nor interface operator |
722 | definition) but that contains a derived-type expression, all type-bound | |
723 | operators defined on that derived-type are checked for a match with | |
724 | the operator call. If there's indeed a relevant definition, the | |
725 | operator call is replaced with an internally generated @code{GENERIC} | |
726 | type-bound procedure call to the respective definition and that call is | |
727 | further processed. | |
728 | ||
215235d7 | 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 | ||
736 | This chapter deals with the transformation of gfortran's frontend data | |
737 | structures to the intermediate language used by the later stages of | |
738 | the compiler, the so-called middle end. | |
739 | ||
740 | Data 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 | ||
753 | Gfortran creates GENERIC as an intermediate language for the | |
754 | middle-end. Details about GENERIC can be found in the GCC manual. | |
755 | ||
756 | The basic data structure of GENERIC is a @code{tree}. Everything in | |
757 | GENERIC is a @code{tree}, including types and statements. Fortunately | |
758 | for the gfortran programmer, @code{tree} variables are | |
759 | garbage-collected, so doing memory management for them is not | |
760 | necessary. | |
761 | ||
762 | @code{tree} expressions are built using functions such as, for | |
763 | example, @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}, | |
765 | calculation @code{c = a * b} would be done by | |
766 | ||
767 | @smallexample | |
768 | c = fold_build2_loc (input_location, MULT_EXPR, | |
769 | gfc_array_index_type, a, b); | |
770 | @end smallexample | |
771 | ||
772 | The types have to agree, otherwise internal compiler errors will occur | |
773 | at a later stage. Expressions can be converted to a different type | |
774 | using @code{fold_convert}. | |
775 | ||
776 | Accessing individual members in the @code{tree} structures should not | |
777 | be done. Rather, access should be done via macros. | |
778 | ||
779 | One basic data structure is the @code{stmtblock_t} struct. This is | |
780 | used for holding a list of statements, expressed as @code{tree} | |
781 | expressions. If a block is created using @code{gfc_start_block}, it | |
782 | has its own scope for variables; if it is created using | |
783 | @code{gfc_init_block}, it does not have its own scope. | |
784 | ||
785 | It 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 | ||
797 | Variables 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 | ||
801 | An example: Creating a default integer type variable in the current | |
802 | scope with the prefix ``everything'' in the @code{stmt_block} | |
803 | @code{block} and assigning the value 42 would be | |
804 | ||
805 | @smallexample | |
806 | tree var, *block; | |
807 | /* Initialize block somewhere here. */ | |
808 | var = gfc_create_var (integer_type_node, "everything"); | |
809 | gfc_add_modify (block, var, build_int_cst (integer_type_node, 42)); | |
810 | @end smallexample | |
811 | ||
812 | @node Converting Expressions | |
813 | @section Converting Expressons to tree | |
814 | ||
815 | Converting expressions to @code{tree} is done by functions called | |
816 | @code{gfc_conv_*}. | |
817 | ||
818 | The central data structure for a GENERIC expression is the | |
819 | @code{gfc_se} structure. Its @code{expr} member is a @code{tree} that | |
820 | holds the value of the expression. A @code{gfc_se} structure is | |
821 | initialized using @code{gfc_init_se}; it needs to be embedded in an | |
822 | outer @code{gfc_se}. | |
823 | ||
824 | Evaluating Fortran expressions often require things to be done before | |
825 | and after evaluation of the expression, for example code for the | |
826 | allocation of a temporary variable and its subsequent deallocation. | |
827 | Therefore, @code{gfc_se} contains the members @code{pre} and | |
828 | @code{post}, which point to @code{stmt_block} blocks for code that | |
829 | needs to be executed before and after evaluation of the expression. | |
830 | ||
831 | When using a local @code{gfc_se} to convert some expression, it is | |
832 | often necessary to add the generated @code{pre} and @code{post} blocks | |
833 | to the @code{pre} or @code{post} blocks of the outer @code{gfc_se}. | |
834 | Code like this (lifted from @file{trans-expr.c}) is fairly common: | |
835 | ||
836 | @smallexample | |
837 | gfc_se cont_se; | |
838 | tree cont_var; | |
839 | ||
840 | /* cont_var = is_contiguous (expr); . */ | |
841 | gfc_init_se (&cont_se, parmse); | |
842 | gfc_conv_is_contiguous_expr (&cont_se, expr); | |
843 | gfc_add_block_to_block (&se->pre, &(&cont_se)->pre); | |
844 | gfc_add_modify (&se->pre, cont_var, cont_se.expr); | |
845 | gfc_add_block_to_block (&se->pre, &(&cont_se)->post); | |
846 | @end smallexample | |
847 | ||
848 | Conversion functions which need a @code{gfc_se} structure will have a | |
849 | corresponding 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 | |
856 | Translating 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 | |
859 | return 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 | |
865 | contain a @code{backend_decl} variable, which contains the @code{tree} | |
866 | used for accessing that entity in the middle-end. | |
867 | ||
868 | Accessing declarations is usually done by functions called | |
869 | @code{gfc_get*}. | |
12347af6 | 870 | |
a191dd08 | 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 | |
84e17338 | 889 | @comment Based on https://gcc.gnu.org/wiki/SymbolVersioning, |
a191dd08 | 890 | @comment as of 2006-11-05, written by Janne Blomqvist. |
891 | ||
892 | In general, this capability exists only on a few platforms, thus there | |
893 | is a need for configure magic so that it is used only on those targets | |
894 | where it is supported. | |
895 | ||
896 | The central concept in symbol versioning is the so-called map file, | |
897 | which specifies the version node(s) exported symbols are labeled with. | |
898 | Also, the map file is used to hide local symbols. | |
899 | ||
900 | Some relevant references: | |
901 | @itemize @bullet | |
902 | @item | |
84e17338 | 903 | @uref{https://sourceware.org/binutils/docs/ld/VERSION.html, |
a191dd08 | 904 | GNU @command{ld} manual} |
905 | ||
906 | @item | |
ae587dd8 | 907 | @uref{https://www.akkadia.org/drepper/symbol-versioning, ELF Symbol |
a191dd08 | 908 | Versioning - Ulrich Depper} |
909 | ||
910 | @item | |
ae587dd8 | 911 | @uref{https://www.akkadia.org/drepper/dsohowto.pdf, How to Write Shared |
2dd2bcbd | 912 | Libraries - Ulrich Drepper (see Chapter 3)} |
a191dd08 | 913 | |
914 | @end itemize | |
915 | ||
916 | If one adds a new symbol to a library that should be exported, the new | |
917 | symbol should be mentioned in the map file and a new version node | |
2dd2bcbd | 918 | defined, e.g., if one adds a new symbols @code{foo} and @code{bar} to |
a191dd08 | 919 | libgfortran for the next GCC release, the following should be added to |
920 | the map file: | |
921 | @smallexample | |
922 | GFORTRAN_1.1 @{ | |
923 | global: | |
924 | foo; | |
925 | bar; | |
926 | @} GFORTRAN_1.0; | |
927 | @end smallexample | |
928 | @noindent | |
929 | where @code{GFORTRAN_1.0} is the version node of the current release, | |
930 | and @code{GFORTRAN_1.1} is the version node of the next release where | |
931 | foo and bar are made available. | |
932 | ||
933 | If one wants to change an existing interface, it is possible by using | |
934 | some 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 | ||
943 | In this example, @code{foo@@} represents the symbol @code{foo} bound to | |
944 | the unspecified base version of the symbol. The source file that | |
945 | contains this example would define 4 C functions: @code{original_foo}, | |
946 | @code{old_foo}, @code{old_foo1}, and @code{new_foo}. | |
947 | ||
948 | In this case the map file must contain @code{foo} in @code{VERS_1.1} | |
949 | and @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 |