gcc/gcc.hlp

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