1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set copyrights-gfortran 2007
6 @include gcc-common.texi
8 @settitle GNU Fortran Compiler Internals
12 @c Use with @@smallbook.
14 @c %** start of document
16 @c Cause even numbered pages to be printed on the left hand side of
17 @c the page and odd numbered pages to be printed on the right hand
18 @c side of the page. Using this, you can print on both sides of a
19 @c sheet of paper and have the text on the same part of the sheet.
21 @c The text on right hand pages is pushed towards the right hand
22 @c margin and the text on left hand pages is pushed toward the left
24 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
27 @c \global\bindingoffset=0.75in
28 @c \global\normaloffset =0.75in
32 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
34 Permission is granted to copy, distribute and/or modify this document
35 under the terms of the GNU Free Documentation License, Version 1.1 or
36 any later version published by the Free Software Foundation; with the
37 Invariant Sections being ``GNU General Public License'' and ``Funding
38 Free Software'', the Front-Cover
39 texts being (a) (see below), and with the Back-Cover Texts being (b)
40 (see below). A copy of the license is included in the section entitled
41 ``GNU Free Documentation License''.
43 (a) The FSF's Front-Cover Text is:
47 (b) The FSF's Back-Cover Text is:
49 You have freedom to copy and modify this GNU Manual, like GNU
50 software. Copies published by the Free Software Foundation raise
51 funds for GNU development.
55 @dircategory Software development
57 * gfortran: (gfortran). The GNU Fortran Compiler.
59 This file documents the internals of the GNU Fortran
60 compiler, (@command{gfortran}).
62 Published by the Free Software Foundation
63 51 Franklin Street, Fifth Floor
64 Boston, MA 02110-1301 USA
70 @setchapternewpage odd
72 @title GNU Fortran Internals
74 @author The @t{gfortran} team
76 @vskip 0pt plus 1filll
77 Published by the Free Software Foundation@*
78 51 Franklin Street, Fifth Floor@*
79 Boston, MA 02110-1301, USA@*
80 @c Last printed ??ber, 19??.@*
81 @c Printed copies are available for $? each.@*
92 @c ---------------------------------------------------------------------
93 @c TexInfo table of contents.
94 @c ---------------------------------------------------------------------
101 This manual documents the internals of @command{gfortran},
102 the GNU Fortran compiler.
105 @emph{Warning:} This document, and the compiler it describes, are still
106 under development. While efforts are made to keep it up-to-date, it might
107 not accurately reflect the status of the most recent GNU Fortran compiler.
111 @comment When you add a new menu item, please keep the right hand
112 @comment aligned to the same column. Do not use tabs. This provides
113 @comment better formatting.
116 * Introduction:: About this manual.
117 * User Interface:: Code that Interacts with the User.
118 * LibGFortran:: The LibGFortran Runtime Library.
119 * GNU Free Documentation License::
120 How you can copy and share this manual.
121 * Index:: Index of this documentation.
125 @c ---------------------------------------------------------------------
127 @c ---------------------------------------------------------------------
130 @chapter Introduction
132 @c The following duplicates the text on the TexInfo table of contents.
134 This manual documents the internals of @command{gfortran}, the GNU Fortran
138 @emph{Warning:} This document, and the compiler it describes, are still
139 under development. While efforts are made to keep it up-to-date, it
140 might not accurately reflect the status of the most recent GNU Fortran
145 At present, this manual is very much a work in progress, containing
146 miscellaneous notes about the internals of the compiler. It is hoped
147 that at some point in the future it will become a reasonably complete
148 guide; in the interim, GNU Fortran developers are strongly encouraged to
149 contribute to it as a way of keeping notes while working on the
153 @c ---------------------------------------------------------------------
154 @c Code that Interacts with the User
155 @c ---------------------------------------------------------------------
158 @chapter Code that Interacts with the User
161 * Command-Line Options:: Command-Line Options.
162 * Error Handling:: Error Handling.
166 @c ---------------------------------------------------------------------
167 @c Command-Line Options
168 @c ---------------------------------------------------------------------
170 @node Command-Line Options
171 @section Command-Line Options
173 Command-line options for @command{gfortran} involve four interrelated
174 pieces within the Fortran compiler code.
176 The relevant command-line flag is defined in @file{lang.opt}, according
177 to the documentation in @ref{Options,, Options, gccint, GNU Compiler
178 Collection Internals}. This is then processed by the overall GCC
179 machinery to create the code that enables @command{gfortran} and
180 @command{gcc} to recognize the option in the command-line arguments and
181 call the relevant handler function.
183 This generated code calls the @code{gfc_handle_option} code in
184 @file{options.c} with an enumerator variable indicating which option is
185 to be processed, and the relevant integer or string values associated
186 with that option flag. Typically, @code{gfc_handle_option} uses these
187 arguments to set global flags which record the option states.
189 The global flags that record the option states are stored in the
190 @code{gfc_option_t} struct, which is defined in @file{gfortran.h}.
191 Before the options are processed, initial values for these flags are set
192 in @code{gfc_init_option} in @file{options.c}; these become the default
193 values for the options.
197 @c ---------------------------------------------------------------------
199 @c ---------------------------------------------------------------------
202 @section Error Handling
204 The GNU Fortran compiler's parser operates by testing each piece of
205 source code against a variety of matchers. In some cases, if these
206 matchers do not match the source code, they will store an error message
207 in a buffer. If the parser later finds a matcher that does correctly
208 match the source code, then the buffered error is discarded. However,
209 if the parser cannot find a match, then the buffered error message is
210 reported to the user. This enables the compiler to provide more
211 meaningful error messages even in the many cases where (erroneous)
212 Fortran syntax is ambiguous due to things like the absence of reserved
215 As an example of how this works, consider the following line:
219 Hypothetically, this may get passed to the matcher for an @code{IF}
220 statement. Since this could plausibly be an erroneous @code{IF}
221 statement, the matcher will buffer an error message reporting the
222 absence of an expected @samp{(} following an @code{IF}. Since no
223 matchers reported an error-free match, however, the parser will also try
224 matching this against a variable assignment. When @code{IF} is a valid
225 variable, this will be parsed as an assignment statement, and the error
226 discarded. However, when @code{IF} is not a valid variable, this
227 buffered error message will be reported to the user.
229 The error handling code is implemented in @file{error.c}. Errors are
230 normally entered into the buffer with the @code{gfc_error} function.
231 Warnings go through a similar buffering process, and are entered into
232 the buffer with @code{gfc_warning}. There is also a special-purpose
233 function, @code{gfc_notify_std}, for things which have an error/warning
234 status that depends on the currently-selected language standard.
236 The @code{gfc_error_check} function checks the buffer for errors,
237 reports the error message to the user if one exists, clears the buffer,
238 and returns a flag to the user indicating whether or not an error
239 existed. To check the state of the buffer without changing its state or
240 reporting the errors, the @code{gfc_error_flag_test} function can be
241 used. The @code{gfc_clear_error} function will clear out any errors in
242 the buffer, without reporting them. The @code{gfc_warning_check} and
243 @code{gfc_clear_warning} functions provide equivalent functionality for
246 Only one error and one warning can be in the buffers at a time, and
247 buffering another will overwrite the existing one. In cases where one
248 may wish to work on a smaller piece of source code without disturbing an
249 existing error state, the @code{gfc_push_error}, @code{gfc_pop_error},
250 and @code{gfc_free_error} mechanism exists to implement a stack for the
253 For cases where an error or warning should be reported immediately
254 rather than buffered, the @code{gfc_error_now} and
255 @code{gfc_warning_now} functions can be used. Normally, the compiler
256 will continue attempting to parse the program after an error has
257 occurred, but if this is not appropriate, the @code{gfc_fatal_error}
258 function should be used instead. For errors that are always the result
259 of a bug somewhere in the compiler, the @code{gfc_internal_error}
260 function should be used.
262 The syntax for the strings used to produce the error/warning message in
263 the various error and warning functions is similar to the @code{printf}
264 syntax, with @samp{%}-escapes to insert variable values. The details,
265 and the allowable codes, are documented in the @code{error_print}
266 function in @file{error.c}.
270 @c ---------------------------------------------------------------------
272 @c ---------------------------------------------------------------------
275 @chapter The LibGFortran Runtime Library
278 * Symbol Versioning:: Symbol Versioning.
282 @c ---------------------------------------------------------------------
284 @c ---------------------------------------------------------------------
286 @node Symbol Versioning
287 @section Symbol Versioning
288 @comment Based on http://gcc.gnu.org/wiki/SymbolVersioning,
289 @comment as of 2006-11-05, written by Janne Blomqvist.
291 In general, this capability exists only on a few platforms, thus there
292 is a need for configure magic so that it is used only on those targets
293 where it is supported.
295 The central concept in symbol versioning is the so-called map file,
296 which specifies the version node(s) exported symbols are labeled with.
297 Also, the map file is used to hide local symbols.
299 Some relevant references:
302 @uref{http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html,
303 GNU @command{ld} manual}
306 @uref{http://people.redhat.com/drepper/symbol-versioning, ELF Symbol
307 Versioning - Ulrich Depper}
310 @uref{http://people.redhat.com/drepper/dsohowto.pdf, How to Write Shared
311 Libraries - Ulrich Depper (see Chapter 3)}
315 If one adds a new symbol to a library that should be exported, the new
316 symbol should be mentioned in the map file and a new version node
317 defined, e.g. if one adds a new symbols @code{foo} and @code{bar} to
318 libgfortran for the next GCC release, the following should be added to
328 where @code{GFORTRAN_1.0} is the version node of the current release,
329 and @code{GFORTRAN_1.1} is the version node of the next release where
330 foo and bar are made available.
332 If one wants to change an existing interface, it is possible by using
333 some asm trickery (from the @command{ld} manual referenced above):
336 __asm__(".symver original_foo,foo@@");
337 __asm__(".symver old_foo,foo@@VERS_1.1");
338 __asm__(".symver old_foo1,foo@@VERS_1.2");
339 __asm__(".symver new_foo,foo@@VERS_2.0");
342 In this example, @code{foo@@} represents the symbol @code{foo} bound to
343 the unspecified base version of the symbol. The source file that
344 contains this example would define 4 C functions: @code{original_foo},
345 @code{old_foo}, @code{old_foo1}, and @code{new_foo}.
347 In this case the map file must contain @code{foo} in @code{VERS_1.1}
348 and @code{VERS_1.2} as well as in @code{VERS_2.0}.
351 @c ---------------------------------------------------------------------
352 @c GNU Free Documentation License
353 @c ---------------------------------------------------------------------
358 @c ---------------------------------------------------------------------
360 @c ---------------------------------------------------------------------