invoke.texi

理解和实践操作系统的一本好书

@section Influencing runtime behavior
@cindex options, runtime

These options affect the runtime behavior of programs compiled with GNU Fortran.
@table @gcctabopt
@item -fconvert=@var{conversion}
@opindex @code{fconvert=}@var{conversion}
Specify the representation of data for unformatted files.  Valid
values for conversion are: @samp{native}, the default; @samp{swap},
swap between big- and little-endian; @samp{big-endian}, use big-endian
representation for unformatted files; @samp{little-endian}, use little-endian
representation for unformatted files.

@emph{This option has an effect only when used in the main program.
The @code{CONVERT} specifier and the GFORTRAN_CONVERT_UNIT environment
variable override the default specified by @option{-fconvert}.}

@item -frecord-marker=@var{length}
@opindex @code{frecord-marker=}@var{length}
Specify the length of record markers for unformatted files.
Valid values for @var{length} are 4 and 8.  Default is 4.
@emph{This is different from previous versions of @command{gfortran}},
which specified a default record marker length of 8 on most
systems.  If you want to read or write files compatible
with earlier versions of @command{gfortran}, use @option{-frecord-marker=8}.

@item -fmax-subrecord-length=@var{length}
@opindex @code{fmax-subrecord-length=}@var{length}
Specify the maximum length for a subrecord.  The maximum permitted
value for length is 2147483639, which is also the default.  Only
really useful for use by the gfortran testsuite.

@item -fsign-zero
@opindex @code{fsign-zero}
When writing zero values, show the negative sign if the sign bit is set.
@code{fno-sign-zero} does not print the negative sign of zero values for
compatibility with F77.  Default behavior is to show the negative sign.
@end table

@node Code Gen Options
@section Options for code generation conventions
@cindex code generation, conventions
@cindex options, code generation
@cindex options, run-time

These machine-independent options control the interface conventions
used in code generation.

Most of them have both positive and negative forms; the negative form
of @option{-ffoo} would be @option{-fno-foo}.  In the table below, only
one of the forms is listed---the one which is not the default.  You
can figure out the other form by either removing @option{no-} or adding
it.

@table @gcctabopt
@item -fno-automatic
@opindex @code{fno-automatic}
@cindex @code{SAVE} statement
@cindex statement, @code{SAVE}
Treat each program unit (except those marked as RECURSIVE) as if the
@code{SAVE} statement were specified for every local variable and array
referenced in it. Does not affect common blocks. (Some Fortran compilers
provide this option under the name @option{-static} or @option{-save}.)
The default, which is @option{-fautomatic}, uses the stack for local
variables smaller than the value given by @option{-fmax-stack-var-size}.
Use the option @option{-frecursive} to use no static memory. 

@item -ff2c
@opindex ff2c
@cindex calling convention
@cindex @command{f2c} calling convention
@cindex @command{g77} calling convention
@cindex libf2c calling convention
Generate code designed to be compatible with code generated
by @command{g77} and @command{f2c}.

The calling conventions used by @command{g77} (originally implemented
in @command{f2c}) require functions that return type
default @code{REAL} to actually return the C type @code{double}, and
functions that return type @code{COMPLEX} to return the values via an
extra argument in the calling sequence that points to where to
store the return value.  Under the default GNU calling conventions, such
functions simply return their results as they would in GNU
C---default @code{REAL} functions return the C type @code{float}, and
@code{COMPLEX} functions return the GNU C type @code{complex}.
Additionally, this option implies the @option{-fsecond-underscore}
option, unless @option{-fno-second-underscore} is explicitly requested.

This does not affect the generation of code that interfaces with
the @command{libgfortran} library.

@emph{Caution:} It is not a good idea to mix Fortran code compiled with
@option{-ff2c} with code compiled with the default @option{-fno-f2c}
calling conventions as, calling @code{COMPLEX} or default @code{REAL}
functions between program parts which were compiled with different
calling conventions will break at execution time.

@emph{Caution:} This will break code which passes intrinsic functions
of type default @code{REAL} or @code{COMPLEX} as actual arguments, as
the library implementations use the @option{-fno-f2c} calling conventions.

@item -fno-underscoring
@opindex @code{fno-underscoring}
@cindex underscore
@cindex symbol names, underscores
@cindex transforming symbol names
@cindex symbol names, transforming
Do not transform names of entities specified in the Fortran
source file by appending underscores to them.

With @option{-funderscoring} in effect, GNU Fortran appends one
underscore to external names with no underscores.  This is done to ensure
compatibility with code produced by many UNIX Fortran compilers.

@emph{Caution}: The default behavior of GNU Fortran is
incompatible with @command{f2c} and @command{g77}, please use the
@option{-ff2c} option if you want object files compiled with
GNU Fortran to be compatible with object code created with these
tools.

Use of @option{-fno-underscoring} is not recommended unless you are
experimenting with issues such as integration of GNU Fortran into
existing system environments (vis-@`{a}-vis existing libraries, tools,
and so on).

For example, with @option{-funderscoring}, and assuming other defaults like
@option{-fcase-lower} and that @code{j()} and @code{max_count()} are
external functions while @code{my_var} and @code{lvar} are local variables,
a statement like
@smallexample
I = J() + MAX_COUNT (MY_VAR, LVAR)
@end smallexample
@noindent
is implemented as something akin to:
@smallexample
i = j_() + max_count__(&my_var__, &lvar);
@end smallexample

With @option{-fno-underscoring}, the same statement is implemented as:

@smallexample
i = j() + max_count(&my_var, &lvar);
@end smallexample

Use of @option{-fno-underscoring} allows direct specification of
user-defined names while debugging and when interfacing GNU Fortran
code with other languages.

Note that just because the names match does @emph{not} mean that the
interface implemented by GNU Fortran for an external name matches the
interface implemented by some other language for that same name.
That is, getting code produced by GNU Fortran to link to code produced
by some other compiler using this or any other method can be only a
small part of the overall solution---getting the code generated by
both compilers to agree on issues other than naming can require
significant effort, and, unlike naming disagreements, linkers normally
cannot detect disagreements in these other areas.

Also, note that with @option{-fno-underscoring}, the lack of appended
underscores introduces the very real possibility that a user-defined
external name will conflict with a name in a system library, which
could make finding unresolved-reference bugs quite difficult in some
cases---they might occur at program run time, and show up only as
buggy behavior at run time.

In future versions of GNU Fortran we hope to improve naming and linking
issues so that debugging always involves using the names as they appear
in the source, even if the names as seen by the linker are mangled to
prevent accidental linking between procedures with incompatible
interfaces.

@item -fsecond-underscore
@opindex @code{fsecond-underscore}
@cindex underscore
@cindex symbol names, underscores
@cindex transforming symbol names
@cindex symbol names, transforming
@cindex @command{f2c} calling convention
@cindex @command{g77} calling convention
@cindex libf2c calling convention
By default, GNU Fortran appends an underscore to external
names.  If this option is used GNU Fortran appends two
underscores to names with underscores and one underscore to external names
with no underscores.  GNU Fortran also appends two underscores to
internal names with underscores to avoid naming collisions with external
names.

This option has no effect if @option{-fno-underscoring} is
in effect.  It is implied by the @option{-ff2c} option.

Otherwise, with this option, an external name such as @code{MAX_COUNT}
is implemented as a reference to the link-time external symbol
@code{max_count__}, instead of @code{max_count_}.  This is required
for compatibility with @command{g77} and @command{f2c}, and is implied
by use of the @option{-ff2c} option.

@item -fbounds-check
@opindex @code{fbounds-check}
@cindex array, bounds checking
@cindex bounds checking
@cindex range checking
@cindex subscript checking
@cindex checking subscripts
Enable generation of run-time checks for array subscripts
and against the declared minimum and maximum values.  It also
checks array indices for assumed and deferred
shape arrays against the actual allocated bounds.

Some checks require that @option{-fbounds-check} is set for
the compilation of the main program.

In the future this may also include other forms of checking, e.g., checking
substring references.

@item -fmax-stack-var-size=@var{n}
@opindex @code{fmax-stack-var-size}
This option specifies the size in bytes of the largest array that will be put
on the stack; if the size is exceeded static memory is used (except in
procedures marked as RECURSIVE). Use the option @option{-frecursive} to
allow for recursive procedures which do not have a RECURSIVE attribute or
for parallel programs. Use @option{-fno-automatic} to never use the stack.

This option currently only affects local arrays declared with constant
bounds, and may not apply to all character variables.
Future versions of GNU Fortran may improve this behavior.

The default value for @var{n} is 32768.

@item -fpack-derived
@opindex @code{fpack-derived}
@cindex structure packing
This option tells GNU Fortran to pack derived type members as closely as
possible.  Code compiled with this option is likely to be incompatible
with code compiled without this option, and may execute slower.

@item -frepack-arrays
@opindex @code{frepack-arrays}
@cindex repacking arrays
In some circumstances GNU Fortran may pass assumed shape array
sections via a descriptor describing a noncontiguous area of memory.
This option adds code to the function prologue to repack the data into
a contiguous block at runtime.

This should result in faster accesses to the array.  However it can introduce
significant overhead to the function call, especially  when the passed data
is noncontiguous.

@item -fshort-enums
@opindex @code{fshort-enums}
This option is provided for interoperability with C code that was
compiled with the @option{-fshort-enums} option.  It will make
GNU Fortran choose the smallest @code{INTEGER} kind a given
enumerator set will fit in, and give all its enumerators this kind.

@item -fexternal-blas
@opindex @code{fexternal-blas}
This option will make @command{gfortran} generate calls to BLAS functions
for some matrix operations like @code{MATMUL}, instead of using our own
algorithms, if the size of the matrices involved is larger than a given
limit (see @option{-fblas-matmul-limit}).  This may be profitable if an
optimized vendor BLAS library is available.  The BLAS library will have
to be specified at link time.

@item -fblas-matmul-limit=@var{n}
@opindex @code{fblas-matmul-limit}
Only significant when @option{-fexternal-blas} is in effect.
Matrix multiplication of matrices with size larger than (or equal to) @var{n}
will be performed by calls to BLAS functions, while others will be
handled by @command{gfortran} internal algorithms. If the matrices
involved are not square, the size comparison is performed using the
geometric mean of the dimensions of the argument and result matrices.

The default value for @var{n} is 30.

@item -frecursive
@opindex @code{frecursive}
Allow indirect recursion by forcing all local arrays to be allocated
on the stack. This flag cannot be used together with
@option{-fmax-stack-var-size=} or @option{-fno-automatic}.

@item -finit-local-zero
@item -finit-integer=@var{n}
@item -finit-real=@var{<zero|inf|-inf|nan>} 
@item -finit-logical=@var{<true|false>}
@item -finit-character=@var{n}
@opindex @code{finit-local-zero}
@opindex @code{finit-integer}
@opindex @code{finit-real}
@opindex @code{finit-logical}
@opindex @code{finit-character}
The @option{-finit-local-zero} option instructs the compiler to
initialize local @code{INTEGER}, @code{REAL}, and @code{COMPLEX}
variables to zero, @code{LOGICAL} variables to false, and
@code{CHARACTER} variables to a string of null bytes.  Finer-grained
initialization options are provided by the
@option{-finit-integer=@var{n}},
@option{-finit-real=@var{<zero|inf|-inf|nan>}} (which also initializes
the real and imaginary parts of local @code{COMPLEX} variables),
@option{-finit-logical=@var{<true|false>}}, and
@option{-finit-character=@var{n}} (where @var{n} is an ASCII character
value) options.  These options do not initialize components of derived
type variables, nor do they initialize variables that appear in an
@code{EQUIVALENCE} statement.  (This limitation may be removed in
future releases).

Note that the @option{-finit-real=nan} option initializes @code{REAL}
and @code{COMPLEX} variables with a quiet NaN.
@end table

@xref{Code Gen Options,,Options for Code Generation Conventions,
gcc,Using the GNU Compiler Collection (GCC)}, for information on more options
offered by the GBE
shared by @command{gfortran}, @command{gcc}, and other GNU compilers.


@c man end

@node Environment Variables
@section Environment variables affecting @command{gfortran}
@cindex environment variable

@c man begin ENVIRONMENT

The @command{gfortran} compiler currently does not make use of any environment
variables to control its operation above and beyond those
that affect the operation of @command{gcc}.

@xref{Environment Variables,,Environment Variables Affecting GCC,
gcc,Using the GNU Compiler Collection (GCC)}, for information on environment
variables.

@xref{Runtime}, for environment variables that affect the
run-time behavior of programs compiled with GNU Fortran.
@c man end