NetBSD/gnu/dist/gcc/gcc.hlp

407 lines
14 KiB
Plaintext

1 GCC
The GCC command invokes the GNU C compiler.
GCC file-spec
2 Parameters
file-spec
A C source file. If no input file extension is specified, GNU C
assumes .C as the default extension unless the /PLUS qualifier is
given, in which case .CC is assumed as the default extension.
If an extension of .CPP is given, then the source file is assumed to
be the output of the preprocessor, and thus the preprocessor is not
executed.
If an extension of .S is given, then the source file is assumed to be
the assembly code output of the compiler, and only the assembler is
called to generate an object file.
2 Qualifiers
GNU C command qualifiers modify the way the compiler handles the
compilation.
The following is the list of available qualifiers for GNU C:
/CASE_HACK
/CC1_OPTIONS=(option [,option...]])
/DEBUG
/DEFINE=(identifier[=definition][,...])
/G_FLOAT
/INCLUDE_DIRECTORY=(path [,path...]])
/LIST[=filename]
/MACHINE_CODE
/OBJECT[=filename]
/OPTIMIZE
/PLUS
/PROFILE[=identifier]
/SCAN=(file[,file...])
/SHOW[=option]
/UNDEFINE=(identifier[,identifier,...])
/VERBOSE
/VERSION
/WARNING
2 Linking
When linking programs compiled with GNU C, you should include the GNU
C library before the VAX C library. For example,
LINK object-file,GNU_CC:[000000]GCCLIB/LIB,SYS$LIBRARY:VAXCRTL/LIB
You can also link your program with the shared VAX C library. This
can reduce the size of the .EXE file, as well as make it smaller when
it's running. For example,
$ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,SYS$INPUT/OPT
SYS$SHARE:VAXCRTL/SHARE
(If you use the second example and type it in by hand, be sure to
type ^Z after the last carriage return). A simpler alternative would
be to place the single line:
SYS$SHARE:VAXCRTL/SHARE
into a file called VAXCRTL.OPT, and then use the link command:
$ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,VAXCRTL.OPT/OPT
If a program has been compiled with /G_FLOAT, then the linking
instructions are slightly different. If you are linking with the
non-shared library, then the command that you should use would be:
LINK object-file,GNU_CC:[000000]GCCLIB/LIB,SYS$LIBRARY:VAXCRTLG/LIB -
,SYS$LIBRARY:VAXCRTL/LIB
Note that both VAXCRTL and VAXCRTLG must be linked to. If you are
using the shared VAX C library, then you should use a command like:
$ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,SYS$INPUT:/OPTIONS
SYS$SHARE:VAXCRTLG/SHARE
In the case of the sharable library, only one library needs to be
linked to.
If you need to link to libg++, it is easiest to use the command
procedure supplied with libg++ to link your program.
2 /CASE_HACK
/[NO]CASE_HACK D=/CASE_HACK
Since the VMS Linker and Librarian are not case sensitive with
respect to symbol names, a "case-hack" is appended to a symbol name
when the symbol contains upper case characters.
There are cases where this is undesirable, (mainly when using certain
applications where modules have been precompiled, perhaps in another
language) and we want to compile without case hacking. In these
cases the /NOCASE_HACK switch disables case hacking.
2 /CC1_OPTIONS
This specifies additional switches to the compiler itself which
cannot be set by means of the compiler driver.
2 /DEBUG
/DEBUG includes additional information in the object file output so
that the program can be debugged with the VAX Symbolic Debugger.
To use the debugger it is also necessary to link the debugger to your
program, which is done by specifying the /DEBUG qualifier to the link
command. With the debugger it is possible to set breakpoints,
examine variables, and set variables to new values. See the VAX
Symbolic Debugger manual for more information, or type "HELP" from
the debugger prompt.
2 /DEFINE
/DEFINE=(identifier[=definition][,...])
/DEFINE defines a string or macro ('definition') to be substituted
for every occurrence of a given string ('identifier') in a program.
It is equivalent to the #define preprocessor directive.
All definitions and identifiers are converted to uppercase unless
they are in quotation marks.
The simple form of the /DEFINE qualifier:
/DEFINE=vms
results in a definition equivalent to the preprocessor directive:
#define VMS 1
You must enclose macro definitions in quotation marks, as in this
example:
/DEFINE="C(x)=((x) & 0xff)"
This definition is the same as the preprocessor definition:
#define C(x) ((x) & 0xff)
If more than one /DEFINE is present on the GCC command line, only the
last /DEFINE is used.
If both /DEFINE and /UNDEFINE are present on a command line, /DEFINE
is evaluated before /UNDEFINE.
2 /G_FLOAT
Instructs the compiler to use "G" floating point arithmetic instead
of "D". The difference is that double precision has a range of
approximately +/-0.56e-308 to +/-0.9 e+308, with approximately 15
decimal digits precision.
"D" floating point has the same range as single precision floating
point, with approximately 17 decimal digits precision.
If you use the /G_FLOAT qualifier, the linking instructions are
different. See "Linking" for further details.
2 /LIST
/LIST[=list_file_name]
This does not generate a listing file in the usual sense, however it
does direct the compiler to save the preprocessor output. If a file
is not specified, then this output is written into a file with the
same name as the source file and an extension of .CPP.
2 /INCLUDE_DIRECTORY
/INCLUDE_DIRECTORY=(path [,path...])
The /INCLUDE_DIRECTORY qualifier provides additional directories to
search for user-defined include files. 'path' can be either a
logical name or a directory specification.
There are two forms for specifying include files - #include
"file-spec" and #include <file-spec>. For the #include "file-spec"
form, the search order is:
1. The directory containing the source file.
2. The directories in the /INCLUDE qualifier (if any).
3. The directory (or directories) specified in the logical name
GNU_CC_INCLUDE.
4. The directory (or directories) specified in the logical name
SYS$LIBRARY.
For the #include <file-spec> form, the search order is:
1. The directories specified in the /INCLUDE qualifier (if any).
2. The directory (or directories) specified in the logical name
GNU_CC_INCLUDE.
3. The directory (or directories) specified in the logical name
SYS$LIBRARY.
2 /MACHINE_CODE
Tells GNU C to output the machine code generated by the compiler.
The machine code is output to a file with the same name as the input
file, with the extension .S. An object file is still generated,
unless /NOOBJ is also specified.
2 /OBJECT
/OBJECT[=filename]
/NOOBJECT
Controls whether or not an object file is generated by the
compiler.
2 /OPTIMIZE
/[NO]OPTIMIZE
Controls whether optimization is performed by the compiler. By
default, optimization is on. /NOOPTIMIZE turns optimization off.
2 /PLUS
Instructs the compiler driver to use the GNU-C++ compiler instead of
the GNU-C compiler. Note that the default extension of source files
is .CC when this qualifier is in effect.
2 /PROFILE
/PROFILE[=identifier]
Instructs the compiler to generate function profiling code. You must
link your program to the profiler when you use this options. The
profile statistics are automatically printed out on the terminal
during image exit. (i.e. no modifications to your source file are
required in order to use the profiler).
There are three identifiers that can be used with the /PROFILE
switch. These are ALL, FUNCTION, and BLOCK. If /PROFILE is given
without an identifier, then FUNCTION is assumed.
3 Block_Profiler
The block profiler counts how many times control of the program
passes certain points in your program. This is useful in determining
which portions of a program would benefit from recoding for
optimization.
The report for the block profiler contains the function name, file
name, PC, and the source file line number as well as the count of how
many times control has passed through the specified source line.
3 Function_Profiler
The function profiler counts how many times each function is entered,
and keeps track of how much CPU time is used within each function.
You should be careful about interpreting the results of profiles
where there are inline functions. When a function is included as
inline, then there is no call to the internal data collection routine
used by the profiler, and thus there will be no record of this
function being called. The compiler does generate a callable version
of each inline function, and if this called version is used, then the
profiler's data collection routine will be called.
2 /SCAN
/SCAN=(file[,file...])
This qualifier supplies a list of files that will be read as input,
and the output will be discarded before processing the regular input
file. Because the output generated from the files is discarded, the
only effect of this qualifier is to make the macros defined in the
files available for use in the main input.
2 /SHOW
/SHOW[=option]
This causes the preprocessor to generate information other than the
preprocessed input file. When this qualifier is used, no assembly
code and no object file is generated.
The output of the preprocessor is placed in the file specified by the
/LIST qualifier, if present. If the /LIST qualifier is not present,
then the output is placed in a file with the same name as the input
file with an extension that depends upon which option that is
selected.
3 DEFINITIONS
This option causes the preprocessor to dump a list of all of the
definitions to the output file. This is useful for debugging
purposes, since it lets you determine whether or not everything has
been defined properly.
If the default file name is used for the output, the extension will
be .DEF.
3 RULES
This option causes the preprocessor to output a rule suitable for
MAKE, describing the dependencies of the main source file. The
preprocessor outputs one MAKE rule containing the object file name
for that source file, a colon, and the names of all the concluded
files. If there are many included files then the rule is split into
several lines using the '\'-newline.
When using this option, only files included with the "#include "file"
directive are mentioned.
If the default file name is used for the output, a null extension
will be used.
3 ALL
This option is similar to RULES, except that it also mentions files
included with the "#include <file.h>" directive.
If the default file name is used for the output, a null extension
will be used.
2 /UNDEFINE
/UNDEFINE cancels a macro definition. Thus, it is the same as the
#undef preprocessor directive.
If more than one /UNDEFINE is present on the GCC command line, only
the last /UNDEFINE is used.
If both /DEFINE and /UNDEFINE are present on a command line, /DEFINE
is evaluated before /UNDEFINE.
2 /VERBOSE
Controls whether the user sees the invocation command strings for the
preprocessor, compiler, and assembler. The compiler also outputs
some statistics on time spent in its various phases.
2 /VERSION
Causes the preprocessor and the compiler to identify themselves by
their version numbers, and in the case of the compiler, the version
number of the compiler that built it.
2 /WARNING
When this qualifier is present, warnings about usage that should be
avoided are given by the compiler. For more information, see "Using
and Porting GNU CC", in the section on command line options, under
"-Wall".
Warnings are also generated by the preprocessor when this qualifier
is given.
2 Known_Incompatibilities_with_VAX-C
There are several known incompatibilities between GNU-C and VAX-C.
Some common ones will be briefly described here. A complete
description can be found in "Using and Porting GNU CC" in the chapter
entitled "Using GNU CC on VMS".
GNU-C provides case hacking as a means of giving case sensitivity
to symbol names. The case hack is a hexadecimal number appended to
the symbol name, with a bit being set for each upper case letter.
Symbols with all lower case, or symbols that have a dollar sign ("$")
are not case hacked. There are times that this is undesirable,
namely when you wish to link your program against a precompiled
library which was compiled with a non-GNU-C compiler. X-windows (or
DECWindows) is an example of this. In these instances, the
/NOCASE_HACK switch should be used.
If you require case hacking in some cases, but not in others (i.e.
Libg++ with DECWindows), then it is recommended that you develop a
header file which will define all mixed case functions that should
not have a case hack as the lower case equivalents.
GNU-C does not provide the globaldef and globalref mechanism
which is used by VAX-C to coerce the VMS linker to include certain
object modules from a library. There are assembler hacks, which are
available to the user through the macros defined in gnu_hacks.h,
which effectively give you the ability to perform these functions.
While not syntactically identical, they do provide most of the
functionality.
Note that globaldefs of enums is not supported in the way that it is
under VAX-C. This can be easily simulated, however, by globaldefing
an integer variable, and then globalvaluing all of the enumerated
states.
Furthermore, the way that globalvalue is currently implemented, the
data type of the globalvalue variable is seen to the compiler to be a
pointer to the data type that you specify. This is necessary in
order to make the compiler correctly address the globalvalue
variables.