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.