Compiler directives are special comments that control the compiler and its behavior, similar to #pragma directives in C++. This chapter discusses compiler directives and lists all the compiler directives Delphi supports.

A directive comment is one whose first character is a dollar sign ($). You can use either kind of Pascal-style comment:

{$AppType GUI}
(*$AppType GUI*)

You cannot use a C++ style comment (//$Apptype) for a compiler directive.

If the first character of a comment is not a dollar sign, the comment is not a compiler directive. A common trick to deactivate or “comment out” a compiler directive is to insert a space or other character just before the dollar sign, for example:

{ $AppType GUI}
(**$AppType GUI*)

Delphi has three varieties of compiler directives: switches, parameters, and conditional compilation. A switch is a Boolean flag: a feature can be enabled or disabled. A parameter provides information, such as a filename or stack size. Conditional compilation lets you define conditions and selectively compile parts of a source file depending on which conditions are set. Conditions are Boolean (set or not set).

The names and parameters of compiler directives are not case-sensitive. You cannot abbreviate the name of a compiler directive. Delphi ignores extra text in the comment after the compiler directive and its parameters (if any). You should refrain from including extra text, though, because future versions of Delphi might introduce additional parameters for compiler directives. Instead of including commentary within the directive’s comment, use a separate comment.

You can combine multiple directives in a single comment by separating them with commas. Do not allow any spaces before or after the comma. If you use a long directive name, it must be the last directive in the comment. If you have multiple long directives, or any parameter directive, you must use separate comments for each one:

{$R+,Q+,C+,Align On}
{$O+,M 1024,40980}

Some directives are global for a project. These directives usually appear in the project’s source file (.dpr file). Some apply only to packages and must appear in the package source file (.dpk file). Other directives apply to the entire file in which they appear. That file can be a project, package, or unit source file. If you use the same project or file directive more than once, Delphi keeps the last one it sees.

Some directives are local in scope. You can enable and disable them multiple times in the same file. A few local directives apply to an entire subroutine, using the directive in force at the end of the subroutine.

Some directives have two names, a single character and a long name. Long names are easier to read, and they are also helpful when the single letter is both a switch and a parameter. For example, the $I switch is equivalent to $IOChecks, and the $I parameter means $Include. By using the long name, you avoid any possibility of mistakes, such as {$I -}, which includes the file named "-" instead of disabling the $I switch (because of the space between the I and the -).

Usually compiler directives appear in the source file, but you can also supply directives on the command line. (See Appendix A, for details.) Most compiler options also have equivalent settings in the project options, so you can set the options in the IDE. These options apply to all the units in the project, but you can override the project options with directives in the unit source files. For your convenience, the IDE also creates a compiler configuration file (.cfg ), which contains roughly the same configuration information, but in a format suitable for use with the command-line compiler.

Using project options in the IDE is convenient. If you do so, be sure to store the Delphi options file (.dof ) with the project’s source files in your version control system. If you are not storing the .dof file with your source files, or if you are selling source code and don’t want to include the .dof files, you should include the compiler options in the source files. Not everyone uses the same options, and several of the options affect the syntax and semantics of the compiler. Without knowing the correct options to use, you cannot recompile most Delphi programs.

Some of the compiler directives apply to C++ Builder, not Delphi. Delphi ignores these directives. C++ Builder uses them to guide how it generates the .hpp file for a Pascal unit.