OSDN Git Service

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