OSDN Git Service

6d3681d69a110c730f216e5a8c35c7ccec68d40b
[pf3gnuchains/gcc-fork.git] / gcc / fortran / invoke.texi
1 @c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010
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.
5
6 @ignore
7 @c man begin COPYRIGHT
8 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009
9 Free Software Foundation, Inc.
10
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 ``Funding Free Software'', the Front-Cover
15 Texts being (a) (see below), and with the Back-Cover Texts being (b)
16 (see below).  A copy of the license is included in the gfdl(7) man page.
17
18 (a) The FSF's Front-Cover Text is:
19
20      A GNU Manual
21
22 (b) The FSF's Back-Cover Text is:
23
24      You have freedom to copy and modify this GNU Manual, like GNU
25      software.  Copies published by the Free Software Foundation raise
26      funds for GNU development.
27 @c man end
28 @c Set file name and title for the man page.
29 @setfilename gfortran
30 @settitle GNU Fortran compiler.
31 @c man begin SYNOPSIS
32 gfortran [@option{-c}|@option{-S}|@option{-E}]
33          [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
34          [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
35          [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
36          [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
37          [@option{-f}@var{option}@dots{}]
38          [@option{-m}@var{machine-option}@dots{}]
39          [@option{-o} @var{outfile}] @var{infile}@dots{}
40
41 Only the most useful options are listed here; see below for the
42 remainder.
43 @c man end
44 @c man begin SEEALSO
45 gpl(7), gfdl(7), fsf-funding(7),
46 cpp(1), gcov(1), gcc(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
47 and the Info entries for @file{gcc}, @file{cpp}, @file{gfortran}, @file{as},
48 @file{ld}, @file{binutils} and @file{gdb}.
49 @c man end
50 @c man begin BUGS
51 For instructions on reporting bugs, see
52 @w{@value{BUGURL}}.
53 @c man end
54 @c man begin AUTHOR
55 See the Info entry for @command{gfortran} for contributors to GCC and
56 GNU Fortran.
57 @c man end
58 @end ignore
59
60 @node Invoking GNU Fortran
61 @chapter GNU Fortran Command Options
62 @cindex GNU Fortran command options
63 @cindex command options
64 @cindex options, @command{gfortran} command
65
66 @c man begin DESCRIPTION
67
68 The @command{gfortran} command supports all the options supported by the
69 @command{gcc} command.  Only options specific to GNU Fortran are documented here.
70
71 @xref{Invoking GCC,,GCC Command Options,gcc,Using the GNU Compiler
72 Collection (GCC)}, for information
73 on the non-Fortran-specific aspects of the @command{gcc} command (and,
74 therefore, the @command{gfortran} command).
75
76 @cindex options, negative forms
77 All GCC and GNU Fortran options
78 are accepted both by @command{gfortran} and by @command{gcc}
79 (as well as any other drivers built at the same time,
80 such as @command{g++}),
81 since adding GNU Fortran to the GCC distribution
82 enables acceptance of GNU Fortran options
83 by all of the relevant drivers.
84
85 In some cases, options have positive and negative forms;
86 the negative form of @option{-ffoo} would be @option{-fno-foo}.
87 This manual documents only one of these two forms, whichever
88 one is not the default.
89 @c man end
90
91 @menu
92 * Option Summary::      Brief list of all @command{gfortran} options,
93                         without explanations.
94 * Fortran Dialect Options::  Controlling the variant of Fortran language
95                              compiled.
96 * Preprocessing Options::  Enable and customize preprocessing.
97 * Error and Warning Options::     How picky should the compiler be?
98 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
99 * Directory Options::   Where to find module files
100 * Link Options ::       Influencing the linking step
101 * Runtime Options::     Influencing runtime behavior
102 * Code Gen Options::    Specifying conventions for function calls, data layout
103                         and register usage.
104 * Environment Variables:: Environment variables that affect @command{gfortran}.
105 @end menu
106
107 @node Option Summary
108 @section Option summary
109
110 @c man begin OPTIONS
111
112 Here is a summary of all the options specific to GNU Fortran, grouped
113 by type.  Explanations are in the following sections.
114
115 @table @emph
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  -fno-range-check -fbackslash -fmodule-private}
125
126 @item Preprocessing Options
127 @xref{Preprocessing Options,,Enable and customize preprocessing}.
128 @gccoptlist{-cpp -dD -dI -dM -dN -dU -fworking-directory @gol
129 -imultilib @var{dir} -iprefix @var{file} -isysroot @var{dir} @gol
130 -iquote -isystem @var{dir} -nocpp -nostdinc -undef @gol
131 -A@var{question}=@var{answer} -A-@var{question}@r{[}=@var{answer}@r{]} @gol
132 -C -CC -D@var{macro}@r{[}=@var{defn}@r{]} -U@var{macro} -H -P}
133
134 @item Error and Warning Options
135 @xref{Error and Warning Options,,Options to request or suppress errors
136 and warnings}.
137 @gccoptlist{-fmax-errors=@var{n} @gol
138 -fsyntax-only  -pedantic  -pedantic-errors @gol
139 -Wall  -Waliasing  -Wampersand  -Warray-bounds -Wcharacter-truncation @gol
140 -Wconversion -Wimplicit-interface  -Wimplicit-procedure  -Wline-truncation @gol
141 -Wintrinsics-std  -Wsurprising  -Wno-tabs  -Wunderflow  -Wunused-parameter @gol
142 -Wintrinsics-shadow  -Wno-align-commons}
143
144 @item Debugging Options
145 @xref{Debugging Options,,Options for debugging your program or GNU Fortran}.
146 @gccoptlist{-fdump-parse-tree  -ffpe-trap=@var{list} @gol
147 -fdump-core -fbacktrace}
148
149 @item Directory Options
150 @xref{Directory Options,,Options for directory search}.
151 @gccoptlist{-I@var{dir}  -J@var{dir}  -M@var{dir}  @gol
152 -fintrinsic-modules-path @var{dir}}
153
154 @item Link Options
155 @xref{Link Options,,Options for influencing the linking step}.
156 @gccoptlist{-static-libgfortran}
157
158 @item Runtime Options
159 @xref{Runtime Options,,Options for influencing runtime behavior}.
160 @gccoptlist{-fconvert=@var{conversion}  -fno-range-check
161 -frecord-marker=@var{length} @gol  -fmax-subrecord-length=@var{length}
162 -fsign-zero}
163
164 @item Code Generation Options
165 @xref{Code Gen Options,,Options for code generation conventions}.
166 @gccoptlist{-fno-automatic  -ff2c  -fno-underscoring @gol
167 -fwhole-file -fsecond-underscore @gol
168 -fbounds-check -fcheck-array-temporaries  -fmax-array-constructor =@var{n} @gol
169 -fcheck=@var{<all|array-temps|bounds|do|mem|pointer|recursion>}
170 -fmax-stack-var-size=@var{n} @gol
171 -fpack-derived  -frepack-arrays  -fshort-enums  -fexternal-blas @gol
172 -fblas-matmul-limit=@var{n} -frecursive -finit-local-zero @gol
173 -finit-integer=@var{n} -finit-real=@var{<zero|inf|-inf|nan|snan>} @gol
174 -finit-logical=@var{<true|false>} -finit-character=@var{n} @gol
175 -fno-align-commons -fno-protect-parens}
176 @end table
177
178 @menu
179 * Fortran Dialect Options::  Controlling the variant of Fortran language
180                              compiled.
181 * Preprocessing Options::  Enable and customize preprocessing.
182 * Error and Warning Options::     How picky should the compiler be?
183 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
184 * Directory Options::   Where to find module files
185 * Link Options ::       Influencing the linking step
186 * Runtime Options::     Influencing runtime behavior
187 * Code Gen Options::    Specifying conventions for function calls, data layout
188                         and register usage.
189 @end menu
190
191 @node Fortran Dialect Options
192 @section Options controlling Fortran dialect
193 @cindex dialect options
194 @cindex language, dialect options
195 @cindex options, dialect
196
197 The following options control the details of the Fortran dialect
198 accepted by the compiler:
199
200 @table @gcctabopt
201 @item -ffree-form
202 @item -ffixed-form
203 @opindex @code{ffree-form}
204 @opindex @code{fno-fixed-form}
205 @cindex options, fortran dialect
206 @cindex file format, free
207 @cindex file format, fixed
208 Specify the layout used by the source file.  The free form layout
209 was introduced in Fortran 90.  Fixed form was traditionally used in
210 older Fortran programs.  When neither option is specified, the source
211 form is determined by the file extension.
212
213 @item -fall-intrinsics
214 @opindex @code{fall-intrinsics}
215 This option causes all intrinsic procedures (including the GNU-specific
216 extensions) to be accepted.  This can be useful with @option{-std=f95} to
217 force standard-compliance but get access to the full range of intrinsics
218 available with @command{gfortran}.  As a consequence, @option{-Wintrinsics-std}
219 will be ignored and no user-defined procedure with the same name as any
220 intrinsic will be called except when it is explicitly declared @code{EXTERNAL}.
221
222 @item -fd-lines-as-code
223 @item -fd-lines-as-comments
224 @opindex @code{fd-lines-as-code}
225 @opindex @code{fd-lines-as-comments}
226 Enable special treatment for lines beginning with @code{d} or @code{D}
227 in fixed form sources.  If the @option{-fd-lines-as-code} option is
228 given they are treated as if the first column contained a blank.  If the
229 @option{-fd-lines-as-comments} option is given, they are treated as
230 comment lines.
231
232 @item -fdefault-double-8
233 @opindex @code{fdefault-double-8}
234 Set the @code{DOUBLE PRECISION} type to an 8 byte wide type.  If
235 @option{-fdefault-real-8} is given, @code{DOUBLE PRECISION} would
236 instead be promoted to 16 bytes if possible, and @option{-fdefault-double-8}
237 can be used to prevent this.  The kind of real constants like @code{1.d0} will
238 not be changed by @option{-fdefault-real-8} though, so also
239 @option{-fdefault-double-8} does not affect it.
240
241 @item -fdefault-integer-8
242 @opindex @code{fdefault-integer-8}
243 Set the default integer and logical types to an 8 byte wide type.
244 Do nothing if this is already the default.  This option also affects
245 the kind of integer constants like @code{42}.
246
247 @item -fdefault-real-8
248 @opindex @code{fdefault-real-8}
249 Set the default real type to an 8 byte wide type.
250 Do nothing if this is already the default.  This option also affects
251 the kind of non-double real constants like @code{1.0}, and does promote
252 the default width of @code{DOUBLE PRECISION} to 16 bytes if possible, unless
253 @code{-fdefault-double-8} is given, too.
254
255 @item -fdollar-ok
256 @opindex @code{fdollar-ok}
257 @cindex $
258 @cindex symbol names
259 @cindex character set
260 Allow @samp{$} as a valid non-first character in a symbol name. Symbols 
261 that start with @samp{$} are rejected since it is unclear which rules to
262 apply to implicit typing as different vendors implement different rules.
263 Using @samp{$} in @code{IMPLICIT} statements is also rejected.
264
265 @item -fbackslash
266 @opindex @code{backslash}
267 @cindex backslash
268 @cindex escape characters
269 Change the interpretation of backslashes in string literals from a single
270 backslash character to ``C-style'' escape characters. The following
271 combinations are expanded @code{\a}, @code{\b}, @code{\f}, @code{\n},
272 @code{\r}, @code{\t}, @code{\v}, @code{\\}, and @code{\0} to the ASCII
273 characters alert, backspace, form feed, newline, carriage return,
274 horizontal tab, vertical tab, backslash, and NUL, respectively.
275 Additionally, @code{\x}@var{nn}, @code{\u}@var{nnnn} and
276 @code{\U}@var{nnnnnnnn} (where each @var{n} is a hexadecimal digit) are
277 translated into the Unicode characters corresponding to the specified code
278 points. All other combinations of a character preceded by \ are
279 unexpanded.
280
281 @item -fmodule-private
282 @opindex @code{fmodule-private}
283 @cindex module entities
284 @cindex private
285 Set the default accessibility of module entities to @code{PRIVATE}.
286 Use-associated entities will not be accessible unless they are explicitly
287 declared as @code{PUBLIC}.
288
289 @item -ffixed-line-length-@var{n}
290 @opindex @code{ffixed-line-length-}@var{n}
291 @cindex file format, fixed
292 Set column after which characters are ignored in typical fixed-form
293 lines in the source file, and through which spaces are assumed (as
294 if padded to that length) after the ends of short fixed-form lines.
295
296 Popular values for @var{n} include 72 (the
297 standard and the default), 80 (card image), and 132 (corresponding
298 to ``extended-source'' options in some popular compilers).
299 @var{n} may also be @samp{none}, meaning that the entire line is meaningful
300 and that continued character constants never have implicit spaces appended
301 to them to fill out the line.
302 @option{-ffixed-line-length-0} means the same thing as
303 @option{-ffixed-line-length-none}.
304
305 @item -ffree-line-length-@var{n}
306 @opindex @code{ffree-line-length-}@var{n}
307 @cindex file format, free
308 Set column after which characters are ignored in typical free-form
309 lines in the source file. The default value is 132.
310 @var{n} may be @samp{none}, meaning that the entire line is meaningful.
311 @option{-ffree-line-length-0} means the same thing as
312 @option{-ffree-line-length-none}.
313
314 @item -fmax-identifier-length=@var{n}
315 @opindex @code{fmax-identifier-length=}@var{n}
316 Specify the maximum allowed identifier length. Typical values are
317 31 (Fortran 95) and 63 (Fortran 2003 and Fortran 2008).
318
319 @item -fimplicit-none
320 @opindex @code{fimplicit-none}
321 Specify that no implicit typing is allowed, unless overridden by explicit
322 @code{IMPLICIT} statements.  This is the equivalent of adding
323 @code{implicit none} to the start of every procedure.
324
325 @item -fcray-pointer
326 @opindex @code{fcray-pointer}
327 Enable the Cray pointer extension, which provides C-like pointer
328 functionality.
329
330 @item -fopenmp
331 @opindex @code{fopenmp}
332 @cindex OpenMP
333 Enable the OpenMP extensions.  This includes OpenMP @code{!$omp} directives
334 in free form
335 and @code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form,
336 @code{!$} conditional compilation sentinels in free form
337 and @code{c$}, @code{*$} and @code{!$} sentinels in fixed form, 
338 and when linking arranges for the OpenMP runtime library to be linked
339 in.  The option @option{-fopenmp} implies @option{-frecursive}.
340
341 @item -fno-range-check
342 @opindex @code{frange-check}
343 Disable range checking on results of simplification of constant
344 expressions during compilation.  For example, GNU Fortran will give
345 an error at compile time when simplifying @code{a = 1. / 0}.
346 With this option, no error will be given and @code{a} will be assigned
347 the value @code{+Infinity}.  If an expression evaluates to a value
348 outside of the relevant range of [@code{-HUGE()}:@code{HUGE()}],
349 then the expression will be replaced by @code{-Inf} or @code{+Inf}
350 as appropriate.
351 Similarly, @code{DATA i/Z'FFFFFFFF'/} will result in an integer overflow
352 on most systems, but with @option{-fno-range-check} the value will
353 ``wrap around'' and @code{i} will be initialized to @math{-1} instead.
354
355 @item -std=@var{std}
356 @opindex @code{std=}@var{std} option
357 Specify the standard to which the program is expected to conform, which
358 may be one of @samp{f95}, @samp{f2003}, @samp{f2008}, @samp{gnu}, or
359 @samp{legacy}.  The default value for @var{std} is @samp{gnu}, which
360 specifies a superset of the Fortran 95 standard that includes all of the
361 extensions supported by GNU Fortran, although warnings will be given for
362 obsolete extensions not recommended for use in new code.  The
363 @samp{legacy} value is equivalent but without the warnings for obsolete
364 extensions, and may be useful for old non-standard programs.  The
365 @samp{f95}, @samp{f2003} and @samp{f2008} values specify strict
366 conformance to the Fortran 95, Fortran 2003 and Fortran 2008 standards,
367 respectively; errors are given for all extensions beyond the relevant
368 language standard, and warnings are given for the Fortran 77 features
369 that are permitted but obsolescent in later standards.
370
371 @end table
372
373 @node Preprocessing Options
374 @section Enable and customize preprocessing
375 @cindex preprocessor
376 @cindex options, preprocessor
377 @cindex CPP
378
379 Preprocessor related options. See section 
380 @ref{Preprocessing and conditional compilation} for more detailed
381 information on preprocessing in @command{gfortran}.
382
383 @table @gcctabopt
384 @item -cpp
385 @item -nocpp
386 @opindex @code{cpp}
387 @opindex @code{fpp}
388 @cindex preprocessor, enable
389 @cindex preprocessor, disable
390 Enable preprocessing. The preprocessor is automatically invoked if
391 the file extension is @file{.fpp}, @file{.FPP},  @file{.F}, @file{.FOR},
392 @file{.FTN}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. Use
393 this option to manually enable preprocessing of any kind of Fortran file.
394
395 To disable preprocessing of files with any of the above listed extensions,
396 use the negative form: @option{-nocpp}.
397
398 The preprocessor is run in traditional mode, be aware that any
399 restrictions of the file-format, e.g. fixed-form line width,
400 apply for preprocessed output as well.
401
402 @item -dM
403 @opindex @code{dM}
404 @cindex preprocessor, debugging
405 @cindex debugging, preprocessor
406 Instead of the normal output, generate a list of @code{'#define'}
407 directives for all the macros defined during the execution of the
408 preprocessor, including predefined macros. This gives you a way
409 of finding out what is predefined in your version of the preprocessor.
410 Assuming you have no file @file{foo.f90}, the command
411 @smallexample
412   touch foo.f90; gfortran -cpp -dM foo.f90
413 @end smallexample
414 will show all the predefined macros.
415
416 @item -dD
417 @opindex @code{dD}
418 @cindex preprocessor, debugging
419 @cindex debugging, preprocessor
420 Like @option{-dM} except in two respects: it does not include the
421 predefined macros, and it outputs both the @code{#define} directives
422 and the result of preprocessing. Both kinds of output go to the
423 standard output file.
424
425 @item -dN
426 @opindex @code{dN}
427 @cindex preprocessor, debugging
428 @cindex debugging, preprocessor
429 Like @option{-dD}, but emit only the macro names, not their expansions.
430
431 @item -dU
432 @opindex @code{dU}
433 @cindex preprocessor, debugging
434 @cindex debugging, preprocessor
435 Like @option{dD} except that only macros that are expanded, or whose
436 definedness is tested in preprocessor directives, are output; the 
437 output is delayed until the use or test of the macro; and @code{'#undef'}
438 directives are also output for macros tested but undefined at the time.
439
440 @item -dI
441 @opindex @code{dI}
442 @cindex preprocessor, debugging
443 @cindex debugging, preprocessor
444 Output @code{'#include'} directives in addition to the result
445 of preprocessing.
446
447 @item -fworking-directory
448 @opindex @code{fworking-directory}
449 @cindex preprocessor, working directory
450 Enable generation of linemarkers in the preprocessor output that will
451 let the compiler know the current working directory at the time of
452 preprocessing. When this option is enabled, the preprocessor will emit,
453 after the initial linemarker, a second linemarker with the current
454 working directory followed by two slashes. GCC will use this directory,
455 when it's present in the preprocessed input, as the directory emitted
456 as the current working directory in some debugging information formats.
457 This option is implicitly enabled if debugging information is enabled,
458 but this can be inhibited with the negated form
459 @option{-fno-working-directory}. If the @option{-P} flag is present
460 in the command line, this option has no effect, since no @code{#line}
461 directives are emitted whatsoever.
462
463 @item -idirafter @var{dir}
464 @opindex @code{idirafter @var{dir}}
465 @cindex preprocessing, include path
466 Search @var{dir} for include files, but do it after all directories
467 specified with @option{-I} and the standard system directories have
468 been exhausted. @var{dir} is treated as a system include directory.
469 If dir begins with @code{=}, then the @code{=} will be replaced by
470 the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
471
472 @item -imultilib @var{dir}
473 @opindex @code{imultilib @var{dir}}
474 @cindex preprocessing, include path
475 Use @var{dir} as a subdirectory of the directory containing target-specific
476 C++ headers.
477
478 @item -iprefix @var{prefix}
479 @opindex @code{iprefix @var{prefix}}
480 @cindex preprocessing, include path
481 Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
482 options. If the @var{prefix} represents a directory, you should include
483 the final @code{'/'}.
484
485 @item -isysroot @var{dir}
486 @opindex @code{isysroot @var{dir}}
487 @cindex preprocessing, include path
488 This option is like the @option{--sysroot} option, but applies only to
489 header files. See the @option{--sysroot} option for more information.
490
491 @item -iquote @var{dir}
492 @opindex @code{iquote @var{dir}}
493 @cindex preprocessing, include path
494 Search @var{dir} only for header files requested with @code{#include "file"};
495 they are not searched for @code{#include <file>}, before all directories
496 specified by @option{-I} and before the standard system directories. If
497 @var{dir} begins with @code{=}, then the @code{=} will be replaced by the
498 sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
499
500 @item -isystem @var{dir}
501 @opindex @code{isystem @var{dir}}
502 @cindex preprocessing, include path
503 Search @var{dir} for header files, after all directories specified by
504 @option{-I} but before the standard system directories. Mark it as a
505 system directory, so that it gets the same special treatment as is
506 applied to the standard system directories. If @var{dir} begins with
507 @code{=}, then the @code{=} will be replaced by the sysroot prefix;
508 see @option{--sysroot} and @option{-isysroot}.
509
510 @item -nostdinc
511 @opindex @code{nostdinc}
512 Do not search the standard system directories for header files. Only
513 the directories you have specified with @option{-I} options (and the
514 directory of the current file, if appropriate) are searched.
515
516 @item -undef
517 @opindex @code{undef}
518 Do not predefine any system-specific or GCC-specific macros.
519 The standard predefined macros remain defined.
520
521 @item -A@var{predicate}=@var{answer}
522 @opindex @code{A@var{predicate}=@var{answer}}
523 @cindex preprocessing, assertation
524 Make an assertion with the predicate @var{predicate} and answer @var{answer}.
525 This form is preferred to the older form -A predicate(answer), which is still
526 supported, because it does not use shell special characters.
527
528 @item -A-@var{predicate}=@var{answer}
529 @opindex @code{A-@var{predicate}=@var{answer}}
530 @cindex preprocessing, assertation
531 Cancel an assertion with the predicate @var{predicate} and answer @var{answer}.
532
533 @item -C
534 @opindex @code{C}
535 @cindex preprocessing, keep comments
536 Do not discard comments. All comments are passed through to the output
537 file, except for comments in processed directives, which are deleted
538 along with the directive.
539
540 You should be prepared for side effects when using @option{-C}; it causes
541 the preprocessor to treat comments as tokens in their own right. For example,
542 comments appearing at the start of what would be a directive line have the
543 effect of turning that line into an ordinary source line, since the first
544 token on the line is no longer a @code{'#'}.
545
546 Warning: this currently handles C-Style comments only. The preprocessor
547 does not yet recognize Fortran-style comments.
548
549 @item -CC
550 @opindex @code{CC}
551 @cindex preprocessing, keep comments
552 Do not discard comments, including during macro expansion. This is like
553 @option{-C}, except that comments contained within macros are also passed
554 through to the output file where the macro is expanded.
555
556 In addition to the side-effects of the @option{-C} option, the @option{-CC}
557 option causes all C++-style comments inside a macro to be converted to C-style
558 comments. This is to prevent later use of that macro from inadvertently
559 commenting out the remainder of the source line. The @option{-CC} option
560 is generally used to support lint comments.
561
562 Warning: this currently handles C- and C++-Style comments only. The
563 preprocessor does not yet recognize Fortran-style comments.
564
565 @item -D@var{name}
566 @opindex @code{D@var{name}}
567 @cindex preprocessing, define macros
568 Predefine name as a macro, with definition @code{1}.
569
570 @item -D@var{name}=@var{definition}
571 @opindex @code{D@var{name}=@var{definition}}
572 @cindex preprocessing, define macros
573 The contents of @var{definition} are tokenized and processed as if they
574 appeared during translation phase three in a @code{'#define'} directive.
575 In particular, the definition will be truncated by embedded newline
576 characters.
577
578 If you are invoking the preprocessor from a shell or shell-like program
579 you may need to use the shell's quoting syntax to protect characters such
580 as spaces that have a meaning in the shell syntax.
581
582 If you wish to define a function-like macro on the command line, write
583 its argument list with surrounding parentheses before the equals sign
584 (if any). Parentheses are meaningful to most shells, so you will need
585 to quote the option. With sh and csh, @code{-D'name(args...)=definition'}
586 works.
587
588 @option{-D} and @option{-U} options are processed in the order they are
589 given on the command line. All -imacros file and -include file options
590 are processed after all -D and -U options.
591
592 @item -H
593 @opindex @code{H}
594 Print the name of each header file used, in addition to other normal
595 activities. Each name is indented to show how deep in the @code{'#include'}
596 stack it is.
597
598 @item -P
599 @opindex @code{P}
600 @cindex preprocessing, no linemarkers
601 Inhibit generation of linemarkers in the output from the preprocessor.
602 This might be useful when running the preprocessor on something that
603 is not C code, and will be sent to a program which might be confused
604 by the linemarkers.
605
606 @item -U@var{name}
607 @opindex @code{U@var{name}}
608 @cindex preprocessing, undefine macros
609 Cancel any previous definition of @var{name}, either built in or provided
610 with a @option{-D} option.
611 @end table
612
613
614 @node Error and Warning Options
615 @section Options to request or suppress errors and warnings
616 @cindex options, warnings
617 @cindex options, errors
618 @cindex warnings, suppressing
619 @cindex messages, error
620 @cindex messages, warning
621 @cindex suppressing warnings
622
623 Errors are diagnostic messages that report that the GNU Fortran compiler
624 cannot compile the relevant piece of source code.  The compiler will
625 continue to process the program in an attempt to report further errors
626 to aid in debugging, but will not produce any compiled output.  
627
628 Warnings are diagnostic messages that report constructions which
629 are not inherently erroneous but which are risky or suggest there is
630 likely to be a bug in the program.  Unless @option{-Werror} is specified,
631 they do not prevent compilation of the program.
632
633 You can request many specific warnings with options beginning @option{-W},
634 for example @option{-Wimplicit} to request warnings on implicit
635 declarations.  Each of these specific warning options also has a
636 negative form beginning @option{-Wno-} to turn off warnings;
637 for example, @option{-Wno-implicit}.  This manual lists only one of the
638 two forms, whichever is not the default.
639
640 These options control the amount and kinds of errors and warnings produced
641 by GNU Fortran:
642
643 @table @gcctabopt
644 @item -fmax-errors=@var{n}
645 @opindex @code{fmax-errors=}@var{n}
646 @cindex errors, limiting
647 Limits the maximum number of error messages to @var{n}, at which point
648 GNU Fortran bails out rather than attempting to continue processing the
649 source code.  If @var{n} is 0, there is no limit on the number of error
650 messages produced.
651
652 @item -fsyntax-only
653 @opindex @code{fsyntax-only}
654 @cindex syntax checking
655 Check the code for syntax errors, but don't actually compile it.  This
656 will generate module files for each module present in the code, but no
657 other output file.
658
659 @item -pedantic
660 @opindex @code{pedantic}
661 Issue warnings for uses of extensions to Fortran 95.
662 @option{-pedantic} also applies to C-language constructs where they
663 occur in GNU Fortran source files, such as use of @samp{\e} in a
664 character constant within a directive like @code{#include}.
665
666 Valid Fortran 95 programs should compile properly with or without
667 this option.
668 However, without this option, certain GNU extensions and traditional
669 Fortran features are supported as well.
670 With this option, many of them are rejected.
671
672 Some users try to use @option{-pedantic} to check programs for conformance.
673 They soon find that it does not do quite what they want---it finds some
674 nonstandard practices, but not all.
675 However, improvements to GNU Fortran in this area are welcome.
676
677 This should be used in conjunction with @option{-std=f95},
678 @option{-std=f2003} or @option{-std=f2008}.
679
680 @item -pedantic-errors
681 @opindex @code{pedantic-errors}
682 Like @option{-pedantic}, except that errors are produced rather than
683 warnings.
684
685 @item -Wall
686 @opindex @code{Wall}
687 @cindex all warnings
688 @cindex warnings, all
689 Enables commonly used warning options pertaining to usage that
690 we recommend avoiding and that we believe are easy to avoid.
691 This currently includes @option{-Waliasing},
692 @option{-Wampersand}, @option{-Wsurprising}, @option{-Wintrinsics-std},
693 @option{-Wno-tabs}, @option{-Wintrinsic-shadow} and @option{-Wline-truncation}.
694
695 @item -Waliasing
696 @opindex @code{Waliasing}
697 @cindex aliasing
698 @cindex warnings, aliasing
699 Warn about possible aliasing of dummy arguments. Specifically, it warns
700 if the same actual argument is associated with a dummy argument with
701 @code{INTENT(IN)} and a dummy argument with @code{INTENT(OUT)} in a call
702 with an explicit interface.
703
704 The following example will trigger the warning.
705 @smallexample
706   interface
707     subroutine bar(a,b)
708       integer, intent(in) :: a
709       integer, intent(out) :: b
710     end subroutine
711   end interface
712   integer :: a
713
714   call bar(a,a)
715 @end smallexample
716
717 @item -Wampersand
718 @opindex @code{Wampersand}
719 @cindex warnings, ampersand
720 @cindex &
721 Warn about missing ampersand in continued character constants. The warning is
722 given with @option{-Wampersand}, @option{-pedantic}, @option{-std=f95},
723 @option{-std=f2003} and @option{-std=f2008}. Note: With no ampersand
724 given in a continued character constant, GNU Fortran assumes continuation
725 at the first non-comment, non-whitespace character after the ampersand
726 that initiated the continuation.
727
728 @item -Warray-temporaries
729 @opindex @code{Warray-temporaries}
730 @cindex warnings, array temporaries
731 Warn about array temporaries generated by the compiler.  The information
732 generated by this warning is sometimes useful in optimization, in order to
733 avoid such temporaries.
734
735 @item -Wcharacter-truncation
736 @opindex @code{Wcharacter-truncation}
737 @cindex warnings, character truncation
738 Warn when a character assignment will truncate the assigned string.
739
740 @item -Wline-truncation
741 @opindex @code{Wline-truncation}
742 @cindex warnings, line truncation
743 Warn when a source code line will be truncated.
744
745 @item -Wconversion
746 @opindex @code{Wconversion}
747 @cindex warnings, conversion
748 @cindex conversion
749 Warn about implicit conversions between different types.
750
751 @item -Wimplicit-interface
752 @opindex @code{Wimplicit-interface}
753 @cindex warnings, implicit interface
754 Warn if a procedure is called without an explicit interface.
755 Note this only checks that an explicit interface is present.  It does not
756 check that the declared interfaces are consistent across program units.
757
758 @item -Wimplicit-procedure
759 @opindex @code{Wimplicit-procedure}
760 @cindex warnings, implicit procedure
761 Warn if a procedure is called that has neither an explicit interface
762 nor has been declared as @code{EXTERNAL}.
763
764 @item -Wintrinsics-std
765 @opindex @code{Wintrinsics-std}
766 @cindex warnings, non-standard intrinsics
767 @cindex warnings, intrinsics of other standards
768 Warn if @command{gfortran} finds a procedure named like an intrinsic not
769 available in the currently selected standard (with @option{-std}) and treats
770 it as @code{EXTERNAL} procedure because of this.  @option{-fall-intrinsics} can
771 be used to never trigger this behavior and always link to the intrinsic
772 regardless of the selected standard.
773
774 @item -Wsurprising
775 @opindex @code{Wsurprising}
776 @cindex warnings, suspicious code
777 Produce a warning when ``suspicious'' code constructs are encountered.
778 While technically legal these usually indicate that an error has been made.
779
780 This currently produces a warning under the following circumstances:
781
782 @itemize @bullet
783 @item
784 An INTEGER SELECT construct has a CASE that can never be matched as its
785 lower value is greater than its upper value.
786
787 @item
788 A LOGICAL SELECT construct has three CASE statements.
789
790 @item
791 A TRANSFER specifies a source that is shorter than the destination.
792
793 @item
794 The type of a function result is declared more than once with the same type.  If
795 @option{-pedantic} or standard-conforming mode is enabled, this is an error.
796
797 @item
798 A @code{CHARACTER} variable is declared with negative length.
799 @end itemize
800
801 @item -Wtabs
802 @opindex @code{Wtabs}
803 @cindex warnings, tabs
804 @cindex tabulators
805 By default, tabs are accepted as whitespace, but tabs are not members
806 of the Fortran Character Set.  For continuation lines, a tab followed
807 by a digit between 1 and 9 is supported.  @option{-Wno-tabs} will cause
808 a warning to be issued if a tab is encountered. Note, @option{-Wno-tabs}
809 is active for @option{-pedantic}, @option{-std=f95}, @option{-std=f2003},
810 @option{-std=f2008} and @option{-Wall}.
811
812 @item -Wunderflow
813 @opindex @code{Wunderflow}
814 @cindex warnings, underflow
815 @cindex underflow
816 Produce a warning when numerical constant expressions are
817 encountered, which yield an UNDERFLOW during compilation.
818
819 @item -Wintrinsic-shadow
820 @opindex @code{Wintrinsic-shadow}
821 @cindex warnings, intrinsic
822 @cindex intrinsic
823 Warn if a user-defined procedure or module procedure has the same name as an
824 intrinsic; in this case, an explicit interface or @code{EXTERNAL} or
825 @code{INTRINSIC} declaration might be needed to get calls later resolved to
826 the desired intrinsic/procedure.
827
828 @item -Wunused-parameter
829 @opindex @code{Wunused-parameter}
830 @cindex warnings, unused parameter
831 @cindex unused parameter
832 Contrary to @command{gcc}'s meaning of @option{-Wunused-parameter},
833 @command{gfortran}'s implementation of this option does not warn
834 about unused dummy arguments, but about unused @code{PARAMETER} values.
835 @option{-Wunused-parameter} is not included in @option{-Wall} but is
836 implied by @option{-Wall -Wextra}.
837
838 @item -Walign-commons
839 @opindex @code{Walign-commons}
840 @cindex warnings, alignment of COMMON blocks
841 @cindex alignment of COMMON blocks
842 By default, @command{gfortran} warns about any occasion of variables being
843 padded for proper alignment inside a COMMON block. This warning can be turned
844 off via @option{-Wno-align-commons}. See also @option{-falign-commons}.
845
846 @item -Werror
847 @opindex @code{Werror}
848 @cindex warnings, to errors
849 Turns all warnings into errors.
850 @end table
851
852 @xref{Error and Warning Options,,Options to Request or Suppress Errors and
853 Warnings, gcc,Using the GNU Compiler Collection (GCC)}, for information on
854 more options offered by the GBE shared by @command{gfortran}, @command{gcc}
855 and other GNU compilers.
856
857 Some of these have no effect when compiling programs written in Fortran.
858
859 @node Debugging Options
860 @section Options for debugging your program or GNU Fortran
861 @cindex options, debugging
862 @cindex debugging information options
863
864 GNU Fortran has various special options that are used for debugging
865 either your program or the GNU Fortran compiler.
866
867 @table @gcctabopt
868 @item -fdump-parse-tree
869 @opindex @code{fdump-parse-tree}
870 Output the internal parse tree before starting code generation.  Only
871 really useful for debugging the GNU Fortran compiler itself.
872
873 @item -ffpe-trap=@var{list}
874 @opindex @code{ffpe-trap=}@var{list}
875 Specify a list of IEEE exceptions when a Floating Point Exception
876 (FPE) should be raised.  On most systems, this will result in a SIGFPE
877 signal being sent and the program being interrupted, producing a core
878 file useful for debugging.  @var{list} is a (possibly empty) comma-separated
879 list of the following IEEE exceptions: @samp{invalid} (invalid floating
880 point operation, such as @code{SQRT(-1.0)}), @samp{zero} (division by
881 zero), @samp{overflow} (overflow in a floating point operation),
882 @samp{underflow} (underflow in a floating point operation),
883 @samp{precision} (loss of precision during operation) and @samp{denormal}
884 (operation produced a denormal value).
885
886 Some of the routines in the Fortran runtime library, like
887 @samp{CPU_TIME}, are likely to trigger floating point exceptions when
888 @code{ffpe-trap=precision} is used. For this reason, the use of 
889 @code{ffpe-trap=precision} is not recommended.
890
891 @item -fbacktrace
892 @opindex @code{fbacktrace}
893 @cindex backtrace
894 @cindex trace
895 Specify that, when a runtime error is encountered or a deadly signal is
896 emitted (segmentation fault, illegal instruction, bus error or
897 floating-point exception), the Fortran runtime
898 library should output a backtrace of the error.  This option
899 only has influence for compilation of the Fortran main program.
900
901 @item -fdump-core
902 @cindex core, dump
903 @opindex @code{fdump-core}
904 Request that a core-dump file is written to disk when a runtime error
905 is encountered on systems that support core dumps. This option is
906 only effective for the compilation of the Fortran main program.
907 @end table
908
909 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
910 gcc,Using the GNU Compiler Collection (GCC)}, for more information on
911 debugging options.
912
913 @node Directory Options
914 @section Options for directory search
915 @cindex directory, options
916 @cindex options, directory search
917 @cindex search path
918 @cindex INCLUDE directive
919 @cindex directive, INCLUDE
920 These options affect how GNU Fortran searches
921 for files specified by the @code{INCLUDE} directive and where it searches
922 for previously compiled modules.
923
924 It also affects the search paths used by @command{cpp} when used to preprocess
925 Fortran source.
926
927 @table @gcctabopt
928 @item -I@var{dir}
929 @opindex @code{I}@var{dir}
930 @cindex directory, search paths for inclusion
931 @cindex inclusion, directory search paths for
932 @cindex search paths, for included files
933 @cindex paths, search
934 @cindex module search path
935 These affect interpretation of the @code{INCLUDE} directive
936 (as well as of the @code{#include} directive of the @command{cpp}
937 preprocessor).
938
939 Also note that the general behavior of @option{-I} and
940 @code{INCLUDE} is pretty much the same as of @option{-I} with
941 @code{#include} in the @command{cpp} preprocessor, with regard to
942 looking for @file{header.gcc} files and other such things.
943
944 This path is also used to search for @file{.mod} files when previously
945 compiled modules are required by a @code{USE} statement.
946
947 @xref{Directory Options,,Options for Directory Search,
948 gcc,Using the GNU Compiler Collection (GCC)}, for information on the
949 @option{-I} option.
950
951 @item -J@var{dir}
952 @item -M@var{dir}
953 @opindex @code{J}@var{dir}
954 @opindex @code{M}@var{dir}
955 @cindex paths, search
956 @cindex module search path
957 This option specifies where to put @file{.mod} files for compiled modules.
958 It is also added to the list of directories to searched by an @code{USE}
959 statement.
960
961 The default is the current directory.
962
963 @option{-M} is deprecated to avoid conflicts with existing GCC options.
964
965 @item -fintrinsic-modules-path @var{dir}
966 @opindex @code{fintrinsic-modules-path} @var{dir}
967 @cindex paths, search
968 @cindex module search path
969 This option specifies the location of pre-compiled intrinsic modules, if
970 they are not in the default location expected by the compiler.
971 @end table
972
973 @node Link Options
974 @section Influencing the linking step
975 @cindex options, linking
976 @cindex linking, static
977
978 These options come into play when the compiler links object files into an 
979 executable output file. They are meaningless if the compiler is not doing 
980 a link step.
981
982 @table @gcctabopt
983 @item -static-libgfortran
984 @opindex @code{static-libgfortran}
985 On systems that provide @file{libgfortran} as a shared and a static
986 library, this option forces the use of the static version. If no
987 shared version of @file{libgfortran} was built when the compiler was
988 configured, this option has no effect.
989 @end table
990
991
992 @node Runtime Options
993 @section Influencing runtime behavior
994 @cindex options, runtime
995
996 These options affect the runtime behavior of programs compiled with GNU Fortran.
997 @table @gcctabopt
998 @item -fconvert=@var{conversion}
999 @opindex @code{fconvert=}@var{conversion}
1000 Specify the representation of data for unformatted files.  Valid
1001 values for conversion are: @samp{native}, the default; @samp{swap},
1002 swap between big- and little-endian; @samp{big-endian}, use big-endian
1003 representation for unformatted files; @samp{little-endian}, use little-endian
1004 representation for unformatted files.
1005
1006 @emph{This option has an effect only when used in the main program.
1007 The @code{CONVERT} specifier and the GFORTRAN_CONVERT_UNIT environment
1008 variable override the default specified by @option{-fconvert}.}
1009
1010
1011 @item -fno-range-check
1012 @opindex @code{fno-range-check}
1013 Disable range checking of input values during integer @code{READ} operations.
1014 For example, GNU Fortran will give an error if an input value is
1015 outside of the relevant range of [@code{-HUGE()}:@code{HUGE()}]. In other words,
1016 with @code{INTEGER (kind=4) :: i} , attempting to read @math{-2147483648} will
1017 give an error unless @option{-fno-range-check} is given. 
1018
1019
1020 @item -frecord-marker=@var{length}
1021 @opindex @code{frecord-marker=}@var{length}
1022 Specify the length of record markers for unformatted files.
1023 Valid values for @var{length} are 4 and 8.  Default is 4.
1024 @emph{This is different from previous versions of @command{gfortran}},
1025 which specified a default record marker length of 8 on most
1026 systems.  If you want to read or write files compatible
1027 with earlier versions of @command{gfortran}, use @option{-frecord-marker=8}.
1028
1029 @item -fmax-subrecord-length=@var{length}
1030 @opindex @code{fmax-subrecord-length=}@var{length}
1031 Specify the maximum length for a subrecord.  The maximum permitted
1032 value for length is 2147483639, which is also the default.  Only
1033 really useful for use by the gfortran testsuite.
1034
1035 @item -fsign-zero
1036 @opindex @code{fsign-zero}
1037 When enabled, floating point numbers of value zero with the sign bit set
1038 are written as negative number in formatted output and treated as
1039 negative in the @code{SIGN} intrinsic.  @code{fno-sign-zero} does not
1040 print the negative sign of zero values and regards zero as positive
1041 number in the @code{SIGN} intrinsic for compatibility with F77.
1042 Default behavior is to show the negative sign.
1043 @end table
1044
1045 @node Code Gen Options
1046 @section Options for code generation conventions
1047 @cindex code generation, conventions
1048 @cindex options, code generation
1049 @cindex options, run-time
1050
1051 These machine-independent options control the interface conventions
1052 used in code generation.
1053
1054 Most of them have both positive and negative forms; the negative form
1055 of @option{-ffoo} would be @option{-fno-foo}.  In the table below, only
1056 one of the forms is listed---the one which is not the default.  You
1057 can figure out the other form by either removing @option{no-} or adding
1058 it.
1059
1060 @table @gcctabopt
1061 @item -fno-automatic
1062 @opindex @code{fno-automatic}
1063 @cindex @code{SAVE} statement
1064 @cindex statement, @code{SAVE}
1065 Treat each program unit (except those marked as RECURSIVE) as if the
1066 @code{SAVE} statement were specified for every local variable and array
1067 referenced in it. Does not affect common blocks. (Some Fortran compilers
1068 provide this option under the name @option{-static} or @option{-save}.)
1069 The default, which is @option{-fautomatic}, uses the stack for local
1070 variables smaller than the value given by @option{-fmax-stack-var-size}.
1071 Use the option @option{-frecursive} to use no static memory. 
1072
1073 @item -ff2c
1074 @opindex ff2c
1075 @cindex calling convention
1076 @cindex @command{f2c} calling convention
1077 @cindex @command{g77} calling convention
1078 @cindex libf2c calling convention
1079 Generate code designed to be compatible with code generated
1080 by @command{g77} and @command{f2c}.
1081
1082 The calling conventions used by @command{g77} (originally implemented
1083 in @command{f2c}) require functions that return type
1084 default @code{REAL} to actually return the C type @code{double}, and
1085 functions that return type @code{COMPLEX} to return the values via an
1086 extra argument in the calling sequence that points to where to
1087 store the return value.  Under the default GNU calling conventions, such
1088 functions simply return their results as they would in GNU
1089 C---default @code{REAL} functions return the C type @code{float}, and
1090 @code{COMPLEX} functions return the GNU C type @code{complex}.
1091 Additionally, this option implies the @option{-fsecond-underscore}
1092 option, unless @option{-fno-second-underscore} is explicitly requested.
1093
1094 This does not affect the generation of code that interfaces with
1095 the @command{libgfortran} library.
1096
1097 @emph{Caution:} It is not a good idea to mix Fortran code compiled with
1098 @option{-ff2c} with code compiled with the default @option{-fno-f2c}
1099 calling conventions as, calling @code{COMPLEX} or default @code{REAL}
1100 functions between program parts which were compiled with different
1101 calling conventions will break at execution time.
1102
1103 @emph{Caution:} This will break code which passes intrinsic functions
1104 of type default @code{REAL} or @code{COMPLEX} as actual arguments, as
1105 the library implementations use the @option{-fno-f2c} calling conventions.
1106
1107 @item -fno-underscoring
1108 @opindex @code{fno-underscoring}
1109 @cindex underscore
1110 @cindex symbol names, underscores
1111 @cindex transforming symbol names
1112 @cindex symbol names, transforming
1113 Do not transform names of entities specified in the Fortran
1114 source file by appending underscores to them.
1115
1116 With @option{-funderscoring} in effect, GNU Fortran appends one
1117 underscore to external names with no underscores.  This is done to ensure
1118 compatibility with code produced by many UNIX Fortran compilers.
1119
1120 @emph{Caution}: The default behavior of GNU Fortran is
1121 incompatible with @command{f2c} and @command{g77}, please use the
1122 @option{-ff2c} option if you want object files compiled with
1123 GNU Fortran to be compatible with object code created with these
1124 tools.
1125
1126 Use of @option{-fno-underscoring} is not recommended unless you are
1127 experimenting with issues such as integration of GNU Fortran into
1128 existing system environments (vis-@`{a}-vis existing libraries, tools,
1129 and so on).
1130
1131 For example, with @option{-funderscoring}, and assuming other defaults like
1132 @option{-fcase-lower} and that @code{j()} and @code{max_count()} are
1133 external functions while @code{my_var} and @code{lvar} are local variables,
1134 a statement like
1135 @smallexample
1136 I = J() + MAX_COUNT (MY_VAR, LVAR)
1137 @end smallexample
1138 @noindent
1139 is implemented as something akin to:
1140 @smallexample
1141 i = j_() + max_count__(&my_var__, &lvar);
1142 @end smallexample
1143
1144 With @option{-fno-underscoring}, the same statement is implemented as:
1145
1146 @smallexample
1147 i = j() + max_count(&my_var, &lvar);
1148 @end smallexample
1149
1150 Use of @option{-fno-underscoring} allows direct specification of
1151 user-defined names while debugging and when interfacing GNU Fortran
1152 code with other languages.
1153
1154 Note that just because the names match does @emph{not} mean that the
1155 interface implemented by GNU Fortran for an external name matches the
1156 interface implemented by some other language for that same name.
1157 That is, getting code produced by GNU Fortran to link to code produced
1158 by some other compiler using this or any other method can be only a
1159 small part of the overall solution---getting the code generated by
1160 both compilers to agree on issues other than naming can require
1161 significant effort, and, unlike naming disagreements, linkers normally
1162 cannot detect disagreements in these other areas.
1163
1164 Also, note that with @option{-fno-underscoring}, the lack of appended
1165 underscores introduces the very real possibility that a user-defined
1166 external name will conflict with a name in a system library, which
1167 could make finding unresolved-reference bugs quite difficult in some
1168 cases---they might occur at program run time, and show up only as
1169 buggy behavior at run time.
1170
1171 In future versions of GNU Fortran we hope to improve naming and linking
1172 issues so that debugging always involves using the names as they appear
1173 in the source, even if the names as seen by the linker are mangled to
1174 prevent accidental linking between procedures with incompatible
1175 interfaces.
1176
1177 @item -fwhole-file
1178 @opindex @code{fwhole-file}
1179 By default, GNU Fortran parses, resolves and translates each procedure
1180 in a file separately.  Using this option modifies this such that the
1181 whole file is parsed and placed in a single front-end tree.  During
1182 resolution, in addition to all the usual checks and fixups, references
1183 to external procedures that are in the same file effect resolution of
1184 that procedure, if not already done, and a check of the interfaces. The
1185 dependences are resolved by changing the order in which the file is
1186 translated into the backend tree.  Thus, a procedure that is referenced
1187 is translated before the reference and the duplication of backend tree
1188 declarations eliminated.
1189
1190 @item -fsecond-underscore
1191 @opindex @code{fsecond-underscore}
1192 @cindex underscore
1193 @cindex symbol names, underscores
1194 @cindex transforming symbol names
1195 @cindex symbol names, transforming
1196 @cindex @command{f2c} calling convention
1197 @cindex @command{g77} calling convention
1198 @cindex libf2c calling convention
1199 By default, GNU Fortran appends an underscore to external
1200 names.  If this option is used GNU Fortran appends two
1201 underscores to names with underscores and one underscore to external names
1202 with no underscores.  GNU Fortran also appends two underscores to
1203 internal names with underscores to avoid naming collisions with external
1204 names.
1205
1206 This option has no effect if @option{-fno-underscoring} is
1207 in effect.  It is implied by the @option{-ff2c} option.
1208
1209 Otherwise, with this option, an external name such as @code{MAX_COUNT}
1210 is implemented as a reference to the link-time external symbol
1211 @code{max_count__}, instead of @code{max_count_}.  This is required
1212 for compatibility with @command{g77} and @command{f2c}, and is implied
1213 by use of the @option{-ff2c} option.
1214
1215 @item -fcheck=@var{<keyword>}
1216 @opindex @code{fcheck}
1217 @cindex array, bounds checking
1218 @cindex bounds checking
1219 @cindex pointer checking
1220 @cindex memory checking
1221 @cindex range checking
1222 @cindex subscript checking
1223 @cindex checking subscripts
1224 @cindex run-time checking
1225 @cindex checking array temporaries
1226
1227 Enable the generation of run-time checks; the argument shall be
1228 a comma-delimited list of the following keywords.
1229
1230 @table @asis
1231 @item @samp{all}
1232 Enable all run-time test of @option{-fcheck}.
1233
1234 @item @samp{array-temps}
1235 Warns at run time when for passing an actual argument a temporary array
1236 had to be generated. The information generated by this warning is
1237 sometimes useful in optimization, in order to avoid such temporaries.
1238
1239 Note: The warning is only printed once per location.
1240
1241 @item @samp{bounds}
1242 Enable generation of run-time checks for array subscripts
1243 and against the declared minimum and maximum values.  It also
1244 checks array indices for assumed and deferred
1245 shape arrays against the actual allocated bounds and ensures that all string
1246 lengths are equal for character array constructors without an explicit
1247 typespec.
1248
1249 Some checks require that @option{-fcheck=bounds} is set for
1250 the compilation of the main program.
1251
1252 Note: In the future this may also include other forms of checking, e.g.,
1253 checking substring references.
1254
1255 @item @samp{do}
1256 Enable generation of run-time checks for invalid modification of loop
1257 iteration variables.
1258
1259 @item @samp{mem}
1260 Enable generation of run-time checks for memory allocation.
1261 Note: This option does not affect explicit allocations using the
1262 @code{ALLOCATE} statement, which will be always checked.
1263
1264 @item @samp{pointer}
1265 Enable generation of run-time checks for pointers and allocatables.
1266
1267 @item @samp{recursion}
1268 Enable generation of run-time checks for recursively called subroutines and
1269 functions which are not marked as recursive. See also @option{-frecursive}.
1270 Note: This check does not work for OpenMP programs and is disabled if used
1271 together with @option{-frecursive} and @option{-fopenmp}.
1272 @end table
1273
1274
1275 @item -fbounds-check
1276 @opindex @code{fbounds-check}
1277 @c Note: This option is also referred in gcc's manpage
1278 Deprecated alias for @option{-fcheck=bounds}.
1279
1280 @item -fcheck-array-temporaries
1281 @opindex @code{fcheck-array-temporaries}
1282 Deprecated alias for @option{-fcheck=array-temps}.
1283
1284 @item -fmax-array-constructor=@var{n}
1285 @opindex @code{fmax-array-constructor}
1286 This option can be used to increase the upper limit permitted in 
1287 array constructors.  The code below requires this option to expand
1288 the array at compile time.
1289
1290 @smallexample
1291 @code{program test}
1292 @code{implicit none}
1293 @code{integer j}
1294 @code{integer, parameter :: n = 100000}
1295 @code{integer, parameter :: i(n) = (/ (2*j, j = 1, n) /)}
1296 @code{print '(10(I0,1X))', i}
1297 @code{end program test}
1298 @end smallexample
1299
1300 @emph{Caution:  This option can lead to long compile times and excessively
1301 large object files.}
1302
1303 The default value for @var{n} is 65535.
1304
1305
1306 @item -fmax-stack-var-size=@var{n}
1307 @opindex @code{fmax-stack-var-size}
1308 This option specifies the size in bytes of the largest array that will be put
1309 on the stack; if the size is exceeded static memory is used (except in
1310 procedures marked as RECURSIVE). Use the option @option{-frecursive} to
1311 allow for recursive procedures which do not have a RECURSIVE attribute or
1312 for parallel programs. Use @option{-fno-automatic} to never use the stack.
1313
1314 This option currently only affects local arrays declared with constant
1315 bounds, and may not apply to all character variables.
1316 Future versions of GNU Fortran may improve this behavior.
1317
1318 The default value for @var{n} is 32768.
1319
1320 @item -fpack-derived
1321 @opindex @code{fpack-derived}
1322 @cindex structure packing
1323 This option tells GNU Fortran to pack derived type members as closely as
1324 possible.  Code compiled with this option is likely to be incompatible
1325 with code compiled without this option, and may execute slower.
1326
1327 @item -frepack-arrays
1328 @opindex @code{frepack-arrays}
1329 @cindex repacking arrays
1330 In some circumstances GNU Fortran may pass assumed shape array
1331 sections via a descriptor describing a noncontiguous area of memory.
1332 This option adds code to the function prologue to repack the data into
1333 a contiguous block at runtime.
1334
1335 This should result in faster accesses to the array.  However it can introduce
1336 significant overhead to the function call, especially  when the passed data
1337 is noncontiguous.
1338
1339 @item -fshort-enums
1340 @opindex @code{fshort-enums}
1341 This option is provided for interoperability with C code that was
1342 compiled with the @option{-fshort-enums} option.  It will make
1343 GNU Fortran choose the smallest @code{INTEGER} kind a given
1344 enumerator set will fit in, and give all its enumerators this kind.
1345
1346 @item -fexternal-blas
1347 @opindex @code{fexternal-blas}
1348 This option will make @command{gfortran} generate calls to BLAS functions
1349 for some matrix operations like @code{MATMUL}, instead of using our own
1350 algorithms, if the size of the matrices involved is larger than a given
1351 limit (see @option{-fblas-matmul-limit}).  This may be profitable if an
1352 optimized vendor BLAS library is available.  The BLAS library will have
1353 to be specified at link time.
1354
1355 @item -fblas-matmul-limit=@var{n}
1356 @opindex @code{fblas-matmul-limit}
1357 Only significant when @option{-fexternal-blas} is in effect.
1358 Matrix multiplication of matrices with size larger than (or equal to) @var{n}
1359 will be performed by calls to BLAS functions, while others will be
1360 handled by @command{gfortran} internal algorithms. If the matrices
1361 involved are not square, the size comparison is performed using the
1362 geometric mean of the dimensions of the argument and result matrices.
1363
1364 The default value for @var{n} is 30.
1365
1366 @item -frecursive
1367 @opindex @code{frecursive}
1368 Allow indirect recursion by forcing all local arrays to be allocated
1369 on the stack. This flag cannot be used together with
1370 @option{-fmax-stack-var-size=} or @option{-fno-automatic}.
1371
1372 @item -finit-local-zero
1373 @item -finit-integer=@var{n}
1374 @item -finit-real=@var{<zero|inf|-inf|nan|snan>} 
1375 @item -finit-logical=@var{<true|false>}
1376 @item -finit-character=@var{n}
1377 @opindex @code{finit-local-zero}
1378 @opindex @code{finit-integer}
1379 @opindex @code{finit-real}
1380 @opindex @code{finit-logical}
1381 @opindex @code{finit-character}
1382 The @option{-finit-local-zero} option instructs the compiler to
1383 initialize local @code{INTEGER}, @code{REAL}, and @code{COMPLEX}
1384 variables to zero, @code{LOGICAL} variables to false, and
1385 @code{CHARACTER} variables to a string of null bytes.  Finer-grained
1386 initialization options are provided by the
1387 @option{-finit-integer=@var{n}},
1388 @option{-finit-real=@var{<zero|inf|-inf|nan|snan>}} (which also initializes
1389 the real and imaginary parts of local @code{COMPLEX} variables),
1390 @option{-finit-logical=@var{<true|false>}}, and
1391 @option{-finit-character=@var{n}} (where @var{n} is an ASCII character
1392 value) options.  These options do not initialize components of derived
1393 type variables, nor do they initialize variables that appear in an
1394 @code{EQUIVALENCE} statement.  (This limitation may be removed in
1395 future releases).
1396
1397 Note that the @option{-finit-real=nan} option initializes @code{REAL}
1398 and @code{COMPLEX} variables with a quiet NaN. For a signalling NaN
1399 use @option{-finit-real=snan}; note, however, that compile-time
1400 optimizations may convert them into quiet NaN and that trapping
1401 needs to be enabled (e.g. via @option{-ffpe-trap}).
1402
1403 @item -falign-commons
1404 @opindex @code{falign-commons}
1405 @cindex alignment of COMMON blocks
1406 By default, @command{gfortran} enforces proper alignment of all variables in a
1407 COMMON block by padding them as needed. On certain platforms this is mandatory,
1408 on others it increases performance. If a COMMON block is not declared with
1409 consistent data types everywhere, this padding can cause trouble, and
1410 @option{-fno-align-commons } can be used to disable automatic alignment. The
1411 same form of this option should be used for all files that share a COMMON block.
1412 To avoid potential alignment issues in COMMON blocks, it is recommended to order
1413 objects from largests to smallest.
1414
1415 @item -fno-protect-parens
1416 @opindex @code{fno-protect-parens}
1417 @cindex re-association of parenthesed expressions
1418 By default the parentheses in expression are honored for all optimization
1419 levels such that the compiler does not do any re-association. Using
1420 @option{-fno-protect-parens} allows the compiler to reorder REAL and
1421 COMPLEX expressions to produce faster code. Note that for the re-association
1422 optimization @option{-fno-signed-zeros} and @option{-fno-trapping-math}
1423 need to be in effect.
1424 @end table
1425
1426 @xref{Code Gen Options,,Options for Code Generation Conventions,
1427 gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
1428 offered by the GBE
1429 shared by @command{gfortran}, @command{gcc}, and other GNU compilers.
1430
1431
1432 @c man end
1433
1434 @node Environment Variables
1435 @section Environment variables affecting @command{gfortran}
1436 @cindex environment variable
1437
1438 @c man begin ENVIRONMENT
1439
1440 The @command{gfortran} compiler currently does not make use of any environment
1441 variables to control its operation above and beyond those
1442 that affect the operation of @command{gcc}.
1443
1444 @xref{Environment Variables,,Environment Variables Affecting GCC,
1445 gcc,Using the GNU Compiler Collection (GCC)}, for information on environment
1446 variables.
1447
1448 @xref{Runtime}, for environment variables that affect the
1449 run-time behavior of programs compiled with GNU Fortran.
1450 @c man end