The command-line compiler

Delphi's command-line compiler (DCC.EXE) lets you invoke all the functions of the IDE compiler (DELPHI.EXE) from the DOS command line. You run the command- line compiler from the DOS prompt using the following syntax:

DCC [options] filename [options]

options are zero or more optional parameters that provide additional information to the compiler. filename is the name of the source file to compile. If you type DCC alone, it displays a help screen of command-line options and syntax.

If filename does not have an extension, the command-line compiler assumes .PAS. If you don't want the file you're compiling to have an extension, you must append a period (.) to the end of the filename.

If the source text contained in filename is a program, the compiler creates an executable file named filename.EXE, and if filename contains a library, the compiler creates a file named filename.DLL. If filename contains a unit, the compiler creates a unit file named filename.DCU.

You can specify a number of options for the command-line compiler. An option consists of a slash (/) immediately followed by an option letter. In some cases, the option letter is followed by additional information, such as a number, a symbol, or a directory name. Options can be given in any order and can come before and/or after the file name.

Command-line compiler options

The IDE lets you set various options through the menus; the command-line compiler gives you access to these options using the slash (/) delimiter. You can also precede options with a hyphen (-) instead of a slash (/), but those options that start with a hyphen must be separated by blanks. For example, the following two command lines are equivalent and legal:

DCC -IC:\DELPHI -DDEBUG SORTNAME -$S- -$F+ DCC /IC:\DELPHI/DDEBUG SORTNAME /$S-/$F+

The first command line uses hyphens with at least one blank separating options; the second uses slashes and no separation is needed.

The following table lists the command-line options.

Table A-1 Command-line options

/$A+ Align data on word boundaries

/$A- Align data on byte boundaries

/$B+ Complete Boolean evaluation

/$B- Short circuit Boolean evaluation

/$D+ Debugging information on

/$D- Debugging information off

/$E+ 80x87 emulation on

/$E- 80x87 emulation off

/$F+ Force far calls on

/$F- Force far calls off

/$G+ 286 code generation on

/$G- 286 code generation off

/$I+ I/O checking on

/$I- I/O checking off

/$K+ Smart callbacks on

/$K- Smart callbacks off

/$L+ Local debug symbols on

/$L- Local debug symbols off

/$M Memory sizes

/$M+ Run-time type information on

/$M- Run-time type information off

/$N+ Numeric coprocessor on

/$N- Numeric coprocessor off

/$P+ Open parameters on

/$P- Open parameters off

/$Q+ Overflow checking on

/$Q- Overflow checking off

/$R+ Range checking on

/$R- Range checking off

/$S+ Stack checking on

/$S- Stack checking off

/$T+ Type-checked pointers on

/$T- Type-checked pointers off

/$U+ Pentium safe FDIV on

/$U- Pentium safe FDIV off

/$V+ Strict var-string checking

/$V- Relaxed var-string checking

/$W+ Windows stack frames on

/$W- Windows stack frames off

/$X+ Extended syntax support on

/$X- Extended syntax support off

/$Y+ Symbol reference information on

/$Y- Symbol reference information off

/$Z+ Word-sized enumerations

/$Z- Byte-sized enumerations

/B Build all units

/Ddefines Define conditional symbol

/Epath EXE and DCU directory

/Fsegment: offset Find run-time error

/GS Map file with segments

/GP Map file with publics

/GD Detailed map file

/Ipath Include directories

/L Link buffer on disk

/M Make modified units

/Opath Object directories

/Q Quiet compile

/Rpath Resource directories

/Tpath DSL and CFG directory

/Upath Unit directories

/V EXE debug information

If you type DCC alone at the command line, a list of command-line compiler options appears on your screen.

Compiler directive options

Delphi supports several compiler directives, all described in Appendix B, "Compiler directives." The /$ and /D command-line options allow you to change the default states of most compiler directives. Using /$ and /D on the command line is equivalent to inserting the corresponding compiler directive at the beginning of each source file compiled.

The switch directive option

The /$ option lets you change the default state of all of the switch directives. The syntax of a switch directive option is /$ followed by the directive letter, followed by a plus (+) or a minus (-). For example,

DCC MYSTUFF /$R-

compiles MYSTUFF.PAS with range-checking turned off, while

DCC MYSTUFF /$R+

compiles it with range checking turned on. Note that if a {$R+} or {$R-} compiler directive appears in the source text, it overrides the /$R command-line option.

You can repeat the /$ option in order to specify multiple compiler directives:

DCC MYSTUFF /$R-/$I-/$V-/$F+

Alternately, the command-line compiler lets you write a list of directives (except for

$M), separated by commas:

DCC MYSTUFF /$R-,I-,V-,F+

Note that only one dollar sign ($) is needed.

In addition to changing switch directives, /$ also lets you specify a program's memory allocation parameters using the following format:

/$Mstacksize,heapsize

where stacksize is the stack size and heapsize is the size of the Windows local heap area in the data segment. The values are in bytes, and each is a decimal number unless it is preceded by a dollar sign ($), in which case it is assumed to be hexadecimal. So, for example, the following command lines are equivalent:

DCC MYSTUFF /$M16384,4096 DCC MYSTUFF /$M$4000,$1000

Note that, because of its format, you cannot use the $M option in a list of directives separated by commas.

The conditional defines option

The /D option lets you define conditional symbols, corresponding to the {$DEFINE symbol} compiler directive. The /D option must be followed by one or more conditional symbols separated by semicolons (;). For example, the following command line

DCC MYSTUFF /DIOCHECK;DEBUG;LIST

defines three conditional symbols, iocheck, debug, and list, for the compilation of MYSTUFF.PAS. This is equivalent to inserting

{$DEFINE IOCHECK}

{$DEFINE DEBUG}

{$DEFINE LIST}

at the beginning of MYSTUFF.PAS. If you specify multiple /D directives, you can concatenate the symbol lists. Therefore,

DCC MYSTUFF /DIOCHECK/DDEBUG/DLIST

is equivalent to the first example.

Compiler mode options

A few options affect how the compiler itself functions. These are /M (Make), /B (Build), /F (Find Error), /L (Link Buffer) and /Q (Quiet). As with the other options, you can use the hyphen format. Remember to separate the options with at least one blank.

The make (/M) option

The command-line compiler has a built-in MAKE utility to aid in project maintenance. The /M option instructs command-line compiler to check all units upon which the file being compiled depends.

A unit will be recompiled if

• The source file for that unit has been modified since the unit file

  was created.

• Any file included with the $I directive, any .OBJ file linked in

  by the $L directive, or any .RES file referenced by the $R directive, is newer than the unit file.

• The interface section of a unit referenced in a uses statement

  has changed. Units in DELPHI.DSL are excluded from this process.

If you were applying this option to the previous example, the command would be

DCC MYSTUFF /M

The build all (/B) option

Instead of relying on the /M option to determine what needs to be updated, you can tell command-line compiler to update all units upon which your program depends using the /B option. You can't use /M and /B at the same time.

If you were using this option in the previous example, the command would be

DCC MYSTUFF /B

The find error (/F) option

When a program terminates due to a run-time error, it displays an error code and the logical segment address, (segment: offset) at which the error occurred. By specifying that address in a /Fsegment: offset option, you can locate the statement in the source text that caused the error, provided your program and units were compiled with debug information enabled (via the $D compiler directive).

In order for the command-line compiler to find the run-time error with /F, you must compile the program with all the same command-line parameters you used the first time you compiled it.

As mentioned previously, you must compile your program and units with debug information enabled for the command-line compiler to be able to find run-time errors. By default, all programs and units are compiled with debug information enabled, but if you turn it off, using a {$D-} compiler directive or a /$D- option, the command-line compiler will not be able to locate run-time errors.

The link buffer (/L) option

The /L option disables buffering in memory when unit files are linked to create an

.EXE file. Delphi's built-in linker makes two passes. In the first pass through the unit files, the linker marks every procedure called by other procedures. In the second

pass, it generates an .EXE file by extracting the marked procedures from the unit files.

By default, the unit files are kept in memory between the two passes; however, if the

/L option is specified, they are read again from disk during the second pass. The default method is faster but requires more memory; for very large programs, you may have to specify /L to link successfully.

The quiet (/Q) option

The quiet mode option suppresses the printing of file names and line numbers during compilation. When the command-line compiler is invoked with the quiet mode option

DCC MYSTUFF /Q

its output is limited to the sign-on message and the usual statistics at the end of compilation. If an error occurs, it will be reported.

Directory options

The command-line compiler supports several options that allow you to specify the six directory lists used by the command-line compiler: DSL & CFG, EXE & DCU, Include, Unit, Resource, and Object.

Excluding the EXE and DCU directory option, you can specify one or multiple directories for each command-line directory option. If you specify multiple directories, separate them with semicolons (;). For example, this command line tells the command-line compiler to search for Include files in C:\DELPHI\INCLUDE and D:\INC after searching the current directory:

DCC MYSTUFF /IC:\DELPHI\INCLUDE;D:\INC

If you specify multiple directives, the directory lists are concatenated. Therefore,

DCC MYSTUFF /IC:\DELPHI\INCLUDE /ID:\INC

is equivalent to the first example.

The DSL & CFG Directory (/T) option

DCC looks for two files when it is executed: DCC.CFG, the configuration file, and DELPHI.DSL, the resident library file. The command-line compiler automatically searches the current directory and the directory containing .EXE file. The /T option lets you specify other directories in which to search. For example, you could say

DCC /TC:\DELPHI\BIN MYSTUFF

If you want the /T option to affect the search for the .CFG file, it must be the very first command-line argument, as in the previous example.

The EXE & DCU directory (/E) option

This option lets you tell the command-line compiler where to put the .EXE and unit files it creates. It takes a directory path as its argument:

DCC MYSTUFF /EC:\DELPHI\BIN

You can specify only one EXE and DCU directory.

If no such option is given, the command-line compiler creates the .EXE and unit files in the same directories as their corresponding source files.

The include directories (/I) option

Delphi supports include files through the {$I filename} compiler directive. The /I

option lets you specify a list of directories in which to search for include files.

The unit directories (/U) option

When you compile a program that uses units, the command-line compiler first attempts to find the units in the DELPHI.DSL file. If they cannot be found there, the command-line compiler searches for unit files in the current directory. The /U option lets you specify additional directories in which to search for units.

The resource directories (/R) option

DCC searches for resource files in the current directory. The /R option lets you indicate additional directories where DCC should look for resource files.

The object files directories (/O) option

Using {$L filename} compiler directives, Delphi lets you link in .OBJ files containing external assembly language routines, as explained in Chapter 20, "Linking assembler code." The /O option lets you specify a list of directories in which to search for such

.OBJ files.

Debug options

The command-line compiler has two command-line options that enable you to generate debugging information: the map file option and the debugging option.

The map file (/G) option

The /G option instructs the command-line compiler to generate a .MAP file that shows the layout of the .EXE file. Unlike the binary format of .EXE and .DCU files, a

.MAP file is a legible text file that can be output on a printer or loaded into the editor. The /G option must be followed by the letter S, P, or D to indicate the desired level of information in the .MAP file. A .MAP file is divided into three sections:

• Segment

• Publics

• Line Numbers

The /GS option outputs only the Segment section, /GP outputs the Segment and Publics section, and /GD outputs all three sections.

For modules (program and units) compiled in the {$D+,L+} state (the default), the Publics section shows all global variables, procedures, and functions, and the Line Numbers section shows line numbers for all procedures and functions in the module. In the {$D+,L-} state, only symbols defined in a unit's interface part are listed in the Publics section. For modules compiled in the {$D-} state, there are no entries in the Line Numbers section.

The debugging (/V) option

When you specify the /V option on the command line, the command-line compiler appends Turbo Debugger-compatible debug information at the end of the .EXE file. Turbo Debugger includes both source- and machine-level debugging and powerful breakpoints including breakpoints with conditionals or expressions attached to them.

Even though the debug information generated by /V makes the resulting .EXE file larger, it does not affect the actual code in the .EXE file, and if it is included, the

.EXE file does not require additional memory.

The extent of debug information appended to the .EXE file depends on the setting of the $D and $L compiler directives in each of the modules (program and units) that make up the application. For modules compiled in the {$D+,L+} state, which is the default, all constant, variable, type, procedure, and function symbols become known to the debugger. In the {$D+,L-} state, only symbols defined in a unit's interface section become known to the debugger. In the {$D-} state, no line-number records are generated, so the debugger cannot display source lines when you debug the application.

The DCC.CFG file

You can set up a list of options in a configuration file called DCC.CFG, which will then be used in addition to the options entered on the command line. Each line in configuration file corresponds to an extra command-line argument inserted before the actual command-line arguments. Thus, by creating a configuration file, you can change the default setting of any command-line option.

The command-line compiler lets you enter the same command-line option several times, ignoring all but the last occurrence. This way, even though you've changed some settings with a configuration file, you can still override them on the command line.

When DCC starts, it looks for DCC.CFG in the current directory. If the file isn't found there, DCC looks in the directory where DCC.EXE resides. To force DCC to look in a specific list of directories (in addition to the current directory), specify a /T option as the first option on the command-line.

If DCC.CFG contains a line that does not start with a slash (/) or a hyphen (-), that line defines a default file name to compile. In that case, starting DCC with an empty command line (or with a command line consisting of command-line options only and no file name) will cause it to compile the default file name, instead of displaying a syntax summary.

Here's an example DCC.CFG file, defining some default directories for include, object, and unit files, and changing the default states of the $F and $S compiler directives:

/IC:\DELPHI\INC;C:\DELPHI\SRC

/OC:\DELPHI\ASM

/UC:\DELPHI\UNITS

/$F+

/$S-

Now, if you type

DCC MYSTUFF

at the system prompt, DCC acts as if you had typed in the following:

DCC /IC:\DELPHI\INC;C:\DELPHI\SRC /OC:\DELPHI\ASM /UC:\DELPHI\UNITS /$F+ /$S- MYSTUFF

A p p e n d i x