Initial revisionmisc/cutover-egcs-1

From-SVN: r14764

1 files changed, 406 insertions, 0 deletions

diff --git a/gcc/gcc.hlp b/gcc/gcc.hlp
new file mode 100644
index 00000000000..7ba1264a234
--- /dev/null
+++ b/gcc/gcc.hlp
@@ -0,0 +1,406 @@
+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.
+