1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set copyrights-gfortran 1999-2005
6 @include gcc-common.texi
8 @settitle The GNU Fortran 95 Compiler
10 @c Create a separate index for command line options
12 @c Merge the standard indexes into a single one.
21 @c Use with @@smallbook.
23 @c %** start of document
25 @c Cause even numbered pages to be printed on the left hand side of
26 @c the page and odd numbered pages to be printed on the right hand
27 @c side of the page. Using this, you can print on both sides of a
28 @c sheet of paper and have the text on the same part of the sheet.
30 @c The text on right hand pages is pushed towards the right hand
31 @c margin and the text on left hand pages is pushed toward the left
33 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
36 @c \global\bindingoffset=0.75in
37 @c \global\normaloffset =0.75in
41 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
43 Permission is granted to copy, distribute and/or modify this document
44 under the terms of the GNU Free Documentation License, Version 1.1 or
45 any later version published by the Free Software Foundation; with the
46 Invariant Sections being ``GNU General Public License'' and ``Funding
47 Free Software'', the Front-Cover
48 texts being (a) (see below), and with the Back-Cover Texts being (b)
49 (see below). A copy of the license is included in the section entitled
50 ``GNU Free Documentation License''.
52 (a) The FSF's Front-Cover Text is:
56 (b) The FSF's Back-Cover Text is:
58 You have freedom to copy and modify this GNU Manual, like GNU
59 software. Copies published by the Free Software Foundation raise
60 funds for GNU development.
64 @dircategory Programming
66 * gfortran: (gfortran). The GNU Fortran 95 Compiler.
68 This file documents the use and the internals of
69 the GNU Fortran 95 compiler, (@command{gfortran}).
71 Published by the Free Software Foundation
72 51 Franklin Street, Fifth Floor
73 Boston, MA 02110-1301 USA
78 Contributed by Steven Bosscher (@email{s.bosscher@@gcc.gnu.org}).
80 @setchapternewpage odd
82 @title Using GNU Fortran 95
84 @center Steven Bosscher
86 @vskip 0pt plus 1filll
87 For the @value{version-GCC} Version*
89 Published by the Free Software Foundation @*
90 51 Franklin Street, Fifth Floor@*
91 Boston, MA 02110-1301, USA@*
92 @c Last printed ??ber, 19??.@*
93 @c Printed copies are available for $? each.@*
102 @node Top, Copying,, (DIR)
106 This manual documents the use of @command{gfortran},
107 the GNU Fortran 95 compiler. You can find in this manual how to invoke
108 @command{gfortran}, as well as its features and incompatibilities.
111 @emph{Warning:} This document, and the compiler it describes, are still
112 under development. While efforts are made to keep it up-to-date, it might
113 not accurately reflect the status of the most recent @command{gfortran}.
117 @comment When you add a new menu item, please keep the right hand
118 @comment aligned to the same column. Do not use tabs. This provides
119 @comment better formatting.
122 * Copying:: GNU General Public License says
123 how you can copy and share GNU Fortran.
124 * GNU Free Documentation License::
125 How you can copy and share this manual.
126 * Funding:: How to help assure continued work for free software.
127 * Getting Started:: What you should know about @command{gfortran}.
128 * GFORTRAN and GCC:: You can compile Fortran, C, or other programs.
129 * GFORTRAN and G77:: Why we chose to start from scratch.
130 * Invoking GFORTRAN:: Command options supported by @command{gfortran}.
131 * Project Status:: Status of @command{gfortran}, roadmap, proposed extensions.
132 * Contributing:: How you can help.
133 * Standards:: Standards supported by @command{gfortran}
134 * Extensions:: Language extensions implemented by @command{gfortran}
135 * Intrinsic Procedures:: Intrinsic procedures supported by @command{gfortran}
136 * Index:: Index of this documentation.
141 @c ---------------------------------------------------------------------
142 @c GNU General Public License
143 @c ---------------------------------------------------------------------
149 @c ---------------------------------------------------------------------
150 @c GNU Free Documentation License
151 @c ---------------------------------------------------------------------
157 @c ---------------------------------------------------------------------
158 @c Funding Free Software
159 @c ---------------------------------------------------------------------
161 @include funding.texi
165 @c ---------------------------------------------------------------------
167 @c ---------------------------------------------------------------------
169 @node Getting Started
170 @chapter Getting Started
172 Gfortran is the GNU Fortran 95 compiler front end,
173 designed initially as a free replacement for,
174 or alternative to, the unix @command{f95} command;
175 @command{gfortran} is the command you'll use to invoke the compiler.
177 Gfortran is still in an early state of development.
178 @command{gfortran} can generate code for most constructs and expressions,
179 but much work remains to be done.
181 When @command{gfortran} is finished,
182 it will do everything you expect from any decent compiler:
186 Read a user's program,
187 stored in a file and containing instructions written
188 in Fortran 77, Fortran 90 or Fortran 95.
189 This file contains @dfn{source code}.
192 Translate the user's program into instructions a computer
193 can carry out more quickly than it takes to translate the
194 instructions in the first
195 place. The result after compilation of a program is
197 code designed to be efficiently translated and processed
198 by a machine such as your computer.
199 Humans usually aren't as good writing machine code
200 as they are at writing Fortran (or C++, Ada, or Java),
201 because is easy to make tiny mistakes writing machine code.
204 Provide the user with information about the reasons why
205 the compiler is unable to create a binary from the source code.
206 Usually this will be the case if the source code is flawed.
207 When writing Fortran, it is easy to make big mistakes.
208 The Fortran 90 requires that the compiler can point out
209 mistakes to the user.
210 An incorrect usage of the language causes an @dfn{error message}.
212 The compiler will also attempt to diagnose cases where the
213 user's program contains a correct usage of the language,
214 but instructs the computer to do something questionable.
215 This kind of diagnostics message is called a @dfn{warning message}.
218 Provide optional information about the translation passes
219 from the source code to machine code.
220 This can help a user of the compiler to find the cause of
221 certain bugs which may not be obvious in the source code,
222 but may be more easily found at a lower level compiler output.
223 It also helps developers to find bugs in the compiler itself.
226 Provide information in the generated machine code that can
227 make it easier to find bugs in the program (using a debugging tool,
228 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
231 Locate and gather machine code already generated to
232 perform actions requested by statements in the user's program.
233 This machine code is organized into @dfn{modules} and is located
234 and @dfn{linked} to the user program.
237 Gfortran consists of several components:
241 A version of the @command{gcc} command
242 (which also might be installed as the system's @command{cc} command)
243 that also understands and accepts Fortran source code.
244 The @command{gcc} command is the @dfn{driver} program for
245 all the languages in the GNU Compiler Collection (GCC);
247 you can compile the source code of any language for
248 which a front end is available in GCC.
251 The @command{gfortran} command itself,
252 which also might be installed as the
253 system's @command{f95} command.
254 @command{gfortran} is just another driver program,
255 but specifically for the Fortran 95 compiler only.
256 The difference with @command{gcc} is that @command{gfortran}
257 will automatically link the correct libraries to your program.
260 A collection of run-time libraries.
261 These libraries contain the machine code needed to support
262 capabilities of the Fortran language that are not directly
263 provided by the machine code generated by the
264 @command{gfortran} compilation phase,
265 such as intrinsic functions and subroutines,
266 and routines for interaction with files and the operating system.
267 @c and mechanisms to spawn,
268 @c unleash and pause threads in parallelized code.
271 The Fortran compiler itself, (@command{f951}).
272 This is the gfortran parser and code generator,
273 linked to and interfaced with the GCC backend library.
274 @command{f951} ``translates'' the source code to
275 assembler code. You would typically not use this
277 instead, the @command{gcc} or @command{gfortran} driver
278 programs will call it for you.
283 @c ---------------------------------------------------------------------
285 @c ---------------------------------------------------------------------
287 @node GFORTRAN and GCC
288 @chapter GFORTRAN and GCC
289 @cindex GNU Compiler Collection
291 GCC used to be the GNU ``C'' Compiler,
292 but is now known as the @dfn{GNU Compiler Collection}.
293 GCC provides the GNU system with a very versatile
294 compiler middle end (shared optimization passes),
295 and back ends (code generators) for many different
296 computer architectures and operating systems.
297 The code of the middle end and back end are shared by all
298 compiler front ends that are in the GNU Compiler Collection.
300 A GCC front end is essentially a source code parser
301 and an intermediate code generator. The code generator translates the
302 semantics of the source code into a language independent form called
305 The parser takes a source file written in a
306 particular computer language, reads and parses it,
307 and tries to make sure that the source code conforms to
309 Once the correctness of a program has been established,
310 the compiler will build a data structure known as the
311 @dfn{Abstract Syntax tree},
312 or just @dfn{AST} or ``tree'' for short.
313 This data structure represents the whole program
314 or a subroutine or a function.
315 The ``tree'' is passed to the GCC middle end,
316 which will perform optimization passes on it. The optimized AST is then
317 handed off too the back end which assembles the program unit.
319 Different phases in this translation process can be,
320 and in fact @emph{are} merged in many compiler front ends.
321 GNU Fortran 95 has a strict separation between the
322 parser and code generator.
324 The goal of the gfortran project is to build a new front end for GCC.
325 Specifically, a Fortran 95 front end.
326 In a non-gfortran installation,
327 @command{gcc} will not be able to compile Fortran 95 source code
328 (only the ``C'' front end has to be compiled if you want to build GCC,
329 all other languages are optional).
330 If you build GCC with gfortran, @command{gcc} will recognize
331 @file{.f/.f90/.f95} source files and accepts Fortran 95 specific
332 command line options.
336 @c ---------------------------------------------------------------------
338 @c ---------------------------------------------------------------------
340 @node GFORTRAN and G77
341 @chapter GFORTRAN and G77
345 Why do we write a compiler front end from scratch?
346 There's a fine Fortran 77 compiler in the
347 GNU Compiler Collection that accepts some features
348 of the Fortran 90 standard as extensions.
349 Why not start from there and revamp it?
351 One of the reasons is that Craig Burley, the author of G77,
352 has decided to stop working on the G77 front end.
353 On @uref{http://world.std.com/~burley/g77-why.html,
354 Craig explains the reasons for his decision to stop working on G77}
355 in one of the pages in his homepage.
356 Among the reasons is a lack of interest in improvements to
358 Users appear to be quite satisfied with @command{g77} as it is.
359 While @command{g77} is still being maintained (by Toon Moene),
360 it is unlikely that sufficient people will be willing
361 to completely rewrite the existing code.
363 But there are other reasons to start from scratch.
364 Many people, including Craig Burley,
365 no longer agreed with certain design decisions in the G77 front end.
366 Also, the interface of @command{g77} to the back end is written in
367 a style which is confusing and not up to date on recommended practice.
368 In fact, a full rewrite had already been planned for GCC 3.0.
370 When Craig decided to stop,
371 it just seemed to be a better idea to start a new project from scratch,
372 because it was expected to be easier to maintain code we
373 develop ourselves than to do a major overhaul of @command{g77} first,
374 and then build a Fortran 95 compiler out of it.
378 @c ---------------------------------------------------------------------
380 @c ---------------------------------------------------------------------
383 @chapter Project Status
386 As soon as gfortran can parse all of the statements correctly,
387 it will be in the ``larva'' state.
388 When we generate code, the ``puppa'' state.
389 When gfortran is done,
390 we'll see if it will be a beautiful butterfly,
391 or just a big bug....
393 --Andy Vaught, April 2000
396 The start of the GNU Fortran 95 project was announced on
397 the GCC homepage in March 18, 2000
398 (even though Andy had already been working on it for a while,
401 Gfortran is currently reaching the stage where is is able to compile real
402 world programs. However it is still under development and has many rough
408 * Proposed Extensions::
411 @node Compiler Status
412 @section Compiler Status
416 This is the part of gfortran which parses a source file, verifies that it
417 is valid Fortran 95, performs compile time replacement of constants
418 (PARAMETER variables) and reads and generate module files. This is
419 almost complete. Every Fortran 95 source should be accepted, and most
420 none-Fortran 95 source should be rejected. If you find a source file where
421 this is not true, please tell us. You can use the -fsyntax-only switch to
422 make gfortran quit after running the front end, effectively reducing it to
425 @item Middle end interface
426 These are the parts of gfortran that take the parse tree generated by the
427 front end and translate it to the GENERIC form required by the GCC back
428 end. Work is ongoing in these parts of gfortran, but a large part has
429 already been completed.
433 @section Library Status
435 Some intrinsic functions map directly to library functions, and in most
436 cases the name of the library function used depends on the type of the
437 arguments. For some intrinsics we generate inline code, and for others,
438 such as sin, cos and sqrt, we rely on the backend to use special
439 instructions in the floating point unit of the CPU if available, or to
440 fall back to a call to libm if these are not available.
442 Implementation of some non-elemental intrinsic functions (eg. DOT_PRODUCT,
443 AVERAGE) is not yet optimal. This is hard because we have to make decisions
444 whether to use inline code (good for small arrays as no function call
445 overhead occurs) or generate function calls (good for large arrays as it
446 allows use of hand-optimized assembly routines, SIMD instructions, etc.)
448 The IO library is still under development. The following features should be
449 usable for real programs:
453 @item Unformatted sequential
459 @item Formatted sequential ('T' edit descriptor, and others)
465 @item Unformatted direct access
466 @item Formatted direct access
469 Many Fortran programs only use a small subset of the available IO
470 capabilities, so your mileage may vary.
472 @node Proposed Extensions
473 @section Proposed Extensions
475 Here's a list of proposed extensions for @command{gfortran}, in no particular
476 order. Most of these are necessary to be fully compatible with
477 existing Fortran compilers, but they are not part of the official
478 J3 Fortran 95 standard.
480 @subsection Compiler extensions:
483 Flag for defining the kind number for default logicals.
486 User-specified alignment rules for structures.
488 Flag to generate @code{Makefile} info.
491 Automatically extend single precision constants to double.
494 Cray pointers (this was high on the @command{g77} wishlist).
497 Compile code that conserves memory by dynamically allocating common and
498 module storage either on stack or heap.
501 Flag to cause the compiler to distinguish between upper and lower case
502 names. The Fortran 95 standard does not distinguish them.
505 Compile flag to generate code for array conformance checking (suggest -CC).
508 User control of symbol names (underscores, etc).
511 Compile setting for maximum size of stack frame size before spilling
512 parts to static or heap.
515 Flag to force local variables into static space.
518 Flag to force local variables onto stack.
521 Flag to compile lines beginning with ``D''.
524 Flag to ignore lines beginning with ``D''.
527 Flag for maximum errors before ending compile.
530 Generate code to check for null pointer dereferences -- prints locus of
531 dereference instead of segfaulting. There was some discussion about this
532 option in the g95 development mailing list.
535 Allow setting the default unit number.
538 Option to initialize otherwise uninitialized integer and floating
542 Support for OpenMP directives. This also requires support from the runtime
543 library and the rest of the compiler.
546 Support for Fortran 200x. This includes several new features including
547 floating point exceptions, extended use of allocatable arrays, C
548 interoperability, Parameterizer data types and function pointers.
552 @subsection Environment Options
555 Pluggable library modules for random numbers, linear algebra.
556 LA should use BLAS calling conventions.
559 Environment variables controlling actions on arithmetic exceptions like
560 overflow, underflow, precision loss -- Generate NaN, abort, default.
564 Set precision for fp units that support it (i387).
567 Variable for setting fp rounding mode.
570 Variable to fill uninitialized variables with a user-defined bit
574 Environment variable controlling filename that is opened for that unit
578 Environment variable to clear/trash memory being freed.
581 Environment variable to control tracing of allocations and frees.
584 Environment variable to display allocated memory at normal program end.
587 Environment variable for filename for * IO-unit.
590 Environment variable for temporary file directory.
593 Environment variable forcing standard output to be line buffered (unix).
596 Variable for swapping endianness during unformatted read.
599 Variable for swapping Endianness during unformatted write.
602 @c ---------------------------------------------------------------------
604 @c ---------------------------------------------------------------------
606 @c Maybe this chapter should be merged with the 'Standards' section,
607 @c whenever that is written :-)
613 @command{gfortran} implements a number of extensions over standard
614 Fortran. This chapter contains information on their syntax and
615 meaning. There are currently two categories of @command{gfortran}
616 extensions, those that provide functionality beyond that provided
617 by any standard, and those that are supported by @command{gfortran}
618 purely for backward compatibility with legacy compilers. By default,
619 @option{-std=gnu} allows the compiler to accept both types of
620 extensions, but to warn about the use of the latter. Specifying
621 either @option{-std=f95} or @option{-std=f2003} disables both types
622 of extensions, and @option{-std=legacy} allows both without warning.
625 * Old-style kind specifications::
626 * Old-style variable initialization::
627 * Extensions to namelist::
628 * X format descriptor::
629 * Commas in FORMAT specifications::
631 * Hexadecimal constants::
632 * Real array indices::
634 * Implicitly interconvert LOGICAL and INTEGER::
637 @node Old-style kind specifications
638 @section Old-style kind specifications
639 @cindex Kind specifications
641 @command{gfortran} allows old-style kind specifications in
642 declarations. These look like:
646 where @code{TYPESPEC} is a basic type, and where @code{k} is a valid kind
647 number for that type. The statement then declares @code{x}, @code{y}
648 and @code{z} to be of type @code{TYPESPEC} with kind @code{k}. In
649 other words, it is equivalent to the standard conforming declaration
654 @node Old-style variable initialization
655 @section Old-style variable initialization
656 @cindex Initialization
658 @command{gfortran} allows old-style initialization of variables of the
662 REAL*8 x(2,2) /3*0.,1./
664 These are only allowed in declarations without double colons
665 (@code{::}), as these were introduced in Fortran 90 which also
666 introduced a new syntax for variable initializations. The syntax for
667 the individual initializers is as for the @code{DATA} statement, but
668 unlike in a @code{DATA} statement, an initializer only applies to the
669 variable immediately preceding. In other words, something like
670 @code{INTEGER I,J/2,3/} is not valid.
672 Examples of standard conforming code equivalent to the above example, are:
675 INTEGER(4) :: i = 1, j = 2
676 REAL(8) :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
679 DOUBLE PRECISION x(2,2)
680 DATA i,j,x /1,2,3*0.,1./
683 @node Extensions to namelist
684 @section Extensions to namelist
687 @command{gfortran} fully supports the Fortran 95 standard for namelist I/O
688 including array qualifiers, substrings and fully qualified derived types.
689 The output from a namelist write is compatible with namelist read. The
690 output has all names in upper case and indentation to column 1 after the
691 namelist name. Two extensions are permitted:
693 Old-style use of $ instead of &
696 X(:)%Y(2) = 1.0 2.0 3.0
701 It should be noticed that the default terminator is / rather than &END.
703 Querying of the namelist when inputting from stdin. After at least
704 one space, entering ? sends to stdout the namelist name and the names of
705 the variables in the namelist:
716 Entering =? outputs the namelist to stdout, as if WRITE (*,NML = mynml)
722 X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
723 X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
724 X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
728 To aid this dialog, when input is from stdin, errors send their
729 messages to stderr and execution continues, even if IOSTAT is set.
731 @node X format descriptor
732 @section X format descriptor
733 @cindex X format descriptor
735 To support legacy codes, @command{gfortran} permits the count field
736 of the X edit descriptor in FORMAT statements to be omitted. When
737 omitted, the count is implicitly assumed to be one.
741 10 FORMAT (I1, X, I1)
744 @node Commas in FORMAT specifications
745 @section Commas in FORMAT specifications
746 @cindex Commas in FORMAT specifications
748 To support legacy codes, @command{gfortran} allows the comma separator
749 to be omitted immediately before and after character string edit
750 descriptors in FORMAT statements.
754 10 FORMAT ('FOO='I1' BAR='I2)
758 @section I/O item lists
759 @cindex I/O item lists
761 To support legacy codes, @command{gfortran} allows the input item list
762 of the READ statement, and the output item lists of the WRITE and PRINT
763 statements to start with a comma.
765 @node Hexadecimal constants
766 @section Hexadecimal constants
767 @cindex Hexadecimal constants
769 As a GNU extension, @command{gfortran} allows hexadecimal constants to
770 be specified using the X prefix, in addition to the standard Z prefix.
772 @node Real array indices
773 @section Real array indices
774 @cindex Real array indices
776 As a GNU extension, @command{gfortran} allows arrays to be indexed using
777 real types, whose values are implicitly converted to integers.
779 @node Unary operators
780 @section Unary operators
781 @cindex Unary operators
783 As a GNU extension, @command{gfortran} allows unary plus and unary
784 minus operators to appear as the second operand of binary arithmetic
785 operators without the need for parenthesis.
791 @node Implicitly interconvert LOGICAL and INTEGER
792 @section Implicitly interconvert LOGICAL and INTEGER
793 @cindex Implicitly interconvert LOGICAL and INTEGER
795 As a GNU extension for backwards compatibility with other compilers,
796 @command{gfortran} allows the implicit conversion of LOGICALs to INTEGERs
797 and vice versa. When converting from a LOGICAL to an INTEGER, the numeric
798 value of @code{.FALSE.} is zero, and that of @code{.TRUE.} is one. When
799 converting from INTEGER to LOGICAL, the value zero is interpreted as
800 @code{.FALSE.} and any non-zero value is interpreted as @code{.TRUE.}.
807 @include intrinsic.texi
808 @c ---------------------------------------------------------------------
810 @c ---------------------------------------------------------------------
813 @chapter Contributing
816 Free software is only possible if people contribute to efforts
818 We're always in need of more people helping out with ideas
819 and comments, writing documentation and contributing code.
821 If you want to contribute to GNU Fortran 95,
822 have a look at the long lists of projects you can take on.
823 Some of these projects are small,
824 some of them are large;
825 some are completely orthogonal to the rest of what is
826 happening on @command{gfortran},
827 but others are ``mainstream'' projects in need of enthusiastic hackers.
828 All of these projects are important!
829 We'll eventually get around to the things here,
830 but they are also things doable by someone who is willing and able.
839 @section Contributors to GNU Fortran 95
844 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
845 also the initiator of the whole project. Thanks Andy!
846 Most of the interface with GCC was written by @emph{Paul Brook}.
848 The following individuals have contributed code and/or
849 ideas and significant help to the gfortran project
850 (in no particular order):
854 @item Katherine Holcomb
855 @item Tobias Schlüter
856 @item Steven Bosscher
859 @item Niels Kristian Bech Jensen
866 The following people have contributed bug reports,
867 smaller or larger patches,
868 and much needed feedback and encouragement for the
869 @command{gfortran} project:
877 Many other individuals have helped debug,
878 test and improve @command{gfortran} over the past two years,
879 and we welcome you to do the same!
880 If you already have done so,
881 and you would like to see your name listed in the
882 list above, please contact us.
890 @item Help build the test suite
891 Solicit more code for donation to the test suite.
892 We can keep code private on request.
894 @item Bug hunting/squishing
895 Find bugs and write more test cases!
896 Test cases are especially very welcome,
897 because it allows us to concentrate on fixing bugs
898 instead of isolating them.
900 @item Smaller projects (``bug'' fixes):
902 @item Allow init exprs to be numbers raised to integer powers.
903 @item Implement correct rounding.
904 @item Implement F restrictions on Fortran 95 syntax.
905 @item See about making Emacs-parsable error messages.
909 If you wish to work on the runtime libraries,
910 please contact a project maintainer.
914 @c ---------------------------------------------------------------------
916 @c ---------------------------------------------------------------------
922 The GNU Fortran 95 Compiler aims to be a conforming implementation of
923 ISO/IEC 1539:1997 (Fortran 95).
925 In the future it may also support other variants and extensions to the Fortran
926 language. This includes ANSI Fortran 77, Fortran 90, Fortran 2000 (not yet
927 finalized), and OpenMP.