Operating Details

From HI-TECH C for CP/M Fan WIKI(EN)
Jump to: navigation, search

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:

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 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.
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.
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.
Invoke the optimizer on all compiled code; also requests the assembler to perform jump optimization.
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.
Verbose: each step of the compilation will be echoed as it is executed.
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.
Define a symbol to the preprocessor: e.g. -DCPM will define the symbol CPM as though via #define CPM 1.
Undefine a pre-defined symbol. The complement of -D.
Request the linker to produce a symbol file, for usewith the debugger.
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.
Strip local symbols from any files compiled, assembled or linked. Only global symbols will remain.
Request the linker to produce a link map.
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.
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.
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.
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 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.
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.
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.
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 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.
Like -1 but for the 80286 and 68020.
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 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:

The Z80 assembler.
The 8086 assembler.
The linker
The library maintainer
Object to hex converter
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.