-

Difference between revisions of "Operating Details"

From HI-TECH C for CP/M Fan WIKI(EN)
Jump to: navigation, search
(Created page with "HI-TECH C was designed for ease of use; a single command will compile, assemble and link a C program. The syntax of the C command is as follows: C [ options ] files [ libra...")
 
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
HI-TECH C was designed for ease of use; a  single  command will compile, assemble and link a C program. The syntax of the C command is as follows:
 
HI-TECH C was designed for ease of use; a  single  command will compile, assemble and link a C program. The syntax of the C command is as follows:
  
C [ options ] files [ libraries ]
+
C [ options ] files [ libraries ]
  
 
The options are zero or more options,  each  consisting of  a dash ('-'), a single key letter, and possibly an argument following the key letter with no intervening space. The files  are  one  or  more  C  source files, assembler source files, or object  files.  Libraries  may  be  zero  or  more library  names, or the abbreviated form -lname which will be expanded to the library name libname.lib.
 
The options are zero or more options,  each  consisting of  a dash ('-'), a single key letter, and possibly an argument following the key letter with no intervening space. The files  are  one  or  more  C  source files, assembler source files, or object  files.  Libraries  may  be  zero  or  more library  names, or the abbreviated form -lname which will be expanded to the library name libname.lib.
Line 12: Line 12:
 
The options recognized by the C command are as follows:
 
The options recognized by the C command are as follows:
  
-S
+
;-S
 
:Leave the results of compilation  of  any  C  files  as assembler output. C source code will be interspersed as comments in the assembler code.
 
:Leave the results of compilation  of  any  C  files  as assembler output. C source code will be interspersed as comments in the assembler code.
  
-C
+
;-C
 
:Leave the results of all  compiles  and  assemblies  as object files; do not invoke the linker. This allows the linker to be invoked separately, or via the  C  command at a later stage.
 
:Leave the results of all  compiles  and  assemblies  as object files; do not invoke the linker. This allows the linker to be invoked separately, or via the  C  command at a later stage.
  
-CR
+
;-CR
:Produce a cross reference listing. -CR on its own  will leave  the  raw  cross-reference  information in a temporary file, allowing the user to run CREF  explicitly, while  supplying  a  file  name,  e.g. -CR_�F_�R_�E_�D._�C_�R_�F will cause CREF to be invoked to process the raw information into the specified file, in this case _�F_�R_�E_�D._�C_�R_�F.
+
:Produce a cross reference listing. -CR on its own  will leave  the  raw  cross-reference  information in a temporary file, allowing the user to run CREF  explicitly, while  supplying  a  file  name,  e.g. -CR<strong>FRED.CRF</strong> will cause CREF to be invoked to process the raw information into the specified file, in this case <strong>FRED.CRF.</strong>
  
-CPM
+
;-CPM
 
:For the Z80 cross compiler only,  produce  CP/M-80  COM files.  Unless the -CPM option is given, the Z80 cross compiler uses the ROM runtime startoff module and  produces  hex  or  binary  images.  If the -CPM option is given, CP/M-80 runtime startoff code is linked used and a CP/M-80 COM file is produced.
 
:For the Z80 cross compiler only,  produce  CP/M-80  COM files.  Unless the -CPM option is given, the Z80 cross compiler uses the ROM runtime startoff module and  produces  hex  or  binary  images.  If the -CPM option is given, CP/M-80 runtime startoff code is linked used and a CP/M-80 COM file is produced.
  
-O
+
;-O
 
:Invoke  the  optimizer  on  all  compiled  code;  also requests the assembler to perform jump optimization.
 
:Invoke  the  optimizer  on  all  compiled  code;  also requests the assembler to perform jump optimization.
  
-O_�O_�U_�T_�F_�I_�L_�E
+
;-O<strong>OUTFILE</strong>
:Specify a name for the executable file to  be  created. By  default the name for the executable file is derived from the name of the first source or object file specified to the compiler. This option allows the default to be overridden. If no dot ('.')  appears  in  the  given file  name, an extension appropriate for the particular operating system will be added, e.g. -O_�F_�R_�E_�D will  generate a file _�F_�R_�E_�D._�E_�X_�E on MS-DOS or _�F_�R_�E_�D._�C_�M_�D on CP/M-86.
+
:Specify a name for the executable file to  be  created. By  default the name for the executable file is derived from the name of the first source or object file specified to the compiler. This option allows the default to be overridden. If no dot ('.')  appears  in  the  given file  name, an extension appropriate for the particular operating system will be added, e.g. -O<strong>FRED</strong> will  generate a file <strong>FRED.EXE</strong> on MS-DOS or <strong>FRED.CMD</strong> on CP/M-86.
For cross compilers this  also  provides  a  means  for specifying the output format, e.g. specifying an output file _�P_�R_�O_�G._�B_�I_�N will make the compiler generate a  binary file, while specifying _�P_�R_�O_�G._�H_�E_�X will make it generate a hexadecimal file.
+
:For cross compilers this  also  provides  a  means  for specifying the output format, e.g. specifying an output file <strong>PROG.BIN</strong> will make the compiler generate a  binary file, while specifying <strong>PROG.HEX</strong> will make it generate a hexadecimal file.
  
-V
+
;-V
 
:Verbose: each step of the compilation will be echoed as it is executed.
 
:Verbose: each step of the compilation will be echoed as it is executed.
  
-I
+
;-I
 
:Specify an additional filename prefix to use in searching  for #include files. For CP/M the default prefix is 0:A: (user number 0, disk  drive  A).  For  MS-DOS  the default  prefix is A:\HITECH\. Under Unix and Xenix the default prefix is /usr/hitech/include/.  Note  that  on MS-DOS  a  trailing  backslash  must be appended to any directory  name  given  as  an  argument  to  -I;  e.g. -I\FRED\  not  -I\FRED.  Under  Unix  a  trailing slash should be added.
 
:Specify an additional filename prefix to use in searching  for #include files. For CP/M the default prefix is 0:A: (user number 0, disk  drive  A).  For  MS-DOS  the default  prefix is A:\HITECH\. Under Unix and Xenix the default prefix is /usr/hitech/include/.  Note  that  on MS-DOS  a  trailing  backslash  must be appended to any directory  name  given  as  an  argument  to  -I;  e.g. -I\FRED\  not  -I\FRED.  Under  Unix  a  trailing slash should be added.
  
-D
+
;-D
 
:Define a symbol to the preprocessor:  e.g.  -DCPM  will define the symbol CPM as though via #define CPM 1.
 
:Define a symbol to the preprocessor:  e.g.  -DCPM  will define the symbol CPM as though via #define CPM 1.
  
-U
+
;-U
 
:Undefine a pre-defined symbol. The complement of -D.
 
:Undefine a pre-defined symbol. The complement of -D.
  
-F
+
;-F
 
:Request the linker to produce a symbol  file,  for  usewith the debugger.
 
:Request the linker to produce a symbol  file,  for  usewith the debugger.
  
-R
+
;-R
 
:For the Z80 CP/M compiler only this option will link in code  to  perform command line I/O redirection and wild card expansion in file names.  See the  description  of _getargs()  in  appendix 5 for details of the syntax of the redirections.
 
:For the Z80 CP/M compiler only this option will link in code  to  perform command line I/O redirection and wild card expansion in file names.  See the  description  of _getargs()  in  appendix 5 for details of the syntax of the redirections.
  
-X
+
;-X
 
:Strip local symbols from any files compiled,  assembled or linked. Only global symbols will remain.
 
:Strip local symbols from any files compiled,  assembled or linked. Only global symbols will remain.
  
-M
+
;-M
 
:Request the linker to produce a link map.
 
:Request the linker to produce a link map.
  
-A
+
;-A
 
:This option, for the Z80 only, will cause the  compiler to  produce  an executable program that will, on execution, self-relocate  itself  to  the  top  of  the  TPA (Transient  Program  Area).  This allows the writing of programs which may execute other programs  under  themselves.  Note that a program compiled in such a manner will not automatically reset the bdos address at  location 6 in order to protect itself. This must be done by the program itself.
 
:This option, for the Z80 only, will cause the  compiler to  produce  an executable program that will, on execution, self-relocate  itself  to  the  top  of  the  TPA (Transient  Program  Area).  This allows the writing of programs which may execute other programs  under  themselves.  Note that a program compiled in such a manner will not automatically reset the bdos address at  location 6 in order to protect itself. This must be done by the program itself.
  
For cross compilers this provides a way  of  specifying to  the  linker the addresses that the compiled program is to be  linked  at.  The  format  of  the  option  is -A_�R_�O_�M_�A_�D_�R,_�R_�A_�M_�A_�D_�R,_�R_�A_�M_�S_�I_�Z_�E_�R_�O_�M_�A_�D_�R is the address of the ROM in the system, and is where the executable code and initialized  data  will  be placed. _�R_�A_�M_�A_�D_�R is the start
+
:For cross compilers this provides a way  of  specifying to  the  linker the addresses that the compiled program is to be  linked  at.  The  format  of  the  option  is -A<strong>ROMADR,RAMADR,RAMSIZE.</strong> <strong>ROMADR</strong> is the address of the ROM in the system, and is where the executable code and initialized  data  will  be placed. <strong>RAMADR</strong> is the start address of RAM, and is where  the  bss  psect  will  be placed,  i.e.  uninitialized data.  <strong>RAMSIZE</strong> is the size of RAM available to the program, and is used to set the top of the stack.
address of RAM, and is where  the  bss  psect  will  be placed,  i.e.  uninitialized data.  _�R_�A_�M_�S_�I_�Z_�E is the size of RAM available to the program, and is used to set the top of the stack.
 
  
For the 6801/6301/68HC11 compiler, the -A option  takes a  fourth  value  which  is  the address of a four byte direct page area called ctemp which the  compiled  code uses as a scratch pad.  If the ctemp address is omitted from the -A option, it defaults to address 0.  Normally this  will  be  acceptable,  however some 6801 variants (like the 6303) have memory mapped I/O ports at address 0 and start their direct page RAM at address $80.
+
:For the 6801/6301/68HC11 compiler, the -A option  takes a  fourth  value  which  is  the address of a four byte direct page area called ctemp which the  compiled  code uses as a scratch pad.  If the ctemp address is omitted from the -A option, it defaults to address 0.  Normally this  will  be  acceptable,  however some 6801 variants (like the 6303) have memory mapped I/O ports at address 0 and start their direct page RAM at address $80.
  
For the large memory model of the 8051 compiler, the -A option  takes  the form -A
+
:For the large memory model of the 8051 compiler, the -A option  takes  the form -A <strong>ROMADR,INTRAM,EXTRAM,EXTSIZE.</strong><strong> ROMADR</strong> is the address of ROM in the system.  <strong>INTRAM</strong> is the  start  address  of  internal RAM, and is where the rbss psect will be placed.  The  8051  internal  stack will  start after the end of the rbss psect.  <strong>EXTRAM</strong> is the start address of external RAM, and is where the bss psect  will be placed.  <strong>EXTSIZE</strong> is the size of external RAM available to the program, and is used  to  set  the top of the external stack.
:�R_�O_�M_�A_�D_�R,_�I_�N_�T_�R_�A_�M,_�E_�X_�T_�R_�A_�M,_�E_�X_�T_�S_�I_�Z_�E. _�R_�O_�M_�A_�D_�R is the address of ROM in the system.  _�I_�N_�T_�R_�A_�M is the  start  address  of  internal RAM, and is where the rbss psect will be placed.  The  8051  internal  stack will  start after the end of the rbss psect.  _�E_�X_�T_�R_�A_�M is the start address of external RAM, and is where the bss psect  will be placed.  _�E_�X_�T_�S_�I_�Z_�E is the size of external RAM available to the program, and is used  to  set  the top of the external stack.
 
  
-B
+
;-B
 
:For compilers  which  support  more  than  one  "memory model",  this  option  is  used  to select which memory model code is to be generated for.  The format of  this option is -Bx where x is one or more letters specifying which memory model to use.  For the 8086,  this  option is  used  to  select  which  one  of five memory models (Tiny, Small, Medium, Compact or Large) is to be used.
 
:For compilers  which  support  more  than  one  "memory model",  this  option  is  used  to select which memory model code is to be generated for.  The format of  this option is -Bx where x is one or more letters specifying which memory model to use.  For the 8086,  this  option is  used  to  select  which  one  of five memory models (Tiny, Small, Medium, Compact or Large) is to be used.
  
:For the 8051 compiler  this  this  option  is  used  to select  which  one  of  the three memory models (Small, Medium or Large) is to be used.  For the 8051  compiler only,  this  option  can  also be used to select static allocation of _�a_�u_�t_�o variables by appending an A  to  the end  of  the -B option.  For example, -Bsa would select small model with static allocation  of  all  variables, while -Bm would select medium model with _�a_�u_�t_�o variables dynamically allocated on the stack.
+
:For the 8051 compiler  this  this  option  is  used  to select  which  one  of  the three memory models (Small, Medium or Large) is to be used.  For the 8051  compiler only,  this  option  can  also be used to select static allocation of <strong>auto</strong> variables by appending an A  to  the end  of  the -B option.  For example, -Bsa would select small model with static allocation  of  all  variables, while -Bm would select medium model with <strong>auto</strong> variables dynamically allocated on the stack.
  
-E
+
;-E
 
:By default the 8086 compiler will initialize  the  executable  file  header  to request a 64K data segment at run time. This may be overridden by the -E  option.  It takes  an  argument (usually in hexadecimal representation) which is the number of BYTES (not paragraphs)  to be  allocated  to  the program at run time. For example -E0ffff0h will request a megabyte. Since this much will not be available, the operating system will allocate as much as it can.
 
:By default the 8086 compiler will initialize  the  executable  file  header  to request a 64K data segment at run time. This may be overridden by the -E  option.  It takes  an  argument (usually in hexadecimal representation) which is the number of BYTES (not paragraphs)  to be  allocated  to  the program at run time. For example -E0ffff0h will request a megabyte. Since this much will not be available, the operating system will allocate as much as it can.
  
-W
+
;-W
 
:This options sets the warning level, i.e. it determines how  picky the compiler is about legal but dubious type conversions etc. -W0 will allow  all  warning  messages (default),  -W1  will  suppress  the  message  "Func() declared implicit int". -W3 is recommended for  compiling  code  originally  written with other, less strict, compilers. -W9 will suppress all warning messages.
 
:This options sets the warning level, i.e. it determines how  picky the compiler is about legal but dubious type conversions etc. -W0 will allow  all  warning  messages (default),  -W1  will  suppress  the  message  "Func() declared implicit int". -W3 is recommended for  compiling  code  originally  written with other, less strict, compilers. -W9 will suppress all warning messages.
  
-H
+
;-H
:This option  generates  a  symbol  file  for  use  with debuggers.  The  format of the symbol file is described elsewhere. The default  name  of  the  symbol  file  is _�l._�s_�y_�m.  An  alternate  name  may  be  specfied with the option, e.g. -H_�s_�y_�m_�f_�i_�l_�e._�a_�b_�c.
+
:This option  generates  a  symbol  file  for  use  with debuggers.  The  format of the symbol file is described elsewhere. The default  name  of  the  symbol  file  is <strong>l.sym</strong>.  An  alternate  name  may  be  specfied with the option, e.g. -H<strong>symfile.abc.</strong>
  
-G
+
;-G
 
:Like -H, -G also generates a symbol file, but one  that contains  line and file number information for a source level debugger. Like -H a file name may  be  specified. When  used in conjunction with -O, only partial optimization  will  be  performed  to  avoid  confusing  the debugger.
 
:Like -H, -G also generates a symbol file, but one  that contains  line and file number information for a source level debugger. Like -H a file name may  be  specified. When  used in conjunction with -O, only partial optimization  will  be  performed  to  avoid  confusing  the debugger.
  
-P
+
;-P
:Execution profiling is available  on  native  compilers running  under  DOS,  CP/M-86 and on the Atari ST. This option generates code to turn  on  execution  profiling when  the  program  is  run. A -H option should also be specified to provide a symbol table  for  the  profiler
+
:Execution profiling is available  on  native  compilers running  under  DOS,  CP/M-86 and on the Atari ST. This option generates code to turn  on  execution  profiling when  the  program  is  run. A -H option should also be specified to provide a symbol table  for  the  profiler EPROF.
EPROF.
 
  
-Z
+
;-Z
 
:For version 5.xx compilers only, the -Z option is  used to  select  global  optimization of the code generated. For the 8086 and 6801/6301/68HC11  compilers  the  only valid  -Z  option  is  -Zg.  For the 8051 compiler, the valid -Z options are -Zg which invokes global optimization,  -Zs  which  optimizes  for  space, and -Zf which optimizes for speed.  The s and f options may  be  used with  the  g option, thus the options -Zgf and -Zgs are valid.  Speed  and  space  optimization  are  mutually exclusive,  i.e.  the  s  and  f options cannot be used together.
 
:For version 5.xx compilers only, the -Z option is  used to  select  global  optimization of the code generated. For the 8086 and 6801/6301/68HC11  compilers  the  only valid  -Z  option  is  -Zg.  For the 8051 compiler, the valid -Z options are -Zg which invokes global optimization,  -Zs  which  optimizes  for  space, and -Zf which optimizes for speed.  The s and f options may  be  used with  the  g option, thus the options -Zgf and -Zgs are valid.  Speed  and  space  optimization  are  mutually exclusive,  i.e.  the  s  and  f options cannot be used together.
  
-1
+
;-1
 
:For the 8086 compiler only, request the  generation  of code which takes advantage of the extra instructions of the 80186 processor. A program compiled  with  -1  will not execute on an 8086 or 8088 processor. For the 68000 compiler, generate instructions for the  68010  processor.
 
:For the 8086 compiler only, request the  generation  of code which takes advantage of the extra instructions of the 80186 processor. A program compiled  with  -1  will not execute on an 8086 or 8088 processor. For the 68000 compiler, generate instructions for the  68010  processor.
  
-2
+
;-2
 
:Like -1 but for the 80286 and 68020.
 
:Like -1 but for the 80286 and 68020.
  
-11
+
;-11
 
:For the 6801/HC11 compiler, this  option  will  request generation  of instructions specific to the 68HC11 processor.
 
:For the 6801/HC11 compiler, this  option  will  request generation  of instructions specific to the 68HC11 processor.
  
-6301
+
;-6301
For the 6801/HC11 compiler, this  option  will  request generation  of  instructions  specific to the 6301/6303 processors.
+
:For the 6801/HC11 compiler, this  option  will  request generation  of  instructions  specific to the 6301/6303 processors.
  
Some examples of the use of the C command are:
+
:Some examples of the use of the C command are:
  
c prog.c
+
c prog.c
  
c -mlink.map prog.c x.obj -lx
+
c -mlink.map prog.c x.obj -lx
  
c -S prog.c
+
c -S prog.c
  
c -O -C -CRprog.crf prog.c prog2.c
+
c -O -C -CRprog.crf prog.c prog2.c
  
c -v -Oxfile.exe afile.obj anfile.c -lf
+
c -v -Oxfile.exe afile.obj anfile.c -lf
  
  
Line 119: Line 116:
 
Taking the above examples in order; the first  compiles and  links  the  C  source  file  prog.c with the standard C library. The second example will compile the file prog.c and link it with the object file x.obj and the library libx.lib; a link map will be written to the file link.map.
 
Taking the above examples in order; the first  compiles and  links  the  C  source  file  prog.c with the standard C library. The second example will compile the file prog.c and link it with the object file x.obj and the library libx.lib; a link map will be written to the file link.map.
  
The third example compiles the file prog.c, leaving the assembler  output  in  a  file prog.as. It does not assemble this file or invoke the linker.  The next  example  compiles both  prog.c  and  prog2.c,  invoking  the optimizer on both files, but does not perform any linking. A  cross  reference listing will be left in the file _�p_�r_�o_�g._�c_�r_�f.
+
The third example compiles the file prog.c, leaving the assembler  output  in  a  file prog.as. It does not assemble this file or invoke the linker.  The next  example  compiles both  prog.c  and  prog2.c,  invoking  the optimizer on both files, but does not perform any linking. A  cross  reference listing will be left in the file <strong>prog.crf</strong>.
  
 
The last example pertains to the 8086  version  of  the compiler,  It runs the compiler with the verbose option, and will cause anfile.c to be compiled without  optimization  to object  code,  yielding  anfile.obj,  then  afile.obj  and anfile.obj will be linked together with the  floating  point library  (from  the  -LF option) and the standard library to yield the executable program  xfile.exe  (assuming  this  is performed  on an MS-DOS system).  One would expect this program to use floating point, if  it  did  not  then  the  -LF option would have been required.
 
The last example pertains to the 8086  version  of  the compiler,  It runs the compiler with the verbose option, and will cause anfile.c to be compiled without  optimization  to object  code,  yielding  anfile.obj,  then  afile.obj  and anfile.obj will be linked together with the  floating  point library  (from  the  -LF option) and the standard library to yield the executable program  xfile.exe  (assuming  this  is performed  on an MS-DOS system).  One would expect this program to use floating point, if  it  did  not  then  the  -LF option would have been required.
Line 127: Line 124:
 
Other commands which may be issued by the user,  rather than automatically by the C command, are:
 
Other commands which may be issued by the user,  rather than automatically by the C command, are:
  
ZAS
+
;ZAS
 
:The Z80 assembler.
 
:The Z80 assembler.
  
AS86
+
;AS86
 
:The 8086 assembler.
 
:The 8086 assembler.
  
LINK
+
;LINK
 
:The linker
 
:The linker
  
LIBR
+
;LIBR
 
:The library maintainer
 
:The library maintainer
  
OBJTOHEX
+
;OBJTOHEX
 
:Object to hex converter
 
:Object to hex converter
  
CREF
+
;CREF
 
:Cross reference generator.
 
:Cross reference generator.
  
:In general, these commands accept the same type of command line as the C command, i.e. zero or more options (indicated by a leading '-') followed by one or more  file  arguments.  If  the  linker  or the librarian is invoked with no arguments, it wll prompt for a  command  line.  This  allows command  lines  of more than 128 bytes to be entered.  Input may also be taken from a file by using the redirection capablities  (see  _getargs()  in the library function listing).
+
In general, these commands accept the same type of command line as the C command, i.e. zero or more options (indicated by a leading '-') followed by one or more  file  arguments.  If  the  linker  or the librarian is invoked with no arguments, it wll prompt for a  command  line.  This  allows command  lines  of more than 128 bytes to be entered.  Input may also be taken from a file by using the redirection capablities  (see  _getargs()  in the library function listing).
 +
 
 
See the discussion above of the C command.  These  commands are described in further detail in their respective manuals.
 
See the discussion above of the C command.  These  commands are described in further detail in their respective manuals.

Latest revision as of 18:01, 30 July 2017

HI-TECH C was designed for ease of use; a single command will compile, assemble and link a C program. The syntax of the C command is as follows:

C [ options ] files [ libraries ]

The options are zero or more options, each consisting of a dash ('-'), a single key letter, and possibly an argument following the key letter with no intervening space. The files are one or more C source files, assembler source files, or object files. Libraries may be zero or more library names, or the abbreviated form -lname which will be expanded to the library name libname.lib.

The C command will, as determined by the specified options, compile any C source files given, assemble them into object code unless requested otherwise, assemble any assembler source files specified, then link the results of the assemblies with any object or library files specified.

If the C command is invoked without arguments, then it will prompt for a command line to be entered. This command line may be extended by typing a backslash ('\') on the end of the line. Another line will then be requested. If the standard input of the command is from a file (e.g. by typing C < afile) then the command lines will be read from that file. Within the file more than one line may be given if each line but the last ends with a backslash. Note that this mechanism does not work in MS-DOS batch file, i.e. the command file for the C command must be a separate file. MS-DOS has no mechanism for providing long command lines or standard input from inside a batch file.

The options recognized by the C command are as follows:

-S
Leave the results of compilation of any C files as assembler output. C source code will be interspersed as comments in the assembler code.
-C
Leave the results of all compiles and assemblies as object files; do not invoke the linker. This allows the linker to be invoked separately, or via the C command at a later stage.
-CR
Produce a cross reference listing. -CR on its own will leave the raw cross-reference information in a temporary file, allowing the user to run CREF explicitly, while supplying a file name, e.g. -CRFRED.CRF will cause CREF to be invoked to process the raw information into the specified file, in this case FRED.CRF.
-CPM
For the Z80 cross compiler only, produce CP/M-80 COM files. Unless the -CPM option is given, the Z80 cross compiler uses the ROM runtime startoff module and produces hex or binary images. If the -CPM option is given, CP/M-80 runtime startoff code is linked used and a CP/M-80 COM file is produced.
-O
Invoke the optimizer on all compiled code; also requests the assembler to perform jump optimization.
-OOUTFILE
Specify a name for the executable file to be created. By default the name for the executable file is derived from the name of the first source or object file specified to the compiler. This option allows the default to be overridden. If no dot ('.') appears in the given file name, an extension appropriate for the particular operating system will be added, e.g. -OFRED will generate a file FRED.EXE on MS-DOS or FRED.CMD on CP/M-86.
For cross compilers this also provides a means for specifying the output format, e.g. specifying an output file PROG.BIN will make the compiler generate a binary file, while specifying PROG.HEX will make it generate a hexadecimal file.
-V
Verbose: each step of the compilation will be echoed as it is executed.
-I
Specify an additional filename prefix to use in searching for #include files. For CP/M the default prefix is 0:A: (user number 0, disk drive A). For MS-DOS the default prefix is A:\HITECH\. Under Unix and Xenix the default prefix is /usr/hitech/include/. Note that on MS-DOS a trailing backslash must be appended to any directory name given as an argument to -I; e.g. -I\FRED\ not -I\FRED. Under Unix a trailing slash should be added.
-D
Define a symbol to the preprocessor: e.g. -DCPM will define the symbol CPM as though via #define CPM 1.
-U
Undefine a pre-defined symbol. The complement of -D.
-F
Request the linker to produce a symbol file, for usewith the debugger.
-R
For the Z80 CP/M compiler only this option will link in code to perform command line I/O redirection and wild card expansion in file names. See the description of _getargs() in appendix 5 for details of the syntax of the redirections.
-X
Strip local symbols from any files compiled, assembled or linked. Only global symbols will remain.
-M
Request the linker to produce a link map.
-A
This option, for the Z80 only, will cause the compiler to produce an executable program that will, on execution, self-relocate itself to the top of the TPA (Transient Program Area). This allows the writing of programs which may execute other programs under themselves. Note that a program compiled in such a manner will not automatically reset the bdos address at location 6 in order to protect itself. This must be done by the program itself.
For cross compilers this provides a way of specifying to the linker the addresses that the compiled program is to be linked at. The format of the option is -AROMADR,RAMADR,RAMSIZE. ROMADR is the address of the ROM in the system, and is where the executable code and initialized data will be placed. RAMADR is the start address of RAM, and is where the bss psect will be placed, i.e. uninitialized data. RAMSIZE is the size of RAM available to the program, and is used to set the top of the stack.
For the 6801/6301/68HC11 compiler, the -A option takes a fourth value which is the address of a four byte direct page area called ctemp which the compiled code uses as a scratch pad. If the ctemp address is omitted from the -A option, it defaults to address 0. Normally this will be acceptable, however some 6801 variants (like the 6303) have memory mapped I/O ports at address 0 and start their direct page RAM at address $80.
For the large memory model of the 8051 compiler, the -A option takes the form -A ROMADR,INTRAM,EXTRAM,EXTSIZE. ROMADR is the address of ROM in the system. INTRAM is the start address of internal RAM, and is where the rbss psect will be placed. The 8051 internal stack will start after the end of the rbss psect. EXTRAM is the start address of external RAM, and is where the bss psect will be placed. EXTSIZE is the size of external RAM available to the program, and is used to set the top of the external stack.
-B
For compilers which support more than one "memory model", this option is used to select which memory model code is to be generated for. The format of this option is -Bx where x is one or more letters specifying which memory model to use. For the 8086, this option is used to select which one of five memory models (Tiny, Small, Medium, Compact or Large) is to be used.
For the 8051 compiler this this option is used to select which one of the three memory models (Small, Medium or Large) is to be used. For the 8051 compiler only, this option can also be used to select static allocation of auto variables by appending an A to the end of the -B option. For example, -Bsa would select small model with static allocation of all variables, while -Bm would select medium model with auto variables dynamically allocated on the stack.
-E
By default the 8086 compiler will initialize the executable file header to request a 64K data segment at run time. This may be overridden by the -E option. It takes an argument (usually in hexadecimal representation) which is the number of BYTES (not paragraphs) to be allocated to the program at run time. For example -E0ffff0h will request a megabyte. Since this much will not be available, the operating system will allocate as much as it can.
-W
This options sets the warning level, i.e. it determines how picky the compiler is about legal but dubious type conversions etc. -W0 will allow all warning messages (default), -W1 will suppress the message "Func() declared implicit int". -W3 is recommended for compiling code originally written with other, less strict, compilers. -W9 will suppress all warning messages.
-H
This option generates a symbol file for use with debuggers. The format of the symbol file is described elsewhere. The default name of the symbol file is l.sym. An alternate name may be specfied with the option, e.g. -Hsymfile.abc.
-G
Like -H, -G also generates a symbol file, but one that contains line and file number information for a source level debugger. Like -H a file name may be specified. When used in conjunction with -O, only partial optimization will be performed to avoid confusing the debugger.
-P
Execution profiling is available on native compilers running under DOS, CP/M-86 and on the Atari ST. This option generates code to turn on execution profiling when the program is run. A -H option should also be specified to provide a symbol table for the profiler EPROF.
-Z
For version 5.xx compilers only, the -Z option is used to select global optimization of the code generated. For the 8086 and 6801/6301/68HC11 compilers the only valid -Z option is -Zg. For the 8051 compiler, the valid -Z options are -Zg which invokes global optimization, -Zs which optimizes for space, and -Zf which optimizes for speed. The s and f options may be used with the g option, thus the options -Zgf and -Zgs are valid. Speed and space optimization are mutually exclusive, i.e. the s and f options cannot be used together.
-1
For the 8086 compiler only, request the generation of code which takes advantage of the extra instructions of the 80186 processor. A program compiled with -1 will not execute on an 8086 or 8088 processor. For the 68000 compiler, generate instructions for the 68010 processor.
-2
Like -1 but for the 80286 and 68020.
-11
For the 6801/HC11 compiler, this option will request generation of instructions specific to the 68HC11 processor.
-6301
For the 6801/HC11 compiler, this option will request generation of instructions specific to the 6301/6303 processors.
Some examples of the use of the C command are:
c prog.c
c -mlink.map prog.c x.obj -lx
c -S prog.c
c -O -C -CRprog.crf prog.c prog2.c
c -v -Oxfile.exe afile.obj anfile.c -lf


Upper and lower case has been used in the above examples for emphasis: the compiler does not distinguish between cases, although arguments specifying names, e.g. -D, are inherently case sensitive.

Taking the above examples in order; the first compiles and links the C source file prog.c with the standard C library. The second example will compile the file prog.c and link it with the object file x.obj and the library libx.lib; a link map will be written to the file link.map.

The third example compiles the file prog.c, leaving the assembler output in a file prog.as. It does not assemble this file or invoke the linker. The next example compiles both prog.c and prog2.c, invoking the optimizer on both files, but does not perform any linking. A cross reference listing will be left in the file prog.crf.

The last example pertains to the 8086 version of the compiler, It runs the compiler with the verbose option, and will cause anfile.c to be compiled without optimization to object code, yielding anfile.obj, then afile.obj and anfile.obj will be linked together with the floating point library (from the -LF option) and the standard library to yield the executable program xfile.exe (assuming this is performed on an MS-DOS system). One would expect this program to use floating point, if it did not then the -LF option would have been required.

If more than one C or assembler source file is given to the C command, the name of each file will be printed on the console as it is processed. If any fatal errors occur during the compilation or assembly of source files, further source files will be processed, but the linker will not be invoked.

Other commands which may be issued by the user, rather than automatically by the C command, are:

ZAS
The Z80 assembler.
AS86
The 8086 assembler.
LINK
The linker
LIBR
The library maintainer
OBJTOHEX
Object to hex converter
CREF
Cross reference generator.

In general, these commands accept the same type of command line as the C command, i.e. zero or more options (indicated by a leading '-') followed by one or more file arguments. If the linker or the librarian is invoked with no arguments, it wll prompt for a command line. This allows command lines of more than 128 bytes to be entered. Input may also be taken from a file by using the redirection capablities (see _getargs() in the library function listing).

See the discussion above of the C command. These commands are described in further detail in their respective manuals.