2.1 Command-line options of C--
--------------------------------
Format for calling C-- from the command line:
C-- [options] [ini file] [source file]
If the source file is specified without the file extension, the compiler
will search for files ending in .c--, .cmm, or .c.
Parameters are always preceded by '/' or '-'.
Options can be inverted by ending them with a '-'.
Supported options:
/0 use only commands recognized by 8086/8088 processors (the
default when compiling 16-bit programs).
/1 use commands for the 80186
/2 use commands and optimization for the 80286
/3 use commands and optimization for the 80386 (default for 32-bit
programs)
/4 use commands and optimization for the 80486
/5 use commands and optimization for the Pentium
/6 use commands and optimization for the Pentium MMX
/7 use commands and optimization for the Pentium Pro
/8 use commands and optimization for the Pentium II
/9 use commands and optimization for the Pentium III (not yet
implemented due to lack of information)
/A data aligned to an even-numbered address, done by default,
supports inversion
/AC align address of the beginning of loops, by default turned off,
supports inversion, makes sense only for Pentium or later
/AL=## set the value of the fill byte for aligning data, by default 0
/AP align the address of the beginning of functions, by default
turned off, supports inversion, makes sense only for Pentium or
later
/ARGC insert a command-line selection block, by default turned off,
supports inversion
/AS alignment in strucrutes by default turned off, supports
inversion
/AT insert an ATEXIT support block, by default turned off, supports inversion
/C insert a CTRL<C> ignore block, by default turned off, supports
inversion makes sense only for DOS
/CRI check included files for repeated loading, by default turned
on, supports inversion
/CPA clear post-area data
/D32 create an *.exe file (32-bit code under DOS); the default is a *.com file
/D=<idname> define an identifier for conditional compilation, the default is none
/DBG generate debugging information, by default do not
/DE temporary expansion size type after multiplying
is it by default unplugged, supports inversion
/DLL create a .dll file for Windows 32; the default is a .com file
/ENV save the address of the environment variables
/EXE create an .exe file for DOS ('small' model); the default is a .com file
/HELP /H /? print this help file to the screen
/IA names of assembler instructions are identifies, by default
turned off, supports inversion
/IND=<name> import names from the file 'name'
/IP=<path> specify the path where included files should be sought, by default none
/IV initialize all variables, by default turned off, supports
inversion
/J0 do not make initial jump to main(),
by default turned off, supports inversion
in .com files does not create a jmp to main. In other files no
initial program initialization block is created, and control
passes at once to main.
/J1 do a short jump to main(),
by default do not do so, makes sense only for .com files
/J2 do a near jump to main()
by default do not do so, makes sense only for .com files
/LAI list supported assembler instructions
/LRS load numeric constants onto the stack,
by default turned on, supports inversion
/LST show an assembler listing
/MEOS create a MeOS .exe file; the default is a .com file
/MER=## set the maximum number of errors, by default 16
/MIF=<file> specify the name of the main file to be compiled
/NS do not link stub files,
by default turned off, supports inversion
/NW=## selectively turn off warnings
/OBJ create an .obj file, 16-bit code only; the default is a .com file
/OC optimize for code size
by default do not, supports inversion
/ON optimize for numbers
by default do not, supports inversion
/OS optimize speed of execution,
by default turned on, supports inversion
/OST optimize identifier strings,
by default turned off, supports inversion
/P insert a command-line parsing block
by default turned off, supports inversion
/R insert an available-memory-size reducing block by default
turned on, supports inversion makes sense only for DOS
/S=##### to install size of stack
by default 2048
/SA=#### initial offset in address for running program, makes sense only
in .com files, by default 0x100
/SOBJ create a slave OBJ file
by default COM
/STM set the startup code block to the main function,
by default turned off, supports inversion
makes sense only for DOS
/SUV=#### initial address of uninitialized variables, for their use by
startup code, makes sense only in .com files, default is /SA
/SYM superstructure for COM file, by default .COM
/SYS create devices drivesr (SYS), by default .com
/TEXE create an .exe file for DOS (TINY model), by default .com
/UL use lea when optimizing register addition
by default turned on, supports inversion
/UST use startup code for variables by default turned off, supports
inversion, makes sense only for .com files
/W permit warnings, by default turned off, supports inversion
/W32 produce an .exe file for Windows32 GUI version, or by default a
.com file
/W32C create an .exe for Windows32 console version, or by default a
.com file
/WBSS place uninitialized data into a separate section, permitted
by default for /W32, forbidden for other operating systems,
supports inversion
/WF=<file> redirect output of warnings to a file.
by default no
/WFA use fast calls to API functions
by default turned on, supports inversion
only under Windows
/WFU create a table of transpositions (for Windows32)
by default turned off, supports inversion
only for Windows,
for a .dll file is set to 'TRUE'.
/WIB=##### set address of image base by default 0x400000
/WMB create a Windows file with a single block
by default turned on, supports inversion
only for Windows,
for DLL is fixed in no
/WORDS list reserved identifiers
/WS=name indicates the filename used as stub under windows.
/X do not insert a SPHINXC-- signature into the code,
by default do insert one, supports inversion, turned off
is there is a J0
Note: 'Supports inversion' means that the opposite of a particular
option can be written as the option followed by '-':
Example:
/WFA-
Command-line options may be written in upper or lower-case letters.
2.1.1 /ON - optimize numeric expressions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Option /ON on the command line or in C--.ini tells the compiler to
analyze operations on numbers and where possible to reduce the number of
operations. For example:
Before optimization | After optimization
-----------------------------------------------
AX = var + 7 - 3; | AX = var + 4;
AX = var * 2 * 5; | AX = var * 10;
AX = var * 2 / 4; | AX = var / 2;
AX = var * 10 / 2; | AX = var * 5;
AX = var / 2 / 3; | AX = var / 6;
AX = var / 4 * 8; | AX = var * 2;
AX = var / 16 * 16; | AX = var;
Possible problems:
Use of such optimization can cause problems, for instance if
a variable must be aligned to a paragraph margin you would write
var = var / 16 * 16;
but after optimization this would become:
var = var;
i. e., there will be no alignment. This can be avoided by splitting
this expression into two expressions:
var = var / 16;
var = var * 16;
which avoids optimization. More compact code can be obtained by writing:
AX = var;
AX = AX / 16;
AX = AX * 16;
var = AX;
2.1.2 /DE - temporarily increase variable size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As we know, multiplication can lead to overflow, i. e., the size of
the result can be greater than the size of the operands, and the result
will be misrepresented. You can avoid this problem in part by using the
command-line option /DE or the line DE in C--.ini. On encountering a
multiplication command, the compiler will look at the rest of the line
and, if it finds that an increase in size is necessary (division and
calculation of a remainder may require an increase in size), measures
will be taken to preserve it. For example:
a = b*c+d/e; // support of size increase is turned on here
a = b*c+d*e; // no support of size increase is needed here
This option can, however, also cause its own problems. For example:
for the expression
a = b * c / d;
if b = 0xC000, c = 0x1000, and d = 0x10, after this program begins to
run, it will depend on receiving a report on whether there was overflow
during division.
2.1.3 /ARGC - use alternate command-line handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command-line handler differs from 'parsecommandline' in that
when calling PARAMSTR(0) it gives the address of the line specifying the
path and the name of the program being run. Subsequent calls to this
function with an increasingly larger parameter will return the addresses
of words in the command line, while calls to PARAMCOUNT will return the
number of words in the command line plus one.
An alternate command-line handler is switched on using the directive
'?argc TRUE,' or from the command line by the keyword '/argc', or by the
line 'argc' in c--.ini.
2.1.4 /OST - merge identical string constants
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If this optimization mode is activated, the compiler will remember
all string constants, and when it detects identical ones, a second copy
of the string constant will not be inserted into the file code, but
reference will be made to the first string constant which was already
detected. Optimization involves only un-named string constants, i. e., if
an array or structure is initalized by a string this string will not
participate in initialization, since this string may be changed while the
program is running. For example:
char var="test"; //this string will not participate in optimization.
void proc(){
WRITESTR("test"); // this string will participate in optimization.
AX="test"; // the variable AX will be assigned the address of the string,
// which was inserted in the program code in
// the previous line.
}
The compiler will warn of cases where a repeated string is found.
This optimization mode is switched on by the directive '#pragma
option ost', by '/ost' on the command line, or by the line 'ost' in
c-.ini.
2.1.5 /D - predefine identifier as TRUE from command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you have written a program which can be compiled in several ways
depending on the state of certain identifiers (using the condition
compilation mode) you may find this option useful. By setting defining
different identifiers from the command line, you can obtain different
variants of the program without editing the source code.
The identifier is entered from the command line using the keyword
'/d=idname'.
2.1.6 /IA - use simplified assembler input
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is now possible to use assembler instructions without the prefix
'$' and outside of an asm block. This mode is switched on by the
directive '#pragma option ia', on the command line by '/ia', or by the
line 'ia' in c--.ini.
When this mode is switched on, all names of assembler instructions
become reserved words, i. e., these names may not be used as names of
variables or functions. The compiler recognized assembler instructions
written in lower or upper case.
2.1.7 /CRI - skip file included more than once
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Usually there is no need to repeatedly include a file in a project to
be compiled, but this may sometimes happen because several included files
themselves include other files. In order to avoid this, it used to be
necessary to check for repeated loading of a file, but now the compiler
does this automatically.
Sometimes (very rarely) you may want to include the same file more
than once, using the command line option '/cri-', which prevents the
compiler from checking for repeated inclusion. You can also use '#pragma
option cri-' as a directive in the compiled file, or 'cri-' in c--.ini.
2.1.8 /IND - import function names from DLL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to use a DLL without a file header describing the
function in some program, the compiler can import names from this DLL.
Just specify the name of this library using the command-line option
'/ind=name.dll', the line 'ind=name.dll' in the c--.ini, or the directive
'#pragma option ind=name.dll'.
A drawback of this method of obtaining names is that during
compilation there must always be a program library on disk from which to
import names. Furthermore, if the names in the library are written
without the suffix @number, the compiler will not check the number of
options of the functions being transferred. Unfortunately the compiler
can import from libraries only .exe files in Windows PE format.
2.1.9 /WS - specify name of stub file for programs under Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Windows programs have a DOS 'stub' which is used to transfer control
when running the program in DOS mode. Usually this stub displays
information to the effect that the program must be run under Windows.
Instead of a standard stub you can use the program's own stub. This
requires specifying either a 16-bit .exe filename or using the command
line option '/ws=filename', or the line 'ws=filename' in the .ini file,
or the directive '#pragma option ws=filename'.
This lets you create programs that will run under both DOS and
Windows.
2.1.10 /WBSS - locate uninitialized data in a separate segment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The .bss segment is automatically created when programs are compiled
with the keyword '/w32'. In order to also create this section for
programs compiled with '/w32c' or '/dll', add '/wbss' to the command
line, or the line 'wbss' to the .ini file, or use the directive '#pragma
option wbss'.
Use of a .bss segment has little effect on the size of the output
file. In theory, for processors with a separate data cache, the use of a
.bss segment should increase program speed.
2.1.11 /DBG - create debugging information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adding '/dbg' to the command line or 'dbg' to the .ini file will
cause the compiler, after compilation, to create a file with debugging
information. The file has the name of the main module followed by the
file extension .tds.
Debugging information created by C-- is compatible with that created
by Borland compilers, but this information is not yet complete. It is,
however, sufficient for doing a simple debugging.
To debug 16-bit DOS programs use Turbo Debugger from Borland C v4.5
or later (td.exe).
To debug Windows programs use the 32-bit debugger (td32.exe).
Turbo Debugger cannot be used for 32-bit programs with a DOS
extender, as far as I know. Write me if you know how to do this with
Borland compilers and I will include it in C--.
2.1.12 /J0 /J1 /J2
~~~~~~~~~~~~~~~~~~~
A synonym of the keywords /J0 /J1 /J2 is the directive '#jumptomain'
with options 'NONE', 'SHORT', and 'NEAR', respectively.
'#jumptomain' acts slightly differently depending on the type of
output file.
Compilation of .com or .exe file with 'tiny' memory model:
#jumptomain NONE (or /J0) - in this case, after the end of the startup
code, a jmp to main is not generated. This directive should be used if
there are no other non-dynamic functions or initialized variables before
main.
#jumptomain SHORT (or /J1) - in this case, after the end of the startup
code, a short jmp to main is generated. This directive should be used if
there are more than 128 bytes of code and data before main.
#jumptomain NEAR (or /J2) - the default. A near jmp to main is generated.
Compiling .exe files (keywords -exe -d32 -w32 -w32c)
#jumptomain NONE (/J0) - in this case startup code is not generated and
control is transferred immediately to main.
In all other cases startup code is generated and control is transferred
to main via the instruction 'call'.
Compiling .dll files:
#jumptomain NONE (-j0) - in this case no startup code is generated and
control is transferred immediately to main.
In all other cases the stub code and control are not transferred to main,
which is not even needed here.
When creating .dll files main should look a bit different than in other
cases:
dword main ( dword hInstDLL, reason, reserv )
{
...
}
2.1.13 /LST - create assembler listing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The command-line option '-lst' can be used to obtain the assembler
listing along with an .exe file. The listing is written to a file of the
same name as the .exe file but with file extension .lst.
The assembler listing is created independently of the compiler by a
part of the code using information gathered during program compilation.
2.1.14 /ENV - save address of environment variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If during compilation /ENV is added to the command line or /ENV to
the .ini file, the compiler will add to the program the variable
'environ', which stores the address of environment variables when the
program is run. For Windows programs this will be the complete address,
and for other OS's only the segment address.
2.1.15 /CPA - clear post-area data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Variables not assigned any value in a program body are not included
in the body of the compiled program. Memory outside the program is
reserved for them, but this memory can be filled by any data.
If uninitialized variables must always have only one value (null)
when a program is run, use the command-line option /CPA or -CPA.
2.1.16 /W - output warnings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default the compiler does not output warnings, and many people
don't even suspect that there is such a useful option. In C-- warnings
are actually suggestions for creating improved programs and frequently
make it easier to debug the program. These warnings can tell you where
short forms of the operators IF, WHILE, FOR, etc. can be used, or which
functions,variables and structures defined in your program remain unused.
They can let you know which registers the compiler used without your
knowledge, and give other useful information.
Warnings are printed to screen by default, but there may be too many
to fit on one screen. There is thus an option to print the warnings to a
file, the name of which is specified in the option. Place the following
two lines into your c--.ini file:
w
wf=warning
and the warnings will be written to file 'warning'.
2.1.17 /NW - selectively switch off types of warnings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The compiler at present outputs 12 types of warnings, and sometimes
there are so many of them that it becomes difficult to make sense of
them. You can now selectively switch off warnings by adding to the
command line or to c--.ini the option '/nw=number', where number is a
number from 1 to 12, corresponding to the following types of warnings:
1 - Optimize numerical expressions
2 - ... has been used by compiler
3 - Short operator '...' may be used
4 - String '...' repeated
5 - Expansion variable
6 - Signed value returned
7 - '...' defined above, therefore skipped.
8 - Variable/structure/function '...' possible not used
9 - Non-initialized variable may have been used
10 - Return flag was destroyed
11 - Code may not be executable
12 - Don't use local/parametric values in inline functions
2.1.18 /WSI - short table import
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Table import usually consists of four tables. The lookup table and
the import address table are identical.
Command-line option '/WSI' forces the compiler to generate only one
of these tables (import address table), producing a more compact import
address table, which in some cases results in the creation of a more
compact output file.