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}
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 -fimplicit-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 currently 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 will trigger the warning 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 ``suspicious'' code constructs are encountered.
358 While technically 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.
372 @cindex options, -Wunderflow
375 Produce a warning when numerical constant expressions are
376 encountered, which yield an UNDERFLOW during compilation.
379 @cindex -Wunused-labels option
380 @cindex options, -Wunused-labels
381 @item -Wunused-labels
382 @cindex unused labels
383 @cindex labels, unused
384 Warn whenever a label is defined but never referenced.
388 @cindex options, -Werror
390 Turns all warnings into errors.
396 @cindex extra warnings
397 @cindex warnings, extra
398 Turns on ``extra warnings'' and, if optimization is specified
399 via @option{-O}, the @option{-Wuninitialized} option.
400 (This might change in future versions of @command{gfortran}
403 @xref{Warning Options,,Options to Request or Suppress Warnings,
404 gcc,Using the GNU Compiler Collection (GCC)}, for information on more
405 options offered by the GBE shared by @command{gfortran}, @command{gcc} and
408 Some of these have no effect when compiling programs written in Fortran.
410 @node Debugging Options
411 @section Options for Debugging Your Program or GNU Fortran
412 @cindex options, debugging
413 @cindex debugging information options
415 GNU Fortran has various special options that are used for debugging
416 either your program or @command{gfortran}
419 @cindex -fdump-parse-tree option
420 @cindex option, -fdump-parse-tree
421 @item -fdump-parse-tree
422 Output the internal parse tree before starting code generation. Only
423 really useful for debugging gfortran itself.
426 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
427 gcc,Using the GNU Compiler Collection (GCC)}, for more information on
430 @node Directory Options
431 @section Options for Directory Search
432 @cindex directory, options
433 @cindex options, directory search
436 @cindex INCLUDE directive
437 @cindex directive, INCLUDE
438 There options affect how affect how @command{gfortran} searches
439 for files specified via the @code{INCLUDE} directive, and where it searches
440 for previously compiled modules.
442 It also affects the search paths used by @command{cpp} when used to preprocess
447 @cindex options, -Idir
449 @cindex directory, search paths for inclusion
450 @cindex inclusion, directory search paths for
451 @cindex search paths, for included files
452 @cindex paths, search
453 @cindex module search path
454 These affect interpretation of the @code{INCLUDE} directive
455 (as well as of the @code{#include} directive of the @command{cpp}
458 Also note that the general behavior of @option{-I} and
459 @code{INCLUDE} is pretty much the same as of @option{-I} with
460 @code{#include} in the @command{cpp} preprocessor, with regard to
461 looking for @file{header.gcc} files and other such things.
463 This path is also used to search for @samp{.mod} files when previously
464 compiled modules are required by a @code{USE} statement.
466 @xref{Directory Options,,Options for Directory Search,
467 gcc,Using the GNU Compiler Collection (GCC)}, for information on the
471 @cindex option, -Mdir
474 This option specifies where to put @samp{.mod} files for compiled modules.
475 It is also added to the list of directories to searched by an @code{USE}
478 The default is the current directory.
480 @option{-J} is an alias for @option{-M} to avoid conflicts with existing
484 @node Code Gen Options
485 @section Options for Code Generation Conventions
486 @cindex code generation, conventions
487 @cindex options, code generation
488 @cindex run-time, options
490 These machine-independent options control the interface conventions
491 used in code generation.
493 Most of them have both positive and negative forms; the negative form
494 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
495 one of the forms is listed---the one which is not the default. You
496 can figure out the other form by either removing @option{no-} or adding
501 @cindex -fno-underscoring option
502 @cindex options, -fno-underscoring
503 @item -fno-underscoring
505 @cindex symbol names, underscores
506 @cindex transforming symbol names
507 @cindex symbol names, transforming
508 Do not transform names of entities specified in the Fortran
509 source file by appending underscores to them.
511 With @option{-funderscoring} in effect, @command{gfortran} appends two
512 underscores to names with underscores and one underscore to external names
513 with no underscores. (@command{gfortran} also appends two underscores to
514 internal names with underscores to avoid naming collisions with external
515 names. The @option{-fno-second-underscore} option disables appending of the
516 second underscore in all cases.)
518 This is done to ensure compatibility with code produced by many
519 UNIX Fortran compilers, including @command{f2c} which perform the
520 same transformations.
522 Use of @option{-fno-underscoring} is not recommended unless you are
523 experimenting with issues such as integration of (GNU) Fortran into
524 existing system environments (vis-a-vis existing libraries, tools, and
527 For example, with @option{-funderscoring}, and assuming other defaults like
528 @option{-fcase-lower} and that @samp{j()} and @samp{max_count()} are
529 external functions while @samp{my_var} and @samp{lvar} are local variables,
533 I = J() + MAX_COUNT (MY_VAR, LVAR)
537 is implemented as something akin to:
540 i = j_() + max_count__(&my_var__, &lvar);
543 With @option{-fno-underscoring}, the same statement is implemented as:
546 i = j() + max_count(&my_var, &lvar);
549 Use of @option{-fno-underscoring} allows direct specification of
550 user-defined names while debugging and when interfacing @command{gfortran}
551 code with other languages.
553 Note that just because the names match does @emph{not} mean that the
554 interface implemented by @command{gfortran} for an external name matches the
555 interface implemented by some other language for that same name.
556 That is, getting code produced by @command{gfortran} to link to code produced
557 by some other compiler using this or any other method can be only a
558 small part of the overall solution---getting the code generated by
559 both compilers to agree on issues other than naming can require
560 significant effort, and, unlike naming disagreements, linkers normally
561 cannot detect disagreements in these other areas.
563 Also, note that with @option{-fno-underscoring}, the lack of appended
564 underscores introduces the very real possibility that a user-defined
565 external name will conflict with a name in a system library, which
566 could make finding unresolved-reference bugs quite difficult in some
567 cases---they might occur at program run time, and show up only as
568 buggy behavior at run time.
570 In future versions of @command{gfortran} we hope to improve naming and linking
571 issues so that debugging always involves using the names as they appear
572 in the source, even if the names as seen by the linker are mangled to
573 prevent accidental linking between procedures with incompatible
576 @cindex -fno-second-underscore option
577 @cindex options, -fno-second-underscore
578 @item -fno-second-underscore
580 @cindex symbol names, underscores
581 @cindex transforming symbol names
582 @cindex symbol names, transforming
583 Do not append a second underscore to names of entities specified
584 in the Fortran source file.
586 This option has no effect if @option{-fno-underscoring} is
589 Otherwise, with this option, an external name such as @samp{MAX_COUNT}
590 is implemented as a reference to the link-time external symbol
591 @samp{max_count_}, instead of @samp{max_count__}.
594 @cindex -fbounds-check option
595 @cindex -ffortran-bounds-check option
597 @cindex bounds checking
598 @cindex range checking
599 @cindex array bounds checking
600 @cindex subscript checking
601 @cindex checking subscripts
602 Enable generation of run-time checks for array subscripts
603 and against the declared minimum and maximum values. It also
604 checks array indices for assumed and deferred
605 shape arrays against the actual allocated bounds.
607 In the future this may also include other forms of checking, eg. checking
608 substring references.
611 @cindex -fmax-stack-var-size option
612 @item -fmax-stack-var-size=@var{n}
613 This option specifies the size in bytes of the largest array that will be put
616 This option currently only affects local arrays declared with constant
617 bounds, and may not apply to all character variables.
618 Future versions of @command{gfortran} may improve this behavior.
620 The default value for @var{n} is 32768.
622 @cindex -fpackderived
624 @cindex Structure packing
625 This option tells gfortran to pack derived type members as closely as
626 possible. Code compiled with this option is likely to be incompatible
627 with code compiled without this option, and may execute slower.
629 @cindex -frepack-arrays option
630 @item -frepack-arrays
631 @cindex Repacking arrays
632 In some circumstances @command{gfortran} may pass assumed shape array
633 sections via a descriptor describing a discontiguous area of memory.
634 This option adds code to the function prologue to repack the data into
635 a contiguous block at runtime.
637 This should result in faster accesses to the array. However it can introduce
638 significant overhead to the function call, especially when the passed data
642 @xref{Code Gen Options,,Options for Code Generation Conventions,
643 gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
645 shared by @command{gfortran} @command{gcc} and other GNU compilers.
650 @node Environment Variables
651 @section Environment Variables Affecting GNU Fortran
652 @cindex environment variables
654 @c man begin ENVIRONMENT
656 GNU Fortran 95 currently does not make use of any environment
657 variables to control its operation above and beyond those
658 that affect the operation of @command{gcc}.
660 @xref{Environment Variables,,Environment Variables Affecting GCC,
661 gcc,Using the GNU Compiler Collection (GCC)}, for information on environment