OSDN Git Service

Merge tree-ssa-20020619-branch into mainline.
[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  -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 -fimpicit-none option
226 @cindex options, -fimplicit-none
227 @item -fimplicit-none
228 Specify that no implicit typing is allowed, unless overridden by explicit
229 @samp{IMPLICIT} statements.  This is the equivalent of adding
230 @samp{implicit none} to the start of every procedure.
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 currenly 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 witll trigger teh warhing 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 ``suspicous'' code constructs are encountered.
358 While techically 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 -Wunused-labels option
372 @cindex options, -Wunused-labels
373 @item -Wunused-labels
374 @cindex unused labels
375 @cindex labels, unused
376 Warn whenever a label is defined but never referenced.
377
378
379 @cindex -Werror
380 @cindex options, -Werror
381 @item -Werror
382 Turns all warnings into errors.
383
384
385 @cindex -W option
386 @cindex options, -W
387 @item -W
388 @cindex extra warnings
389 @cindex warnings, extra
390 Turns on ``extra warnings'' and, if optimization is specified
391 via @option{-O}, the @option{-Wuninitialized} option.
392 (This might change in future versions of @command{gfortran}
393 @end table
394
395 @xref{Warning Options,,Options to Request or Suppress Warnings,
396 gcc,Using the GNU Compiler Collection (GCC)}, for information on more
397 options offered by the GBE shared by @command{gfortran}, @command{gcc} and
398 other GNU compilers.
399
400 Some of these have no effect when compiling programs written in Fortran.
401
402 @node Debugging Options
403 @section Options for Debugging Your Program or GNU Fortran
404 @cindex options, debugging
405 @cindex debugging information options
406
407 GNU Fortran has various special options that are used for debugging
408 either your program or @command{gfortran}
409
410 @table @gcctabopt
411 @cindex -fdump-parse-tree option
412 @cindex option, -fdump-parse-tree
413 @item -fdump-parse-tree
414 Output the internal parse tree before starting code generation.  Only
415 really usedful for debugging gfortran itself.
416 @end table
417
418 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
419 gcc,Using the GNU Compiler Collection (GCC)}, for more information on
420 debugging options.
421
422 @node Directory Options
423 @section Options for Directory Search
424 @cindex directory, options
425 @cindex options, directory search
426 @cindex search path
427
428 @cindex INCLUDE directive
429 @cindex directive, INCLUDE
430 There options affect how affect how @command{gfortran} searches
431 for files specified via the @code{INCLUDE} directive, and where it searches
432 for previously compiled modules.
433
434 It also affects the search paths used by @command{cpp} when used to preprocess
435 fortran source.
436
437 @table @gcctabopt
438 @cindex -Idir option
439 @cindex options, -Idir
440 @item -I@var{dir}
441 @cindex directory, search paths for inclusion
442 @cindex inclusion, directory search paths for
443 @cindex search paths, for included files
444 @cindex paths, search
445 @cindex module search path
446 These affect interpretation of the @code{INCLUDE} directive
447 (as well as of the @code{#include} directive of the @command{cpp}
448 preprocessor).
449
450 Also note that the general behavior of @option{-I} and
451 @code{INCLUDE} is pretty much the same as of @option{-I} with
452 @code{#include} in the @command{cpp} preprocessor, with regard to
453 looking for @file{header.gcc} files and other such things.
454
455 This path is also used to search for @samp{.mod} files when previously
456 compiled modules are required by a @code{USE} statement.
457
458 @xref{Directory Options,,Options for Directory Search,
459 gcc,Using the GNU Compiler Collection (GCC)}, for information on the
460 @option{-I} option.
461
462 @cindex -Mdir option
463 @cindex option, -Mdir
464 @item -M@var{dir}
465 @item -J@var{dir}
466 This option specifies where to put @samp{.mod} files for compiled modiles.
467 It is also added to the list of directories to searhed by an @code{USE}
468 statement.
469
470 The default is the current directory.
471
472 @option{-J} is an alias for @option{-M} to avoid conflicts with existing
473 GCC options.
474 @end table
475
476 @node Code Gen Options
477 @section Options for Code Generation Conventions
478 @cindex code generation, conventions
479 @cindex options, code generation
480 @cindex run-time, options
481
482 These machine-independent options control the interface conventions
483 used in code generation.
484
485 Most of them have both positive and negative forms; the negative form
486 of @option{-ffoo} would be @option{-fno-foo}.  In the table below, only
487 one of the forms is listed---the one which is not the default.  You
488 can figure out the other form by either removing @option{no-} or adding
489 it.
490
491
492 @table @gcctabopt
493 @cindex -fno-underscoring option
494 @cindex options, -fno-underscoring
495 @item -fno-underscoring
496 @cindex underscore
497 @cindex symbol names, underscores
498 @cindex transforming symbol names
499 @cindex symbol names, transforming
500 Do not transform names of entities specified in the Fortran
501 source file by appending underscores to them.
502
503 With @option{-funderscoring} in effect, @command{gfortran} appends two
504 underscores to names with underscores and one underscore to external names
505 with no underscores.  (@command{gfortran} also appends two underscores to
506 internal names with underscores to avoid naming collisions with external
507 names.  The @option{-fno-second-underscore} option disables appending of the
508 second underscore in all cases.)
509
510 This is done to ensure compatibility with code produced by many
511 UNIX Fortran compilers, including @command{f2c} which perform the
512 same transformations.
513
514 Use of @option{-fno-underscoring} is not recommended unless you are
515 experimenting with issues such as integration of (GNU) Fortran into
516 existing system environments (vis-a-vis existing libraries, tools, and
517 so on).
518
519 For example, with @option{-funderscoring}, and assuming other defaults like
520 @option{-fcase-lower} and that @samp{j()} and @samp{max_count()} are
521 external functions while @samp{my_var} and @samp{lvar} are local variables,
522 a statement like
523
524 @smallexample
525 I = J() + MAX_COUNT (MY_VAR, LVAR)
526 @end smallexample
527
528 @noindent
529 is implemented as something akin to:
530
531 @smallexample
532 i = j_() + max_count__(&my_var__, &lvar);
533 @end smallexample
534
535 With @option{-fno-underscoring}, the same statement is implemented as:
536
537 @smallexample
538 i = j() + max_count(&my_var, &lvar);
539 @end smallexample
540
541 Use of @option{-fno-underscoring} allows direct specification of
542 user-defined names while debugging and when interfacing @command{gfortran}
543 code with other languages.
544
545 Note that just because the names match does @emph{not} mean that the
546 interface implemented by @command{gfortran} for an external name matches the
547 interface implemented by some other language for that same name.
548 That is, getting code produced by @command{gfortran} to link to code produced
549 by some other compiler using this or any other method can be only a
550 small part of the overall solution---getting the code generated by
551 both compilers to agree on issues other than naming can require
552 significant effort, and, unlike naming disagreements, linkers normally
553 cannot detect disagreements in these other areas.
554
555 Also, note that with @option{-fno-underscoring}, the lack of appended
556 underscores introduces the very real possibility that a user-defined
557 external name will conflict with a name in a system library, which
558 could make finding unresolved-reference bugs quite difficult in some
559 cases---they might occur at program run time, and show up only as
560 buggy behavior at run time.
561
562 In future versions of @command{gfortran} we hope to improve naming and linking
563 issues so that debugging always involves using the names as they appear
564 in the source, even if the names as seen by the linker are mangled to
565 prevent accidental linking between procedures with incompatible
566 interfaces.
567
568 @cindex -fno-second-underscore option
569 @cindex options, -fno-second-underscore
570 @item -fno-second-underscore
571 @cindex underscore
572 @cindex symbol names, underscores
573 @cindex transforming symbol names
574 @cindex symbol names, transforming
575 Do not append a second underscore to names of entities specified
576 in the Fortran source file.
577
578 This option has no effect if @option{-fno-underscoring} is
579 in effect.
580
581 Otherwise, with this option, an external name such as @samp{MAX_COUNT}
582 is implemented as a reference to the link-time external symbol
583 @samp{max_count_}, instead of @samp{max_count__}.
584
585
586 @cindex -fbounds-check option
587 @cindex -ffortran-bounds-check option
588 @item -fbounds-check
589 @cindex bounds checking
590 @cindex range checking
591 @cindex array bounds checking
592 @cindex subscript checking
593 @cindex checking subscripts
594 Enable generation of run-time checks for array subscripts
595 and against the declared minimum and maximum values.  It also
596 checks array indices for assumed and deferred
597 shape arrays against the actual allocated bounds.
598
599 In the future this may also include other forms of checking, eg. checing
600 substring references.
601
602
603 @cindex -fmax-stack-var-size option
604 @item -fmax-stack-var-size=@var{n}
605 This option specifies the size in bytes of the largest array that will be put
606 on the stack.
607
608 This option currently only affects local arrays declared with constant
609 bounds, and may not apply to all character variables.
610 Future versions of @command{gfortran} may improve this behavior.
611
612 The default value for @var{n} is 32768.
613
614 @cindex -fpackderived
615 @item -fpackderived
616 @cindex Structure packing
617 This option tells gfortran to pack derived type members as closely as
618 possible.  Code compiled with this option is likley to be incompatible
619 with code compiled without this option, and may execute slower.
620
621 @cindex -frepack-arrays option
622 @item -frepack-arrays
623 @cindex Repacking arrays
624 In some circumstances @command{gfortran} may pass assumed shape array
625 sections via a descriptor describing a discontiguous area of memory.
626 This option adds code to the function prologue to repack the data into
627 a contiguous block at runtime.
628
629 This should result in faster accesses to the array.  However it can introduce
630 significant overhead to the function call, especially  when the passed data
631 is discontiguous.
632 @end table
633
634 @xref{Code Gen Options,,Options for Code Generation Conventions,
635 gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
636 offered by the GBE
637 shared by @command{gfortran} @command{gcc} and other GNU compilers.
638
639
640 @c man end
641
642 @node Environment Variables
643 @section Environment Variables Affecting GNU Fortran
644 @cindex environment variables
645
646 @c man begin ENVIRONMENT
647
648 GNU Fortran 95 currently does not make use of any environment
649 variables to control its operation above and beyond those
650 that affect the operation of @command{gcc}.
651
652 @xref{Environment Variables,,Environment Variables Affecting GCC,
653 gcc,Using the GNU Compiler Collection (GCC)}, for information on environment
654 variables.
655
656 @c man end