OSDN Git Service

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