2 @c Free Software Foundation, Inc.
3 @c This is part of the GFORTRAN manual.
4 @c For copying conditions, see the file gfortran.texi.
8 Copyright @copyright{} 2004
9 Free Software Foundation, Inc.
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU Free Documentation License, Version 1.2 or
13 any later version published by the Free Software Foundation; with the
14 Invariant Sections being ``GNU General Public License'' and ``Funding
15 Free Software'', the Front-Cover texts being (a) (see below), and with
16 the Back-Cover Texts being (b) (see below). A copy of the license is
17 included in the gfdl(7) man page.
19 (a) The FSF's Front-Cover Text is:
23 (b) The FSF's Back-Cover Text is:
25 You have freedom to copy and modify this GNU Manual, like GNU
26 software. Copies published by the Free Software Foundation raise
27 funds for GNU development.
29 @c Set file name and title for the man page.
31 @settitle GNU Fortran 95 compiler.
33 gfortran [@option{-c}|@option{-S}|@option{-E}]
34 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
35 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
36 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
37 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
38 [@option{-f}@var{option}@dots{}]
39 [@option{-m}@var{machine-option}@dots{}]
40 [@option{-o} @var{outfile}] @var{infile}@dots{}
42 Only the most useful options are listed here; see below for the
46 gpl(7), gfdl(7), fsf-funding(7),
47 cpp(1), gcov(1), gcc(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
48 and the Info entries for @file{gcc}, @file{cpp}, @file{gfortran}, @file{as},
49 @file{ld}, @file{binutils} and @file{gdb}.
52 For instructions on reporting bugs, see
53 @w{@uref{http://gcc.gnu.org/bugs.html}}.
56 See the Info entry for @command{gfortran} for contributors to GCC and
61 @node Invoking GFORTRAN
62 @chapter GNU Fortran 95 Command Options
63 @cindex GNU Fortran 95 command options
64 @cindex command options
65 @cindex options, GNU Fortran 95 command
67 @c man begin DESCRIPTION
69 The @command{gfortran} command supports all the options supported by the
70 @command{gcc} command. Only options specific to gfortran are documented here.
72 @xref{Invoking GCC,,GCC Command Options,gcc,Using the GNU Compiler
73 Collection (GCC)}, for information
74 on the non-Fortran-specific aspects of the @command{gcc} command (and,
75 therefore, the @command{gfortran} command).
77 @cindex options, negative forms
78 @cindex negative forms of options
79 All @command{gcc} and @command{gfortran} 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 @command{gfortran} to the @command{gcc} distribution
84 enables acceptance of @command{gfortran} options
85 by all of the relevant drivers.
87 In some cases, options have positive and negative forms;
88 the negative form of @option{-ffoo} would be @option{-fno-foo}.
89 This manual documents only one of these two forms, whichever
90 one is not the default.
94 * Option Summary:: Brief list of all @command{gfortran} options,
96 * Fortran Dialect Options:: Controlling the variant of Fortran language
98 * 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 * Code Gen Options:: Specifying conventions for function calls, data layout
103 * Environment Variables:: Env vars that affect GNU Fortran.
107 @section Option Summary
111 Here is a summary of all the options specific to GNU Fortran, grouped
112 by type. Explanations are in the following sections.
115 @item Fortran Language Options
116 @xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}.
118 -ffree-form -fno-fixed-form @gol
119 -fdollar-ok -fimplicit-none -fmax-identifier-length @gol
121 -ffixed-line-length-@var{n} -ffixed-line-length-none @gol
124 @item Warning Options
125 @xref{Warning Options,,Options to Request or Suppress Warnings}.
127 -fsyntax-only -pedantic -pedantic-errors @gol
128 -w -Wall -Waliasing -Wconversion @gol
129 -Wimplicit-interface -Wsurprising -Wunderflow -Wunused-labels @gol
130 -Wline-truncation @gol
133 @item Debugging Options
134 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
138 @item Directory Options
139 @xref{Directory Options,,Options for Directory Search}.
141 -I@var{dir} -M@var{dir}}
143 @item Code Generation Options
144 @xref{Code Gen Options,,Options for Code Generation Conventions}.
146 -fno-underscoring -fno-second-underscore @gol
147 -fbounds-check -fmax-stack-var-size=@var{n} @gol
148 -fpackderived -frepack-arrays}
152 * Fortran Dialect Options:: Controlling the variant of Fortran language
154 * Warning Options:: How picky should the compiler be?
155 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
156 * Directory Options:: Where to find module files
157 * Code Gen Options:: Specifying conventions for function calls, data layout
161 @node Fortran Dialect Options
162 @section Options Controlling Fortran Dialect
163 @cindex dialect options
164 @cindex language, dialect options
165 @cindex options, dialect
167 The following options control the dialect of Fortran
168 that the compiler accepts:
171 @cindex -ffree-form option
172 @cindex options, -ffree-form
173 @cindex -fno-fixed-form option
174 @cindex options, -fno-fixed-form
175 @cindex source file format
179 @cindex Fortran 90, features
182 Specify the layout used by the the source file. The tree form layout
183 was introduced in Fortran 90. Fixed form was traditionally used in
184 older Fortran programs.
186 @cindex -fdollar-ok option
187 @cindex options, -fdollar-ok
191 @cindex character set
192 Allow @samp{$} as a valid character in a symbol name.
194 @cindex -ffixed-line-length-@var{n} option
195 @cindex options, -ffixed-line-length-@var{n}
196 @item -ffixed-line-length-@var{n}
197 @cindex source file format
198 @cindex lines, length
199 @cindex length of source lines
201 @cindex limits, lengths of source lines
202 Set column after which characters are ignored in typical fixed-form
203 lines in the source file, and through which spaces are assumed (as
204 if padded to that length) after the ends of short fixed-form lines.
207 @cindex extended-source option
208 Popular values for @var{n} include 72 (the
209 standard and the default), 80 (card image), and 132 (corresponds
210 to ``extended-source'' options in some popular compilers).
211 @var{n} may be @samp{none}, meaning that the entire line is meaningful
212 and that continued character constants never have implicit spaces appended
213 to them to fill out the line.
214 @option{-ffixed-line-length-0} means the same thing as
215 @option{-ffixed-line-length-none}.
217 @cindex -fmax-identifier-length=@var{n} option
218 @cindex option -fmax-identifier-length=@var{n}
219 @item -fmax-identifier-length=@var{n}
220 Specify the maximum allowed identifier length. Typical values are
221 31 (Fortran 95) and 63 (Fortran 200x).
223 @cindex -fimplicit-none option
224 @cindex options, -fimplicit-none
225 @item -fimplicit-none
226 Specify that no implicit typing is allowed, unless overridden by explicit
227 @samp{IMPLICIT} statements. This is the equivalent of adding
228 @samp{implicit none} to the start of every procedure.
230 @cindex -std=@var{std} option
231 @cindex option, -std=@var{std}
233 Conform to the specified standard. Allowed values for @var{std} are
234 @samp{gnu}, @samp{f95} and @samp{f90}.
245 The @option{-i8} and @option{-r8} options set the default @code{INTEGER}
246 and @code{REAL} kinds to @code{KIND=8}. The @option{-d8} option is
247 equivalent to specifying both @option{-i8} and @option{-r8}.
249 When @option{-r8} is specified, the @code{DOUBLE PRECISION} kind is set
250 to @code{KIND=16} if the target supports a 16 byte floating point format.
251 If no such format exists, the @code{DOUBLE PRECISION} kind is unchanged.
255 @node Warning Options
256 @section Options to Request or Suppress Warnings
257 @cindex options, warnings
258 @cindex warnings, suppressing
259 @cindex messages, warning
260 @cindex suppressing warnings
262 Warnings are diagnostic messages that report constructions which
263 are not inherently erroneous but which are risky or suggest there
264 might have been an error.
266 You can request many specific warnings with options beginning @option{-W},
267 for example @option{-Wimplicit} to request warnings on implicit
268 declarations. Each of these specific warning options also has a
269 negative form beginning @option{-Wno-} to turn off warnings;
270 for example, @option{-Wno-implicit}. This manual lists only one of the
271 two forms, whichever is not the default.
273 These options control the amount and kinds of warnings produced by GNU
277 @cindex syntax checking
278 @cindex -fsyntax-only option
279 @cindex options, -fsyntax-only
281 Check the code for syntax errors, but don't do anything beyond that.
283 @cindex -pedantic option
284 @cindex options, -pedantic
286 Issue warnings for uses of extensions to FORTRAN 95.
287 @option{-pedantic} also applies to C-language constructs where they
288 occur in GNU Fortran source files, such as use of @samp{\e} in a
289 character constant within a directive like @samp{#include}.
291 Valid FORTRAN 95 programs should compile properly with or without
293 However, without this option, certain GNU extensions and traditional
294 Fortran features are supported as well.
295 With this option, many of them are rejected.
297 Some users try to use @option{-pedantic} to check programs for conformance.
298 They soon find that it does not do quite what they want---it finds some
299 nonstandard practices, but not all.
300 However, improvements to @command{gfortran} in this area are welcome.
302 This should be used in conjunction with -std=@var{std}.
304 @cindex -pedantic-errors option
305 @cindex options, -pedantic-errors
306 @item -pedantic-errors
307 Like @option{-pedantic}, except that errors are produced rather than
313 Inhibit all warning messages.
317 @cindex options, -Wall
320 @cindex warnings, all
321 Enables commonly used warning options that which pertain to usage that
322 we recommend avoiding and that we believe is easy to avoid.
323 This currently includes @option{-Wunused-labels}, @option{-Waliasing},
324 @option{-Wsurprising} and @option{-Wline-truncation}.
327 @cindex -Waliasing option
328 @cindex options, -Waliasing
331 Warn about possible aliasing of dummy arguments. The following example
332 will trigger the warning as it would be illegal to @code{bar} to
333 modify either parameter.
340 @cindex -Wconversion option
341 @cindex options, -Wconversion
344 Warn about implicit conversions between different types.
347 @cindex -Wimplicit-interface option
348 @cindex options, -Wimplicit-interface
349 @item -Wimplicit-interface
350 Warn about when procedure are called without an explicit interface.
351 Note this only checks that an explicit interface is present. It does not
352 check that the declared interfaces are consistent across program units.
356 @cindex options, -Wsurprising
359 Produce a warning when ``suspicious'' code constructs are encountered.
360 While technically legal these usually indicate that an error has been made.
362 This currently produces a warning under the following circumstances:
366 An INTEGER SELECT construct has a CASE the can never be matched as it's
367 lower value that is greater than its upper value.
370 A LOGICAL SELECT construct has three CASE statements.
374 @cindex options, -Wunderflow
377 Produce a warning when numerical constant expressions are
378 encountered, which yield an UNDERFLOW during compilation.
381 @cindex -Wunused-labels option
382 @cindex options, -Wunused-labels
383 @item -Wunused-labels
384 @cindex unused labels
385 @cindex labels, unused
386 Warn whenever a label is defined but never referenced.
390 @cindex options, -Werror
392 Turns all warnings into errors.
398 @cindex extra warnings
399 @cindex warnings, extra
400 Turns on ``extra warnings'' and, if optimization is specified
401 via @option{-O}, the @option{-Wuninitialized} option.
402 (This might change in future versions of @command{gfortran}
405 @xref{Warning Options,,Options to Request or Suppress Warnings,
406 gcc,Using the GNU Compiler Collection (GCC)}, for information on more
407 options offered by the GBE shared by @command{gfortran}, @command{gcc} and
410 Some of these have no effect when compiling programs written in Fortran.
412 @node Debugging Options
413 @section Options for Debugging Your Program or GNU Fortran
414 @cindex options, debugging
415 @cindex debugging information options
417 GNU Fortran has various special options that are used for debugging
418 either your program or @command{gfortran}
421 @cindex -fdump-parse-tree option
422 @cindex option, -fdump-parse-tree
423 @item -fdump-parse-tree
424 Output the internal parse tree before starting code generation. Only
425 really useful for debugging gfortran itself.
428 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
429 gcc,Using the GNU Compiler Collection (GCC)}, for more information on
432 @node Directory Options
433 @section Options for Directory Search
434 @cindex directory, options
435 @cindex options, directory search
438 @cindex INCLUDE directive
439 @cindex directive, INCLUDE
440 There options affect how affect how @command{gfortran} searches
441 for files specified via the @code{INCLUDE} directive, and where it searches
442 for previously compiled modules.
444 It also affects the search paths used by @command{cpp} when used to preprocess
449 @cindex options, -Idir
451 @cindex directory, search paths for inclusion
452 @cindex inclusion, directory search paths for
453 @cindex search paths, for included files
454 @cindex paths, search
455 @cindex module search path
456 These affect interpretation of the @code{INCLUDE} directive
457 (as well as of the @code{#include} directive of the @command{cpp}
460 Also note that the general behavior of @option{-I} and
461 @code{INCLUDE} is pretty much the same as of @option{-I} with
462 @code{#include} in the @command{cpp} preprocessor, with regard to
463 looking for @file{header.gcc} files and other such things.
465 This path is also used to search for @samp{.mod} files when previously
466 compiled modules are required by a @code{USE} statement.
468 @xref{Directory Options,,Options for Directory Search,
469 gcc,Using the GNU Compiler Collection (GCC)}, for information on the
473 @cindex option, -Mdir
476 This option specifies where to put @samp{.mod} files for compiled modules.
477 It is also added to the list of directories to searched by an @code{USE}
480 The default is the current directory.
482 @option{-J} is an alias for @option{-M} to avoid conflicts with existing
486 @node Code Gen Options
487 @section Options for Code Generation Conventions
488 @cindex code generation, conventions
489 @cindex options, code generation
490 @cindex run-time, options
492 These machine-independent options control the interface conventions
493 used in code generation.
495 Most of them have both positive and negative forms; the negative form
496 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
497 one of the forms is listed---the one which is not the default. You
498 can figure out the other form by either removing @option{no-} or adding
503 @cindex -fno-underscoring option
504 @cindex options, -fno-underscoring
505 @item -fno-underscoring
507 @cindex symbol names, underscores
508 @cindex transforming symbol names
509 @cindex symbol names, transforming
510 Do not transform names of entities specified in the Fortran
511 source file by appending underscores to them.
513 With @option{-funderscoring} in effect, @command{gfortran} appends two
514 underscores to names with underscores and one underscore to external names
515 with no underscores. (@command{gfortran} also appends two underscores to
516 internal names with underscores to avoid naming collisions with external
517 names. The @option{-fno-second-underscore} option disables appending of the
518 second underscore in all cases.)
520 This is done to ensure compatibility with code produced by many
521 UNIX Fortran compilers, including @command{f2c} which perform the
522 same transformations.
524 Use of @option{-fno-underscoring} is not recommended unless you are
525 experimenting with issues such as integration of (GNU) Fortran into
526 existing system environments (vis-a-vis existing libraries, tools, and
529 For example, with @option{-funderscoring}, and assuming other defaults like
530 @option{-fcase-lower} and that @samp{j()} and @samp{max_count()} are
531 external functions while @samp{my_var} and @samp{lvar} are local variables,
535 I = J() + MAX_COUNT (MY_VAR, LVAR)
539 is implemented as something akin to:
542 i = j_() + max_count__(&my_var__, &lvar);
545 With @option{-fno-underscoring}, the same statement is implemented as:
548 i = j() + max_count(&my_var, &lvar);
551 Use of @option{-fno-underscoring} allows direct specification of
552 user-defined names while debugging and when interfacing @command{gfortran}
553 code with other languages.
555 Note that just because the names match does @emph{not} mean that the
556 interface implemented by @command{gfortran} for an external name matches the
557 interface implemented by some other language for that same name.
558 That is, getting code produced by @command{gfortran} to link to code produced
559 by some other compiler using this or any other method can be only a
560 small part of the overall solution---getting the code generated by
561 both compilers to agree on issues other than naming can require
562 significant effort, and, unlike naming disagreements, linkers normally
563 cannot detect disagreements in these other areas.
565 Also, note that with @option{-fno-underscoring}, the lack of appended
566 underscores introduces the very real possibility that a user-defined
567 external name will conflict with a name in a system library, which
568 could make finding unresolved-reference bugs quite difficult in some
569 cases---they might occur at program run time, and show up only as
570 buggy behavior at run time.
572 In future versions of @command{gfortran} we hope to improve naming and linking
573 issues so that debugging always involves using the names as they appear
574 in the source, even if the names as seen by the linker are mangled to
575 prevent accidental linking between procedures with incompatible
578 @cindex -fno-second-underscore option
579 @cindex options, -fno-second-underscore
580 @item -fno-second-underscore
582 @cindex symbol names, underscores
583 @cindex transforming symbol names
584 @cindex symbol names, transforming
585 Do not append a second underscore to names of entities specified
586 in the Fortran source file.
588 This option has no effect if @option{-fno-underscoring} is
591 Otherwise, with this option, an external name such as @samp{MAX_COUNT}
592 is implemented as a reference to the link-time external symbol
593 @samp{max_count_}, instead of @samp{max_count__}.
596 @cindex -fbounds-check option
597 @cindex -ffortran-bounds-check option
599 @cindex bounds checking
600 @cindex range checking
601 @cindex array bounds checking
602 @cindex subscript checking
603 @cindex checking subscripts
604 Enable generation of run-time checks for array subscripts
605 and against the declared minimum and maximum values. It also
606 checks array indices for assumed and deferred
607 shape arrays against the actual allocated bounds.
609 In the future this may also include other forms of checking, eg. checking
610 substring references.
613 @cindex -fmax-stack-var-size option
614 @item -fmax-stack-var-size=@var{n}
615 This option specifies the size in bytes of the largest array that will be put
618 This option currently only affects local arrays declared with constant
619 bounds, and may not apply to all character variables.
620 Future versions of @command{gfortran} may improve this behavior.
622 The default value for @var{n} is 32768.
624 @cindex -fpackderived
626 @cindex Structure packing
627 This option tells gfortran to pack derived type members as closely as
628 possible. Code compiled with this option is likely to be incompatible
629 with code compiled without this option, and may execute slower.
631 @cindex -frepack-arrays option
632 @item -frepack-arrays
633 @cindex Repacking arrays
634 In some circumstances @command{gfortran} may pass assumed shape array
635 sections via a descriptor describing a discontiguous area of memory.
636 This option adds code to the function prologue to repack the data into
637 a contiguous block at runtime.
639 This should result in faster accesses to the array. However it can introduce
640 significant overhead to the function call, especially when the passed data
644 @xref{Code Gen Options,,Options for Code Generation Conventions,
645 gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
647 shared by @command{gfortran} @command{gcc} and other GNU compilers.
652 @node Environment Variables
653 @section Environment Variables Affecting GNU Fortran
654 @cindex environment variables
656 @c man begin ENVIRONMENT
658 GNU Fortran 95 currently does not make use of any environment
659 variables to control its operation above and beyond those
660 that affect the operation of @command{gcc}.
662 @xref{Environment Variables,,Environment Variables Affecting GCC,
663 gcc,Using the GNU Compiler Collection (GCC)}, for information on environment