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.