1 @c Copyright (C) 2004, 2005, 2006, 2007
2 @c Free Software Foundation, Inc.
3 @c This is part of the GNU Fortran manual.
4 @c For copying conditions, see the file gfortran.texi.
8 Copyright @copyright{} 2004, 2005, 2006, 2007
9 Free Software Foundation, Inc.
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU Free Documentation License, Version 1.2 or
13 any later version published by the Free Software Foundation; with the
14 Invariant Sections being ``GNU General Public License'' and ``Funding
15 Free Software'', the Front-Cover texts being (a) (see below), and with
16 the Back-Cover Texts being (b) (see below). A copy of the license is
17 included in the gfdl(7) man page.
19 (a) The FSF's Front-Cover Text is:
23 (b) The FSF's Back-Cover Text is:
25 You have freedom to copy and modify this GNU Manual, like GNU
26 software. Copies published by the Free Software Foundation raise
27 funds for GNU development.
29 @c Set file name and title for the man page.
31 @settitle GNU Fortran compiler.
33 gfortran [@option{-c}|@option{-S}|@option{-E}]
34 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
35 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
36 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
37 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
38 [@option{-f}@var{option}@dots{}]
39 [@option{-m}@var{machine-option}@dots{}]
40 [@option{-o} @var{outfile}] @var{infile}@dots{}
42 Only the most useful options are listed here; see below for the
46 gpl(7), gfdl(7), fsf-funding(7),
47 cpp(1), gcov(1), gcc(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
48 and the Info entries for @file{gcc}, @file{cpp}, @file{gfortran}, @file{as},
49 @file{ld}, @file{binutils} and @file{gdb}.
52 For instructions on reporting bugs, see
53 @w{@uref{http://gcc.gnu.org/bugs.html}}.
56 See the Info entry for @command{gfortran} for contributors to GCC and
61 @node Invoking GNU Fortran
62 @chapter GNU Fortran Command Options
63 @cindex GNU Fortran command options
64 @cindex command options
65 @cindex options, @command{gfortran} command
67 @c man begin DESCRIPTION
69 The @command{gfortran} command supports all the options supported by the
70 @command{gcc} command. Only options specific to GNU Fortran are documented here.
72 @xref{Invoking GCC,,GCC Command Options,gcc,Using the GNU Compiler
73 Collection (GCC)}, for information
74 on the non-Fortran-specific aspects of the @command{gcc} command (and,
75 therefore, the @command{gfortran} command).
77 @cindex options, negative forms
78 @cindex negative forms of options
79 All GCC and GNU Fortran options
80 are accepted both by @command{gfortran} and by @command{gcc}
81 (as well as any other drivers built at the same time,
82 such as @command{g++}),
83 since adding GNU Fortran to the GCC distribution
84 enables acceptance of GNU Fortran options
85 by all of the relevant drivers.
87 In some cases, options have positive and negative forms;
88 the negative form of @option{-ffoo} would be @option{-fno-foo}.
89 This manual documents only one of these two forms, whichever
90 one is not the default.
94 * Option Summary:: Brief list of all @command{gfortran} options,
96 * Fortran Dialect Options:: Controlling the variant of Fortran language
98 * Error and Warning Options:: How picky should the compiler be?
99 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
100 * Directory Options:: Where to find module files
101 * Runtime Options:: Influencing runtime behavior
102 * Code Gen Options:: Specifying conventions for function calls, data layout
104 * Environment Variables:: Env vars that affect @command{gfortran}.
108 @section Option Summary
112 Here is a summary of all the options specific to GNU Fortran, grouped
113 by type. Explanations are in the following sections.
116 @item Fortran Language Options
117 @xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}.
118 @gccoptlist{-fall-intrinsics -ffree-form -fno-fixed-form @gol
119 -fdollar-ok -fimplicit-none -fmax-identifier-length @gol
120 -std=@var{std} -fd-lines-as-code -fd-lines-as-comments @gol
121 -ffixed-line-length-@var{n} -ffixed-line-length-none @gol
122 -ffree-line-length-@var{n} -ffree-line-length-none @gol
123 -fdefault-double-8 -fdefault-integer-8 -fdefault-real-8 @gol
124 -fcray-pointer -fopenmp -frange-check -fno-backslash }
126 @item Error and Warning Options
127 @xref{Error and Warning Options,,Options to Request or Suppress Errors
129 @gccoptlist{-fmax-errors=@var{n} @gol
130 -fsyntax-only -pedantic -pedantic-errors @gol
131 -w -Wall -Waliasing -Wampersand -Wconversion -Wimplicit-interface @gol
132 -Wtabs -Wnonstd-intrinsics -Wsurprising -Wunderflow @gol
133 -Wline-truncation -W}
135 @item Debugging Options
136 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
137 @gccoptlist{-fdump-parse-tree -ffpe-trap=@var{list} @gol
138 -fdump-core -fbacktrace}
140 @item Directory Options
141 @xref{Directory Options,,Options for Directory Search}.
142 @gccoptlist{-I@var{dir} -M@var{dir}}
144 @item Runtime Options
145 @xref{Runtime Options,,Options for influencing runtime behavior}.
146 @gccoptlist{-fconvert=@var{conversion} -frecord-marker=@var{length}}
148 @item Code Generation Options
149 @xref{Code Gen Options,,Options for Code Generation Conventions}.
150 @gccoptlist{-fno-automatic -ff2c -fno-underscoring
151 -fsecond-underscore @gol
152 -fbounds-check -fmax-stack-var-size=@var{n} @gol
153 -fpack-derived -frepack-arrays -fshort-enums -fexternal-blas @gol
154 -fblas-matmul-limit=@var{n}}
158 * Fortran Dialect Options:: Controlling the variant of Fortran language
160 * Error and Warning Options:: How picky should the compiler be?
161 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
162 * Directory Options:: Where to find module files
163 * Runtime Options:: Influencing runtime behavior
164 * Code Gen Options:: Specifying conventions for function calls, data layout
168 @node Fortran Dialect Options
169 @section Options Controlling Fortran Dialect
170 @cindex dialect options
171 @cindex language, dialect options
172 @cindex options, dialect
174 The following options control the details of the Fortran dialect
175 accepted by the compiler:
180 @cindex @code{-ffree-form} option
181 @cindex option, @code{-ffree-form}
182 @cindex @code{-fno-fixed-form} option
183 @cindex option, @code{-fno-fixed-form}
184 @cindex source file format
188 @cindex Fortran 90, features
189 Specify the layout used by the source file. The free form layout
190 was introduced in Fortran 90. Fixed form was traditionally used in
191 older Fortran programs. When neither option is specified, the source
192 form is determined by the file extension.
194 @item -fall-intrinsics
195 @cindex @code{-fall-intrinsics} option
196 @cindex option, @code{-fall-intrinsics}
197 Accept all of the intrinsic procedures provided in libgfortran
198 without regard to the setting of @option{-std}. In particular,
199 this option can be quite useful with @option{-std=f95}. Additionally,
200 @command{gfortran} will ignore @option{-Wnonstd-intrinsics}.
202 @item -fd-lines-as-code
203 @item -fd-lines-as-comment
204 @cindex @code{-fd-lines-as-code}, option
205 @cindex option, @code{-fd-lines-as-code}
206 @cindex @code{-fd-lines-as-comments}, option
207 @cindex option, @code{-fd-lines-as-comments}
208 Enable special treatment for lines beginning with @code{d} or @code{D}
209 in fixed form sources. If the @option{-fd-lines-as-code} option is
210 given they are treated as if the first column contained a blank. If the
211 @option{-fd-lines-as-comments} option is given, they are treated as
214 @item -fdefault-double-8
215 @cindex @code{-fdefault-double-8}, option
216 @cindex option, @code{-fdefault-double-8}
217 Set the @code{DOUBLE PRECISION} type to an 8 byte wide type.
219 @item -fdefault-integer-8
220 @cindex @code{-fdefault-integer-8}, option
221 @cindex option, @code{-fdefault-integer-8}
222 Set the default integer and logical types to an 8 byte wide type.
223 Do nothing if this is already the default.
225 @item -fdefault-real-8
226 @cindex @code{-fdefault-real-8}, option
227 @cindex option, @code{-fdefault-real-8}
228 Set the default real type to an 8 byte wide type.
229 Do nothing if this is already the default.
232 @cindex @code{-fdollar-ok} option
233 @cindex option, @code{-fdollar-ok}
236 @cindex character set
237 Allow @samp{$} as a valid character in a symbol name.
240 @cindex @code{-fno-backslash} option
241 @cindex option, @code{-fno-backslash}
243 @cindex escape characters
244 Change the interpretation of backslashes in string literals from
245 ``C-style'' escape characters to a single backslash character.
247 @item -ffixed-line-length-@var{n}
248 @cindex @code{-ffixed-line-length-}@var{n} option
249 @cindex option, @code{-ffixed-line-length-}@var{n}
250 @cindex source file format
251 @cindex lines, length
252 @cindex length of source lines
254 @cindex limits, lengths of source lines
255 Set column after which characters are ignored in typical fixed-form
256 lines in the source file, and through which spaces are assumed (as
257 if padded to that length) after the ends of short fixed-form lines.
260 @cindex extended-source option
261 Popular values for @var{n} include 72 (the
262 standard and the default), 80 (card image), and 132 (corresponding
263 to ``extended-source'' options in some popular compilers).
264 @var{n} may also be @samp{none}, meaning that the entire line is meaningful
265 and that continued character constants never have implicit spaces appended
266 to them to fill out the line.
267 @option{-ffixed-line-length-0} means the same thing as
268 @option{-ffixed-line-length-none}.
270 @item -ffree-line-length-@var{n}
271 @cindex @code{-ffree-line-length-}@var{n} option
272 @cindex option, @code{-ffree-line-length-}@var{n}
273 @cindex source file format
274 @cindex lines, length
275 @cindex length of source lines
277 @cindex limits, lengths of source lines
278 Set column after which characters are ignored in typical free-form
279 lines in the source file. The default value is 132.
280 @var{n} may be @samp{none}, meaning that the entire line is meaningful.
281 @option{-ffree-line-length-0} means the same thing as
282 @option{-ffree-line-length-none}.
284 @item -fmax-identifier-length=@var{n}
285 @cindex @code{-fmax-identifier-length=}@var{n} option
286 @cindex option @option{-fmax-identifier-length=}@var{n}
287 Specify the maximum allowed identifier length. Typical values are
288 31 (Fortran 95) and 63 (Fortran 2003).
290 @item -fimplicit-none
291 @cindex @code{-fimplicit-none} option
292 @cindex option, @code{-fimplicit-none}
293 Specify that no implicit typing is allowed, unless overridden by explicit
294 @code{IMPLICIT} statements. This is the equivalent of adding
295 @code{implicit none} to the start of every procedure.
298 @cindex @code{-fcray-pointer} option
299 @cindex option, @code{-fcray-pointer}
300 Enable the Cray pointer extension, which provides C-like pointer
304 @cindex @code{-fopenmp} option
305 @cindex option, @code{-fopenmp}
307 Enable the OpenMP extensions. This includes OpenMP @code{!$omp} directives
309 and @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form,
310 @code{!$} conditional compilation sentinels in free form
311 and @code{c$}, @code{*$} and @code{!$} sentinels in fixed form,
312 and when linking arranges for the OpenMP runtime library to be linked
316 @cindex @code{-frange-check} option
317 @cindex option, @code{-frange-check}
318 Enable range checking on results of simplification of constant
319 expressions during compilation. For example, by default, GNU Fortran
320 will give an overflow error at compile time when simplifying @code{a =
321 EXP(1000)}. With @option{-fno-range-check}, no error will be given and
322 the variable @code{a} will be assigned the value @code{+Infinity}.
323 Similarly, @code{DATA i/Z'FFFFFFFF'/} will result in an integer overflow
324 on most systems, but with @option{-fno-range-check} the value will
325 ``wrap around'' and @code{i} will be initialized to @math{-1} instead.
328 @cindex @code{-std=}@var{std} option
329 @cindex option, @code{-std=}@var{std}
330 Conform to the specified standard. The default value for @var{std} is
331 @samp{gnu}; a superset of the Fortran 95 standard which includes all
332 of the GNU extensions recommended for use in new code. The @samp{legacy}
333 value also includes obsolete extensions that may be required for old
334 non-standard programs. Strict conformance to the Fortran 95 and Fortran 2003
335 standards is specified by @samp{f95} and @samp{f2003}, respectively.
339 @node Error and Warning Options
340 @section Options to Request or Suppress Errors and Warnings
341 @cindex options, warnings
342 @cindex options, errors
343 @cindex warnings, suppressing
344 @cindex messages, error
345 @cindex messages, warning
346 @cindex suppressing warnings
348 Errors are diagnostic messages that report that the GNU Fortran compiler
349 cannot compile the relevant piece of source code. The compiler will
350 continue to process the program in an attempt to report further errors
351 to aid in debugging, but will not produce any compiled output.
353 Warnings are diagnostic messages that report constructions which
354 are not inherently erroneous but which are risky or suggest there is
355 likely to be a bug in the program. Unless @option{-Werror} is specified,
356 they do not prevent compilation of the program.
358 You can request many specific warnings with options beginning @option{-W},
359 for example @option{-Wimplicit} to request warnings on implicit
360 declarations. Each of these specific warning options also has a
361 negative form beginning @option{-Wno-} to turn off warnings;
362 for example, @option{-Wno-implicit}. This manual lists only one of the
363 two forms, whichever is not the default.
365 These options control the amount and kinds of errors and warnings produced
369 @item -fmax-errors-@var{n}
370 @cindex @code{-fmax-errors-}@var{n} option
371 @cindex option, @code{-fmax-errors-}@var{n}
372 @cindex errors, limiting
373 Limits the maximum number of error messages to @var{n}, at which point
374 GNU Fortran bails out rather than attempting to continue processing the
375 source code. If @var{n} is 0, there is no limit on the number of error
379 @cindex @code{-fsyntax-only} option
380 @cindex option, @code{-fsyntax-only}
381 @cindex syntax checking
382 Check the code for syntax errors, but don't do anything beyond that.
385 @cindex @code{-pedantic} option
386 @cindex option, @code{-pedantic}
387 Issue warnings for uses of extensions to Fortran 95.
388 @option{-pedantic} also applies to C-language constructs where they
389 occur in GNU Fortran source files, such as use of @samp{\e} in a
390 character constant within a directive like @code{#include}.
392 Valid Fortran 95 programs should compile properly with or without
394 However, without this option, certain GNU extensions and traditional
395 Fortran features are supported as well.
396 With this option, many of them are rejected.
398 Some users try to use @option{-pedantic} to check programs for conformance.
399 They soon find that it does not do quite what they want---it finds some
400 nonstandard practices, but not all.
401 However, improvements to GNU Fortran in this area are welcome.
403 This should be used in conjunction with @option{-std=f95} or
406 @item -pedantic-errors
407 @cindex @code{-pedantic-errors} option
408 @cindex option, @code{-pedantic-errors}
409 Like @option{-pedantic}, except that errors are produced rather than
413 @cindex @code{-w} option
414 @cindex option, @code{-w}
415 Inhibit all warning messages.
418 @cindex @code{-Wall} option
419 @cindex option, @code{-Wall}
421 @cindex warnings, all
422 Enables commonly used warning options pertaining to usage that
423 we recommend avoiding and that we believe are easy to avoid.
424 This currently includes @option{-Waliasing},
425 @option{-Wampersand}, @option{-Wsurprising}, @option{-Wnonstd-intrinsic},
426 @option{-Wno-tabs}, and @option{-Wline-truncation}.
429 @cindex @code{-Waliasing} option
430 @cindex option, @code{-Waliasing}
432 Warn about possible aliasing of dummy arguments. Specifically, it warns
433 if the same actual argument is associated with a dummy argument with
434 @code{INTENT(IN)} and a dummy argument with @code{INTENT(OUT)} in a call
435 with an explicit interface.
437 The following example will trigger the warning.
441 integer, intent(in) :: a
442 integer, intent(out) :: b
451 @cindex @code{-Wampersand} option
452 @cindex option, @code{-Wampersand}
454 Warn about missing ampersand in continued character constants. The warning is
455 given with @option{-Wampersand}, @option{-pedantic}, @option{-std=f95}, and
456 @option{-std=f2003}. Note: With no ampersand given in a continued character
457 constant, GNU Fortran assumes continuation at the first non-comment,
458 non-whitespace character after the ampersand that initiated the continuation.
461 @cindex @code{-Wconversion} option
462 @cindex option, @code{-Wconversion}
464 Warn about implicit conversions between different types.
466 @item -Wimplicit-interface
467 @cindex @code{-Wimplicit-interface} option
468 @cindex option, @code{-Wimplicit-interface}
469 Warn if a procedure is called without an explicit interface.
470 Note this only checks that an explicit interface is present. It does not
471 check that the declared interfaces are consistent across program units.
473 @item -Wnonstd-intrinsic
474 @cindex @code{-Wnonstd-intrinsic} option
475 @cindex option, @code{-Wnonstd-intrinsic}
476 Warn if the user tries to use an intrinsic that does not belong to the
477 standard the user has chosen via the -std option.
480 @cindex @code{-Wsurprising} option
481 @cindex option, @code{-Wsurprising}
482 @cindex Suspicious code
483 Produce a warning when ``suspicious'' code constructs are encountered.
484 While technically legal these usually indicate that an error has been made.
486 This currently produces a warning under the following circumstances:
490 An INTEGER SELECT construct has a CASE that can never be matched as its
491 lower value is greater than its upper value.
494 A LOGICAL SELECT construct has three CASE statements.
498 @cindex @code{-Wtabs} option
499 @cindex option, @code{-Wtabs}
501 By default, tabs are accepted as whitespace, but tabs are not members
502 of the Fortran Character Set. @option{-Wno-tabs} will cause a warning
503 to be issued if a tab is encountered. Note, @option{-Wno-tabs} is active
504 for @option{-pedantic}, @option{-std=f95}, @option{-std=f2003}, and
508 @cindex @code{-Wunderflow} option
509 @cindex option, @code{-Wunderflow}
511 Produce a warning when numerical constant expressions are
512 encountered, which yield an UNDERFLOW during compilation.
515 @cindex @code{-Werror} option
516 @cindex option, @code{-Werror}
517 Turns all warnings into errors.
520 @cindex @code{-W} option
521 @cindex option, @code{-W}
522 @cindex extra warnings
523 @cindex warnings, extra
524 Turns on ``extra warnings'' and, if optimization is specified
525 via @option{-O}, the @option{-Wuninitialized} option.
526 (This might change in future versions of GNU Fortran.)
529 @xref{Error and Warning Options,,Options to Request or Suppress Errors and
530 Warnings, gcc,Using the GNU Compiler Collection (GCC)}, for information on
531 more options offered by the GBE shared by @command{gfortran}, @command{gcc}
532 and other GNU compilers.
534 Some of these have no effect when compiling programs written in Fortran.
536 @node Debugging Options
537 @section Options for Debugging Your Program or GNU Fortran
538 @cindex options, debugging
539 @cindex debugging information options
541 GNU Fortran has various special options that are used for debugging
542 either your program or the GNU Fortran compiler.
545 @item -fdump-parse-tree
546 @cindex @code{-fdump-parse-tree} option
547 @cindex option, @code{-fdump-parse-tree}
548 Output the internal parse tree before starting code generation. Only
549 really useful for debugging the GNU Fortran compiler itself.
551 @item -ffpe-trap=@var{list}
552 @cindex @code{-ffpe-trap=}@var{list} option
553 @cindex option, @code{-ffpe-trap=}@var{list}
554 Specify a list of IEEE exceptions when a Floating Point Exception
555 (FPE) should be raised. On most systems, this will result in a SIGFPE
556 signal being sent and the program being interrupted, producing a core
557 file useful for debugging. @var{list} is a (possibly empty) comma-separated
558 list of the following IEEE exceptions: @samp{invalid} (invalid floating
559 point operation, such as @code{SQRT(-1.0)}), @samp{zero} (division by
560 zero), @samp{overflow} (overflow in a floating point operation),
561 @samp{underflow} (underflow in a floating point operation),
562 @samp{precision} (loss of precision during operation) and @samp{denormal}
563 (operation produced a denormal value).
565 @cindex -fbacktrace option
566 @cindex options, -fbacktrace
570 Specify that, when a runtime error is encountered, the Fortran runtime
571 library should output a backtrace of the error. This option
572 only has influence for compilation of the Fortran main program.
574 @cindex -fdump-core option
575 @cindex options, -fdump-core
578 Request that a core-dump file is written to disk when a runtime error
579 is encountered on systems that support core dumps. This option is
580 only effective for the compilation of the Fortran main program.
584 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
585 gcc,Using the GNU Compiler Collection (GCC)}, for more information on
588 @node Directory Options
589 @section Options for Directory Search
590 @cindex directory, options
591 @cindex options, directory search
593 @cindex INCLUDE directive
594 @cindex directive, INCLUDE
595 These options affect how GNU Fortran searches
596 for files specified by the @code{INCLUDE} directive and where it searches
597 for previously compiled modules.
599 It also affects the search paths used by @command{cpp} when used to preprocess
604 @cindex @code{-I}@var{dir} option
605 @cindex option, @code{-I}@var{dir}
606 @cindex directory, search paths for inclusion
607 @cindex inclusion, directory search paths for
608 @cindex search paths, for included files
609 @cindex paths, search
610 @cindex module search path
611 These affect interpretation of the @code{INCLUDE} directive
612 (as well as of the @code{#include} directive of the @command{cpp}
615 Also note that the general behavior of @option{-I} and
616 @code{INCLUDE} is pretty much the same as of @option{-I} with
617 @code{#include} in the @command{cpp} preprocessor, with regard to
618 looking for @file{header.gcc} files and other such things.
620 This path is also used to search for @file{.mod} files when previously
621 compiled modules are required by a @code{USE} statement.
623 @xref{Directory Options,,Options for Directory Search,
624 gcc,Using the GNU Compiler Collection (GCC)}, for information on the
629 @cindex @code{-M}@var{dir} option
630 @cindex option, -@code{-M}@var{dir}
631 @cindex @code{-J}@var{dir} option
632 @cindex option, -@code{-J}@var{dir}
633 This option specifies where to put @file{.mod} files for compiled modules.
634 It is also added to the list of directories to searched by an @code{USE}
637 The default is the current directory.
639 @option{-J} is an alias for @option{-M} to avoid conflicts with existing
643 @node Runtime Options
644 @section Influencing runtime behavior
645 @cindex runtime, options
647 These options affect the runtime behavior of programs compiled with GNU Fortran.
649 @item -fconvert=@var{conversion}
650 @cindex @code{-fconvert=}@var{conversion} option
651 @cindex option, @code{-fconvert=}@var{conversion}
652 Specify the representation of data for unformatted files. Valid
653 values for conversion are: @samp{native}, the default; @samp{swap},
654 swap between big- and little-endian; @samp{big-endian}, use big-endian
655 representation for unformatted files; @samp{little-endian}, use little-endian
656 representation for unformatted files.
658 @emph{This option has an effect only when used in the main program.
659 The @code{CONVERT} specifier and the GFORTRAN_CONVERT_UNIT environment
660 variable override the default specified by @option{-fconvert}.}
662 @item -frecord-marker=@var{length}
663 @cindex @code{-frecord-marker=}@var{length} option
664 @cindex option, @code{-frecord-marker=}@var{length}
665 Specify the length of record markers for unformatted files.
666 Valid values for @var{length} are 4 and 8. Default is 4.
667 @emph{This is different from previous versions of gfortran},
668 which specified a default record marker length of 8 on most
669 systems. If you want to read or write files compatible
670 with earlier versions of gfortran, use @option{-frecord-marker=8}.
672 @item -fmax-subrecord-length=@var{length}
673 @cindex @code{-fmax-subrecord-length=}@var{length} option
674 @cindex option, @code{-fmax-subrecord-length=}@var{length}
675 Specify the maximum length for a subrecord. The maximum permitted
676 value for length is 2147483639, which is also the default. Only
677 really useful for use by the gfortran testsuite.
680 @node Code Gen Options
681 @section Options for Code Generation Conventions
682 @cindex code generation, conventions
683 @cindex options, code generation
684 @cindex run-time, options
686 These machine-independent options control the interface conventions
687 used in code generation.
689 Most of them have both positive and negative forms; the negative form
690 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
691 one of the forms is listed---the one which is not the default. You
692 can figure out the other form by either removing @option{no-} or adding
697 @cindex @code{-fno-automatic} option
698 @cindex option, @code{-fno-automatic}
699 @cindex SAVE statement
700 @cindex statements, SAVE
701 Treat each program unit as if the @code{SAVE} statement was specified for
702 every local variable and array referenced in it. Does not affect common
703 blocks. (Some Fortran compilers provide this option under the name
707 @cindex @code{-ff2c} option
708 @cindex option, @code{-ff2c}
709 @cindex calling convention
710 @cindex @command{f2c} calling convention
711 @cindex @command{g77} calling convention
712 @cindex libf2c calling convention
713 Generate code designed to be compatible with code generated
714 by @command{g77} and @command{f2c}.
716 The calling conventions used by @command{g77} (originally implemented
717 in @command{f2c}) require functions that return type
718 default @code{REAL} to actually return the C type @code{double}, and
719 functions that return type @code{COMPLEX} to return the values via an
720 extra argument in the calling sequence that points to where to
721 store the return value. Under the default GNU calling conventions, such
722 functions simply return their results as they would in GNU
723 C---default @code{REAL} functions return the C type @code{float}, and
724 @code{COMPLEX} functions return the GNU C type @code{complex}.
725 Additionally, this option implies the @option{-fsecond-underscore}
726 option, unless @option{-fno-second-underscore} is explicitly requested.
728 This does not affect the generation of code that interfaces with
729 the @command{libgfortran} library.
731 @emph{Caution:} It is not a good idea to mix Fortran code compiled with
732 @option{-ff2c} with code compiled with the default @option{-fno-f2c}
733 calling conventions as, calling @code{COMPLEX} or default @code{REAL}
734 functions between program parts which were compiled with different
735 calling conventions will break at execution time.
737 @emph{Caution:} This will break code which passes intrinsic functions
738 of type default @code{REAL} or @code{COMPLEX} as actual arguments, as
739 the library implementations use the @option{-fno-f2c} calling conventions.
741 @item -fno-underscoring
742 @cindex @code{-fno-underscoring option}
743 @cindex option, @code{-fno-underscoring}
745 @cindex symbol names, underscores
746 @cindex transforming symbol names
747 @cindex symbol names, transforming
748 Do not transform names of entities specified in the Fortran
749 source file by appending underscores to them.
751 With @option{-funderscoring} in effect, GNU Fortran appends one
752 underscore to external names with no underscores. This is done to ensure
753 compatibility with code produced by many UNIX Fortran compilers.
755 @emph{Caution}: The default behavior of GNU Fortran is
756 incompatible with @command{f2c} and @command{g77}, please use the
757 @option{-ff2c} option if you want object files compiled with
758 GNU Fortran to be compatible with object code created with these
761 Use of @option{-fno-underscoring} is not recommended unless you are
762 experimenting with issues such as integration of GNU Fortran into
763 existing system environments (vis-a-vis existing libraries, tools, and
766 For example, with @option{-funderscoring}, and assuming other defaults like
767 @option{-fcase-lower} and that @code{j()} and @code{max_count()} are
768 external functions while @code{my_var} and @code{lvar} are local variables,
771 I = J() + MAX_COUNT (MY_VAR, LVAR)
774 is implemented as something akin to:
776 i = j_() + max_count__(&my_var__, &lvar);
779 With @option{-fno-underscoring}, the same statement is implemented as:
782 i = j() + max_count(&my_var, &lvar);
785 Use of @option{-fno-underscoring} allows direct specification of
786 user-defined names while debugging and when interfacing GNU Fortran
787 code with other languages.
789 Note that just because the names match does @emph{not} mean that the
790 interface implemented by GNU Fortran for an external name matches the
791 interface implemented by some other language for that same name.
792 That is, getting code produced by GNU Fortran to link to code produced
793 by some other compiler using this or any other method can be only a
794 small part of the overall solution---getting the code generated by
795 both compilers to agree on issues other than naming can require
796 significant effort, and, unlike naming disagreements, linkers normally
797 cannot detect disagreements in these other areas.
799 Also, note that with @option{-fno-underscoring}, the lack of appended
800 underscores introduces the very real possibility that a user-defined
801 external name will conflict with a name in a system library, which
802 could make finding unresolved-reference bugs quite difficult in some
803 cases---they might occur at program run time, and show up only as
804 buggy behavior at run time.
806 In future versions of GNU Fortran we hope to improve naming and linking
807 issues so that debugging always involves using the names as they appear
808 in the source, even if the names as seen by the linker are mangled to
809 prevent accidental linking between procedures with incompatible
812 @item -fsecond-underscore
813 @cindex @code{-fsecond-underscore option}
814 @cindex option, @code{-fsecond-underscore}
816 @cindex symbol names, underscores
817 @cindex transforming symbol names
818 @cindex symbol names, transforming
819 @cindex @command{f2c} calling convention
820 @cindex @command{g77} calling convention
821 @cindex libf2c calling convention
822 By default, GNU Fortran appends an underscore to external
823 names. If this option is used GNU Fortran appends two
824 underscores to names with underscores and one underscore to external names
825 with no underscores. GNU Fortran also appends two underscores to
826 internal names with underscores to avoid naming collisions with external
829 This option has no effect if @option{-fno-underscoring} is
830 in effect. It is implied by the @option{-ff2c} option.
832 Otherwise, with this option, an external name such as @code{MAX_COUNT}
833 is implemented as a reference to the link-time external symbol
834 @code{max_count__}, instead of @code{max_count_}. This is required
835 for compatibility with @command{g77} and @command{f2c}, and is implied
836 by use of the @option{-ff2c} option.
839 @cindex @code{-fbounds-check} option
840 @cindex option, @code{-fbounds-check}
841 @cindex bounds checking
842 @cindex range checking
843 @cindex array bounds checking
844 @cindex subscript checking
845 @cindex checking subscripts
846 Enable generation of run-time checks for array subscripts
847 and against the declared minimum and maximum values. It also
848 checks array indices for assumed and deferred
849 shape arrays against the actual allocated bounds.
851 In the future this may also include other forms of checking, e.g., checking
852 substring references.
854 @item -fmax-stack-var-size=@var{n}
855 @cindex @code{-fmax-stack-var-size} option
856 @cindex option, @code{-fmax-stack-var-size}
857 This option specifies the size in bytes of the largest array that will be put
860 This option currently only affects local arrays declared with constant
861 bounds, and may not apply to all character variables.
862 Future versions of GNU Fortran may improve this behavior.
864 The default value for @var{n} is 32768.
867 @cindex @code{-fpack-derived} option
868 @cindex option, @code{-fpack-derived}
869 @cindex Structure packing
870 This option tells GNU Fortran to pack derived type members as closely as
871 possible. Code compiled with this option is likely to be incompatible
872 with code compiled without this option, and may execute slower.
874 @item -frepack-arrays
875 @cindex @code{-frepack-arrays} option
876 @cindex option, @code{-frepack-arrays}
877 @cindex Repacking arrays
878 In some circumstances GNU Fortran may pass assumed shape array
879 sections via a descriptor describing a noncontiguous area of memory.
880 This option adds code to the function prologue to repack the data into
881 a contiguous block at runtime.
883 This should result in faster accesses to the array. However it can introduce
884 significant overhead to the function call, especially when the passed data
888 @cindex @code{-fshort-enums} option
889 @cindex option, @code{-fshort-enums}
890 This option is provided for interoperability with C code that was
891 compiled with the @option{-fshort-enums} option. It will make
892 GNU Fortran choose the smallest @code{INTEGER} kind a given
893 enumerator set will fit in, and give all its enumerators this kind.
895 @item -fexternal-blas
896 @cindex @code{-fexternal-blas} option
897 @cindex option, @code{-fexternal-blas}
898 This option will make gfortran generate calls to BLAS functions for some
899 matrix operations like @code{MATMUL}, instead of using our own
900 algorithms, if the size of the matrices involved is larger than a given
901 limit (see @option{-fblas-matmul-limit}). This may be profitable if an
902 optimized vendor BLAS library is available. The BLAS library will have
903 to be specified at link time.
905 @item -fblas-matmul-limit=@var{n}
906 @cindex @code{-fblas-matmul-limit} option
907 @cindex option, @code{-fblas-matmul-limit}
908 Only significant when @option{-fexternal-blas} is in effect.
909 Matrix multiplication of matrices with size larger than (or equal to) @var{n}
910 will be performed by calls to BLAS functions, while others will be
911 handled by @command{gfortran} internal algorithms. If the matrices
912 involved are not square, the size comparison is performed using the
913 geometric mean of the dimensions of the argument and result matrices.
915 The default value for @var{n} is 30.
919 @xref{Code Gen Options,,Options for Code Generation Conventions,
920 gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
922 shared by @command{gfortran}, @command{gcc}, and other GNU compilers.
927 @node Environment Variables
928 @section Environment Variables Affecting @command{gfortran}
929 @cindex environment variables
931 @c man begin ENVIRONMENT
933 The @command{gfortran} compiler currently does not make use of any environment
934 variables to control its operation above and beyond those
935 that affect the operation of @command{gcc}.
937 @xref{Environment Variables,,Environment Variables Affecting GCC,
938 gcc,Using the GNU Compiler Collection (GCC)}, for information on environment
941 @xref{Runtime}, for environment variables that affect the
942 run-time behavior of programs compiled with GNU Fortran.