OSDN Git Service

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