1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set last-update March 10, 2004
5 @set copyrights-gfortran 1999-2004
6 @set version-gfortran 0.235
8 @include gcc-common.texi
10 @c This indicates that this documentation is still under development.
11 @c For example, if this option is set, overfull boxes are marked with
12 @c an ugly black square.
15 @settitle The GNU Fortran 95 Compiler
17 @c Create a separate index for command line options
19 @c Merge the standard indexes into a single one.
28 @c Use with @@smallbook.
30 @c %** start of document
32 @c Cause even numbered pages to be printed on the left hand side of
33 @c the page and odd numbered pages to be printed on the right hand
34 @c side of the page. Using this, you can print on both sides of a
35 @c sheet of paper and have the text on the same part of the sheet.
37 @c The text on right hand pages is pushed towards the right hand
38 @c margin and the text on left hand pages is pushed toward the left
40 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
43 @c \global\bindingoffset=0.75in
44 @c \global\normaloffset =0.75in
48 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
50 Permission is granted to copy, distribute and/or modify this document
51 under the terms of the GNU Free Documentation License, Version 1.1 or
52 any later version published by the Free Software Foundation; with the
53 Invariant Sections being ``GNU General Public License'' and ``Funding
54 Free Software'', the Front-Cover
55 texts being (a) (see below), and with the Back-Cover Texts being (b)
56 (see below). A copy of the license is included in the section entitled
57 ``GNU Free Documentation License''.
59 (a) The FSF's Front-Cover Text is:
63 (b) The FSF's Back-Cover Text is:
65 You have freedom to copy and modify this GNU Manual, like GNU
66 software. Copies published by the Free Software Foundation raise
67 funds for GNU development.
71 @dircategory Programming
73 * gfortran: (gfortran). The GNU Fortran 95 Compiler.
75 This file documents the use and the internals of
76 the GNU Fortran 95 compiler, (@command{gfortran}).
78 Published by the Free Software Foundation
79 59 Temple Place - Suite 330
80 Boston, MA 02111-1307 USA
85 Contributed by Steven Bosscher (@email{s.bosscher@@gcc.gnu.org}).
87 @setchapternewpage odd
89 @title Using GNU Fortran 95
91 @center Steven Bosscher
93 @center Last updated @value{last-update}
95 @center for version @value {version-gfortran}
97 @vskip 0pt plus 1filll
98 For the @value{version-gfortran} Version*
100 Published by the Free Software Foundation @*
101 59 Temple Place - Suite 330@*
102 Boston, MA 02111-1307, USA@*
103 @c Last printed ??ber, 19??.@*
104 @c Printed copies are available for $? each.@*
113 @node Top, Copying,, (DIR)
117 This manual documents the use of @command{gfortran},
118 the GNU Fortran 95 compiler. You can find in this manual how to invoke
119 @command{gfortran}, as well as its features and incompatibilities,
120 and how to report bugs.
123 @emph{Warning:} This document, and the compiler it describes, are still
124 under development. While efforts are made too keep it up-to-date it might
125 not accurately reflect the status of the most recent @command{gfortran}.
129 * Copying:: GNU General Public License says
130 how you can copy and share GNU Fortran.
131 * GNU Free Documentation License::
132 How you can copy and share this manual.
133 * Funding:: How to help assure continued work for free software.
134 * Getting Started:: What you should know about @command{gfortran}.
135 * GFORTRAN and GCC:: You can compile Fortran, C, or other programs.
136 * GFORTRAN and G77:: Why we choose to start from scratch.
137 * Invoking GFORTRAN:: Command options supported by @command{gfortran}.
138 * Compiling and Testing::
139 Need-to-knows about compiling and testing.
140 * Project Status:: Status of GFORTRAN, Roadmap, proposed extensions.
141 * Contributing:: Helping you can help.
142 * Standards:: Standards supported by GFORTRAN.
143 * Index:: Index of this documentation.
148 @c ---------------------------------------------------------------------
149 @c GNU General Public License
150 @c ---------------------------------------------------------------------
156 @c ---------------------------------------------------------------------
157 @c GNU Free Documentation License
158 @c ---------------------------------------------------------------------
164 @c ---------------------------------------------------------------------
165 @c Funding Free Software
166 @c ---------------------------------------------------------------------
168 @include funding.texi
172 @c ---------------------------------------------------------------------
174 @c ---------------------------------------------------------------------
176 @node Getting Started
177 @chapter Getting Started
179 Gfortran is the GNU Fortran 95 compiler front end,
180 designed initially as a free replacement for,
181 or alternative to, the unix @command{f95} command;
182 @command{gfortran} is command you'll use to invoke the compiler.
184 Gfortran is still in an early state of development.
185 @command{gfortran} can generate code for most constructs and expressions,
186 but much work remains to be done.
188 When @command{gfortran} is finished,
189 it will do everything you expect from any decent compiler:
193 Read a user's program,
194 stored in a file and containing instructions written
195 in Fortran 77, Fortran 90 or Fortran 95.
196 This file contains @dfn{source code}.
199 Translate the user's program into instructions a computer
200 can carry out more quickly than it takes to translate the
201 instructions in the first
202 place. The result after compilation of a program is
204 code designed to be efficiently translated and processed
205 by a machine such as your computer.
206 Humans usually aren't as good writing machine code
207 as they are at writing Fortran (or C++, Ada, or Java),
208 because is easy to make tiny mistakes writing machine code.
211 Provide the user with information about the reasons why
212 the compiler is unable to create a binary from the source code.
213 Usually this will be the case if the source code is flawed.
214 When writing Fortran, it is easy to make big mistakes.
215 The Fortran 90 requires that the compiler can point out
216 mistakes to the user.
217 An incorrect usage of the language causes an @dfn{error message}.
219 The compiler will also attempt to diagnose cases where the
220 user's program contains a correct usage of the language,
221 but instructs the computer to do something questionable.
222 This kind of diagnostics message is called a @dfn{warning message}.
225 Provide optional information about the translation passes
226 from the source code to machine code.
227 This can help a user of the compiler to find the cause of
228 certain bugs which may not be obvious in the source code,
229 but may be more easily found at a lower level compiler output.
230 It also helps developers to find bugs in the compiler itself.
233 Provide information in the generated machine code that can
234 make it easier to find bugs in the program (using a debugging tool,
235 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
238 Locate and gather machine code already generated to
239 perform actions requested by statements in the user's program.
240 This machine code is organized into @dfn{modules} and is located
241 and @dfn{linked} to the user program.
244 Gfortran consists of several components:
248 A version of the @command{gcc} command
249 (which also might be installed as the system's @command{cc} command)
250 that also understands and accepts Fortran source code.
251 The @command{gcc} command is the @dfn{driver} program for
252 all the languages in the GNU Compiler Collection (GCC);
254 you can compiler the source code of any language for
255 which a front end is available in GCC.
258 The @command{gfortran} command itself,
259 which also might be installed as the
260 system's @command{f95} command.
261 @command{gfortran} is just another driver program,
262 but specifically for the Fortran 95 compiler only.
263 The difference with @command{gcc} is that @command{gfortran}
264 will automatically link the correct libraries to your program.
267 A collection of run-time libraries.
268 These libraries contains the machine code needed to support
269 capabilities of the Fortran language that are not directly
270 provided by the machine code generated by the
271 @command{gfortran} compilation phase,
272 such as intrinsic functions and subroutines,
273 and routines for interaction with files and the operating system.
274 @c and mechanisms to spawn,
275 @c unleash and pause threads in parallelized code.
278 The Fortran compiler itself, (@command{f951}).
279 This is the gfortran parser and code generator,
280 linked to and interfaced with the GCC backend library.
281 @command{f951} ``translates'' the source code to
282 assembler code. You would typically not use this
284 instead, the @command{gcc} or @command{gfortran} driver
285 programs will call it for you.
290 @c ---------------------------------------------------------------------
292 @c ---------------------------------------------------------------------
294 @node GFORTRAN and GCC
295 @chapter GFORTRAN and GCC
296 @cindex GNU Compiler Collection
298 GCC used to be the GNU ``C'' Compiler,
299 but is now known as the @dfn{GNU Compiler Collection}.
300 GCC provides the GNU system with a very versatile
301 compiler middle end (shared optimization passes),
302 and with back ends (code generators) for many different
303 computer architectures and operating systems.
304 The code of the middle end and back end are shared by all
305 compiler front ends that are in the GNU Compiler Collection.
307 A GCC front end is essentially a source code parser
308 and a pass to generate a representation of the semantics
309 of the program in the source code in the GCC language
310 independent intermediate language,
311 called @dfn{GENERIC}.
313 The parser takes a source file written in a
314 particular computer language, reads and parses it,
315 and tries to make sure that the source code conforms to
317 Once the correctness of a program has been established,
318 the compiler will build a data structure known as the
319 @dfn{Abstract Syntax tree},
320 or just @dfn{AST} or ``tree'' for short.
321 This data structure represents the whole program
322 or a subroutine or a function.
323 The ``tree'' is passed to the GCC middle end,
324 which will perform optimization passes on it,
325 pass the optimized AST and generate assembly
326 for the program unit.
328 Different phases in this translation process can be,
329 and in fact @emph{are} merged in many compiler front ends.
330 GNU Fortran 95 has a strict separation between the
331 parser and code generator.
333 The goal of the gfortran project is to build a new front end for GCC:
334 A Fortran 95 front end.
335 In a non-gfortran installation,
336 @command{gcc} will not be able to compile Fortran 95 source code
337 (only the ``C'' front end has to be compiled if you want to build GCC,
338 all other languages are optional).
339 If you build GCC with gfortran, @command{gcc} will recognize
340 @file{.f/.f90/.f95} source files and accepts Fortran 95 specific
341 command line options.
345 @c ---------------------------------------------------------------------
347 @c ---------------------------------------------------------------------
349 @node GFORTRAN and G77
350 @chapter GFORTRAN and G77
354 Why do we write a compiler front end from scratch?
355 There's a fine Fortran 77 compiler in the
356 GNU Compiler Collection that accepts some features
357 of the Fortran 90 standard as extensions.
358 Why not start from there and revamp it?
360 One of the reasons is that Craig Burley, the author of G77,
361 has decided to stop working on the G77 front end.
362 On @uref{http://world.std.com/~burley/g77-why.html,
363 Craig explains the reasons for his decision to stop working on G77}
364 in one of the pages in his homepage.
365 Among the reasons is a lack of interest in improvements to
367 Users appear to be quite satisfied with @command{g77} as it is.
368 While @command{g77} is still being maintained (by Toon Moene),
369 it is unlikely that sufficient people will be willing
370 to completely rewrite the existing code.
372 But there are other reasons to start from scratch.
373 Many people, including Craig Burley,
374 no longer agreed with certain design decisions in the G77 front end.
375 Also, the interface of @command{g77} to the back end is written in
376 a style which is confusing and not up to date on recommended practice.
377 In fact, a full rewrite had already been planned for GCC 3.0.
379 When Craig decided to stop,
380 it just seemed to be a better idea to start a new project from scratch,
381 because it was expected to be easier to maintain code we
382 develop ourselves than to do a major overhaul of @command{g77} first,
383 and then build a Fortran 95 compiler out of it.
388 @c ---------------------------------------------------------------------
389 @c Compiling and Testing
390 @c ---------------------------------------------------------------------
392 @node Compiling and Testing
393 @chapter Compiling and Testing
395 @command{gfortran} is not yet part of an official GCC release, so it is
396 unlikley that OS distributor will provide it.
399 * Precompiled Binaries::
400 * General notes about compiling GFORTRAN::
401 * Compiling GFORTRAN::
405 @node Precompiled Binaries
406 @section Precompiled Binaries
408 Precompiled binaries for i686-pc-linux-gnu in rpm format are available from
409 @uref{http://people.redhat.com/dnovillo/pub/tree-ssa/snapshot/}
411 @node General notes about compiling GFORTRAN
412 @section General notes about compiling GFORTRAN
414 @cindex Multiple Precision Library
416 Compiling gfortran requires the presence of GMP,
417 the GNU Multiple Precision library version 4.0
418 or better in order to do its arithmetic.
419 Download @code{gmp} from your favorite GNU mirror,
420 configure and compile it. If your OS distributor provides prepackaged
421 GMP libraries, you may also need the developent pacakges.
423 If you do not have GMP installed in a standard system location, you may
424 need to configure GCC with @option{--with-gmp} or @option{--with-gmp-dir}.
426 Note: GMP is only required for the compiler itself. Compiled fortran programs
427 do not depend on the GMP library.
429 @node Compiling GFORTRAN
430 @section Compiling GFORTRAN
433 To build gfortran, you first need to get a copy of the GCC source tree.
434 gfortran uses the new @dfn{GENERIC} intermediate representation
435 to communicate with the back end.
436 This new IR has not been merged yet with the GCC mainline,
437 so you'll need to get a snapshot of the
438 @emph{tree-ssa-20020619-branch} from the GCC CVS repository.
439 This branch also contains the latest version
440 You can check out this branch from the GNU Subversions server:
444 $ cvs -z9 -d :ext:anoncvs@@subversions.gnu.org:/cvsroot/gcc co -r tree-ssa-20020619-branch gcc
447 You can now build GCC following the instructions on the
448 @uref{htpp://gcc.gnu.org/,GCC homepage},
449 (configure with @option{--enable-languages=f95}).
457 The number of possible Fortran 95 programs is unlimited,
458 and this means that gfortran has to correctly handle lots of possible inputs.
459 Whenever you make any changes to the compiler,
460 you should first test your change on a test program,
461 then test your change against the gfortran test suite.
462 In this way, we can be assured that once your fix has been made,
463 the problem isn't re-introduced at some later time.
465 The gfortran test suite is included in the gcc source distribution.
467 We also encourage you to test gfortran on your own Fortran codes.
469 @c ---------------------------------------------------------------------
471 @c ---------------------------------------------------------------------
474 @chapter Project Status
477 As soon as gfortran can parse all of the statements correctly,
478 it will be in the ``larva'' state.
479 When we generate code, the ``puppa'' state.
480 When gfortran is done,
481 we'll see if it will be a beautiful butterfly,
482 or just a big bug....
484 --Andy Vaught, April 2000
487 The start of the GNU Fortran 95 project was announced on
488 the GCC homepage in March 18, 2000
489 (even though Andy had already been working on it for a while,
492 Gfortran is currently reaching the stage where is is able to compile real
493 world programs. However it is still under development and has many rough
499 * Proposed Extensions::
502 @node Compiler Status
503 @section Compiler Status
507 This is the part of gfortran which parses a source file, verifies that it
508 is valid Fortran 95, performs compile time replacement of constants
509 (PARAMETER variables) and reads and generate module files. This is
510 almost complete. Every Fortran 95 source should be accepted, and most
511 none-Fortran 95 source should be rejected. If you find a source file where
512 this is not true, please tell us. You can use the -fsyntax-only switch to
513 make gfortran quit after running the front end, effectively reducing it to
516 @item Middle end interface
517 These are the parts of gfortran that take the parse tree generated by the
518 front end and translate it to the GENERIC form required by the GCC back
519 end. Work is ongoing in these parts of gfortran, but a large part has
520 already been completed.
524 @section Library Status
526 Some intrinsic functions map directly to library functions, and in most
527 cases the name of the library function used depends on the type of the
528 arguments. For some intrinsics we generate inline code, and for others,
529 such as sin, cos and sqrt, we rely on the backend to use special
530 instructions in the floating point unit of the CPU if available, or to
531 fall back to a call to libm if these are not available.
533 Implementation of some non-elemental intrinsic functions (eg. DOT_PRODUCT,
534 AVERAGE) is not yet optimal. This is hard because we have to make decisions
535 whether to use inline code (good for small arrays as no function call
536 overhead occurs) or generate function calls (good for large arrays as it
537 allows use of hand-optimized assembly routines, SIMD instructions, etc.)
539 The IO library is still under development. The following features should be
540 usable for real programs:
544 @item Unformatted sequential
550 @item Formatted sequential ('T' edit descriptor, and others)
551 @item Namelist (can read a namelist that it writes, but not free-form)
557 @item Unformatted direct access
558 @item Formatted direct access
561 Many Fortran programs only use a small subset of the available IO
562 capabilities, so your milage may vary.
564 @node Proposed Extensions
565 @section Proposed Extensions
567 Here's a list of proposed extensions for @command{gfortran}, in no particular
568 order. Most of these are necessary to be fully compatible with
569 existing Fortran compilers, but they are not part of the official
570 J3 Fortran 95 standard.
572 @subsection Compiler extensions:
575 Flag for defining the kind number for default logicals.
578 User-specified alignment rules for structures.
580 Flag to generate a @code{Makefile} info.
583 Automatically extend single precision constants to double.
586 Cray pointers (this was high on the @command{g77} wishlist).
589 Compile code that conserves memory by dynamically allocating common and
590 module storage either on stack or heap.
593 Flag to cause the compiler to distinguish between upper and lower case
594 names. The Fortran 95 standard does not distinguish them.
597 Compile switch for changing the interpretation of a backslash from a
598 character to ``C''-style escape characters.
601 Compile flag to generate code for array conformance checking (suggest -CC).
604 User control of symbol names (underscores, etc).
607 Compile setting for maximum size of stack frame size before spilling
608 parts to static or heap.
611 Flag to force local variables into static space.
614 Flag to force local variables onto stack.
617 Flag to compile lines beginning with ``D''.
620 Flag to ignore lines beginning with ``D''.
623 Flag for maximum errors before ending compile.
626 Generate code to check for null pointer dereferences -- prints locus of
627 dereference instead of segfaulting. There was some discussion about this
628 option in the g95 development mailing list.
631 Allow setting default unit number.
634 Option to initialize of otherwise uninitialized integer and floating
638 Support for OpenMP directives. This also requires support from the runtime
639 library and the rest of the compiler.
642 Support for Fortran 200x. This includes several new features including
643 floating point exceptions, extended use of allocatable arrays, C
644 interoperability, Parameterizer data types and function pointers.
648 @subsection Environment Options
651 Pluggable library modules for random numbers, linear algebra.
652 LA should use BLAS calling conventions.
655 Environment variables controlling actions on arithmetic exceptions like
656 overflow, underflow, precision loss -- Generate NaN, abort, default.
660 Set precision for fp units that support it (i387).
663 Variables for setting fp rounding mode.
666 Support old style namelists ending in $end or &end.
669 Variable to fill uninitialized variables with a user-defined bit
673 Environment variable controlling filename that is opened for that unit
677 Environment variable to clear/trash memory being freed.
680 Environment variable to control tracing of allocations and frees.
683 Environment variable to display allocated memory at normal program end.
686 Environment variable for filename for * IO-unit.
689 Environment variable for temporary file directory.
692 Environment variable forcing standard output to be line buffered (unix).
695 Variable for swapping endianness during unformatted read.
698 Variable for swapping Endianness during unformatted write.
703 @c ---------------------------------------------------------------------
705 @c ---------------------------------------------------------------------
708 @chapter Contributing
711 Free software is only possible if people contribute to efforts
713 We're always in need of more people helping out with ideas
714 and comments, writing documentation and contributing code.
716 If you want to contribute to GNU Fortran 95,
717 have a look at the long lists of projects you can take on.
718 Some of these projects are small,
719 some of them are large;
720 some are completely orthogonal to the rest of what is
721 happening on @command{gfortran},
722 but others are ``mainstream'' projects in need of enthusiastic hackers.
723 All of these projects are important!
724 We'll eventually get around to the things here,
725 but they are also things doable by someone who is willing and able.
734 @section Contributors to GNU Fortran 95
739 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
740 also the initiator of the whole project. Thanks Andy!
741 Most of the interface with GCC was written by @emph{Paul Brook}.
743 The following individuals have contributed code and/or
744 ideas and significant help to the gfortran project
745 (in no particular order):
749 @item Katherine Holcomb
750 @item Tobias Schlüter
751 @item Steven Bosscher
754 @item Niels Kristian Bech Jensen
761 The following people have contributed bug reports,
762 smaller or larger patches,
763 and much needed feedback and encouragement for the
764 @command{gfortran} project:
772 Many other individuals have helped debug,
773 test and improve @command{gfortran} over the past two years,
774 and we welcome you to do the same!
775 If you already have done so,
776 and you would like to see your name listed in the
777 list above, please contact us.
785 @item Help build the test suite
786 Solicit more code for donation to the test suite.
787 We can keep code private on request.
789 @item Bug hunting/squishing
790 Find bugs and write more test cases!
791 Test cases are especially very welcome,
792 because it allows us to concentrate on fixing bugs
793 instead of isolating them.
795 @item Smaller projects (``bug'' fixes):
797 @item Allow init exprs to be numbers raised to integer powers.
798 @item Implement correct rounding.
799 @item Implement F restrictions on Fortran 95 syntax.
800 @item See about making Emacs-parsable error messages.
804 If you wish to work on the runtime libraries,
805 please contact a project maintainer.
809 @c ---------------------------------------------------------------------
811 @c ---------------------------------------------------------------------
817 The GNU Fortran 95 Compiler aims to be a conforming implementation of
818 ISO/IEC 1539:1997 (Fortran 95).
820 In the future it may also support other variants and extensions to the Fortran
821 language. This includes ANSI Fortran 77, Fortran 90, Fortran 2000 (not yet
822 finalized), and OpenMP.