| \input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename gfc-internals.info |
| @set copyrights-gfortran 2007 |
| |
| @include gcc-common.texi |
| |
| @synindex tp cp |
| |
| @settitle GNU Fortran Compiler Internals |
| |
| @c %**end of header |
| |
| @c Use with @@smallbook. |
| |
| @c %** start of document |
| |
| @c Cause even numbered pages to be printed on the left hand side of |
| @c the page and odd numbered pages to be printed on the right hand |
| @c side of the page. Using this, you can print on both sides of a |
| @c sheet of paper and have the text on the same part of the sheet. |
| |
| @c The text on right hand pages is pushed towards the right hand |
| @c margin and the text on left hand pages is pushed toward the left |
| @c hand margin. |
| @c (To provide the reverse effect, set bindingoffset to -0.75in.) |
| |
| @c @tex |
| @c \global\bindingoffset=0.75in |
| @c \global\normaloffset =0.75in |
| @c @end tex |
| |
| @copying |
| Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.1 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``GNU General Public License'' and ``Funding |
| Free Software'', the Front-Cover |
| texts being (a) (see below), and with the Back-Cover Texts being (b) |
| (see below). A copy of the license is included in the section entitled |
| ``GNU Free Documentation License''. |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. |
| @end copying |
| |
| @ifinfo |
| @dircategory Software development |
| @direntry |
| * gfortran: (gfortran). The GNU Fortran Compiler. |
| @end direntry |
| This file documents the internals of the GNU Fortran |
| compiler, (@command{gfortran}). |
| |
| Published by the Free Software Foundation |
| 51 Franklin Street, Fifth Floor |
| Boston, MA 02110-1301 USA |
| |
| @insertcopying |
| @end ifinfo |
| |
| |
| @setchapternewpage odd |
| @titlepage |
| @title GNU Fortran Internals |
| @versionsubtitle |
| @author The @t{gfortran} team |
| @page |
| @vskip 0pt plus 1filll |
| Published by the Free Software Foundation@* |
| 51 Franklin Street, Fifth Floor@* |
| Boston, MA 02110-1301, USA@* |
| @c Last printed ??ber, 19??.@* |
| @c Printed copies are available for $? each.@* |
| @c ISBN ??? |
| @sp 1 |
| @insertcopying |
| @end titlepage |
| |
| @summarycontents |
| @contents |
| |
| @page |
| |
| @c --------------------------------------------------------------------- |
| @c TexInfo table of contents. |
| @c --------------------------------------------------------------------- |
| |
| @ifnottex |
| @node Top |
| @top Introduction |
| @cindex Introduction |
| |
| This manual documents the internals of @command{gfortran}, |
| the GNU Fortran compiler. |
| |
| @ifset DEVELOPMENT |
| @emph{Warning:} This document, and the compiler it describes, are still |
| under development. While efforts are made to keep it up-to-date, it might |
| not accurately reflect the status of the most recent GNU Fortran compiler. |
| @end ifset |
| |
| @comment |
| @comment When you add a new menu item, please keep the right hand |
| @comment aligned to the same column. Do not use tabs. This provides |
| @comment better formatting. |
| @comment |
| @menu |
| * Introduction:: About this manual. |
| * User Interface:: Code that Interacts with the User. |
| * Frontend Data Structures:: |
| Data structures used by the frontend |
| * LibGFortran:: The LibGFortran Runtime Library. |
| * GNU Free Documentation License:: |
| How you can copy and share this manual. |
| * Index:: Index of this documentation. |
| @end menu |
| @end ifnottex |
| |
| @c --------------------------------------------------------------------- |
| @c Introduction |
| @c --------------------------------------------------------------------- |
| |
| @node Introduction |
| @chapter Introduction |
| |
| @c The following duplicates the text on the TexInfo table of contents. |
| @iftex |
| This manual documents the internals of @command{gfortran}, the GNU Fortran |
| compiler. |
| |
| @ifset DEVELOPMENT |
| @emph{Warning:} This document, and the compiler it describes, are still |
| under development. While efforts are made to keep it up-to-date, it |
| might not accurately reflect the status of the most recent GNU Fortran |
| compiler. |
| @end ifset |
| @end iftex |
| |
| At present, this manual is very much a work in progress, containing |
| miscellaneous notes about the internals of the compiler. It is hoped |
| that at some point in the future it will become a reasonably complete |
| guide; in the interim, GNU Fortran developers are strongly encouraged to |
| contribute to it as a way of keeping notes while working on the |
| compiler. |
| |
| |
| @c --------------------------------------------------------------------- |
| @c Code that Interacts with the User |
| @c --------------------------------------------------------------------- |
| |
| @node User Interface |
| @chapter Code that Interacts with the User |
| |
| @menu |
| * Command-Line Options:: Command-Line Options. |
| * Error Handling:: Error Handling. |
| @end menu |
| |
| |
| @c --------------------------------------------------------------------- |
| @c Command-Line Options |
| @c --------------------------------------------------------------------- |
| |
| @node Command-Line Options |
| @section Command-Line Options |
| |
| Command-line options for @command{gfortran} involve four interrelated |
| pieces within the Fortran compiler code. |
| |
| The relevant command-line flag is defined in @file{lang.opt}, according |
| to the documentation in @ref{Options,, Options, gccint, GNU Compiler |
| Collection Internals}. This is then processed by the overall GCC |
| machinery to create the code that enables @command{gfortran} and |
| @command{gcc} to recognize the option in the command-line arguments and |
| call the relevant handler function. |
| |
| This generated code calls the @code{gfc_handle_option} code in |
| @file{options.c} with an enumerator variable indicating which option is |
| to be processed, and the relevant integer or string values associated |
| with that option flag. Typically, @code{gfc_handle_option} uses these |
| arguments to set global flags which record the option states. |
| |
| The global flags that record the option states are stored in the |
| @code{gfc_option_t} struct, which is defined in @file{gfortran.h}. |
| Before the options are processed, initial values for these flags are set |
| in @code{gfc_init_option} in @file{options.c}; these become the default |
| values for the options. |
| |
| |
| |
| @c --------------------------------------------------------------------- |
| @c Error Handling |
| @c --------------------------------------------------------------------- |
| |
| @node Error Handling |
| @section Error Handling |
| |
| The GNU Fortran compiler's parser operates by testing each piece of |
| source code against a variety of matchers. In some cases, if these |
| matchers do not match the source code, they will store an error message |
| in a buffer. If the parser later finds a matcher that does correctly |
| match the source code, then the buffered error is discarded. However, |
| if the parser cannot find a match, then the buffered error message is |
| reported to the user. This enables the compiler to provide more |
| meaningful error messages even in the many cases where (erroneous) |
| Fortran syntax is ambiguous due to things like the absence of reserved |
| keywords. |
| |
| As an example of how this works, consider the following line: |
| @smallexample |
| IF = 3 |
| @end smallexample |
| Hypothetically, this may get passed to the matcher for an @code{IF} |
| statement. Since this could plausibly be an erroneous @code{IF} |
| statement, the matcher will buffer an error message reporting the |
| absence of an expected @samp{(} following an @code{IF}. Since no |
| matchers reported an error-free match, however, the parser will also try |
| matching this against a variable assignment. When @code{IF} is a valid |
| variable, this will be parsed as an assignment statement, and the error |
| discarded. However, when @code{IF} is not a valid variable, this |
| buffered error message will be reported to the user. |
| |
| The error handling code is implemented in @file{error.c}. Errors are |
| normally entered into the buffer with the @code{gfc_error} function. |
| Warnings go through a similar buffering process, and are entered into |
| the buffer with @code{gfc_warning}. There is also a special-purpose |
| function, @code{gfc_notify_std}, for things which have an error/warning |
| status that depends on the currently-selected language standard. |
| |
| The @code{gfc_error_check} function checks the buffer for errors, |
| reports the error message to the user if one exists, clears the buffer, |
| and returns a flag to the user indicating whether or not an error |
| existed. To check the state of the buffer without changing its state or |
| reporting the errors, the @code{gfc_error_flag_test} function can be |
| used. The @code{gfc_clear_error} function will clear out any errors in |
| the buffer, without reporting them. The @code{gfc_warning_check} and |
| @code{gfc_clear_warning} functions provide equivalent functionality for |
| the warning buffer. |
| |
| Only one error and one warning can be in the buffers at a time, and |
| buffering another will overwrite the existing one. In cases where one |
| may wish to work on a smaller piece of source code without disturbing an |
| existing error state, the @code{gfc_push_error}, @code{gfc_pop_error}, |
| and @code{gfc_free_error} mechanism exists to implement a stack for the |
| error buffer. |
| |
| For cases where an error or warning should be reported immediately |
| rather than buffered, the @code{gfc_error_now} and |
| @code{gfc_warning_now} functions can be used. Normally, the compiler |
| will continue attempting to parse the program after an error has |
| occurred, but if this is not appropriate, the @code{gfc_fatal_error} |
| function should be used instead. For errors that are always the result |
| of a bug somewhere in the compiler, the @code{gfc_internal_error} |
| function should be used. |
| |
| The syntax for the strings used to produce the error/warning message in |
| the various error and warning functions is similar to the @code{printf} |
| syntax, with @samp{%}-escapes to insert variable values. The details, |
| and the allowable codes, are documented in the @code{error_print} |
| function in @file{error.c}. |
| |
| @c --------------------------------------------------------------------- |
| @c Frontend Data Structures |
| @c --------------------------------------------------------------------- |
| |
| @node Frontend Data Structures |
| @chapter Frontend Data Structures |
| @cindex data structures |
| |
| This chapter should describe the details necessary to understand how |
| the various @code{gfc_*} data are used and interact. In general it is |
| advisable to read the code in @file{dump-parse-tree.c} as its routines |
| should exhaust all possible valid combinations of content for these |
| structures. |
| |
| @menu |
| * gfc_code:: Representation of Executable Statements |
| @end menu |
| |
| @node gfc_code |
| @section @code{gfc_code} |
| @cindex statement chaining |
| @tindex @code{gfc_code} |
| @tindex @code{struct gfc_code} |
| |
| The executable statements in a program unit are represented by a |
| nested chain of @code{gfc_code} structures. The type of statement is |
| identified by the @code{op} member of the structure, the different |
| possible values are enumerated in @code{gfc_exec_op}. A special |
| member of this @code{enum} is @code{EXEC_NOP} which is used to |
| represent the various @code{END} statements if they carry a label. |
| Depending on the type of statement some of the other fields will be |
| filled in. Fields that are generally applicable are the @code{next} |
| and @code{here} fields. The former points to the next statement in |
| the current block or is @code{NULL} if the current statement is the |
| last in a block, @code{here} points to the statement label of the |
| current statement. |
| |
| If the current statement is one of @code{IF}, @code{DO}, @code{SELECT} |
| it starts a block, i.e. a nested level in the program. In order to |
| represent this, the @code{block} member is set to point to a |
| @code{gfc_code} structure whose @code{block} member points to the |
| block in question. The @code{SELECT} and @code{IF} statements may |
| contain various blocks (the chain of @code{ELSE IF} and @code{ELSE} |
| blocks or the various @code{CASE}s, respectively). |
| |
| @c What would be nice here would be an example program together with |
| @c an image that says more than the mythical thousand words. |
| |
| |
| @c --------------------------------------------------------------------- |
| @c LibGFortran |
| @c --------------------------------------------------------------------- |
| |
| @node LibGFortran |
| @chapter The LibGFortran Runtime Library |
| |
| @menu |
| * Symbol Versioning:: Symbol Versioning. |
| @end menu |
| |
| |
| @c --------------------------------------------------------------------- |
| @c Symbol Versioning |
| @c --------------------------------------------------------------------- |
| |
| @node Symbol Versioning |
| @section Symbol Versioning |
| @comment Based on http://gcc.gnu.org/wiki/SymbolVersioning, |
| @comment as of 2006-11-05, written by Janne Blomqvist. |
| |
| In general, this capability exists only on a few platforms, thus there |
| is a need for configure magic so that it is used only on those targets |
| where it is supported. |
| |
| The central concept in symbol versioning is the so-called map file, |
| which specifies the version node(s) exported symbols are labeled with. |
| Also, the map file is used to hide local symbols. |
| |
| Some relevant references: |
| @itemize @bullet |
| @item |
| @uref{http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html, |
| GNU @command{ld} manual} |
| |
| @item |
| @uref{http://people.redhat.com/drepper/symbol-versioning, ELF Symbol |
| Versioning - Ulrich Depper} |
| |
| @item |
| @uref{http://people.redhat.com/drepper/dsohowto.pdf, How to Write Shared |
| Libraries - Ulrich Depper (see Chapter 3)} |
| |
| @end itemize |
| |
| If one adds a new symbol to a library that should be exported, the new |
| symbol should be mentioned in the map file and a new version node |
| defined, e.g. if one adds a new symbols @code{foo} and @code{bar} to |
| libgfortran for the next GCC release, the following should be added to |
| the map file: |
| @smallexample |
| GFORTRAN_1.1 @{ |
| global: |
| foo; |
| bar; |
| @} GFORTRAN_1.0; |
| @end smallexample |
| @noindent |
| where @code{GFORTRAN_1.0} is the version node of the current release, |
| and @code{GFORTRAN_1.1} is the version node of the next release where |
| foo and bar are made available. |
| |
| If one wants to change an existing interface, it is possible by using |
| some asm trickery (from the @command{ld} manual referenced above): |
| |
| @smallexample |
| __asm__(".symver original_foo,foo@@"); |
| __asm__(".symver old_foo,foo@@VERS_1.1"); |
| __asm__(".symver old_foo1,foo@@VERS_1.2"); |
| __asm__(".symver new_foo,foo@@VERS_2.0"); |
| @end smallexample |
| |
| In this example, @code{foo@@} represents the symbol @code{foo} bound to |
| the unspecified base version of the symbol. The source file that |
| contains this example would define 4 C functions: @code{original_foo}, |
| @code{old_foo}, @code{old_foo1}, and @code{new_foo}. |
| |
| In this case the map file must contain @code{foo} in @code{VERS_1.1} |
| and @code{VERS_1.2} as well as in @code{VERS_2.0}. |
| |
| |
| @c --------------------------------------------------------------------- |
| @c GNU Free Documentation License |
| @c --------------------------------------------------------------------- |
| |
| @include fdl.texi |
| |
| |
| @c --------------------------------------------------------------------- |
| @c Index |
| @c --------------------------------------------------------------------- |
| |
| @node Index |
| @unnumbered Index |
| |
| @printindex cp |
| |
| @bye |