Root > Basic procedures > Configuring project itself

Configuring project itself

Previous pageReturn to chapter overviewNext page   

This article is a part of basic procedures.

 

 

How to differentiate between development and production builds

Default project configuration in modern IDEs has 3 build configurations defined:

Base build configuration
Debug build configuration
Release build configuration

The supposed meaning is:

1. Using the Debug build configuration for developing;
2. Using the Release build configuration for production.

 

 

Default build configurations

 

You can also check current build configuration in your source code:

 

{$IFDEF DEBUG}
ShowMessage('Development build');
{$ELSE}
ShowMessage('Production build');
{$ENDIF}

 

We recommend to follow that approach.

 

See also: EurekaLog does not work when compiling "Release" profile in C++ Builder.

 

Note: if you are using old IDE without build configurations support - the alternative way would be to create two projects, which will include the same set of units and share the same project source (.dpr file). Assign one project to be a development project, and second project to be a production project. The example below would use modern IDE as an example.

 

Important: do not forget to make a full project rebuild (not just compile) when you have switched active build configuration.

 


 

Short Answer

You can improve detalization of your bug reports by selecting the proper project options. This articles explain various project options related to debugging and a recommended choices.

 

1. Be sure that EUREKALOG conditional symbol is defined (it is usually set automatically when you add EurekaLog to your project);

 

2. Ensure there are no {$D-} compiler directives in your source code (or linked include files) - these will disable debug information for your code;

 

3. Clear .map, .tds, .dcu, .obj, .a files of your project;

 

4. Set up mandatory options (these are usually enabled automatically by the EurekaLog IDE wizard):
[Delphi] Enable:
o"Compiler" / "Debug information"
o"Linker" / "Map file" = "Detailed".
[C++ Builder] Enable:
o"C++ Compiler" / "Enable exceptions"
o"C++ Compiler" / "Debugging" / "Debug information"
o"C++ Compiler" / "Debugging" / "Debug line number information"
o"C++ Linker" / "Full debug information" (32-bit only, see notes below)
o"C++ Linker" / "Output" / "Map file" = "Detailed segment map".

 

5. Set up recommended options:
[Delphi] Enable:
o"Compiler" / "Stack frames"
o"Compiler" / "Range checking"
o"Compiler" / "Use Debug DCUs"
o"Compiler" / "Overflow checking"
o"Linking" / "Place debug information in separate TDS file"
[Delphi] Disable:
o"Packages" / "Runtime Packages" / "Link with runtime packages"
[C++ Builder] Enable:
o"C++ Compiler" / "Standard stack frames"
o"C++ Compiler" / "Use 'classic' Borland compiler"
oCodeGuard for you application (some options may conflict with EurekaLog)
[C++ Builder] Disable:
o"C++ Linker" / "Link with Dynamic RTL"
o"C++ Linker" / "Link with the Delphi RTL"
o"C++ Linker" / "Output" / "Map with mangled names"
o"Packages" / "Runtime Packages" / "Link with runtime packages"

 

7. Make a full project build (not just compile/make): "Project" / "Build All".

 

 

Note: exact options names and locations depend on your IDE version. The specific option may be called differently or be located in other place in your IDE.

 

Important: if you are linking with the run-time packages - we highly recommend to remove EurekaLogCore package from the run-time packages list. Linking with the EurekaLogCore package is designed for special use cases, it should not be used in generic cases.

 

Notes:

1. EurekaLog requires .map file to be present. It uses the .map file to compile debug information and inject it inside your executable. Therefore, linking options of your project must enable map file generation. Usually, EurekaLog does that automatically, otherwise it will be completely useless.
2. Additionally, .map will contain only information that is available in precompiled files. Therefore, debug information for the compiler must be enabled too, otherwise info about your source code will not go into .map. Using debug version of RTL/VCL (the "Use Debug DCUs" option) will add line numbers for RTL/VCL into .map file (and therefore into EurekaLog too).
3. [C++ Builder] Important: C++ Builder's .map file does not contain any line numbers whatsoever:
a. [C++ Builder, 32 bit] EurekaLog uses Turbo Debugger debug information (aka TD32 info) to restore line numbers for C++ Builder projects. That is why generation of TD32 info should be enabled in your linker options.
b. [C++ Builder, 64 bit] 64-bit C++ Builder does not use TD32. It is build on entirely new framework: LLVM, which uses DWARF debug format. Currently EurekaLog is unable to use this information.

 


 

Long Answer

We can give a recommendations for different use cases. These recommendations are written down below. Settings which differs from defaults are marked in bold (i.e. you should toggle items in bold manually).

 

EurekaLog-enabled application

1. BASE SETTINGS FOR EACH BUILD CONFIGURATION

All debug options ("Debug information" (Compiler), "Local symbols", "Reference info") should be definitely turned on. Otherwise, call stack functionality won't be working;
There is no need to turn off "Stack Frames" option - turn it ON;
Generation of map-file should be turned ON;
o[C++ Builder Only] Disable the "Map with mangled names" option.
Disable using run-time packages (when possible);
oIf you are building with run-time packages - remove EurekaLogCore package from the list (highly recommended);
[C++ Builder Only] Disable "Link with Dynamic RTL" (when possible);
[C++ Builder Only] Enable "Use 'classic' Borland compiler" option (when possible);
[C++ Builder Only] Enable "Include TD32 debug info" (aka "Linker" / "Full Debug Information").
[C++ Builder Only] Follow this guide.

 

2a. DEBUG BUILD CONFIGURATION (Local Debugging)

"Use Debug DCUs" - set it as you like;
Turn ON "Range checking" and (optionally) "Overflow checking";
"Include remote debug info" - enable it only if you want to use remote debugger.

 

2b. RELEASE BUILD CONFIGURATION (Production)

Turn ON "Use Debug DCUs" option;
Set "Range checking", "Overflow checking" as you like;
Turn off "Include remote debug info".

 

Note: if you don't do many index-based operations (so additional checks will not slow down your code) - then it may be a good idea to always keep "Range checking" on.

 

Note: your code or 3rd party code (i.e.: non-standard components) may use compiler directives in source code, which affect the options above. For example, a component may have {$D-} directive inside its .pas units to exclude itself from debugging. Obviously, doing so will prevent EurekaLog from getting descriptions for this component. You may need to change the source code and edit/remove such directives.

 

 

Usual application (without EurekaLog)

1. BASE SETTINGS FOR EACH BUILD CONFIGURATION

All debug options ("Debug information" (Compiler), "Local symbols", "Reference info") does not affect the resulting application and do not disturb us - so you usually should keep them always on;
"Use Debug DCUs" - set it as you like (depending on: "do you want to debug standard Delphi code or not?");
There is no need to turn on "Stack Frames" option - turn it off;
There is no need for map-files - turn it off.

 

2a. DEBUG BUILD CONFIGURATION (Local Debugging)

"Use Debug DCUs" - set it as you like;
Turn ON "Stack Frames", "Range checking" and (optionally) "Overflow checking";
"Include TD32 debug info" - enable it only if you use "Attach to process" while debugging;
"Include remote debug info" - enable it only if you want to use remote debugger.

 

2b. RELEASE BUILD CONFIGURATION (Production)

Turn off "Stack Frames", "Range checking", "Overflow checking", "Include TD32 debug info" and "Include remote debug info".

 


 

Detailed explanation of options

Note: we'll talk about project options in this article. We will not talk about EurekaLog project options. You can open project options via "Project" / "Options" IDE menu command.

 

Warning: please, remember that you need to make a full build (and not just "compile"), if you change any of these options.

 

We're interested in "Compiling" and "Linking" pages:

 

 

Compiling page (Delphi)

 

 

C++ Compiler/Debugging page (C++ Builder)

 

On "Compiling" page, we are interested in:

Debug information + Local Symbols + Symbol reference info (Delphi only)
Debug information + Debug line number info (C++ Builder only)
Stack Frames (Delphi only)
I/O Checking (Delphi only)
Overflow checking (Delphi only)
Range checking (Delphi only)

 

 

Linking page (Delphi)

 

 

C++ Linker page (C++ Builder)

 

 

C++ Linker/Output page (C++ Builder)

 

On "Linking" page, we are interested in:

Map file
(Full) Debug Information (this option is known as "Include TD32 debug info" in old IDE versions)
Map with mangled names (C++ Builder only)
Include remote debug symbols (Delphi only)

 

 

What do these options mean?

The most important settings are set of options "Debug information" ("Compiling" page).

 

The program is array of machine's (CPU) instructions - which are just bytes (numbers). The source code is a text file. The question: how does the debugger know, when he needs to stop, when you are setting a breakpoint in your source? Where is correspondence between raw numbers and human-readable text?

 

This correspondence is a debug information. Roughly speaking, the debug information is set of instructions like: "the machine codes no. 1056-1059 correspond to line 234 of Unit1". The debugger works thanks to such debug info.

 

And these options? They controls the generation of debug information for your units.

 

The debug information is stored in dcu-files together with its compiled code. I.e. the very same Unit1.pas can be compiled into different dcu-files (with or without debug information). The debug information increases compilation time, size of dcu-files, but it does not affect size or speed of resulting application (i.e. debug information is not included into application).

 

There are cases, when you want to have debug information in your files or (at least) near them. For example: if you are going to do remote debugging or debugging of external process. OR if you want to have human-readable call-stack in your exception diagnostic tool (EurekaLog).

 

EurekaLog takes care of injecting debug information into your executable. This work is performed by IDE expert or command-line compiler.

 

However, project options affects detalization of debug information. So, you need to set project options properly to maximize result.

 

Let's do a short overview what these options do (see also: Compiling page and Linking page in Delphi's help and C++ Compiler page and C++ Linker page in C++ Builder's help). Most important options are marked in bold.

 

"Debug information" – that is the debug info itself. You should enable this option if you want to do step-by-step debugging or have call stacks with names. EurekaLog IDE expert enables this option automatically for you. But don't forget to enable it, if you don't use IDE expert.
"Local symbols" (Delphi only) – it is "addon" for usual debug information. This is correspondence between program's data and variables names in source code. You need to enable this option if you want to see and change variables. Also, call stack window in Delphi can display function's arguments with this option.
"Reference info" (Delphi only) – this is additional information for code editor, which allows him to display detailed information about identificators. For example: where were a variable declared.
"Debug line number info" (C++ Builder only) - it is "addon" for usual debug information. It adds information about line numbers in source files. EurekaLog IDE expert enables this option automatically for you. But don't forget to enable it, if you don't use IDE expert.

 

Those options are very close related and usually there is no need to enable or disable only one of them - they are switched together.

 

"Use Debug DCUs" (Delphi only) - this very important option switches compilation between using debug and release versions of standard Delphi's units. If you were attentive, then you could notice that real pas-files in Delphi's Source folder are never used during compilation. Instead, the precompiled files (in dcu) are used. They are taken from Lib or Lib\Debug folders. This trick greatly decreases compilation time. Because dcu can be compiled with and without debug information - there are two sets of dcus in Lib folder. By toggling this option you'll specify which one Delphi should use for you. If you switch this option off - then you won't be able to debug standard Delphi code or see detailed call stack for it. EurekaLog doesn't enable this option for you, because it seriously alters debugging experience - you should enable this option manually for release production.
"Stack Frames" (Delphi only) - this option controls stack frames generation. If the option is off then stack frames won't be generated unless they are needed. If the option is on - then stack frames will be generated always. Stack frames are used for frame-based stack-tracing method. I.e. it is used for building call stack. In usual application stack frames are generated almost everywhere.
"Range checking" (Delphi only) - this is a very useful helper for debugging problems with array-based structures. With it, compiler will insert additional checks (for strings, arrays, etc), which checks the correctness of indexes. If you (by mistake) pass an invalid index - the exception of type ERangeError will be generated. And you can find your error. If the option is off then there is no additional code. Enabling this option slightly increases size of your application and slows down it execution. It is recommended to turn this option for debugging only. CodeGuard can serve as alternative to this option in C++ Builder.
"Overflow checking" (Delphi only) - it is somehow similar to "Range checking", except checking code checks overflows in arithmetic operations. If result of operation is not suitable for storage variable - then exception EIntOverflow will be raised. For example: we have a byte variable, which holds 255 now. And we add 2 to it. There should be 257, but it can not be stored in byte variable, so real result will be 1. That is integer overflow.
"I/O Checking" (Delphi only) - this option is used for working with "files in Pascal-style" (AssignFile, Reset, etc).
"Map file" - by enabling this option you tell the Delphi's linker to create a separate .map file along with your executable. Map file contains human-readable representation of debug information. Different settings for this option controls the detalization level of output. Usually, there is no need to change it to anything, which differs from "Off" or "Detailed". The map-file is used by various tools as primary source of debug information. For example, EurekaLog automatically turns this option on and uses map-file to create a debug information in its own format and then injects it into application. That is why you rarely need to change this option manually.
"Debug Information" (Linker page, new Delphi)/"Include TD32 debug info" (old Delphi)/"Full debug information" (C++ Builder) - this option embeds debug information for external debugger in TD32 format into your application. You may need this option if you use "Run"/"Attach to process" and Delphi can not find debug information. Also, EurekaLog uses TD32 info to complete missing information in C++ Builder. Note, that size of your Delphi application can increase 5-10 times by enabling this option (C++ Builder writes information in separate .tds file), unless you enable "Place debug information in separate TDS file" option.
"Include remote debug symbols" - very similar to previous option, but this creates a rsm-file with debug information for Delphi remote debugger. You need this option, if you want to do remote debugging.

 

Note: some of these options can be enabled not only globally, but also separately for each unit (several options can affect single routines or, even, lines of code). This is done by using usual compiler directives (you can see them in help). For example, "Stack Frames" is controlled by {$W+} and {$W-} and Debug information from Compiling page is controlled by {$D+} and {$D-}.

 

 

See also:




Send feedback... Build date: 2023-09-11
Last edited: 2023-09-06
PRIVACY STATEMENT
The documentation team uses the feedback submitted to improve the EurekaLog documentation. We do not use your e-mail address for any other purpose. We will remove your e-mail address from our system after the issue you are reporting has been resolved. While we are working to resolve this issue, we may send you an e-mail message to request more information about your feedback. After the issues have been addressed, we may send you an email message to let you know that your feedback has been addressed.


Permanent link to this article: https://www.eurekalog.com/help/eurekalog/configuring_project_itself.php