Compiling

From RAD Studio
Jump to: navigation, search

Go Up to Delphi Compiler

Project > Options > Building > Delphi Compiler > Compiling

Use this page to set the compiler options for the current project.

Note: Not all of the options described here are available for all types of projects. For example, DCP output directory does not appear for C++ projects.
Options Description

Target, Apply, Save

See Target Options.

Common items

See Common Items on Project Options Pages.

Code Generation Options

Item Description Compiler switches All platforms supported unless noted

Code inlining control

Sets or clears the Delphi compiler directive {$INLINE <ON|OFF|AUTO>}. For more information, see "Using the Inline Directive" in Calling Procedures and Functions (Delphi).

Default = off

‑‑inline

Code page

Enter the code page for the language of your application, such as 1252. Code page is a decimal number representing a specific character encoding table, and there are standard values for various languages.

Default = 0

‑‑codepage

Emit run-time type information

Controls generation of run‑time type information. The default value is False (no run‑time type information is emitted).

Default = False

‑$M+
‑$M‑

Minimum enum size

Specifies the smallest amount of memory to be allocated for an enum. Choices are Byte {$Z1}, Word {$Z2}, Double Word {$Z4}. The Down Arrow pop-up button is described in Common Items on Project Options Pages.

Default = Byte

‑$Z1
‑$Z2
‑$Z4

Optimization

Controls code optimization. When enabled (equivalent to {$O+}), the compiler performs a number of code optimizations, such as placing variables in CPU registers, eliminating common subexpressions, and generating induction variables. When disabled, (equivalent to {$O-}), all such optimizations are disabled.

Other than for certain debugging situations, you should never have a need to turn optimizations off. All optimizations performed by the Delphi compiler are guaranteed not to alter the meaning of a program. In other words, the compiler performs no "unsafe" optimizations that require special awareness by the programmer. This option can only turn optimization on or off for an entire procedure or function. You cannot turn optimization on or off for a single line or group of lines within a routine.

Default = False

‑$O+
‑$O‑

Record field alignment

Controls alignment of fields in Delphi record types and class structures. Click the down-arrow to select from the possible values:

  • If you select option Off (equivalent to {$A1}) or disable the option (equivalent to {$A-}), fields are never aligned. All record and class structures are packed.
  • If you select Byte (equivalent to {$A2}), fields in record types that are declared without the packed modifier and fields in class structures are aligned on byte boundaries.
  • If you select Word (equivalent to {$A2}), fields in record types that are declared without the packed modifier and fields in class structures are aligned on word boundaries.
  • If you select Double Word (equivalent to {$A4}), fields in record types that are declared without the packed modifier and fields in class structures are aligned on double-word boundaries.
  • If you select Quad Word (equivalent to {$A8} or {$A+}), fields in record types that are declared without the packed modifier and fields in class structures are aligned on quad word boundaries.

Regardless of the state of the $A directive, variables and typed constants are always aligned for optimal access. Execution is faster if you set the option to 8 (Quad Word).
This is the default.

‑$A‑
‑$A1
‑$A2
‑$A4
‑$A8
‑$A+

Stack frames

Controls the generation of stack frames for procedures and functions.

When enabled, (equivalent to {$W+}), stack frames are always generated for procedures and functions, even when they are not needed.

When disabled, (equivalent to {$W-}), stack frames are only generated when they are required, as determined by the use of the routine of local variables. Some debugging tools require stack frames to be generated for all procedures and functions, but other than that you should never have a need to enable this option.
Default = True

‑$W+
‑$W‑

  • 32‑bit Windows
  • 64‑bit Windows
  • macOS 

Debugging Options

Item Description Compiler switches All platforms supported unless noted

Assertions

Enables or disables the generation of code for assertions in a Delphi source file. The option is enabled (equivalent to {$C+}) by default. Since assertions are not usually used at run time in shipping versions of a product, compiler directives that disable the generation of code for assertions are provided. Deselect this option to disable assertions.

‑$C+
‑$C‑

Debug information

Debugging information consists of a line-number table for each procedure, which maps object-code addresses into source text line numbers. For units, the debug information is recorded in the unit file along with the object code of the unit. Debug information increases the size of unit file and takes up additional memory when compiling programs that use the unit, but it does not affect the size or speed of the executable program. When a program or unit is compiled with this option enabled (equivalent to {$D+}), the integrated debugger lets you single-step and set breakpoints in that module.

The Place debug information in separate TDS file and Map file options (on the Linking page of the Project Options dialog) produce complete line information for a given module only if you have compiled that module with this option set on. This option is usually used in conjunction with the Local symbols option (the {$L} switch), which enables and disables the generation of local symbol information for debugging.

‑V ‑VN

Local symbols

Enables or disables the generation of local symbol information. Click the down-arrow to select from the possible values (True, False).

Local symbol information consists of the names and types of all local variables and constants in a module, that is, the symbols in the implementation part of the module and the symbols within the procedures and functions of the module. For units, the local symbol information is recorded in the unit file along with the object code of the unit. Local symbol information increases the size of unit files and takes up additional memory when compiling programs that use the unit, but it does not affect the size or speed of the executable program. When a program or unit is compiled with this option enabled (equivalent to {$L+}), the integrated debugger lets you examine and modify the module's local variables.

Furthermore, calls to the module's procedures and functions can be examined by using View > Debug Windows > Call Stack. The Place debug information in separate TDS file and Map file options (on the Linking page of the Project Options dialog) produce local symbol information for a given module only if that module was compiled with this option set on. This option is usually used in conjunction with the Debug information option, which enables and disables the generation of line-number tables for debugging. This option is ignored if the compiler has the Debug information option disabled.

‑$L+
‑$L‑

Symbol Reference info

Generates symbol reference information used by the Code Editor and the Project Manager. Corresponds to the Delphi compiler directive {$Y}.

  • If None is selected ({$Y-}), no symbol reference information is recorded.
  • If Definitions only is checked ({$YD}), the compiler records information about where identifiers are defined.
  • If Reference info is checked ({$Y+}), the compiler records information about where each identifier is defined and where it is used.

This option has no effect unless Debug information and Local symbols (see above) are enabled.

Code completion and code navigation features (Ctrl+Click) work only when Symbol Reference info is set to Reference info.

‑$Y+
‑$YD
‑$Y‑

Use debug .dcus

The debug DCUs contain debug information and are built with stack frames. When this option is checked, the compiler adds the debug DCU path to the search paths specified in Debug Source Path on the Embarcadero Debuggers page.

Use imported data references

Enables packaged units to reference variables in other packages. Equivalent to Delphi compiler directive {$G}.

‑$G+
‑$G‑

  • 32‑bit Windows
  • 64‑bit Windows
  • macOS 

Other Options

Item Description Compiler switches All platforms supported unless noted

Additional options to pass to the compiler

Enter compiler switches that you want to add to the settings controlled by the Project > Options dialog boxes. Use a hyphen as the switch symbol, and separate switches with commas.

Code completion in uses clause also checks .dcus

Code Completion (Ctrl+Space) is a Code Insight feature available in the Code Editor, which makes it easy to complete your code.

Note: It also works with .pas and .dcu files. This feature can be disabled when you want on a per-platform level, in the Project Options.

When you request code completion within a uses section, there are two modes available:

  • Mode 1: List units where only the corresponding .pas file is in the search path.
  • Mode 2: List units where only the .dcu file is located in the search path. This might be the case when working with third-party libraries.

If you uncheck the option "Code completion in uses clause also checks .dcus", then you switch to mode 1. This is useful in environments where the search path contains directories with a lot of DCUs incompatible with the current platform.

For example:

You develop your App for Win32 and MacOS. On both platforms, the search path contains a lot of directories that hold Win32 DCUs. When your current platform is MacOS, you request "uses completion"; then you don't want to see the Win32 units, turn off suggesting DCUs on MacOS.

Allow unsafe code

The term "unsafe" derived from .NET, where "unsafe" meant "not managed", that is, code that accesses memory directly instead of through "managed" code and data structures. "Managed" code and data structures in the .NET environment are not likely to be able to experience memory corruption or resource leaks. Since Assembly statements are neither typed nor "managed" and almost always access memory directly, they are invariably seen as "unsafe" by .NET standards. Of course, Assembly code is safe when written correctly.

Three warnings about unsafe code exist in Delphi so that code can be shared more easily between Win32 and .NET. If messages about unsafe code are not relevant to you, you can disable the warnings on the Hints and Warnings page of the Project Options dialog.

See:

‑P

  • macOS 

Generate XML documentation

Generates a file containing the XML representation in your project directory. For more information, see XML Documentation for Delphi Code.
Default = False

‑‑doc

Look for 8.3 filenames also

Passes the -P compiler switch for DCC32.exe or DCC64.exe.

Default = False

Enables you to use old-style DOS file names that are in the format filename.ext, where filename is 1-8 characters long.

Supported on 32‑bit Windows and 64‑bit Windows platforms.

‑P

  • 32‑bit Windows
  • 64‑bit Windows

Output unit dependency information

Passes the -depends compiler switch for DCC32.exe. Default = False

Causes the Delphi command-line compilers to generate a text file with a ".d" file extension. The generated ".d" files will list all .dcus, unit file names for the project (and all dependencies), including the path names.

Note: This option is only applicable to the command-line compiler, to get a dependency generated for a project in the IDE it is necessary to specify "Use MSBuild externally to compile" as true.

‑‑depends

Require $IF to be terminated by $IFEND

Enables you to use $IFEND (instead of the proper $ENDIF) to terminate a $IF clause. Without this option enabled, the compilers might emit E2029. See the Legacy IFEND (Delphi) compiler directive.

Default = False

‑‑legacy-ifend

XML documentation output directory

Specifies the folder where the XML documentation for your project will be generated. See the Generate XML documentation option above.

‑NX

Generate Android 32-bit and 64-bit application bundle (armeabi-v7a + arm64-v8a)

The compiler creates an application bundle containing both 32-bit and 64-bit Android binaries. Default = False (only 64-bit binary is created).

  • 64‑bit Android

Generate macOS universal binary file (x86_64 + arm64)

The compiler creates a universal binary file for both 64-bit Intel macOS and 64-bit ARM macOS. Default = False (only 64-bit ARM binary is created).

  • macOS ARM 64‑bit 

Run‑time Errors Options

Item Description Compiler switches All platforms supported unless noted

I/O checking

Enables or disables the automatic code generation that checks the result of a call to an I/O procedure. If an I/O procedure returns a nonzero I/O result when this switch is on, an EInOutError exception is raised (or the program is terminated if exception handling is not enabled). When this switch is off, you must check for I/O errors by calling IOResult.
Default = True

‑$I+
‑$I‑

Overflow checking

Controls the generation of overflow checking code. When enabled (equivalent to {$Q+}), certain integer arithmetic operations (+, -, *, Abs, Sqr, Succ, Pred, Inc, and Dec) are checked for overflow. The code for each of these integer arithmetic operations is followed by additional code that verifies that the result is within the supported range. If an overflow check fails, an EIntOverflow exception is raised (or the program is terminated if exception handling is not enabled). This switch is usually used in conjunction with the range checking option (the {$R} switch), which enables and disables the generation of range-checking code. Enabling overflow checking slows down your program and makes it somewhat larger.

Default = True

Note: Setting this option to true might cause a drop in performance while debugging.

‑$Q+
‑$Q‑

Range checking

Enables or disables the generation of range-checking code. When enabled (equivalent to {$R+}), all array and string-indexing expressions are verified as being within the defined bounds, and all assignments to scalar and subrange variables are checked to be within range. If a range check fails, an ERangeError exception is raised (or the program is terminated if exception handling is not enabled). Enabling range checking slows down your program and makes it somewhat larger.

Default = True

Note: Setting this option to true might cause a drop in performance while debugging.

‑$R+
‑$R‑

Syntax Options

Item Description Compiler switches All platforms supported unless noted

Assignable typed constants

Controls whether typed constants can be modified or not. When enabled (equivalent to {$J+}), typed constants can be modified, and are in essence initialized variables. When disabled (equivalent to {$J-}), typed constants are truly constant, and any attempt to modify a typed constant causes the compiler to report an error. Writeable consts refers to the use of a typed const as a variable modifiable at run time.

Old source code that uses writable typed constants must be compiled with this option enabled, but for new applications it is recommended that you use initialized variables and compile your code with the option disabled.

Default = False

‑$J+
‑$J‑

Complete boolean evaluation

Switches between the two different models of Delphi code generation for the AND and OR Boolean operators. When enabled (equivalent to {$B+}), the compiler generates code for complete Boolean expression evaluation. This means that every operand of a Boolean expression built from the AND and OR operators is guaranteed to be evaluated, even when the result of the entire expression is already known. When disabled (equivalent to {$B-}), the compiler generates code for short-circuit Boolean expression evaluation, which means that evaluation stops as soon as the result of the entire expression becomes evident in left to right order of evaluation.

Default = False

‑$B+
‑$B‑

Extended syntax

Provided for backward compatibility. You should not use this option (equivalent to {$X-} mode) when writing Delphi applications. This option enables or disables Delphi extended syntax:

Function statements. In the {$X+} mode, function calls can be used as procedure calls; that is, the result of a function call can be discarded, rather than passed to another function or used in an operation or assignment. Generally, the computations performed by a function are represented through its result, so discarding the result makes little sense. Sometimes, however, a function is called because it performs a task such as setting the value of a global variable, without producing a useful result.

The Result variable. When enabled (equivalent to {$X+}, the predefined variable Result can be used within a function body to hold the function's return value.

Null-terminated strings. When enabled, Delphi strings can be assigned to zero-based character arrays (array[0..X] of Char), which are compatible with PChar types.

Default = True

‑$X+
‑$X‑

Long strings by default

This option (equivalent to the {$H} directive) controls the meaning of the reserved word string when used alone in a type declaration. The generic type string can represent either a long, dynamically-allocated string (the fundamental type UnicodeString) or a short, statically allocated string (the fundamental type ShortString). By default, Delphi defines the generic string type to be the long UnicodeString.

All components in the component libraries are compiled in this state. If you write components, they should also use long strings, as should any code that receives data from component library string-type properties. The disabled (equivalent to {$H-}) state is mostly useful for using code from versions of Delphi that used short strings by default. You can locally override the meaning of string-type definitions to ensure generation of short strings. You can also change declarations of short string types to string[255] or ShortString, which are unambiguous and independent of the enabled option.

Default = True

‑$H+
‑$H‑

  • 32‑bit Windows
  • 64‑bit Windows
  • macOS 

Open parameters

Meaningful only for code compiled supporting huge strings, and is provided for backwards compatibility with early versions of Delphi and Object Pascal. This option, (equivalent to the {$P} directive) controls the meaning of variable parameters declared using the string keyword in the huge strings disabled (equivalent to {$H-}) state. When disabled (equivalent to {$P-}), variable parameters declared using the string keyword are normal variable parameters, but when enabled (equivalent to {$P+}), they are open string parameters. Regardless of the setting of this option, the OpenString identifier can always be used to declare open string parameters.

Default = True

‑$P+
‑$P‑

Strict var-strings

This option (equivalent to the {$V} directive) is meaningful only for Delphi code that uses short strings, and is provided for backwards compatibility with early versions of Delphi and Object Pascal. The option controls type on short strings passed as variable parameters. When enabled (equivalent to {$V+}), strict type is performed, requiring the formal and actual parameters to be of identical string types. When disabled (equivalent to {$V-}) (relaxed), any short string type variable is allowed as an actual parameter, even if the declared maximum length is not the same as that of the formal parameter.

Default = True

‑$V+
‑$V‑

Typed @ operator

Controls the types of pointer values generated by the @ operator and the compatibility of pointer types. When disabled (equivalent to {$T-}), the result of the @ operator is always an untyped pointer (Pointer) that is compatible with all other pointer types. When @ is applied to a variable reference in the enabled (equivalent to {$T+}), the result is a typed pointer that is compatible only with Pointer and with other pointers to the type of the variable. When disabled, distinct pointer types other than Pointer are incompatible (even if they are pointers to the same type). When enabled, pointers to the same type are compatible.

Default = False

‑$T+
‑$T‑


Tip: To display the compiler options in the Messages window when you compile a project, choose Tools > Options > IDE > Compiling and Running and select Show command line. The next time you compile a project, both the command used to compile the project and the response file are displayed in the Messages window. The response file lists the compiler options and the files to be compiled.


Attention: RAD Studio checks the amount of memory the IDE compiler uses, and when it exceeds 60% of the total available memory, the compiler flushes the unit cache. By default, is it set to 60%, but on certain systems this percentage is too high and causes the IDE to crash or to lock up.

To modify the 60% threshold, use the registry setting and follow the steps below:

  1. Shut down the IDE.
  2. Run regedit, and go to the following key; HKEY_CURRENT_USER\Software\Embarcadero\BDS\22.0\Compiling
  3. Create a new DWORD value called “ProcMemAllocLimit” and set the value to 50 (decimal).
  4. Shut down regedit
  5. Start the IDE.

See Also