1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set last-update 13 May 2004
5 @set copyrights-gfortran 1999-2004
6 @set version-gfortran 0.235
8 @include gcc-common.texi
10 @settitle The GNU Fortran 95 Compiler
12 @c Create a separate index for command line options
14 @c Merge the standard indexes into a single one.
23 @c Use with @@smallbook.
25 @c %** start of document
27 @c Cause even numbered pages to be printed on the left hand side of
28 @c the page and odd numbered pages to be printed on the right hand
29 @c side of the page. Using this, you can print on both sides of a
30 @c sheet of paper and have the text on the same part of the sheet.
32 @c The text on right hand pages is pushed towards the right hand
33 @c margin and the text on left hand pages is pushed toward the left
35 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
38 @c \global\bindingoffset=0.75in
39 @c \global\normaloffset =0.75in
43 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
45 Permission is granted to copy, distribute and/or modify this document
46 under the terms of the GNU Free Documentation License, Version 1.1 or
47 any later version published by the Free Software Foundation; with the
48 Invariant Sections being ``GNU General Public License'' and ``Funding
49 Free Software'', the Front-Cover
50 texts being (a) (see below), and with the Back-Cover Texts being (b)
51 (see below). A copy of the license is included in the section entitled
52 ``GNU Free Documentation License''.
54 (a) The FSF's Front-Cover Text is:
58 (b) The FSF's Back-Cover Text is:
60 You have freedom to copy and modify this GNU Manual, like GNU
61 software. Copies published by the Free Software Foundation raise
62 funds for GNU development.
66 @dircategory Programming
68 * gfortran: (gfortran). The GNU Fortran 95 Compiler.
70 This file documents the use and the internals of
71 the GNU Fortran 95 compiler, (@command{gfortran}).
73 Published by the Free Software Foundation
74 59 Temple Place - Suite 330
75 Boston, MA 02111-1307 USA
80 Contributed by Steven Bosscher (@email{s.bosscher@@gcc.gnu.org}).
82 @setchapternewpage odd
84 @title Using GNU Fortran 95
86 @center Steven Bosscher
88 @center Last updated @value{last-update}
90 @center for version @value {version-gfortran}
92 @vskip 0pt plus 1filll
93 For the @value{version-gfortran} Version*
95 Published by the Free Software Foundation @*
96 59 Temple Place - Suite 330@*
97 Boston, MA 02111-1307, USA@*
98 @c Last printed ??ber, 19??.@*
99 @c Printed copies are available for $? each.@*
108 @node Top, Copying,, (DIR)
112 This manual documents the use of @command{gfortran},
113 the GNU Fortran 95 compiler. You can find in this manual how to invoke
114 @command{gfortran}, as well as its features and incompatibilities,
115 and how to report bugs.
118 @emph{Warning:} This document, and the compiler it describes, are still
119 under development. While efforts are made too keep it up-to-date it might
120 not accurately reflect the status of the most recent @command{gfortran}.
124 * Copying:: GNU General Public License says
125 how you can copy and share GNU Fortran.
126 * GNU Free Documentation License::
127 How you can copy and share this manual.
128 * Funding:: How to help assure continued work for free software.
129 * Getting Started:: What you should know about @command{gfortran}.
130 * GFORTRAN and GCC:: You can compile Fortran, C, or other programs.
131 * GFORTRAN and G77:: Why we choose to start from scratch.
132 * Invoking GFORTRAN:: Command options supported by @command{gfortran}.
133 * Compiling and Testing::
134 Need-to-knows about compiling and testing.
135 * Project Status:: Status of GFORTRAN, Roadmap, proposed extensions.
136 * Contributing:: Helping you can help.
137 * Standards:: Standards supported by GFORTRAN.
138 * Index:: Index of this documentation.
143 @c ---------------------------------------------------------------------
144 @c GNU General Public License
145 @c ---------------------------------------------------------------------
151 @c ---------------------------------------------------------------------
152 @c GNU Free Documentation License
153 @c ---------------------------------------------------------------------
159 @c ---------------------------------------------------------------------
160 @c Funding Free Software
161 @c ---------------------------------------------------------------------
163 @include funding.texi
167 @c ---------------------------------------------------------------------
169 @c ---------------------------------------------------------------------
171 @node Getting Started
172 @chapter Getting Started
174 Gfortran is the GNU Fortran 95 compiler front end,
175 designed initially as a free replacement for,
176 or alternative to, the unix @command{f95} command;
177 @command{gfortran} is command you'll use to invoke the compiler.
179 Gfortran is still in an early state of development.
180 @command{gfortran} can generate code for most constructs and expressions,
181 but much work remains to be done.
183 When @command{gfortran} is finished,
184 it will do everything you expect from any decent compiler:
188 Read a user's program,
189 stored in a file and containing instructions written
190 in Fortran 77, Fortran 90 or Fortran 95.
191 This file contains @dfn{source code}.
194 Translate the user's program into instructions a computer
195 can carry out more quickly than it takes to translate the
196 instructions in the first
197 place. The result after compilation of a program is
199 code designed to be efficiently translated and processed
200 by a machine such as your computer.
201 Humans usually aren't as good writing machine code
202 as they are at writing Fortran (or C++, Ada, or Java),
203 because is easy to make tiny mistakes writing machine code.
206 Provide the user with information about the reasons why
207 the compiler is unable to create a binary from the source code.
208 Usually this will be the case if the source code is flawed.
209 When writing Fortran, it is easy to make big mistakes.
210 The Fortran 90 requires that the compiler can point out
211 mistakes to the user.
212 An incorrect usage of the language causes an @dfn{error message}.
214 The compiler will also attempt to diagnose cases where the
215 user's program contains a correct usage of the language,
216 but instructs the computer to do something questionable.
217 This kind of diagnostics message is called a @dfn{warning message}.
220 Provide optional information about the translation passes
221 from the source code to machine code.
222 This can help a user of the compiler to find the cause of
223 certain bugs which may not be obvious in the source code,
224 but may be more easily found at a lower level compiler output.
225 It also helps developers to find bugs in the compiler itself.
228 Provide information in the generated machine code that can
229 make it easier to find bugs in the program (using a debugging tool,
230 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
233 Locate and gather machine code already generated to
234 perform actions requested by statements in the user's program.
235 This machine code is organized into @dfn{modules} and is located
236 and @dfn{linked} to the user program.
239 Gfortran consists of several components:
243 A version of the @command{gcc} command
244 (which also might be installed as the system's @command{cc} command)
245 that also understands and accepts Fortran source code.
246 The @command{gcc} command is the @dfn{driver} program for
247 all the languages in the GNU Compiler Collection (GCC);
249 you can compiler the source code of any language for
250 which a front end is available in GCC.
253 The @command{gfortran} command itself,
254 which also might be installed as the
255 system's @command{f95} command.
256 @command{gfortran} is just another driver program,
257 but specifically for the Fortran 95 compiler only.
258 The difference with @command{gcc} is that @command{gfortran}
259 will automatically link the correct libraries to your program.
262 A collection of run-time libraries.
263 These libraries contains the machine code needed to support
264 capabilities of the Fortran language that are not directly
265 provided by the machine code generated by the
266 @command{gfortran} compilation phase,
267 such as intrinsic functions and subroutines,
268 and routines for interaction with files and the operating system.
269 @c and mechanisms to spawn,
270 @c unleash and pause threads in parallelized code.
273 The Fortran compiler itself, (@command{f951}).
274 This is the gfortran parser and code generator,
275 linked to and interfaced with the GCC backend library.
276 @command{f951} ``translates'' the source code to
277 assembler code. You would typically not use this
279 instead, the @command{gcc} or @command{gfortran} driver
280 programs will call it for you.
285 @c ---------------------------------------------------------------------
287 @c ---------------------------------------------------------------------
289 @node GFORTRAN and GCC
290 @chapter GFORTRAN and GCC
291 @cindex GNU Compiler Collection
293 GCC used to be the GNU ``C'' Compiler,
294 but is now known as the @dfn{GNU Compiler Collection}.
295 GCC provides the GNU system with a very versatile
296 compiler middle end (shared optimization passes),
297 and with back ends (code generators) for many different
298 computer architectures and operating systems.
299 The code of the middle end and back end are shared by all
300 compiler front ends that are in the GNU Compiler Collection.
302 A GCC front end is essentially a source code parser
303 and a pass to generate a representation of the semantics
304 of the program in the source code in the GCC language
305 independent intermediate language,
306 called @dfn{GENERIC}.
308 The parser takes a source file written in a
309 particular computer language, reads and parses it,
310 and tries to make sure that the source code conforms to
312 Once the correctness of a program has been established,
313 the compiler will build a data structure known as the
314 @dfn{Abstract Syntax tree},
315 or just @dfn{AST} or ``tree'' for short.
316 This data structure represents the whole program
317 or a subroutine or a function.
318 The ``tree'' is passed to the GCC middle end,
319 which will perform optimization passes on it,
320 pass the optimized AST and generate assembly
321 for the program unit.
323 Different phases in this translation process can be,
324 and in fact @emph{are} merged in many compiler front ends.
325 GNU Fortran 95 has a strict separation between the
326 parser and code generator.
328 The goal of the gfortran project is to build a new front end for GCC:
329 A Fortran 95 front end.
330 In a non-gfortran installation,
331 @command{gcc} will not be able to compile Fortran 95 source code
332 (only the ``C'' front end has to be compiled if you want to build GCC,
333 all other languages are optional).
334 If you build GCC with gfortran, @command{gcc} will recognize
335 @file{.f/.f90/.f95} source files and accepts Fortran 95 specific
336 command line options.
340 @c ---------------------------------------------------------------------
342 @c ---------------------------------------------------------------------
344 @node GFORTRAN and G77
345 @chapter GFORTRAN and G77
349 Why do we write a compiler front end from scratch?
350 There's a fine Fortran 77 compiler in the
351 GNU Compiler Collection that accepts some features
352 of the Fortran 90 standard as extensions.
353 Why not start from there and revamp it?
355 One of the reasons is that Craig Burley, the author of G77,
356 has decided to stop working on the G77 front end.
357 On @uref{http://world.std.com/~burley/g77-why.html,
358 Craig explains the reasons for his decision to stop working on G77}
359 in one of the pages in his homepage.
360 Among the reasons is a lack of interest in improvements to
362 Users appear to be quite satisfied with @command{g77} as it is.
363 While @command{g77} is still being maintained (by Toon Moene),
364 it is unlikely that sufficient people will be willing
365 to completely rewrite the existing code.
367 But there are other reasons to start from scratch.
368 Many people, including Craig Burley,
369 no longer agreed with certain design decisions in the G77 front end.
370 Also, the interface of @command{g77} to the back end is written in
371 a style which is confusing and not up to date on recommended practice.
372 In fact, a full rewrite had already been planned for GCC 3.0.
374 When Craig decided to stop,
375 it just seemed to be a better idea to start a new project from scratch,
376 because it was expected to be easier to maintain code we
377 develop ourselves than to do a major overhaul of @command{g77} first,
378 and then build a Fortran 95 compiler out of it.
383 @c ---------------------------------------------------------------------
384 @c Compiling and Testing
385 @c ---------------------------------------------------------------------
387 @node Compiling and Testing
388 @chapter Compiling and Testing
390 @command{gfortran} is not yet part of an official GCC release, so it is
391 unlikley that OS distributor will provide it.
394 * Precompiled Binaries::
395 * General notes about compiling GFORTRAN::
399 @node Precompiled Binaries
400 @section Precompiled Binaries
402 Precompiled binaries for i686-pc-linux-gnu in rpm format are available from
403 @uref{http://people.redhat.com/dnovillo/pub/tree-ssa/snapshot/}
405 @node General notes about compiling GFORTRAN
406 @section General notes about compiling GFORTRAN
408 @cindex Multiple Precision Library
410 Compiling gfortran requires the presence of GMP,
411 the GNU Multiple Precision library version 4.0
412 or better in order to do its arithmetic.
413 Download @code{gmp} from your favorite GNU mirror,
414 configure and compile it. If your OS distributor provides prepackaged
415 GMP libraries, you may also need the developent pacakges.
417 If you do not have GMP installed in a standard system location, you may
418 need to configure GCC with @option{--with-gmp} or @option{--with-gmp-dir}.
420 Note: GMP is only required for the compiler itself. Compiled fortran programs
421 do not depend on the GMP library.
428 The number of possible Fortran 95 programs is unlimited,
429 and this means that gfortran has to correctly handle lots of possible inputs.
430 Whenever you make any changes to the compiler,
431 you should first test your change on a test program,
432 then test your change against the gfortran test suite.
433 In this way, we can be assured that once your fix has been made,
434 the problem isn't re-introduced at some later time.
436 The gfortran test suite is included in the gcc source distribution.
438 We also encourage you to test gfortran on your own Fortran codes.
440 @c ---------------------------------------------------------------------
442 @c ---------------------------------------------------------------------
445 @chapter Project Status
448 As soon as gfortran can parse all of the statements correctly,
449 it will be in the ``larva'' state.
450 When we generate code, the ``puppa'' state.
451 When gfortran is done,
452 we'll see if it will be a beautiful butterfly,
453 or just a big bug....
455 --Andy Vaught, April 2000
458 The start of the GNU Fortran 95 project was announced on
459 the GCC homepage in March 18, 2000
460 (even though Andy had already been working on it for a while,
463 Gfortran is currently reaching the stage where is is able to compile real
464 world programs. However it is still under development and has many rough
470 * Proposed Extensions::
473 @node Compiler Status
474 @section Compiler Status
478 This is the part of gfortran which parses a source file, verifies that it
479 is valid Fortran 95, performs compile time replacement of constants
480 (PARAMETER variables) and reads and generate module files. This is
481 almost complete. Every Fortran 95 source should be accepted, and most
482 none-Fortran 95 source should be rejected. If you find a source file where
483 this is not true, please tell us. You can use the -fsyntax-only switch to
484 make gfortran quit after running the front end, effectively reducing it to
487 @item Middle end interface
488 These are the parts of gfortran that take the parse tree generated by the
489 front end and translate it to the GENERIC form required by the GCC back
490 end. Work is ongoing in these parts of gfortran, but a large part has
491 already been completed.
495 @section Library Status
497 Some intrinsic functions map directly to library functions, and in most
498 cases the name of the library function used depends on the type of the
499 arguments. For some intrinsics we generate inline code, and for others,
500 such as sin, cos and sqrt, we rely on the backend to use special
501 instructions in the floating point unit of the CPU if available, or to
502 fall back to a call to libm if these are not available.
504 Implementation of some non-elemental intrinsic functions (eg. DOT_PRODUCT,
505 AVERAGE) is not yet optimal. This is hard because we have to make decisions
506 whether to use inline code (good for small arrays as no function call
507 overhead occurs) or generate function calls (good for large arrays as it
508 allows use of hand-optimized assembly routines, SIMD instructions, etc.)
510 The IO library is still under development. The following features should be
511 usable for real programs:
515 @item Unformatted sequential
521 @item Formatted sequential ('T' edit descriptor, and others)
522 @item Namelist (can read a namelist that it writes, but not free-form)
528 @item Unformatted direct access
529 @item Formatted direct access
532 Many Fortran programs only use a small subset of the available IO
533 capabilities, so your milage may vary.
535 @node Proposed Extensions
536 @section Proposed Extensions
538 Here's a list of proposed extensions for @command{gfortran}, in no particular
539 order. Most of these are necessary to be fully compatible with
540 existing Fortran compilers, but they are not part of the official
541 J3 Fortran 95 standard.
543 @subsection Compiler extensions:
546 Flag for defining the kind number for default logicals.
549 User-specified alignment rules for structures.
551 Flag to generate a @code{Makefile} info.
554 Automatically extend single precision constants to double.
557 Cray pointers (this was high on the @command{g77} wishlist).
560 Compile code that conserves memory by dynamically allocating common and
561 module storage either on stack or heap.
564 Flag to cause the compiler to distinguish between upper and lower case
565 names. The Fortran 95 standard does not distinguish them.
568 Compile switch for changing the interpretation of a backslash from a
569 character to ``C''-style escape characters.
572 Compile flag to generate code for array conformance checking (suggest -CC).
575 User control of symbol names (underscores, etc).
578 Compile setting for maximum size of stack frame size before spilling
579 parts to static or heap.
582 Flag to force local variables into static space.
585 Flag to force local variables onto stack.
588 Flag to compile lines beginning with ``D''.
591 Flag to ignore lines beginning with ``D''.
594 Flag for maximum errors before ending compile.
597 Generate code to check for null pointer dereferences -- prints locus of
598 dereference instead of segfaulting. There was some discussion about this
599 option in the g95 development mailing list.
602 Allow setting default unit number.
605 Option to initialize of otherwise uninitialized integer and floating
609 Support for OpenMP directives. This also requires support from the runtime
610 library and the rest of the compiler.
613 Support for Fortran 200x. This includes several new features including
614 floating point exceptions, extended use of allocatable arrays, C
615 interoperability, Parameterizer data types and function pointers.
619 @subsection Environment Options
622 Pluggable library modules for random numbers, linear algebra.
623 LA should use BLAS calling conventions.
626 Environment variables controlling actions on arithmetic exceptions like
627 overflow, underflow, precision loss -- Generate NaN, abort, default.
631 Set precision for fp units that support it (i387).
634 Variables for setting fp rounding mode.
637 Support old style namelists ending in $end or &end.
640 Variable to fill uninitialized variables with a user-defined bit
644 Environment variable controlling filename that is opened for that unit
648 Environment variable to clear/trash memory being freed.
651 Environment variable to control tracing of allocations and frees.
654 Environment variable to display allocated memory at normal program end.
657 Environment variable for filename for * IO-unit.
660 Environment variable for temporary file directory.
663 Environment variable forcing standard output to be line buffered (unix).
666 Variable for swapping endianness during unformatted read.
669 Variable for swapping Endianness during unformatted write.
674 @c ---------------------------------------------------------------------
676 @c ---------------------------------------------------------------------
679 @chapter Contributing
682 Free software is only possible if people contribute to efforts
684 We're always in need of more people helping out with ideas
685 and comments, writing documentation and contributing code.
687 If you want to contribute to GNU Fortran 95,
688 have a look at the long lists of projects you can take on.
689 Some of these projects are small,
690 some of them are large;
691 some are completely orthogonal to the rest of what is
692 happening on @command{gfortran},
693 but others are ``mainstream'' projects in need of enthusiastic hackers.
694 All of these projects are important!
695 We'll eventually get around to the things here,
696 but they are also things doable by someone who is willing and able.
705 @section Contributors to GNU Fortran 95
710 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
711 also the initiator of the whole project. Thanks Andy!
712 Most of the interface with GCC was written by @emph{Paul Brook}.
714 The following individuals have contributed code and/or
715 ideas and significant help to the gfortran project
716 (in no particular order):
720 @item Katherine Holcomb
721 @item Tobias Schlüter
722 @item Steven Bosscher
725 @item Niels Kristian Bech Jensen
732 The following people have contributed bug reports,
733 smaller or larger patches,
734 and much needed feedback and encouragement for the
735 @command{gfortran} project:
743 Many other individuals have helped debug,
744 test and improve @command{gfortran} over the past two years,
745 and we welcome you to do the same!
746 If you already have done so,
747 and you would like to see your name listed in the
748 list above, please contact us.
756 @item Help build the test suite
757 Solicit more code for donation to the test suite.
758 We can keep code private on request.
760 @item Bug hunting/squishing
761 Find bugs and write more test cases!
762 Test cases are especially very welcome,
763 because it allows us to concentrate on fixing bugs
764 instead of isolating them.
766 @item Smaller projects (``bug'' fixes):
768 @item Allow init exprs to be numbers raised to integer powers.
769 @item Implement correct rounding.
770 @item Implement F restrictions on Fortran 95 syntax.
771 @item See about making Emacs-parsable error messages.
775 If you wish to work on the runtime libraries,
776 please contact a project maintainer.
780 @c ---------------------------------------------------------------------
782 @c ---------------------------------------------------------------------
788 The GNU Fortran 95 Compiler aims to be a conforming implementation of
789 ISO/IEC 1539:1997 (Fortran 95).
791 In the future it may also support other variants and extensions to the Fortran
792 language. This includes ANSI Fortran 77, Fortran 90, Fortran 2000 (not yet
793 finalized), and OpenMP.