InfoMagic Source Code 1993 July/THE_SOURCE_CODE_CD_ROM.iso/gnu/gccdist/gcc-src/vms/gcc.rnh

Text File | 1992-06-11 | 18.6 KB | 598 lines

.!
.!    RUNOFF source file for GCC.HLP
.!
.!    This is a RUNOFF input file which will produce a VMS help file
.!    for the VMS HELP library.
.!
.!    Date of last revision: April 8, 1992
.!
.!
.!    Eric Youngdale
.!
.literal
.end literal
.no paging
.no flags all
.right margin 70
.left margin 1

.indent -1
1 GCC
.skip
 The GCC command invokes the GNU C compiler.
.skip
.literal
      GCC file-spec
.end literal
.skip
.indent -1
2 Parameters
.skip
 file-spec
.skip
     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.
.skip
     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.
.skip
     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.

.skip
.indent -1
2 Qualifiers
.skip

 GNU C command qualifiers modify the way the compiler handles the
 compilation.
.skip
 The following is the list of available qualifiers for GNU C:
.literal

      /[NO]CASE_HACK            (default is /Case_Hack)
      /CC1_OPTIONS=("option"[,"option"...]])
      /[NO]DEBUG                (default is /noDebug)
      /DEFINE=("identifier[=definition]"[,...])
      /[NO]G_FLOAT
      /INCLUDE_DIRECTORY=(path[,path...]])
      /[NO]LIST[=filename]
      /[NO]MACHINE_CODE[=filename]
      /[NO]OBJECT[=filename]
      /[NO]OPTIMIZE[=n]         (default is /Optimize=1)
      /NAMES[=option]
      /[NO]PLUS_PLUS            (default is /noPlus_Plus)
      /PREPROCESS_ONLY[=filename]
      /PROFILE[=identifier]
      /SCAN=(file[,file...])
      /SHOW[=option]
      /[NO]STANDARD[=option]
      /TARGET=machine
      /UNDEFINE=("identifier"[,"identifier",...])
      /[NO]VERBOSE[=option]
      /VERSION
      /WARNINGS
.end literal
.skip
.indent -1
2 Linking
.skip

 When linking programs compiled with GNU C, you should include the GNU
 C library before the VAX C library.  For example,
.skip
.literal
  LINK object-file,GNU_CC:[000000]GCCLIB/LIB,SYS$LIBRARY:VAXCRTL/LIB
.end literal
.skip
 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,
.skip
.literal
  $ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,SYS$INPUT/OPT
  SYS$SHARE:VAXCRTL/SHARE
.end literal
.skip
 (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:
.skip
.literal
  SYS$SHARE:VAXCRTL/SHARE
.end literal
.skip
 into a file called VAXCRTL.OPT, and then use the link command:
.skip
.literal
  $ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,VAXCRTL.OPT/OPT
.end literal
.skip
 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:
.skip
.literal
  LINK object-file,GNU_CC:[000000]GCCLIB/LIB,SYS$LIBRARY:VAXCRTLG/LIB -
                ,SYS$LIBRARY:VAXCRTL/LIB
.end literal
.skip
 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:
.skip
.literal
  $ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,SYS$INPUT:/OPTIONS
  SYS$SHARE:VAXCRTLG/SHARE
.end literal
.skip
 In the case of the sharable library, only one library needs to be linked
 to.
.skip
 If you need to link to libg++, it is easiest to use the command procedure
 supplied with libg++ to link your program.
.skip
.indent -1
2 /CASE_HACK
.skip
.literal
  /[NO]CASE_HACK      D=/CASE_HACK
.end literal
.skip
 Although the VMS Linker and Librarian are case sensitive with respect
 to symbol names, traditionally compilers have generated external
 symbols which were uppercase only.  By default GCC generates uppercase
 symbols, but a "case-hack" is appended to a symbol name when the
 symbol contains any upper case characters (unless it also contains
 one or more dollar sign characters).  This allows symbols whose spelling
 differs only in case to be used together in the same program.  The
 dollar sign exception makes it easier to deal with VMS run-time libraries.
.skip
 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.
.skip
 The /NAMES qualifier supercedes /CASE_HACK.
.skip
.indent -1
2 /CC1_OPTIONS
.skip

 This specifies additional switches to the compiler itself which cannot
 be set by means of the compiler driver.
.skip
.indent -1
2 /DEBUG
.skip

 /DEBUG includes additional information in the object file output so
 that the program can be debugged with the VAX Symbolic Debugger.
.skip
 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.
.skip
.indent -1
2 /DEFINE
.skip
.literal
/DEFINE=(identifier[=definition][,...])
.end literal
.skip
 /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.
.skip
 All definitions and identifiers are converted to uppercase unless they
 are in quotation marks.
.skip
 The simple form of the /DEFINE qualifier:
.skip
.literal
   /DEFINE=vms
.end literal
.skip
 results in a definition equivalent to the preprocessor directive:
.skip
.literal
 #define VMS 1
.end literal
.skip
 You must enclose macro definitions in quotation marks, as in this
 example:
.skip
.literal
 /DEFINE="C(x)=((x) & 0xff)"
.end literal
.skip
 This definition is the same as the preprocessor definition:
.skip
.literal
 #define C(x) ((x) & 0xff)
.end literal
.skip
 If more than one /DEFINE is present on the GCC command line, only
 the last /DEFINE is used.
.skip
 If both /DEFINE and /UNDEFINE are present on a command line, /DEFINE
 is evaluated before /UNDEFINE.
.skip
.indent -1
2 /G_FLOAT
.skip

 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.
.skip
 "D" floating point has the same range as single precision floating
 point, with approximately 17 decimal digits precision.
.skip
 If you use the /G_FLOAT qualifier, the linking instructions are
 different. See "Linking" for further details.
.skip
.indent -1
2 /LIST
.skip
   /LIST[=list_file_name]
.skip
 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.
.skip
.indent -1
2 /INCLUDE_DIRECTORY
.skip
.literal
 /INCLUDE_DIRECTORY=(path [,path...])
.end literal
.skip

 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.
.skip
 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:
.skip
.literal
 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.

.end literal
.indent -1
2 /MACHINE_CODE
.skip
    /[NO]MACHINE_CODE[=filename]
.skip

 Tells GNU C to output the machine code generated by the compiler. The
 machine code is output to the filename specified, or 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.
.skip
 The default is /NOMACHINE_CODE, which causes the intermediate assembler
 file to be written to SYS$SCRATCH:file.S and then deleted upon completion
 of the compilation.
.skip
.indent -1
2 /OBJECT
.skip
.literal
  /OBJECT[=filename]
  /NOOBJECT
.end literal
.skip

 Controls whether or not an object file is generated by the compiler.
.skip
 The default is /OBJECT unless /PREPROCESS_ONLY is specified.
.skip
.indent -1
2 /OPTIMIZE
.skip
    /[NO]OPTIMIZE[=n]
.skip

 Controls whether optimization is performed by the compiler.  By default,
 optimization is on.  /NOOPTIMIZE turns optimization off.

 You can also specify the level of optimization with /OPTIMIZE=n, where
 0 <= n <= 2.  The case n=0 is equivalent to /NOOPTIMIZE, and the default is
 /OPTIMIZE=1.

.skip
.indent -1
2 /NAME
.skip
    /NAME[=option]
.skip

    Controls the mapping of symbol names.  Possible options are
HEX_SUFFIX (default), LOWER, UPPER, and MIXED.  The /NOCASE_HACK switch
is equivalent to the /NAME=UPPER switch.
.skip
.indent -1
2 /PLUS_PLUS
.literal
    /[NO]PLUS_PLUS
.end literal
.skip

   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.
.skip
   The default is /NOPLUS_PLUS, indicating a normal C compilation.
.skip
.indent -1
2 /PREPROCESS_ONLY
.literal
    /[NO]PREPROCESS_ONLY[=filename]
.end literal
.skip
   Instructs the compiler to execute only the preprocessing phase of
 compilation.  If filename is not specified then the name used will be
 the base portion of the input file with .CPP as the filetype.
.skip
   This is similar to /LIST, except that it also implies /NOOBJECT
 and /NOMACHINE_CODE.
.skip
.indent -1
2 /PROFILE
.skip
  /PROFILE[=identifier]
.skip

   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).
.skip
   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.
.skip
.indent -1
3 Block_Profiler
.skip

   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.
.skip
   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.
.skip
.indent -1
3 Function_Profiler
.skip

   The function profiler counts how many times each function is entered, and
 keeps track of how much CPU time is used within each function.
.skip
   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.
.skip
.indent -1
2 /SCAN
.skip
  /SCAN=(file[,file...])
.skip

  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.
.skip
.indent -1
2 /SHOW
.skip
  /SHOW[=option]
.skip

  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.
.skip
  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.
.skip
.indent -1
3 DEFINITIONS
.skip

  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.
.skip
 If the default file name is used for the output, the extension will be .DEF.
.skip
.indent -1
3 RULES
.skip

  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.
.skip
   When using this option, only files included with the "#include "file"
 directive are mentioned.
.skip
 If the default file name is used for the output, a null extension will be
 used.
.skip
.indent -1
3 ALL
.skip

  This option is similar to RULES, except that it also mentions files included
 with the "#include <file.h>" directive.
.skip
 If the default file name is used for the output, a null extension will be
 used.
.skip
.indent -1
2 /STANDARD
.literal
    /STANDARD[=option]
    /NOSTANDARD
.end literal
.skip

 Controls use of GCC's -traditional, -ansi, and -pedantic options.
 The available options are PORTABLE and [NO]ANSI.
 /STANDARD=PORTABLE causes the ``-ansi -pedantic''
 switch combination to be used.  /STANDARD=ANSI is equivalent to
 /STANDARD, and causes ``-ansi'' to be used.  /STANDARD=NOANSI is
 equivalent omitting /STANDARD altogether, and is the default.  No
 special switches are used by the compiler in that case.
.skip
 Specifying /NOSTANDARD is different from simply omitting /STANDARD;
 it causes the ``-traditional'' switch to be used.
.skip
 See the GCC manual for the implications of these compiler switches.
.skip
.indent -1
2 /UNDEFINE
.skip
 /UNDEFINE cancels a macro definition.  Thus, it is the same as the
 #undef preprocessor directive.
.skip
 If more than one /UNDEFINE is present on the GCC command line, only
 the last /UNDEFINE is used.
.skip
 If both /DEFINE and /UNDEFINE are present on a command line, /DEFINE
 is evaluated before /UNDEFINE.
.skip
.indent -1
2 /TARGET=machine
.skip
  Directs the compiler driver to look in a subdirectory (going by the
  machine name) for compiler binaries.  This can be used for cross-
  compilation  or this can be used to maintain several different versions
  of gcc on the system simultaneously.
.skip
.indent -1
2 /VERBOSE
.literal
    /[NO]VERBOSE[=(option,...)]
.end literal
.skip

 Available options are ALL, ECHO, VERIFY (equivalent to ECHO),
 STATISTICS, and NONE.  /VERBOSE=NONE is equivalent to /NOVERBOSE, which
 is the default.  /VERBOSE is equivalent to /VERBOSE=ALL,
 which in turn is equivalent to /VERBOSE=(ECHO,STATISTICS).
.skip
 /VERBOSE=ECHO causes DCL verification to be used by the compiler driver
 routine while it invokes each separate phase of compilation (preprocessor,
 compiler proper, and assembler back-end).
.skip
 /VERBOSE=STATISTICS causes GCC to provide some tracing information
 (source function names) as it progresses, and also to provide internal
 timing statistics when it completes the primary compilation phase.
.skip
 /NOVERBOSE supresses the warning messages about debug being specified
 while optimization is enabled.
.skip
.indent -1
2 /VERSION
.skip

 Causes the driver, 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.
.skip
.indent -1
2 /WARNINGS
.skip
 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".
.skip
 Warnings are also generated by the preprocessor when this qualifier is given.
.skip
.indent -1
2 Known_Incompatibilities_with_VAX-C
.skip
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".
.skip
.indent 4
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.
.skip
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.
.skip
.indent 4
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.
.skip
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.
.skip
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.
.left margin 1