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 -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}
154 * Fortran Dialect Options:: Controlling the variant of Fortran language
156 * Warning Options:: How picky should the compiler be?
157 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
158 * Directory Options:: Where to find module files
159 * Code Gen Options:: Specifying conventions for function calls, data layout
163 @node Fortran Dialect Options
164 @section Options Controlling Fortran Dialect
165 @cindex dialect options
166 @cindex language, dialect options
167 @cindex options, dialect
169 The following options control the dialect of Fortran
170 that the compiler accepts:
173 @cindex -ffree-form option
174 @cindex options, -ffree-form
175 @cindex -fno-fixed-form option
176 @cindex options, -fno-fixed-form
177 @cindex source file format
181 @cindex Fortran 90, features
184 Specify the layout used by the the source file. The tree form layout
185 was introduced in Fortran 90. Fixed form was traditionally used in
186 older Fortran programs.
188 @cindex -fdollar-ok option
189 @cindex options, -fdollar-ok
193 @cindex character set
194 Allow @samp{$} as a valid character in a symbol name.
196 @cindex -ffixed-line-length-@var{n} option
197 @cindex options, -ffixed-line-length-@var{n}
198 @item -ffixed-line-length-@var{n}
199 @cindex source file format
200 @cindex lines, length
201 @cindex length of source lines
203 @cindex limits, lengths of source lines
204 Set column after which characters are ignored in typical fixed-form
205 lines in the source file, and through which spaces are assumed (as
206 if padded to that length) after the ends of short fixed-form lines.
209 @cindex extended-source option
210 Popular values for @var{n} include 72 (the
211 standard and the default), 80 (card image), and 132 (corresponds
212 to ``extended-source'' options in some popular compilers).
213 @var{n} may be @samp{none}, meaning that the entire line is meaningful
214 and that continued character constants never have implicit spaces appended
215 to them to fill out the line.
216 @option{-ffixed-line-length-0} means the same thing as
217 @option{-ffixed-line-length-none}.
219 @cindex -fmax-identifier-length=@var{n} option
220 @cindex option -fmax-identifier-length=@var{n}
221 @item -fmax-identifier-length=@var{n}
222 Specify the maximum allowed identifier length. Typical values are
223 31 (Fortran 95) and 63 (Fortran 200x).
225 @cindex -fimpicit-none option
226 @cindex options, -fimplicit-none
227 @item -fimplicit-none
228 Specify that no implicit typing is allowed, unless overridden by explicit
229 @samp{IMPLICIT} statements. This is the equivalent of adding
230 @samp{implicit none} to the start of every procedure.
232 @cindex -std=@var{std} option
233 @cindex option, -std=@var{std}
235 Conform to the specified standard. Allowed values for @var{std} are
236 @samp{gnu}, @samp{f95} and @samp{f90}.
247 The @option{-i8} and @option{-j8} options set the default INTEGER and REAL
248 kinds to KIND=8. The @option{-d8} option is equivalent to specifying
249 both @option{-i8} and @option{-r8}.
253 @node Warning Options
254 @section Options to Request or Suppress Warnings
255 @cindex options, warnings
256 @cindex warnings, suppressing
257 @cindex messages, warning
258 @cindex suppressing warnings
260 Warnings are diagnostic messages that report constructions which
261 are not inherently erroneous but which are risky or suggest there
262 might have been an error.
264 You can request many specific warnings with options beginning @option{-W},
265 for example @option{-Wimplicit} to request warnings on implicit
266 declarations. Each of these specific warning options also has a
267 negative form beginning @option{-Wno-} to turn off warnings;
268 for example, @option{-Wno-implicit}. This manual lists only one of the
269 two forms, whichever is not the default.
271 These options control the amount and kinds of warnings produced by GNU
275 @cindex syntax checking
276 @cindex -fsyntax-only option
277 @cindex options, -fsyntax-only
279 Check the code for syntax errors, but don't do anything beyond that.
281 @cindex -pedantic option
282 @cindex options, -pedantic
284 Issue warnings for uses of extensions to FORTRAN 95.
285 @option{-pedantic} also applies to C-language constructs where they
286 occur in GNU Fortran source files, such as use of @samp{\e} in a
287 character constant within a directive like @samp{#include}.
289 Valid FORTRAN 95 programs should compile properly with or without
291 However, without this option, certain GNU extensions and traditional
292 Fortran features are supported as well.
293 With this option, many of them are rejected.
295 Some users try to use @option{-pedantic} to check programs for conformance.
296 They soon find that it does not do quite what they want---it finds some
297 nonstandard practices, but not all.
298 However, improvements to @command{gfortran} in this area are welcome.
300 This should be used in conjunction with -std=@var{std}.
302 @cindex -pedantic-errors option
303 @cindex options, -pedantic-errors
304 @item -pedantic-errors
305 Like @option{-pedantic}, except that errors are produced rather than
311 Inhibit all warning messages.
315 @cindex options, -Wall
318 @cindex warnings, all
319 Enables commonly used warning options that which pertain to usage that
320 we recommend avoiding and that we believe is easy to avoid.
321 This currenly includes @option{-Wunused-labels}, @option{-Waliasing},
322 @option{-Wsurprising} and @option{-Wline-truncation}.
325 @cindex -Waliasing option
326 @cindex options, -Waliasing
329 Warn about possible aliasing of dummy arguments. The following example
330 witll trigger teh warhing as it would be illegal to @code{bar} to
331 modify either parameter.
338 @cindex -Wconversion option
339 @cindex options, -Wconversion
342 Warn about implicit conversions between different types.
345 @cindex -Wimplicit-interface option
346 @cindex options, -Wimplicit-interface
347 @item -Wimplicit-interface
348 Warn about when procedure are called without an explicit interface.
349 Note this only checks that an explicit interface is present. It does not
350 check that the declared interfaces are consistent across program units.
354 @cindex options, -Wsurprising
357 Produce a warning when ``suspicous'' code constructs are encountered.
358 While techically legal these usually indicate that an error has been made.
360 This currently produces a warning under the following circumstances:
364 An INTEGER SELECT construct has a CASE the can never be matched as it's
365 lower value that is greater than its upper value.
368 A LOGICAL SELECT construct has three CASE statements.
371 @cindex -Wunused-labels option
372 @cindex options, -Wunused-labels
373 @item -Wunused-labels
374 @cindex unused labels
375 @cindex labels, unused
376 Warn whenever a label is defined but never referenced.
380 @cindex options, -Werror
382 Turns all warnings into errors.
388 @cindex extra warnings
389 @cindex warnings, extra
390 Turns on ``extra warnings'' and, if optimization is specified
391 via @option{-O}, the @option{-Wuninitialized} option.
392 (This might change in future versions of @command{gfortran}
395 @xref{Warning Options,,Options to Request or Suppress Warnings,
396 gcc,Using the GNU Compiler Collection (GCC)}, for information on more
397 options offered by the GBE shared by @command{gfortran}, @command{gcc} and
400 Some of these have no effect when compiling programs written in Fortran.
402 @node Debugging Options
403 @section Options for Debugging Your Program or GNU Fortran
404 @cindex options, debugging
405 @cindex debugging information options
407 GNU Fortran has various special options that are used for debugging
408 either your program or @command{gfortran}
411 @cindex -fdump-parse-tree option
412 @cindex option, -fdump-parse-tree
413 @item -fdump-parse-tree
414 Output the internal parse tree before starting code generation. Only
415 really usedful for debugging gfortran itself.
418 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
419 gcc,Using the GNU Compiler Collection (GCC)}, for more information on
422 @node Directory Options
423 @section Options for Directory Search
424 @cindex directory, options
425 @cindex options, directory search
428 @cindex INCLUDE directive
429 @cindex directive, INCLUDE
430 There options affect how affect how @command{gfortran} searches
431 for files specified via the @code{INCLUDE} directive, and where it searches
432 for previously compiled modules.
434 It also affects the search paths used by @command{cpp} when used to preprocess
439 @cindex options, -Idir
441 @cindex directory, search paths for inclusion
442 @cindex inclusion, directory search paths for
443 @cindex search paths, for included files
444 @cindex paths, search
445 @cindex module search path
446 These affect interpretation of the @code{INCLUDE} directive
447 (as well as of the @code{#include} directive of the @command{cpp}
450 Also note that the general behavior of @option{-I} and
451 @code{INCLUDE} is pretty much the same as of @option{-I} with
452 @code{#include} in the @command{cpp} preprocessor, with regard to
453 looking for @file{header.gcc} files and other such things.
455 This path is also used to search for @samp{.mod} files when previously
456 compiled modules are required by a @code{USE} statement.
458 @xref{Directory Options,,Options for Directory Search,
459 gcc,Using the GNU Compiler Collection (GCC)}, for information on the
463 @cindex option, -Mdir
466 This option specifies where to put @samp{.mod} files for compiled modiles.
467 It is also added to the list of directories to searhed by an @code{USE}
470 The default is the current directory.
472 @option{-J} is an alias for @option{-M} to avoid conflicts with existing
476 @node Code Gen Options
477 @section Options for Code Generation Conventions
478 @cindex code generation, conventions
479 @cindex options, code generation
480 @cindex run-time, options
482 These machine-independent options control the interface conventions
483 used in code generation.
485 Most of them have both positive and negative forms; the negative form
486 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
487 one of the forms is listed---the one which is not the default. You
488 can figure out the other form by either removing @option{no-} or adding
493 @cindex -fno-underscoring option
494 @cindex options, -fno-underscoring
495 @item -fno-underscoring
497 @cindex symbol names, underscores
498 @cindex transforming symbol names
499 @cindex symbol names, transforming
500 Do not transform names of entities specified in the Fortran
501 source file by appending underscores to them.
503 With @option{-funderscoring} in effect, @command{gfortran} appends two
504 underscores to names with underscores and one underscore to external names
505 with no underscores. (@command{gfortran} also appends two underscores to
506 internal names with underscores to avoid naming collisions with external
507 names. The @option{-fno-second-underscore} option disables appending of the
508 second underscore in all cases.)
510 This is done to ensure compatibility with code produced by many
511 UNIX Fortran compilers, including @command{f2c} which perform the
512 same transformations.
514 Use of @option{-fno-underscoring} is not recommended unless you are
515 experimenting with issues such as integration of (GNU) Fortran into
516 existing system environments (vis-a-vis existing libraries, tools, and
519 For example, with @option{-funderscoring}, and assuming other defaults like
520 @option{-fcase-lower} and that @samp{j()} and @samp{max_count()} are
521 external functions while @samp{my_var} and @samp{lvar} are local variables,
525 I = J() + MAX_COUNT (MY_VAR, LVAR)
529 is implemented as something akin to:
532 i = j_() + max_count__(&my_var__, &lvar);
535 With @option{-fno-underscoring}, the same statement is implemented as:
538 i = j() + max_count(&my_var, &lvar);
541 Use of @option{-fno-underscoring} allows direct specification of
542 user-defined names while debugging and when interfacing @command{gfortran}
543 code with other languages.
545 Note that just because the names match does @emph{not} mean that the
546 interface implemented by @command{gfortran} for an external name matches the
547 interface implemented by some other language for that same name.
548 That is, getting code produced by @command{gfortran} to link to code produced
549 by some other compiler using this or any other method can be only a
550 small part of the overall solution---getting the code generated by
551 both compilers to agree on issues other than naming can require
552 significant effort, and, unlike naming disagreements, linkers normally
553 cannot detect disagreements in these other areas.
555 Also, note that with @option{-fno-underscoring}, the lack of appended
556 underscores introduces the very real possibility that a user-defined
557 external name will conflict with a name in a system library, which
558 could make finding unresolved-reference bugs quite difficult in some
559 cases---they might occur at program run time, and show up only as
560 buggy behavior at run time.
562 In future versions of @command{gfortran} we hope to improve naming and linking
563 issues so that debugging always involves using the names as they appear
564 in the source, even if the names as seen by the linker are mangled to
565 prevent accidental linking between procedures with incompatible
568 @cindex -fno-second-underscore option
569 @cindex options, -fno-second-underscore
570 @item -fno-second-underscore
572 @cindex symbol names, underscores
573 @cindex transforming symbol names
574 @cindex symbol names, transforming
575 Do not append a second underscore to names of entities specified
576 in the Fortran source file.
578 This option has no effect if @option{-fno-underscoring} is
581 Otherwise, with this option, an external name such as @samp{MAX_COUNT}
582 is implemented as a reference to the link-time external symbol
583 @samp{max_count_}, instead of @samp{max_count__}.
586 @cindex -fbounds-check option
587 @cindex -ffortran-bounds-check option
589 @cindex bounds checking
590 @cindex range checking
591 @cindex array bounds checking
592 @cindex subscript checking
593 @cindex checking subscripts
594 Enable generation of run-time checks for array subscripts
595 and against the declared minimum and maximum values. It also
596 checks array indices for assumed and deferred
597 shape arrays against the actual allocated bounds.
599 In the future this may also include other forms of checking, eg. checing
600 substring references.
603 @cindex -fmax-stack-var-size option
604 @item -fmax-stack-var-size=@var{n}
605 This option specifies the size in bytes of the largest array that will be put
608 This option currently only affects local arrays declared with constant
609 bounds, and may not apply to all character variables.
610 Future versions of @command{gfortran} may improve this behavior.
612 The default value for @var{n} is 32768.
614 @cindex -fpackderived
616 @cindex Structure packing
617 This option tells gfortran to pack derived type members as closely as
618 possible. Code compiled with this option is likley to be incompatible
619 with code compiled without this option, and may execute slower.
621 @cindex -frepack-arrays option
622 @item -frepack-arrays
623 @cindex Repacking arrays
624 In some circumstances @command{gfortran} may pass assumed shape array
625 sections via a descriptor describing a discontiguous area of memory.
626 This option adds code to the function prologue to repack the data into
627 a contiguous block at runtime.
629 This should result in faster accesses to the array. However it can introduce
630 significant overhead to the function call, especially when the passed data
634 @xref{Code Gen Options,,Options for Code Generation Conventions,
635 gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
637 shared by @command{gfortran} @command{gcc} and other GNU compilers.
642 @node Environment Variables
643 @section Environment Variables Affecting GNU Fortran
644 @cindex environment variables
646 @c man begin ENVIRONMENT
648 GNU Fortran 95 currently does not make use of any environment
649 variables to control its operation above and beyond those
650 that affect the operation of @command{gcc}.
652 @xref{Environment Variables,,Environment Variables Affecting GCC,
653 gcc,Using the GNU Compiler Collection (GCC)}, for information on environment