OSDN Git Service

* invoke.texi: Document -Wunderflow and spell check.
[pf3gnuchains/gcc-fork.git] / gcc / fortran / invoke.texi
1 @c Copyright (C) 2004
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.
5
6 @ignore
7 @c man begin COPYRIGHT
8 Copyright @copyright{} 2004
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 95 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 GFORTRAN@.
58 @c man end
59 @end ignore
60
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
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 gfortran 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 @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.
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 * Code Gen Options::    Specifying conventions for function calls, data layout
102                         and register usage.
103 * Environment Variables:: Env vars that affect GNU Fortran.
104 @end menu
105
106 @node Option Summary
107 @section Option Summary
108
109 @c man begin OPTIONS
110
111 Here is a summary of all the options specific to GNU Fortran, grouped
112 by type.  Explanations are in the following sections.
113
114 @table @emph
115 @item Fortran Language Options
116 @xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}.
117 @gccoptlist{
118 -ffree-form  -fno-fixed-form @gol
119 -fdollar-ok  -fimplicit-none  -fmax-identifier-length @gol
120 -std=@var{std}
121 -ffixed-line-length-@var{n}  -ffixed-line-length-none @gol
122 -i8  -r8  -d8}
123
124 @item Warning Options
125 @xref{Warning Options,,Options to Request or Suppress Warnings}.
126 @gccoptlist{
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
131 -Werror  -W}
132
133 @item Debugging Options
134 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
135 @gccoptlist{
136 -fdump-parse-tree}
137
138 @item Directory Options
139 @xref{Directory Options,,Options for Directory Search}.
140 @gccoptlist{
141 -I@var{dir}  -M@var{dir}}
142
143 @item Code Generation Options
144 @xref{Code Gen Options,,Options for Code Generation Conventions}.
145 @gccoptlist{
146 -fno-underscoring  -fno-second-underscore @gol
147 -fbounds-check  -fmax-stack-var-size=@var{n} @gol
148 -fpackderived  -frepack-arrays}
149 @end table
150
151 @c man end
152
153 @menu
154 * Fortran Dialect Options::  Controlling the variant of Fortran language
155                              compiled.
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
160                         and register usage.
161 @end menu
162
163 @node Fortran Dialect Options
164 @section Options Controlling Fortran Dialect
165 @cindex dialect options
166 @cindex language, dialect options
167 @cindex options, dialect
168
169 The following options control the dialect of Fortran
170 that the compiler accepts:
171
172 @table @gcctabopt
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
178 @cindex free form
179 @cindex fixed form
180 @cindex Source Form
181 @cindex Fortran 90, features
182 @item -ffree-form
183 @item -ffixed-form
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.
187
188 @cindex -fdollar-ok option
189 @cindex options, -fdollar-ok
190 @item -fdollar-ok
191 @cindex dollar sign
192 @cindex symbol names
193 @cindex character set
194 Allow @samp{$} as a valid character in a symbol name.
195
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
202 @cindex fixed form
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.
207
208 @cindex card image
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}.
218
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).
224
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.
231
232 @cindex -std=@var{std} option
233 @cindex option, -std=@var{std}
234 @item -std=@var{std}
235 Conform to the specified standard.  Allowed values for @var{std} are
236 @samp{gnu}, @samp{f95} and @samp{f90}.
237
238 @cindex option, -i8
239 @cindex -i8, option
240 @cindex option, -r8
241 @cindex -r8, option
242 @cindex option, -d8
243 @cindex -d8, option
244 @item -i8
245 @item -r8
246 @item -d8
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}.
250
251 @end table
252
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
259
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.
263
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.
270
271 These options control the amount and kinds of warnings produced by GNU
272 Fortran:
273
274 @table @gcctabopt
275 @cindex syntax checking
276 @cindex -fsyntax-only option
277 @cindex options, -fsyntax-only
278 @item -fsyntax-only
279 Check the code for syntax errors, but don't do anything beyond that.
280
281 @cindex -pedantic option
282 @cindex options, -pedantic
283 @item -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}.
288
289 Valid FORTRAN 95 programs should compile properly with or without
290 this option.
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.
294
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.
299
300 This should be used in conjunction with -std=@var{std}.
301
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
306 warnings.
307
308 @cindex -w option
309 @cindex options, -w
310 @item -w
311 Inhibit all warning messages.
312
313
314 @cindex -Wall option
315 @cindex options, -Wall
316 @item -Wall
317 @cindex all warnings
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}.
323
324
325 @cindex -Waliasing option
326 @cindex options, -Waliasing
327 @item -Waliasing
328 @cindex aliasing
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.
332 @smallexample
333   INTEGER A
334   CALL BAR(A,A)
335 @end smallexample
336
337
338 @cindex -Wconversion option
339 @cindex options, -Wconversion
340 @item -Wconversion
341 @cindex conversion
342 Warn about implicit conversions between different types.
343
344
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.
351
352
353 @cindex -Wsurprising
354 @cindex options, -Wsurprising
355 @item -Wsurprising
356 @cindex Suspicious
357 Produce a warning when ``suspicious'' code constructs are encountered.
358 While technically legal these usually indicate that an error has been made.
359
360 This currently produces a warning under the following circumstances:
361
362 @itemize @bullet
363 @item
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.
366
367 @item
368 A LOGICAL SELECT construct has three CASE statements.
369 @end itemize
370
371 @cindex -Wunderflow
372 @cindex options, -Wunderflow
373 @item -Wunderflow
374 @cindex UNDERFLOW
375 Produce a warning when numerical constant expressions are
376 encountered, which yield an UNDERFLOW during compilation.
377
378
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.
385
386
387 @cindex -Werror
388 @cindex options, -Werror
389 @item -Werror
390 Turns all warnings into errors.
391
392
393 @cindex -W option
394 @cindex options, -W
395 @item -W
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}
401 @end table
402
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
406 other GNU compilers.
407
408 Some of these have no effect when compiling programs written in Fortran.
409
410 @node Debugging Options
411 @section Options for Debugging Your Program or GNU Fortran
412 @cindex options, debugging
413 @cindex debugging information options
414
415 GNU Fortran has various special options that are used for debugging
416 either your program or @command{gfortran}
417
418 @table @gcctabopt
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.
424 @end table
425
426 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
427 gcc,Using the GNU Compiler Collection (GCC)}, for more information on
428 debugging options.
429
430 @node Directory Options
431 @section Options for Directory Search
432 @cindex directory, options
433 @cindex options, directory search
434 @cindex search path
435
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.
441
442 It also affects the search paths used by @command{cpp} when used to preprocess
443 Fortran source.
444
445 @table @gcctabopt
446 @cindex -Idir option
447 @cindex options, -Idir
448 @item -I@var{dir}
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}
456 preprocessor).
457
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.
462
463 This path is also used to search for @samp{.mod} files when previously
464 compiled modules are required by a @code{USE} statement.
465
466 @xref{Directory Options,,Options for Directory Search,
467 gcc,Using the GNU Compiler Collection (GCC)}, for information on the
468 @option{-I} option.
469
470 @cindex -Mdir option
471 @cindex option, -Mdir
472 @item -M@var{dir}
473 @item -J@var{dir}
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}
476 statement.
477
478 The default is the current directory.
479
480 @option{-J} is an alias for @option{-M} to avoid conflicts with existing
481 GCC options.
482 @end table
483
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
489
490 These machine-independent options control the interface conventions
491 used in code generation.
492
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
497 it.
498
499
500 @table @gcctabopt
501 @cindex -fno-underscoring option
502 @cindex options, -fno-underscoring
503 @item -fno-underscoring
504 @cindex underscore
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.
510
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.)
517
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.
521
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
525 so on).
526
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,
530 a statement like
531
532 @smallexample
533 I = J() + MAX_COUNT (MY_VAR, LVAR)
534 @end smallexample
535
536 @noindent
537 is implemented as something akin to:
538
539 @smallexample
540 i = j_() + max_count__(&my_var__, &lvar);
541 @end smallexample
542
543 With @option{-fno-underscoring}, the same statement is implemented as:
544
545 @smallexample
546 i = j() + max_count(&my_var, &lvar);
547 @end smallexample
548
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.
552
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.
562
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.
569
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
574 interfaces.
575
576 @cindex -fno-second-underscore option
577 @cindex options, -fno-second-underscore
578 @item -fno-second-underscore
579 @cindex 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.
585
586 This option has no effect if @option{-fno-underscoring} is
587 in effect.
588
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__}.
592
593
594 @cindex -fbounds-check option
595 @cindex -ffortran-bounds-check option
596 @item -fbounds-check
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.
606
607 In the future this may also include other forms of checking, eg. checking
608 substring references.
609
610
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
614 on the stack.
615
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.
619
620 The default value for @var{n} is 32768.
621
622 @cindex -fpackderived
623 @item -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.
628
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.
636
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
639 is discontiguous.
640 @end table
641
642 @xref{Code Gen Options,,Options for Code Generation Conventions,
643 gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
644 offered by the GBE
645 shared by @command{gfortran} @command{gcc} and other GNU compilers.
646
647
648 @c man end
649
650 @node Environment Variables
651 @section Environment Variables Affecting GNU Fortran
652 @cindex environment variables
653
654 @c man begin ENVIRONMENT
655
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}.
659
660 @xref{Environment Variables,,Environment Variables Affecting GCC,
661 gcc,Using the GNU Compiler Collection (GCC)}, for information on environment
662 variables.
663
664 @c man end