OSDN Git Service

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