1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set last-update 13 May 2004
5 @set copyrights-gfortran 1999-2004
7 @include gcc-common.texi
9 @settitle The GNU Fortran 95 Compiler
11 @c Create a separate index for command line options
13 @c Merge the standard indexes into a single one.
22 @c Use with @@smallbook.
24 @c %** start of document
26 @c Cause even numbered pages to be printed on the left hand side of
27 @c the page and odd numbered pages to be printed on the right hand
28 @c side of the page. Using this, you can print on both sides of a
29 @c sheet of paper and have the text on the same part of the sheet.
31 @c The text on right hand pages is pushed towards the right hand
32 @c margin and the text on left hand pages is pushed toward the left
34 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
37 @c \global\bindingoffset=0.75in
38 @c \global\normaloffset =0.75in
42 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
44 Permission is granted to copy, distribute and/or modify this document
45 under the terms of the GNU Free Documentation License, Version 1.1 or
46 any later version published by the Free Software Foundation; with the
47 Invariant Sections being ``GNU General Public License'' and ``Funding
48 Free Software'', the Front-Cover
49 texts being (a) (see below), and with the Back-Cover Texts being (b)
50 (see below). A copy of the license is included in the section entitled
51 ``GNU Free Documentation License''.
53 (a) The FSF's Front-Cover Text is:
57 (b) The FSF's Back-Cover Text is:
59 You have freedom to copy and modify this GNU Manual, like GNU
60 software. Copies published by the Free Software Foundation raise
61 funds for GNU development.
65 @dircategory Programming
67 * gfortran: (gfortran). The GNU Fortran 95 Compiler.
69 This file documents the use and the internals of
70 the GNU Fortran 95 compiler, (@command{gfortran}).
72 Published by the Free Software Foundation
73 59 Temple Place - Suite 330
74 Boston, MA 02111-1307 USA
79 Contributed by Steven Bosscher (@email{s.bosscher@@gcc.gnu.org}).
81 @setchapternewpage odd
83 @title Using GNU Fortran 95
85 @center Steven Bosscher
87 @center Last updated @value{last-update}
89 @center for version @value {version-GCC}
91 @vskip 0pt plus 1filll
92 For the @value{version-GCC} Version*
94 Published by the Free Software Foundation @*
95 59 Temple Place - Suite 330@*
96 Boston, MA 02111-1307, USA@*
97 @c Last printed ??ber, 19??.@*
98 @c Printed copies are available for $? each.@*
107 @node Top, Copying,, (DIR)
111 This manual documents the use of @command{gfortran},
112 the GNU Fortran 95 compiler. You can find in this manual how to invoke
113 @command{gfortran}, as well as its features and incompatibilities.
116 @emph{Warning:} This document, and the compiler it describes, are still
117 under development. While efforts are made too keep it up-to-date it might
118 not accurately reflect the status of the most recent @command{gfortran}.
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 choose 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:: Helping you can help.
133 * Standards:: Standards supported by @command{gfortran}
134 * Extensions:: Language extensions implemented by @command{gfortran}
135 * Index:: Index of this documentation.
140 @c ---------------------------------------------------------------------
141 @c GNU General Public License
142 @c ---------------------------------------------------------------------
148 @c ---------------------------------------------------------------------
149 @c GNU Free Documentation License
150 @c ---------------------------------------------------------------------
156 @c ---------------------------------------------------------------------
157 @c Funding Free Software
158 @c ---------------------------------------------------------------------
160 @include funding.texi
164 @c ---------------------------------------------------------------------
166 @c ---------------------------------------------------------------------
168 @node Getting Started
169 @chapter Getting Started
171 Gfortran is the GNU Fortran 95 compiler front end,
172 designed initially as a free replacement for,
173 or alternative to, the unix @command{f95} command;
174 @command{gfortran} is command you'll use to invoke the compiler.
176 Gfortran is still in an early state of development.
177 @command{gfortran} can generate code for most constructs and expressions,
178 but much work remains to be done.
180 When @command{gfortran} is finished,
181 it will do everything you expect from any decent compiler:
185 Read a user's program,
186 stored in a file and containing instructions written
187 in Fortran 77, Fortran 90 or Fortran 95.
188 This file contains @dfn{source code}.
191 Translate the user's program into instructions a computer
192 can carry out more quickly than it takes to translate the
193 instructions in the first
194 place. The result after compilation of a program is
196 code designed to be efficiently translated and processed
197 by a machine such as your computer.
198 Humans usually aren't as good writing machine code
199 as they are at writing Fortran (or C++, Ada, or Java),
200 because is easy to make tiny mistakes writing machine code.
203 Provide the user with information about the reasons why
204 the compiler is unable to create a binary from the source code.
205 Usually this will be the case if the source code is flawed.
206 When writing Fortran, it is easy to make big mistakes.
207 The Fortran 90 requires that the compiler can point out
208 mistakes to the user.
209 An incorrect usage of the language causes an @dfn{error message}.
211 The compiler will also attempt to diagnose cases where the
212 user's program contains a correct usage of the language,
213 but instructs the computer to do something questionable.
214 This kind of diagnostics message is called a @dfn{warning message}.
217 Provide optional information about the translation passes
218 from the source code to machine code.
219 This can help a user of the compiler to find the cause of
220 certain bugs which may not be obvious in the source code,
221 but may be more easily found at a lower level compiler output.
222 It also helps developers to find bugs in the compiler itself.
225 Provide information in the generated machine code that can
226 make it easier to find bugs in the program (using a debugging tool,
227 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
230 Locate and gather machine code already generated to
231 perform actions requested by statements in the user's program.
232 This machine code is organized into @dfn{modules} and is located
233 and @dfn{linked} to the user program.
236 Gfortran consists of several components:
240 A version of the @command{gcc} command
241 (which also might be installed as the system's @command{cc} command)
242 that also understands and accepts Fortran source code.
243 The @command{gcc} command is the @dfn{driver} program for
244 all the languages in the GNU Compiler Collection (GCC);
246 you can compiler the source code of any language for
247 which a front end is available in GCC.
250 The @command{gfortran} command itself,
251 which also might be installed as the
252 system's @command{f95} command.
253 @command{gfortran} is just another driver program,
254 but specifically for the Fortran 95 compiler only.
255 The difference with @command{gcc} is that @command{gfortran}
256 will automatically link the correct libraries to your program.
259 A collection of run-time libraries.
260 These libraries contains the machine code needed to support
261 capabilities of the Fortran language that are not directly
262 provided by the machine code generated by the
263 @command{gfortran} compilation phase,
264 such as intrinsic functions and subroutines,
265 and routines for interaction with files and the operating system.
266 @c and mechanisms to spawn,
267 @c unleash and pause threads in parallelized code.
270 The Fortran compiler itself, (@command{f951}).
271 This is the gfortran parser and code generator,
272 linked to and interfaced with the GCC backend library.
273 @command{f951} ``translates'' the source code to
274 assembler code. You would typically not use this
276 instead, the @command{gcc} or @command{gfortran} driver
277 programs will call it for you.
282 @c ---------------------------------------------------------------------
284 @c ---------------------------------------------------------------------
286 @node GFORTRAN and GCC
287 @chapter GFORTRAN and GCC
288 @cindex GNU Compiler Collection
290 GCC used to be the GNU ``C'' Compiler,
291 but is now known as the @dfn{GNU Compiler Collection}.
292 GCC provides the GNU system with a very versatile
293 compiler middle end (shared optimization passes),
294 and with back ends (code generators) for many different
295 computer architectures and operating systems.
296 The code of the middle end and back end are shared by all
297 compiler front ends that are in the GNU Compiler Collection.
299 A GCC front end is essentially a source code parser
300 and a pass to generate a representation of the semantics
301 of the program in the source code in the GCC language
302 independent intermediate language,
303 called @dfn{GENERIC}.
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,
317 pass the optimized AST and generate assembly
318 for the program unit.
320 Different phases in this translation process can be,
321 and in fact @emph{are} merged in many compiler front ends.
322 GNU Fortran 95 has a strict separation between the
323 parser and code generator.
325 The goal of the gfortran project is to build a new front end for GCC:
326 A Fortran 95 front end.
327 In a non-gfortran installation,
328 @command{gcc} will not be able to compile Fortran 95 source code
329 (only the ``C'' front end has to be compiled if you want to build GCC,
330 all other languages are optional).
331 If you build GCC with gfortran, @command{gcc} will recognize
332 @file{.f/.f90/.f95} source files and accepts Fortran 95 specific
333 command line options.
337 @c ---------------------------------------------------------------------
339 @c ---------------------------------------------------------------------
341 @node GFORTRAN and G77
342 @chapter GFORTRAN and G77
346 Why do we write a compiler front end from scratch?
347 There's a fine Fortran 77 compiler in the
348 GNU Compiler Collection that accepts some features
349 of the Fortran 90 standard as extensions.
350 Why not start from there and revamp it?
352 One of the reasons is that Craig Burley, the author of G77,
353 has decided to stop working on the G77 front end.
354 On @uref{http://world.std.com/~burley/g77-why.html,
355 Craig explains the reasons for his decision to stop working on G77}
356 in one of the pages in his homepage.
357 Among the reasons is a lack of interest in improvements to
359 Users appear to be quite satisfied with @command{g77} as it is.
360 While @command{g77} is still being maintained (by Toon Moene),
361 it is unlikely that sufficient people will be willing
362 to completely rewrite the existing code.
364 But there are other reasons to start from scratch.
365 Many people, including Craig Burley,
366 no longer agreed with certain design decisions in the G77 front end.
367 Also, the interface of @command{g77} to the back end is written in
368 a style which is confusing and not up to date on recommended practice.
369 In fact, a full rewrite had already been planned for GCC 3.0.
371 When Craig decided to stop,
372 it just seemed to be a better idea to start a new project from scratch,
373 because it was expected to be easier to maintain code we
374 develop ourselves than to do a major overhaul of @command{g77} first,
375 and then build a Fortran 95 compiler out of it.
380 @c ---------------------------------------------------------------------
382 @c ---------------------------------------------------------------------
385 @chapter Project Status
388 As soon as gfortran can parse all of the statements correctly,
389 it will be in the ``larva'' state.
390 When we generate code, the ``puppa'' state.
391 When gfortran is done,
392 we'll see if it will be a beautiful butterfly,
393 or just a big bug....
395 --Andy Vaught, April 2000
398 The start of the GNU Fortran 95 project was announced on
399 the GCC homepage in March 18, 2000
400 (even though Andy had already been working on it for a while,
403 Gfortran is currently reaching the stage where is is able to compile real
404 world programs. However it is still under development and has many rough
410 * Proposed Extensions::
413 @node Compiler Status
414 @section Compiler Status
418 This is the part of gfortran which parses a source file, verifies that it
419 is valid Fortran 95, performs compile time replacement of constants
420 (PARAMETER variables) and reads and generate module files. This is
421 almost complete. Every Fortran 95 source should be accepted, and most
422 none-Fortran 95 source should be rejected. If you find a source file where
423 this is not true, please tell us. You can use the -fsyntax-only switch to
424 make gfortran quit after running the front end, effectively reducing it to
427 @item Middle end interface
428 These are the parts of gfortran that take the parse tree generated by the
429 front end and translate it to the GENERIC form required by the GCC back
430 end. Work is ongoing in these parts of gfortran, but a large part has
431 already been completed.
435 @section Library Status
437 Some intrinsic functions map directly to library functions, and in most
438 cases the name of the library function used depends on the type of the
439 arguments. For some intrinsics we generate inline code, and for others,
440 such as sin, cos and sqrt, we rely on the backend to use special
441 instructions in the floating point unit of the CPU if available, or to
442 fall back to a call to libm if these are not available.
444 Implementation of some non-elemental intrinsic functions (eg. DOT_PRODUCT,
445 AVERAGE) is not yet optimal. This is hard because we have to make decisions
446 whether to use inline code (good for small arrays as no function call
447 overhead occurs) or generate function calls (good for large arrays as it
448 allows use of hand-optimized assembly routines, SIMD instructions, etc.)
450 The IO library is still under development. The following features should be
451 usable for real programs:
455 @item Unformatted sequential
461 @item Formatted sequential ('T' edit descriptor, and others)
462 @item Namelist (can read a namelist that it writes, but not free-form)
468 @item Unformatted direct access
469 @item Formatted direct access
472 Many Fortran programs only use a small subset of the available IO
473 capabilities, so your mileage may vary.
475 @node Proposed Extensions
476 @section Proposed Extensions
478 Here's a list of proposed extensions for @command{gfortran}, in no particular
479 order. Most of these are necessary to be fully compatible with
480 existing Fortran compilers, but they are not part of the official
481 J3 Fortran 95 standard.
483 @subsection Compiler extensions:
486 Flag for defining the kind number for default logicals.
489 User-specified alignment rules for structures.
491 Flag to generate a @code{Makefile} info.
494 Automatically extend single precision constants to double.
497 Cray pointers (this was high on the @command{g77} wishlist).
500 Compile code that conserves memory by dynamically allocating common and
501 module storage either on stack or heap.
504 Flag to cause the compiler to distinguish between upper and lower case
505 names. The Fortran 95 standard does not distinguish them.
508 Compile switch for changing the interpretation of a backslash from a
509 character to ``C''-style escape characters.
512 Compile flag to generate code for array conformance checking (suggest -CC).
515 User control of symbol names (underscores, etc).
518 Compile setting for maximum size of stack frame size before spilling
519 parts to static or heap.
522 Flag to force local variables into static space.
525 Flag to force local variables onto stack.
528 Flag to compile lines beginning with ``D''.
531 Flag to ignore lines beginning with ``D''.
534 Flag for maximum errors before ending compile.
537 Generate code to check for null pointer dereferences -- prints locus of
538 dereference instead of segfaulting. There was some discussion about this
539 option in the g95 development mailing list.
542 Allow setting default unit number.
545 Option to initialize of otherwise uninitialized integer and floating
549 Support for OpenMP directives. This also requires support from the runtime
550 library and the rest of the compiler.
553 Support for Fortran 200x. This includes several new features including
554 floating point exceptions, extended use of allocatable arrays, C
555 interoperability, Parameterizer data types and function pointers.
559 @subsection Environment Options
562 Pluggable library modules for random numbers, linear algebra.
563 LA should use BLAS calling conventions.
566 Environment variables controlling actions on arithmetic exceptions like
567 overflow, underflow, precision loss -- Generate NaN, abort, default.
571 Set precision for fp units that support it (i387).
574 Variables for setting fp rounding mode.
577 Support old style namelists ending in $end or &end.
580 Variable to fill uninitialized variables with a user-defined bit
584 Environment variable controlling filename that is opened for that unit
588 Environment variable to clear/trash memory being freed.
591 Environment variable to control tracing of allocations and frees.
594 Environment variable to display allocated memory at normal program end.
597 Environment variable for filename for * IO-unit.
600 Environment variable for temporary file directory.
603 Environment variable forcing standard output to be line buffered (unix).
606 Variable for swapping endianness during unformatted read.
609 Variable for swapping Endianness during unformatted write.
612 @c ---------------------------------------------------------------------
614 @c ---------------------------------------------------------------------
616 @c Maybe this chapter should be merged with the 'Standards' section,
617 @c whenever that is written :-)
623 @command{gfortran} implements a number of extensions over standard
624 Fortran. This chapter contains information on their syntax and
628 * Old-style kind specifications::
629 * Old-style variable initialization::
632 @node Old-style kind specifications
633 @section Old-style kind specifications
634 @cindex Kind specifications
636 @command{gfortran} allows old-style kind specifications in
637 declarations. These look like:
641 where @code{TYPESPEC} is a basic type, and where @code{k} is a valid kind
642 number for that type. The statement then declares @code{x}, @code{y}
643 and @code{z} to be of type @code{TYPESPEC} with kind @code{k}. In
644 other words, it is equivalent to the standard conforming declaration
649 @node Old-style variable initialization
650 @section Old-style variable initialization
651 @cindex Initialization
653 @command{gfortran} allows old-style initialization of variables of the
657 REAL*8 x(2,2) /3*0.,1./
659 These are only allowed in declarations without double colons
660 (@code{::}), as these were introduced in Fortran 90 which also
661 introduced a new syntax for variable initializations. The syntax for
662 the individual initializers is as for the @code{DATA} statement, but
663 unlike in a @code{DATA} statement, an initializer only applies to the
664 variable immediately preceding. In other words, something like
665 @code{INTEGER I,J/2,3/} is not valid.
667 Examples of standard conforming code equivalent to the above example, are:
670 INTEGER(4) :: i = 1, j = 2
671 REAL(8) :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
674 DOUBLE PRECISION x(2,2)
675 DATA i,j,x /1,2,3*0.,1./
678 @c ---------------------------------------------------------------------
680 @c ---------------------------------------------------------------------
683 @chapter Contributing
686 Free software is only possible if people contribute to efforts
688 We're always in need of more people helping out with ideas
689 and comments, writing documentation and contributing code.
691 If you want to contribute to GNU Fortran 95,
692 have a look at the long lists of projects you can take on.
693 Some of these projects are small,
694 some of them are large;
695 some are completely orthogonal to the rest of what is
696 happening on @command{gfortran},
697 but others are ``mainstream'' projects in need of enthusiastic hackers.
698 All of these projects are important!
699 We'll eventually get around to the things here,
700 but they are also things doable by someone who is willing and able.
709 @section Contributors to GNU Fortran 95
714 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
715 also the initiator of the whole project. Thanks Andy!
716 Most of the interface with GCC was written by @emph{Paul Brook}.
718 The following individuals have contributed code and/or
719 ideas and significant help to the gfortran project
720 (in no particular order):
724 @item Katherine Holcomb
725 @item Tobias Schlüter
726 @item Steven Bosscher
729 @item Niels Kristian Bech Jensen
736 The following people have contributed bug reports,
737 smaller or larger patches,
738 and much needed feedback and encouragement for the
739 @command{gfortran} project:
747 Many other individuals have helped debug,
748 test and improve @command{gfortran} over the past two years,
749 and we welcome you to do the same!
750 If you already have done so,
751 and you would like to see your name listed in the
752 list above, please contact us.
760 @item Help build the test suite
761 Solicit more code for donation to the test suite.
762 We can keep code private on request.
764 @item Bug hunting/squishing
765 Find bugs and write more test cases!
766 Test cases are especially very welcome,
767 because it allows us to concentrate on fixing bugs
768 instead of isolating them.
770 @item Smaller projects (``bug'' fixes):
772 @item Allow init exprs to be numbers raised to integer powers.
773 @item Implement correct rounding.
774 @item Implement F restrictions on Fortran 95 syntax.
775 @item See about making Emacs-parsable error messages.
779 If you wish to work on the runtime libraries,
780 please contact a project maintainer.
784 @c ---------------------------------------------------------------------
786 @c ---------------------------------------------------------------------
792 The GNU Fortran 95 Compiler aims to be a conforming implementation of
793 ISO/IEC 1539:1997 (Fortran 95).
795 In the future it may also support other variants and extensions to the Fortran
796 language. This includes ANSI Fortran 77, Fortran 90, Fortran 2000 (not yet
797 finalized), and OpenMP.