1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfc-internals.info
4 @set copyrights-gfortran 2007-2008
6 @include gcc-common.texi
10 @settitle GNU Fortran Compiler Internals
14 @c Use with @@smallbook.
16 @c %** start of document
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.
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
26 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
29 @c \global\bindingoffset=0.75in
30 @c \global\normaloffset =0.75in
34 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
36 Permission is granted to copy, distribute and/or modify this document
37 under the terms of the GNU Free Documentation License, Version 1.1 or
38 any later version published by the Free Software Foundation; with the
39 Invariant Sections being ``GNU General Public License'' and ``Funding
40 Free Software'', the Front-Cover
41 texts being (a) (see below), and with the Back-Cover Texts being (b)
42 (see below). A copy of the license is included in the section entitled
43 ``GNU Free Documentation License''.
45 (a) The FSF's Front-Cover Text is:
49 (b) The FSF's Back-Cover Text is:
51 You have freedom to copy and modify this GNU Manual, like GNU
52 software. Copies published by the Free Software Foundation raise
53 funds for GNU development.
57 @dircategory Software development
59 * gfortran: (gfortran). The GNU Fortran Compiler.
61 This file documents the internals of the GNU Fortran
62 compiler, (@command{gfortran}).
64 Published by the Free Software Foundation
65 51 Franklin Street, Fifth Floor
66 Boston, MA 02110-1301 USA
72 @setchapternewpage odd
74 @title GNU Fortran Internals
76 @author The @t{gfortran} team
78 @vskip 0pt plus 1filll
79 Published by the Free Software Foundation@*
80 51 Franklin Street, Fifth Floor@*
81 Boston, MA 02110-1301, USA@*
82 @c Last printed ??ber, 19??.@*
83 @c Printed copies are available for $? each.@*
94 @c ---------------------------------------------------------------------
95 @c TexInfo table of contents.
96 @c ---------------------------------------------------------------------
103 This manual documents the internals of @command{gfortran},
104 the GNU Fortran compiler.
107 @emph{Warning:} This document, and the compiler it describes, are still
108 under development. While efforts are made to keep it up-to-date, it might
109 not accurately reflect the status of the most recent GNU Fortran compiler.
113 @comment When you add a new menu item, please keep the right hand
114 @comment aligned to the same column. Do not use tabs. This provides
115 @comment better formatting.
118 * Introduction:: About this manual.
119 * User Interface:: Code that Interacts with the User.
120 * Frontend Data Structures::
121 Data structures used by the frontend
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.
129 @c ---------------------------------------------------------------------
131 @c ---------------------------------------------------------------------
134 @chapter Introduction
136 @c The following duplicates the text on the TexInfo table of contents.
138 This manual documents the internals of @command{gfortran}, the GNU Fortran
142 @emph{Warning:} This document, and the compiler it describes, are still
143 under development. While efforts are made to keep it up-to-date, it
144 might not accurately reflect the status of the most recent GNU Fortran
149 At present, this manual is very much a work in progress, containing
150 miscellaneous notes about the internals of the compiler. It is hoped
151 that at some point in the future it will become a reasonably complete
152 guide; in the interim, GNU Fortran developers are strongly encouraged to
153 contribute to it as a way of keeping notes while working on the
157 @c ---------------------------------------------------------------------
158 @c Code that Interacts with the User
159 @c ---------------------------------------------------------------------
162 @chapter Code that Interacts with the User
165 * Command-Line Options:: Command-Line Options.
166 * Error Handling:: Error Handling.
170 @c ---------------------------------------------------------------------
171 @c Command-Line Options
172 @c ---------------------------------------------------------------------
174 @node Command-Line Options
175 @section Command-Line Options
177 Command-line options for @command{gfortran} involve four interrelated
178 pieces within the Fortran compiler code.
180 The relevant command-line flag is defined in @file{lang.opt}, according
181 to the documentation in @ref{Options,, Options, gccint, GNU Compiler
182 Collection Internals}. This is then processed by the overall GCC
183 machinery to create the code that enables @command{gfortran} and
184 @command{gcc} to recognize the option in the command-line arguments and
185 call the relevant handler function.
187 This generated code calls the @code{gfc_handle_option} code in
188 @file{options.c} with an enumerator variable indicating which option is
189 to be processed, and the relevant integer or string values associated
190 with that option flag. Typically, @code{gfc_handle_option} uses these
191 arguments to set global flags which record the option states.
193 The global flags that record the option states are stored in the
194 @code{gfc_option_t} struct, which is defined in @file{gfortran.h}.
195 Before the options are processed, initial values for these flags are set
196 in @code{gfc_init_option} in @file{options.c}; these become the default
197 values for the options.
201 @c ---------------------------------------------------------------------
203 @c ---------------------------------------------------------------------
206 @section Error Handling
208 The GNU Fortran compiler's parser operates by testing each piece of
209 source code against a variety of matchers. In some cases, if these
210 matchers do not match the source code, they will store an error message
211 in a buffer. If the parser later finds a matcher that does correctly
212 match the source code, then the buffered error is discarded. However,
213 if the parser cannot find a match, then the buffered error message is
214 reported to the user. This enables the compiler to provide more
215 meaningful error messages even in the many cases where (erroneous)
216 Fortran syntax is ambiguous due to things like the absence of reserved
219 As an example of how this works, consider the following line:
223 Hypothetically, this may get passed to the matcher for an @code{IF}
224 statement. Since this could plausibly be an erroneous @code{IF}
225 statement, the matcher will buffer an error message reporting the
226 absence of an expected @samp{(} following an @code{IF}. Since no
227 matchers reported an error-free match, however, the parser will also try
228 matching this against a variable assignment. When @code{IF} is a valid
229 variable, this will be parsed as an assignment statement, and the error
230 discarded. However, when @code{IF} is not a valid variable, this
231 buffered error message will be reported to the user.
233 The error handling code is implemented in @file{error.c}. Errors are
234 normally entered into the buffer with the @code{gfc_error} function.
235 Warnings go through a similar buffering process, and are entered into
236 the buffer with @code{gfc_warning}. There is also a special-purpose
237 function, @code{gfc_notify_std}, for things which have an error/warning
238 status that depends on the currently-selected language standard.
240 The @code{gfc_error_check} function checks the buffer for errors,
241 reports the error message to the user if one exists, clears the buffer,
242 and returns a flag to the user indicating whether or not an error
243 existed. To check the state of the buffer without changing its state or
244 reporting the errors, the @code{gfc_error_flag_test} function can be
245 used. The @code{gfc_clear_error} function will clear out any errors in
246 the buffer, without reporting them. The @code{gfc_warning_check} and
247 @code{gfc_clear_warning} functions provide equivalent functionality for
250 Only one error and one warning can be in the buffers at a time, and
251 buffering another will overwrite the existing one. In cases where one
252 may wish to work on a smaller piece of source code without disturbing an
253 existing error state, the @code{gfc_push_error}, @code{gfc_pop_error},
254 and @code{gfc_free_error} mechanism exists to implement a stack for the
257 For cases where an error or warning should be reported immediately
258 rather than buffered, the @code{gfc_error_now} and
259 @code{gfc_warning_now} functions can be used. Normally, the compiler
260 will continue attempting to parse the program after an error has
261 occurred, but if this is not appropriate, the @code{gfc_fatal_error}
262 function should be used instead. For errors that are always the result
263 of a bug somewhere in the compiler, the @code{gfc_internal_error}
264 function should be used.
266 The syntax for the strings used to produce the error/warning message in
267 the various error and warning functions is similar to the @code{printf}
268 syntax, with @samp{%}-escapes to insert variable values. The details,
269 and the allowable codes, are documented in the @code{error_print}
270 function in @file{error.c}.
272 @c ---------------------------------------------------------------------
273 @c Frontend Data Structures
274 @c ---------------------------------------------------------------------
276 @node Frontend Data Structures
277 @chapter Frontend Data Structures
278 @cindex data structures
280 This chapter should describe the details necessary to understand how
281 the various @code{gfc_*} data are used and interact. In general it is
282 advisable to read the code in @file{dump-parse-tree.c} as its routines
283 should exhaust all possible valid combinations of content for these
287 * gfc_code:: Representation of Executable Statements.
294 @section @code{gfc_code}
295 @cindex statement chaining
296 @tindex @code{gfc_code}
297 @tindex @code{struct gfc_code}
299 The executable statements in a program unit are represented by a
300 nested chain of @code{gfc_code} structures. The type of statement is
301 identified by the @code{op} member of the structure, the different
302 possible values are enumerated in @code{gfc_exec_op}. A special
303 member of this @code{enum} is @code{EXEC_NOP} which is used to
304 represent the various @code{END} statements if they carry a label.
305 Depending on the type of statement some of the other fields will be
306 filled in. Fields that are generally applicable are the @code{next}
307 and @code{here} fields. The former points to the next statement in
308 the current block or is @code{NULL} if the current statement is the
309 last in a block, @code{here} points to the statement label of the
312 If the current statement is one of @code{IF}, @code{DO}, @code{SELECT}
313 it starts a block, i.e.@: a nested level in the program. In order to
314 represent this, the @code{block} member is set to point to a
315 @code{gfc_code} structure whose @code{next} member starts the chain of
316 statements inside the block; this structure's @code{op} member should be set to
317 the same value as the parent structure's @code{op} member. The @code{SELECT}
318 and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF}
319 and @code{ELSE} blocks or the various @code{CASE}s, respectively). These chains
320 are linked-lists formed by the @code{block} members.
322 Consider the following example code:
328 ELSEIF (foo > 50) THEN
336 This statement-block will be represented in the internal gfortran tree as
337 follows, were the horizontal link-chains are those induced by the @code{next}
338 members and vertical links down are those of @code{block}. @samp{==|} and
339 @samp{--|} mean @code{NULL} pointers to mark the end of a chain:
344 +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==|
346 +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==|
348 +--> ELSE ==> PRINT *, "Good" ==|
354 @subsection IF Blocks
356 Conditionals are represented by @code{gfc_code} structures with their
357 @code{op} member set to @code{EXEC_IF}. This structure's @code{block}
358 member must point to another @code{gfc_code} node that is the header of the
359 if-block. This header's @code{op} member must be set to @code{EXEC_IF}, too,
360 its @code{expr} member holds the condition to check for, and its @code{next}
361 should point to the code-chain of the statements to execute if the condition is
364 If in addition an @code{ELSEIF} or @code{ELSE} block is present, the
365 @code{block} member of the if-block-header node points to yet another
366 @code{gfc_code} structure that is the header of the elseif- or else-block. Its
367 structure is identical to that of the if-block-header, except that in case of an
368 @code{ELSE} block without a new condition the @code{expr} member should be
369 @code{NULL}. This block can itself have its @code{block} member point to the
370 next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
375 @code{DO} loops are stored in the tree as @code{gfc_code} nodes with their
376 @code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and
377 to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks.
378 Their @code{block} member should point to a @code{gfc_code} structure heading
379 the code-chain of the loop body; its @code{op} member should be set to
380 @code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively.
382 For @code{DO WHILE} loops, the loop condition is stored on the top
383 @code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are
384 simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in
385 the internal representation.
387 Similarly, @code{DO} loops with an iterator have instead of the condition their
388 @code{ext.iterator} member set to the correct values for the loop iterator
389 variable and its range.
392 @subsection @code{SELECT} Statements
394 A @code{SELECT} block is introduced by a @code{gfc_code} structure with an
395 @code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression
396 to evaluate and test. Its @code{block} member starts a list of @code{gfc_code}
397 structures linked together by their @code{block} members that stores the various
400 Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too,
401 its @code{next} member points to the code-chain to be executed in the current
402 case-block, and @code{extx.case_list} contains the case-values this block
403 corresponds to. The @code{block} member links to the next case in the list.
406 @c ---------------------------------------------------------------------
408 @c ---------------------------------------------------------------------
411 @chapter The LibGFortran Runtime Library
414 * Symbol Versioning:: Symbol Versioning.
418 @c ---------------------------------------------------------------------
420 @c ---------------------------------------------------------------------
422 @node Symbol Versioning
423 @section Symbol Versioning
424 @comment Based on http://gcc.gnu.org/wiki/SymbolVersioning,
425 @comment as of 2006-11-05, written by Janne Blomqvist.
427 In general, this capability exists only on a few platforms, thus there
428 is a need for configure magic so that it is used only on those targets
429 where it is supported.
431 The central concept in symbol versioning is the so-called map file,
432 which specifies the version node(s) exported symbols are labeled with.
433 Also, the map file is used to hide local symbols.
435 Some relevant references:
438 @uref{http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html,
439 GNU @command{ld} manual}
442 @uref{http://people.redhat.com/drepper/symbol-versioning, ELF Symbol
443 Versioning - Ulrich Depper}
446 @uref{http://people.redhat.com/drepper/dsohowto.pdf, How to Write Shared
447 Libraries - Ulrich Drepper (see Chapter 3)}
451 If one adds a new symbol to a library that should be exported, the new
452 symbol should be mentioned in the map file and a new version node
453 defined, e.g., if one adds a new symbols @code{foo} and @code{bar} to
454 libgfortran for the next GCC release, the following should be added to
464 where @code{GFORTRAN_1.0} is the version node of the current release,
465 and @code{GFORTRAN_1.1} is the version node of the next release where
466 foo and bar are made available.
468 If one wants to change an existing interface, it is possible by using
469 some asm trickery (from the @command{ld} manual referenced above):
472 __asm__(".symver original_foo,foo@@");
473 __asm__(".symver old_foo,foo@@VERS_1.1");
474 __asm__(".symver old_foo1,foo@@VERS_1.2");
475 __asm__(".symver new_foo,foo@@VERS_2.0");
478 In this example, @code{foo@@} represents the symbol @code{foo} bound to
479 the unspecified base version of the symbol. The source file that
480 contains this example would define 4 C functions: @code{original_foo},
481 @code{old_foo}, @code{old_foo1}, and @code{new_foo}.
483 In this case the map file must contain @code{foo} in @code{VERS_1.1}
484 and @code{VERS_1.2} as well as in @code{VERS_2.0}.
487 @c ---------------------------------------------------------------------
488 @c GNU Free Documentation License
489 @c ---------------------------------------------------------------------
494 @c ---------------------------------------------------------------------
496 @c ---------------------------------------------------------------------