OSDN Git Service

* invoke.texi: Fix typos.
[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  -Wnonstd-intrinsics  -Wsurprising  -Wunderflow @gol
130 -Wunused-labels -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 @menu
152 * Fortran Dialect Options::  Controlling the variant of Fortran language
153                              compiled.
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
158                         and register usage.
159 @end menu
160
161 @node Fortran Dialect Options
162 @section Options Controlling Fortran Dialect
163 @cindex dialect options
164 @cindex language, dialect options
165 @cindex options, dialect
166
167 The following options control the dialect of Fortran
168 that the compiler accepts:
169
170 @table @gcctabopt
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
176 @cindex free form
177 @cindex fixed form
178 @cindex Source Form
179 @cindex Fortran 90, features
180 @item -ffree-form
181 @item -ffixed-form
182 Specify the layout used by the the source file. The free form layout
183 was introduced in Fortran 90.  Fixed form was traditionally used in
184 older Fortran programs.
185
186 @cindex -fdollar-ok option
187 @cindex options, -fdollar-ok
188 @item -fdollar-ok
189 @cindex dollar sign
190 @cindex symbol names
191 @cindex character set
192 Allow @samp{$} as a valid character in a symbol name.
193
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
200 @cindex fixed form
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.
205
206 @cindex card image
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}.
216
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).
222
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.
229
230 @cindex -std=@var{std} option
231 @cindex option, -std=@var{std}
232 @item -std=@var{std}
233 Conform to the specified standard.  Allowed values for @var{std} are
234 @samp{gnu}, @samp{f95} and @samp{f90}.
235
236 @cindex option, -i8
237 @cindex -i8, option
238 @cindex option, -r8
239 @cindex -r8, option
240 @cindex option, -d8
241 @cindex -d8, option
242 @item -i8
243 @item -r8
244 @item -d8
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}.
248
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.
252
253 @end table
254
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
261
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.
265
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.
272
273 These options control the amount and kinds of warnings produced by GNU
274 Fortran:
275
276 @table @gcctabopt
277 @cindex syntax checking
278 @cindex -fsyntax-only option
279 @cindex options, -fsyntax-only
280 @item -fsyntax-only
281 Check the code for syntax errors, but don't do anything beyond that.
282
283 @cindex -pedantic option
284 @cindex options, -pedantic
285 @item -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}.
290
291 Valid FORTRAN 95 programs should compile properly with or without
292 this option.
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.
296
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.
301
302 This should be used in conjunction with -std=@var{std}.
303
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
308 warnings.
309
310 @cindex -w option
311 @cindex options, -w
312 @item -w
313 Inhibit all warning messages.
314
315
316 @cindex -Wall option
317 @cindex options, -Wall
318 @item -Wall
319 @cindex all warnings
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}, @option{-Wnonstd-intrinsic} and
325 @option{-Wline-truncation}.
326
327
328 @cindex -Waliasing option
329 @cindex options, -Waliasing
330 @item -Waliasing
331 @cindex aliasing
332 Warn about possible aliasing of dummy arguments. The following example
333 will trigger the warning as it would be illegal to @code{bar} to
334 modify either parameter.
335 @smallexample
336   INTEGER A
337   CALL BAR(A,A)
338 @end smallexample
339
340
341 @cindex -Wconversion option
342 @cindex options, -Wconversion
343 @item -Wconversion
344 @cindex conversion
345 Warn about implicit conversions between different types.
346
347
348 @cindex -Wimplicit-interface option
349 @cindex options, -Wimplicit-interface
350 @item -Wimplicit-interface
351 Warn about when procedure are called without an explicit interface.
352 Note this only checks that an explicit interface is present.  It does not
353 check that the declared interfaces are consistent across program units.
354
355
356 @cindex -Wnonstd-intrinsic option
357 @cindex options, -Wnonstd-intrinsic
358 @item -Wnonstd-intrinsic
359 Warn if the user tries to use an intrinsic that does not belong to the 
360 standard the user has chosen via the -std option.
361
362
363 @cindex -Wsurprising
364 @cindex options, -Wsurprising
365 @item -Wsurprising
366 @cindex Suspicious
367 Produce a warning when ``suspicious'' code constructs are encountered.
368 While technically legal these usually indicate that an error has been made.
369
370 This currently produces a warning under the following circumstances:
371
372 @itemize @bullet
373 @item
374 An INTEGER SELECT construct has a CASE that can never be matched as its
375 lower value is greater than its upper value.
376
377 @item
378 A LOGICAL SELECT construct has three CASE statements.
379 @end itemize
380
381 @cindex -Wunderflow
382 @cindex options, -Wunderflow
383 @item -Wunderflow
384 @cindex UNDERFLOW
385 Produce a warning when numerical constant expressions are
386 encountered, which yield an UNDERFLOW during compilation.
387
388
389 @cindex -Wunused-labels option
390 @cindex options, -Wunused-labels
391 @item -Wunused-labels
392 @cindex unused labels
393 @cindex labels, unused
394 Warn whenever a label is defined but never referenced.
395
396
397 @cindex -Werror
398 @cindex options, -Werror
399 @item -Werror
400 Turns all warnings into errors.
401
402
403 @cindex -W option
404 @cindex options, -W
405 @item -W
406 @cindex extra warnings
407 @cindex warnings, extra
408 Turns on ``extra warnings'' and, if optimization is specified
409 via @option{-O}, the @option{-Wuninitialized} option.
410 (This might change in future versions of @command{gfortran}
411 @end table
412
413 @xref{Warning Options,,Options to Request or Suppress Warnings,
414 gcc,Using the GNU Compiler Collection (GCC)}, for information on more
415 options offered by the GBE shared by @command{gfortran}, @command{gcc} and
416 other GNU compilers.
417
418 Some of these have no effect when compiling programs written in Fortran.
419
420 @node Debugging Options
421 @section Options for Debugging Your Program or GNU Fortran
422 @cindex options, debugging
423 @cindex debugging information options
424
425 GNU Fortran has various special options that are used for debugging
426 either your program or @command{gfortran}
427
428 @table @gcctabopt
429 @cindex -fdump-parse-tree option
430 @cindex option, -fdump-parse-tree
431 @item -fdump-parse-tree
432 Output the internal parse tree before starting code generation.  Only
433 really useful for debugging gfortran itself.
434 @end table
435
436 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
437 gcc,Using the GNU Compiler Collection (GCC)}, for more information on
438 debugging options.
439
440 @node Directory Options
441 @section Options for Directory Search
442 @cindex directory, options
443 @cindex options, directory search
444 @cindex search path
445
446 @cindex INCLUDE directive
447 @cindex directive, INCLUDE
448 There options affect how affect how @command{gfortran} searches
449 for files specified via the @code{INCLUDE} directive, and where it searches
450 for previously compiled modules.
451
452 It also affects the search paths used by @command{cpp} when used to preprocess
453 Fortran source.
454
455 @table @gcctabopt
456 @cindex -Idir option
457 @cindex options, -Idir
458 @item -I@var{dir}
459 @cindex directory, search paths for inclusion
460 @cindex inclusion, directory search paths for
461 @cindex search paths, for included files
462 @cindex paths, search
463 @cindex module search path
464 These affect interpretation of the @code{INCLUDE} directive
465 (as well as of the @code{#include} directive of the @command{cpp}
466 preprocessor).
467
468 Also note that the general behavior of @option{-I} and
469 @code{INCLUDE} is pretty much the same as of @option{-I} with
470 @code{#include} in the @command{cpp} preprocessor, with regard to
471 looking for @file{header.gcc} files and other such things.
472
473 This path is also used to search for @samp{.mod} files when previously
474 compiled modules are required by a @code{USE} statement.
475
476 @xref{Directory Options,,Options for Directory Search,
477 gcc,Using the GNU Compiler Collection (GCC)}, for information on the
478 @option{-I} option.
479
480 @cindex -Mdir option
481 @cindex option, -Mdir
482 @item -M@var{dir}
483 @item -J@var{dir}
484 This option specifies where to put @samp{.mod} files for compiled modules.
485 It is also added to the list of directories to searched by an @code{USE}
486 statement.
487
488 The default is the current directory.
489
490 @option{-J} is an alias for @option{-M} to avoid conflicts with existing
491 GCC options.
492 @end table
493
494 @node Code Gen Options
495 @section Options for Code Generation Conventions
496 @cindex code generation, conventions
497 @cindex options, code generation
498 @cindex run-time, options
499
500 These machine-independent options control the interface conventions
501 used in code generation.
502
503 Most of them have both positive and negative forms; the negative form
504 of @option{-ffoo} would be @option{-fno-foo}.  In the table below, only
505 one of the forms is listed---the one which is not the default.  You
506 can figure out the other form by either removing @option{no-} or adding
507 it.
508
509
510 @table @gcctabopt
511 @cindex -fno-underscoring option
512 @cindex options, -fno-underscoring
513 @item -fno-underscoring
514 @cindex underscore
515 @cindex symbol names, underscores
516 @cindex transforming symbol names
517 @cindex symbol names, transforming
518 Do not transform names of entities specified in the Fortran
519 source file by appending underscores to them.
520
521 With @option{-funderscoring} in effect, @command{gfortran} appends two
522 underscores to names with underscores and one underscore to external names
523 with no underscores.  (@command{gfortran} also appends two underscores to
524 internal names with underscores to avoid naming collisions with external
525 names.  The @option{-fno-second-underscore} option disables appending of the
526 second underscore in all cases.)
527
528 This is done to ensure compatibility with code produced by many
529 UNIX Fortran compilers, including @command{f2c} which perform the
530 same transformations.
531
532 Use of @option{-fno-underscoring} is not recommended unless you are
533 experimenting with issues such as integration of (GNU) Fortran into
534 existing system environments (vis-a-vis existing libraries, tools, and
535 so on).
536
537 For example, with @option{-funderscoring}, and assuming other defaults like
538 @option{-fcase-lower} and that @samp{j()} and @samp{max_count()} are
539 external functions while @samp{my_var} and @samp{lvar} are local variables,
540 a statement like
541
542 @smallexample
543 I = J() + MAX_COUNT (MY_VAR, LVAR)
544 @end smallexample
545
546 @noindent
547 is implemented as something akin to:
548
549 @smallexample
550 i = j_() + max_count__(&my_var__, &lvar);
551 @end smallexample
552
553 With @option{-fno-underscoring}, the same statement is implemented as:
554
555 @smallexample
556 i = j() + max_count(&my_var, &lvar);
557 @end smallexample
558
559 Use of @option{-fno-underscoring} allows direct specification of
560 user-defined names while debugging and when interfacing @command{gfortran}
561 code with other languages.
562
563 Note that just because the names match does @emph{not} mean that the
564 interface implemented by @command{gfortran} for an external name matches the
565 interface implemented by some other language for that same name.
566 That is, getting code produced by @command{gfortran} to link to code produced
567 by some other compiler using this or any other method can be only a
568 small part of the overall solution---getting the code generated by
569 both compilers to agree on issues other than naming can require
570 significant effort, and, unlike naming disagreements, linkers normally
571 cannot detect disagreements in these other areas.
572
573 Also, note that with @option{-fno-underscoring}, the lack of appended
574 underscores introduces the very real possibility that a user-defined
575 external name will conflict with a name in a system library, which
576 could make finding unresolved-reference bugs quite difficult in some
577 cases---they might occur at program run time, and show up only as
578 buggy behavior at run time.
579
580 In future versions of @command{gfortran} we hope to improve naming and linking
581 issues so that debugging always involves using the names as they appear
582 in the source, even if the names as seen by the linker are mangled to
583 prevent accidental linking between procedures with incompatible
584 interfaces.
585
586 @cindex -fno-second-underscore option
587 @cindex options, -fno-second-underscore
588 @item -fno-second-underscore
589 @cindex underscore
590 @cindex symbol names, underscores
591 @cindex transforming symbol names
592 @cindex symbol names, transforming
593 Do not append a second underscore to names of entities specified
594 in the Fortran source file.
595
596 This option has no effect if @option{-fno-underscoring} is
597 in effect.
598
599 Otherwise, with this option, an external name such as @samp{MAX_COUNT}
600 is implemented as a reference to the link-time external symbol
601 @samp{max_count_}, instead of @samp{max_count__}.
602
603
604 @cindex -fbounds-check option
605 @cindex -ffortran-bounds-check option
606 @item -fbounds-check
607 @cindex bounds checking
608 @cindex range checking
609 @cindex array bounds checking
610 @cindex subscript checking
611 @cindex checking subscripts
612 Enable generation of run-time checks for array subscripts
613 and against the declared minimum and maximum values.  It also
614 checks array indices for assumed and deferred
615 shape arrays against the actual allocated bounds.
616
617 In the future this may also include other forms of checking, eg. checking
618 substring references.
619
620
621 @cindex -fmax-stack-var-size option
622 @item -fmax-stack-var-size=@var{n}
623 This option specifies the size in bytes of the largest array that will be put
624 on the stack.
625
626 This option currently only affects local arrays declared with constant
627 bounds, and may not apply to all character variables.
628 Future versions of @command{gfortran} may improve this behavior.
629
630 The default value for @var{n} is 32768.
631
632 @cindex -fpackderived
633 @item -fpackderived
634 @cindex Structure packing
635 This option tells gfortran to pack derived type members as closely as
636 possible.  Code compiled with this option is likely to be incompatible
637 with code compiled without this option, and may execute slower.
638
639 @cindex -frepack-arrays option
640 @item -frepack-arrays
641 @cindex Repacking arrays
642 In some circumstances @command{gfortran} may pass assumed shape array
643 sections via a descriptor describing a discontiguous area of memory.
644 This option adds code to the function prologue to repack the data into
645 a contiguous block at runtime.
646
647 This should result in faster accesses to the array.  However it can introduce
648 significant overhead to the function call, especially  when the passed data
649 is discontiguous.
650 @end table
651
652 @xref{Code Gen Options,,Options for Code Generation Conventions,
653 gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
654 offered by the GBE
655 shared by @command{gfortran} @command{gcc} and other GNU compilers.
656
657
658 @c man end
659
660 @node Environment Variables
661 @section Environment Variables Affecting GNU Fortran
662 @cindex environment variables
663
664 @c man begin ENVIRONMENT
665
666 GNU Fortran 95 currently does not make use of any environment
667 variables to control its operation above and beyond those
668 that affect the operation of @command{gcc}.
669
670 @xref{Environment Variables,,Environment Variables Affecting GCC,
671 gcc,Using the GNU Compiler Collection (GCC)}, for information on environment
672 variables.
673
674 @c man end