home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1995 April / Internet Tools.iso / osi / isode / vmsisode / vmsgcc139_tar.Z / vmsgcc139_tar / gcc.hlp < prev    next >
Encoding:
Text File  |  1991-12-18  |  13.7 KB  |  412 lines
  1. !
  2. !       Thinking about editing this file???? DON'T!!!! Edit GCC.RNH
  3. !       to make the changes you need and then use RUNOFF on your
  4. !       modified help file.
  5. !
  6. 1 GCC
  7.  
  8.  The GCC command invokes the GNU C compiler.
  9.  
  10.        GCC file-spec
  11.  
  12. 2 Parameters
  13.  
  14.  file-spec
  15.  
  16.  A C source file.  If no input file  extension  is  specified,  GNU  C
  17.  assumes  .C  as  the  default extension unless the /PLUS qualifier is
  18.  given, in which case .CC is assumed as the default extension.
  19.  
  20.  If an extension of .CPP is given, then the source file is assumed  to
  21.  be  the  output of the preprocessor, and thus the preprocessor is not
  22.  executed.
  23.  
  24.  If an extension of .S is given, then the source file is assumed to be
  25.  the  assembly  code output of the compiler, and only the assembler is
  26.  called to generate an object file.
  27.  
  28. 2 Qualifiers
  29.  
  30.  GNU C command qualifiers modify the  way  the  compiler  handles  the
  31.  compilation.
  32.  
  33.  The following is the list of available qualifiers for GNU C:
  34.  
  35.        /CASE_HACK
  36.        /CC1_OPTIONS=(option [,option...]])
  37.        /DEBUG
  38.        /DEFINE=(identifier[=definition][,...])
  39.        /G_FLOAT
  40.        /INCLUDE_DIRECTORY=(path [,path...]])
  41.        /LIST[=filename]
  42.        /MACHINE_CODE
  43.        /OBJECT[=filename]
  44.        /OPTIMIZE
  45.        /PLUS
  46.        /PROFILE[=identifier]
  47.        /SCAN=(file[,file...])
  48.        /SHOW[=option]
  49.        /UNDEFINE=(identifier[,identifier,...])
  50.        /VERBOSE
  51.        /VERSION
  52.        /WARNING
  53.  
  54. 2 Linking
  55.  
  56.  When linking programs compiled with GNU C, you should include the GNU
  57.  C library before the VAX C library.  For example,
  58.  
  59.    LINK object-file,GNU_CC:[000000]GCCLIB/LIB,SYS$LIBRARY:VAXCRTL/LIB
  60.  
  61.  You can also link your program with the shared VAX C  library.   This
  62.  can reduce the size of the .EXE file, as well as make it smaller when
  63.  it's running.  For example,
  64.  
  65.    $ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,SYS$INPUT/OPT
  66.    SYS$SHARE:VAXCRTL/SHARE
  67.  
  68.  (If you use the second example and type it in by  hand,  be  sure  to
  69.  type ^Z after the last carriage return).  A simpler alternative would
  70.  be to place the single line:
  71.  
  72.    SYS$SHARE:VAXCRTL/SHARE
  73.  
  74.  into a file called VAXCRTL.OPT, and then use the link command:
  75.  
  76.    $ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,VAXCRTL.OPT/OPT
  77.  
  78.  If a program has  been  compiled  with  /G_FLOAT,  then  the  linking
  79.  instructions  are  slightly  different.   If you are linking with the
  80.  non-shared library, then the command that you should use would be:
  81.  
  82.    LINK object-file,GNU_CC:[000000]GCCLIB/LIB,SYS$LIBRARY:VAXCRTLG/LIB -
  83.                                 ,SYS$LIBRARY:VAXCRTL/LIB
  84.  
  85.  Note that both VAXCRTL and VAXCRTLG must be linked to.   If  you  are
  86.  using the shared VAX C library, then you should use a command like:
  87.  
  88.    $ LINK object-file, GNU_CC:[000000]GCCLIB/LIB,SYS$INPUT:/OPTIONS
  89.    SYS$SHARE:VAXCRTLG/SHARE
  90.  
  91.  In the case of the sharable library, only one  library  needs  to  be
  92.  linked to.
  93.  
  94. 2 /CASE_HACK
  95.  
  96.    /[NO]CASE_HACK      D=/CASE_HACK
  97.  
  98.  Since the VMS Linker  and  Librarian  are  not  case  sensitive  with
  99.  respect  to  symbol names, a "case-hack" is appended to a symbol name
  100.  when the symbol contains upper case characters.
  101.  
  102.  There are cases where this is undesirable, (mainly when using certain
  103.  applications  where modules have been precompiled, perhaps in another
  104.  language) and we want to compile  without  case  hacking.   In  these
  105.  cases the /NOCASE_HACK switch disables case hacking.
  106.  
  107. 2 /CC1_OPTIONS
  108.  
  109.  This specifies additional  switches  to  the  compiler  itself  which
  110.  cannot be set by means of the compiler driver.
  111.  
  112. 2 /DEBUG
  113.  
  114.  /DEBUG includes additional information in the object file  output  so
  115.  that the program can be debugged with the VAX Symbolic Debugger.
  116.  
  117.  To use the debugger it is also necessary to link the debugger to your
  118.  program, which is done by specifying the /DEBUG qualifier to the link
  119.  command.  With the  debugger  it  is  possible  to  set  breakpoints,
  120.  examine  variables,  and  set  variables  to new values.  See the VAX
  121.  Symbolic Debugger manual for more information, or  type  "HELP"  from
  122.  the debugger prompt.
  123.  
  124. 2 /DEFINE
  125.  
  126.  /DEFINE=(identifier[=definition][,...])
  127.  
  128.  /DEFINE defines a string or macro ('definition')  to  be  substituted
  129.  for  every  occurrence of a given string ('identifier') in a program.
  130.  It is equivalent to the #define preprocessor directive.
  131.  
  132.  All definitions and identifiers are  converted  to  uppercase  unless
  133.  they are in quotation marks.
  134.  
  135.  The simple form of the /DEFINE qualifier:
  136.  
  137.     /DEFINE=vms
  138.  
  139.  results in a definition equivalent to the preprocessor directive:
  140.  
  141.   #define VMS 1
  142.  
  143.  You must enclose macro definitions in quotation  marks,  as  in  this
  144.  example:
  145.  
  146.   /DEFINE="C(x)=((x) & 0xff)"
  147.  
  148.  This definition is the same as the preprocessor definition:
  149.  
  150.   #define C(x) ((x) & 0xff)
  151.  
  152.  If more than one /DEFINE is present on the GCC command line, only the
  153.  last /DEFINE is used.
  154.  
  155.  If both /DEFINE and /UNDEFINE are present on a command line,  /DEFINE
  156.  is evaluated before /UNDEFINE.
  157.  
  158. 2 /G_FLOAT
  159.  
  160.  Instructs the compiler to use "G" floating point  arithmetic  instead
  161.  of  "D".   The  difference  is  that  double precision has a range of
  162.  approximately +/-0.56e-308 to +/-0.9  e+308,  with  approximately  15
  163.  decimal digits precision.
  164.  
  165.  "D" floating point has the same range as  single  precision  floating
  166.  point, with approximately 17 decimal digits precision.
  167.  
  168.  If you use the  /G_FLOAT  qualifier,  the  linking  instructions  are
  169.  different.  See "Linking" for further details.
  170.  
  171. 2 /LIST
  172.  
  173.  /LIST[=list_file_name]
  174.  
  175.  This does not generate a listing file in the usual sense, however  it
  176.  does  direct the compiler to save the preprocessor output.  If a file
  177.  is not specified, then this output is written into a  file  with  the
  178.  same name as the source file and an extension of .CPP.
  179.  
  180. 2 /INCLUDE_DIRECTORY
  181.  
  182.   /INCLUDE_DIRECTORY=(path [,path...])
  183.  
  184.  The /INCLUDE_DIRECTORY qualifier provides additional  directories  to
  185.  search  for  user-defined  include  files.   'path'  can  be either a
  186.  logical name or a directory specification.
  187.  
  188.  There  are  two  forms  for  specifying  include  files  -   #include
  189.  "file-spec"  and  #include <file-spec>.  For the #include "file-spec"
  190.  form, the search order is:
  191.  
  192.   1.  The directory containing the source file.
  193.  
  194.   2.  The directories in the /INCLUDE qualifier (if any).
  195.  
  196.   3.  The directory (or directories) specified in the logical name
  197.       GNU_CC_INCLUDE.
  198.  
  199.   4.  The directory (or directories) specified in the logical name
  200.       SYS$LIBRARY.
  201.  
  202.   For the #include <file-spec> form, the search order is:
  203.  
  204.   1.  The directories specified in the /INCLUDE qualifier (if any).
  205.  
  206.   2.  The directory (or directories) specified in the logical name
  207.       GNU_CC_INCLUDE.
  208.  
  209.   3.  The directory (or directories) specified in the logical name
  210.       SYS$LIBRARY.
  211.  
  212. 2 /MACHINE_CODE
  213.  
  214.  Tells GNU C to output the machine code  generated  by  the  compiler.
  215.  The  machine code is output to a file with the same name as the input
  216.  file, with the extension .S.  An  object  file  is  still  generated,
  217.  unless /NOOBJ is also specified.
  218.  
  219. 2 /OBJECT
  220.  
  221.    /OBJECT[=filename]
  222.    /NOOBJECT
  223.  
  224.         Controls whether or not an object file  is  generated  by  the
  225.  compiler.
  226.  
  227. 2 /OPTIMIZE
  228.  
  229.  /[NO]OPTIMIZE
  230.  
  231.  Controls whether optimization  is  performed  by  the  compiler.   By
  232.  default, optimization is on.  /NOOPTIMIZE turns optimization off.
  233.  
  234. 2 /PLUS
  235.  
  236.  Instructs the compiler driver to use the GNU-C++ compiler instead  of
  237.  the  GNU-C compiler.  Note that the default extension of source files
  238.  is .CC when this qualifier is in effect.
  239.  
  240. 2 /PROFILE
  241.  
  242.  /PROFILE[=identifier]
  243.  
  244.  Instructs the compiler to generate function profiling code.  You must
  245.  link  your  program  to  the profiler when you use this options.  The
  246.  profile statistics are automatically  printed  out  on  the  terminal
  247.  during  image  exit.  (i.e.  no modifications to your source file are
  248.  required in order to use the profiler).
  249.  
  250.  There are three identifiers  that  can  be  used  with  the  /PROFILE
  251.  switch.   These  are  ALL, FUNCTION, and BLOCK.  If /PROFILE is given
  252.  without an identifier, then FUNCTION is assumed.
  253.  
  254. 3 Block_Profiler
  255.  
  256.  The block profiler counts how  many  times  control  of  the  program
  257.  passes certain points in your program.  This is useful in determining
  258.  which  portions  of  a  program  would  benefit  from  recoding   for
  259.  optimization.
  260.  
  261.  The report for the block profiler contains the  function  name,  file
  262.  name, PC, and the source file line number as well as the count of how
  263.  many times control has passed through the specified source line.
  264.  
  265. 3 Function_Profiler
  266.  
  267.  The function profiler counts how many times each function is entered,
  268.  and keeps track of how much CPU time is used within each function.
  269.  
  270.  You should be careful about  interpreting  the  results  of  profiles
  271.  where  there  are  inline  functions.  When a function is included as
  272.  inline, then there is no call to the internal data collection routine
  273.  used  by  the  profiler,  and  thus  there  will be no record of this
  274.  function being called.  The compiler does generate a callable version
  275.  of each inline function, and if this called version is used, then the
  276.  profiler's data collection routine will be called.
  277.  
  278. 2 /SCAN
  279.  
  280.  /SCAN=(file[,file...])
  281.  
  282.  This qualifier supplies a list of files that will be read  as  input,
  283.  and  the output will be discarded before processing the regular input
  284.  file.  Because the output generated from the files is discarded,  the
  285.  only  effect  of  this qualifier is to make the macros defined in the
  286.  files available for use in the main input.
  287.  
  288. 2 /SHOW
  289.  
  290.  /SHOW[=option]
  291.  
  292.  This causes the preprocessor to generate information other  than  the
  293.  preprocessed  input  file.   When this qualifier is used, no assembly
  294.  code and no object file is generated.
  295.  
  296.  The output of the preprocessor is placed in the file specified by the
  297.  /LIST  qualifier, if present.  If the /LIST qualifier is not present,
  298.  then the output is placed in a file with the same name as  the  input
  299.  file  with  an  extension  that  depends  upon  which  option that is
  300.  selected.
  301.  
  302. 3 DEFINITIONS
  303.  
  304.  This option causes the preprocessor to dump a  list  of  all  of  the
  305.  definitions  to  the  output  file.   This  is  useful  for debugging
  306.  purposes, since it lets you determine whether or not  everything  has
  307.  been defined properly.
  308.  
  309.  If the default file name is used for the output, the  extension  will
  310.  be .DEF.
  311.  
  312. 3 RULES
  313.  
  314.  This option causes the preprocessor to output  a  rule  suitable  for
  315.  MAKE,  describing  the  dependencies  of  the  main source file.  The
  316.  preprocessor outputs one MAKE rule containing the  object  file  name
  317.  for  that  source  file,  a colon, and the names of all the concluded
  318.  files.  If there are many included files then the rule is split  into
  319.  several lines using the '\'-newline.
  320.  
  321.  When using this option, only files included with the "#include "file"
  322.  directive are mentioned.
  323.  
  324.  If the default file name is used for the  output,  a  null  extension
  325.  will be used.
  326.  
  327. 3 ALL
  328.  
  329.  This option is similar to RULES, except that it also  mentions  files
  330.  included with the "#include <file.h>" directive.
  331.  
  332.  If the default file name is used for the  output,  a  null  extension
  333.  will be used.
  334.  
  335. 2 /UNDEFINE
  336.  
  337.  /UNDEFINE cancels a macro definition.  Thus, it is the  same  as  the
  338.  #undef preprocessor directive.
  339.  
  340.  If more than one /UNDEFINE is present on the GCC command  line,  only
  341.  the last /UNDEFINE is used.
  342.  
  343.  If both /DEFINE and /UNDEFINE are present on a command line,  /DEFINE
  344.  is evaluated before /UNDEFINE.
  345.  
  346. 2 /VERBOSE
  347.  
  348.  Controls whether the user sees the invocation command strings for the
  349.  preprocessor,  compiler,  and  assembler.   The compiler also outputs
  350.  some statistics on time spent in its various phases.
  351.  
  352. 2 /VERSION
  353.  
  354.  Causes the preprocessor and the compiler to  identify  themselves  by
  355.  their  version  numbers, and in the case of the compiler, the version
  356.  number of the compiler that built it.
  357.  
  358. 2 /WARNING
  359.  
  360.  When this qualifier is present, warnings about usage that  should  be
  361.  avoided  are given by the compiler.  For more information, see "Using
  362.  and Porting GNU CC", in the section on command  line  options,  under
  363.  "-Wall".
  364.  
  365.  Warnings are also generated by the preprocessor when  this  qualifier
  366.  is given.
  367.  
  368. 2 Known_Incompatibilities_with_VAX-C
  369.  
  370.  There are several known incompatibilities between  GNU-C  and  VAX-C.
  371.  These are:
  372.  
  373.      GNU-C does not provide a default return value  for  the  function
  374.  main().   If  main()  exits  without  a return or a call to exit, the
  375.  return value in R0 is determined by previous  calculations,  and  VMS
  376.  interprets  this  as a status code.  In general, this will show up as
  377.  an unexpected and unusual error message when the program  exits.   It
  378.  is good programming practice to use a
  379.  
  380.       return 1;
  381.  
  382.  at the end of main() to indicate to VMS a normal completion.
  383.  
  384.      GNU-C provides case hacking as a means of giving case sensitivity
  385.  to  symbol  names.  The case hack is a hexadecimal number appended to
  386.  the symbol name, with a bit being set for  each  upper  case  letter.
  387.  Symbols with all lower case, or symbols that have a dollar sign ("$")
  388.  are not case hacked.  There  are  times  that  this  is  undesirable,
  389.  namely  when  you  wish  to  link  your program against a precompiled
  390.  library which was compiled with a non-GNU-C compiler.  X-windows  (or
  391.  DECWindows)   is  an  example  of  this.   In  these  instances,  the
  392.  /NOCASE_HACK switch should be used.
  393.  
  394.      GNU-C does not provide  the  globaldef  and  globalref  mechanism
  395.  which  is  used  by VAX-C to coerce the VMS linker to include certain
  396.  object modules from a library.  globaldef  can  be  achieved  in  the
  397.  following manner with GNU-C:
  398.  
  399.      #ifdef __GNUC__
  400.      force_this_module(){ };
  401.      #else
  402.      globaldef force_this_module;
  403.      #endif
  404.  
  405.  The globalref can be provided in a similar way:
  406.  
  407.      #ifdef __GNUC__
  408.      static force_that_module(){force_this_module();};
  409.      #else
  410.      globalref force_this_module;
  411.      #endif
  412.