Return to gcc.hlp CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/gcc.hlp, revision 1.1

1.1     ! root        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: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.