Root > Basic procedures > Configuring project itself

Configuring project itself

Previous pageReturn to chapter overviewNext page   

This article is a part of basic procedures.

 

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.

 

Short answer:

1. To solve problems with non-working, partial or misleading call stack - clear .map, .tds and .dcu files of your project and be sure to:
(Delphi) enable "Compiler"/"Debug information", "Linker"/"Map file" = "Detailed".
(C++ Builder) enable "C++ Compiler"/"Debugging"/"Debug information", "C++ Compiler"/"Debugging"/"Debug line number information", "C++ Linker"/"Full debug information", "C++ Linker"/"Output"/"Map file" = "Detailed segment map".

 

2. To increase help level of EurekaLog:
(Delphi) enable "Compiler"/"Stack frames", "Compiler"/"Range checking" and "Compiler"/"Use Debug DCUs" options and make "Project"/"Build all".
(C++ Builder) disable "C++ Linker"/"Output"/"Map with mangled names" option, enable CodeGuard for you application (some options may conflict with EurekaLog).

 

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.

 

For best results it's recommended to disable packages in application (if possible) and turn off dynamic RTL - C++ only (if possible).

 


 

Long answer:

 

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, that 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-}.

 

So, we can give a recommendations for different use cases by summarizing all this info. These recommendations are written down below. Settings which differs from defaults are marked in bold (i.e. you should toggle items in bold manually).

 

 

Usual application, without EurekaLog

 

1. BASE SETTINGS FOR EACH PROFILE

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 PROFILE

Turn ON "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 PROFILE

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

 

 

EurekaLog-enabled application

 

1. BASE SETTINGS FOR EACH PROFILE

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, but EurekaLog's expert takes cares of it.
Generation of TD32 information should be turned ON for C++ Builder, but EurekaLog's expert takes cares of it.

 

2a. DEBUG PROFILE

"Use Debug DCUs" - set it as you like.
Turn ON "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 PROFILE

Turn ON "Use Debug DCUs" option.
Turn off "Range checking", "Overflow checking", "Include TD32 debug info" and "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.

 

 

See also:




Send feedback... Build date: 2018-11-26
Last edited: 2018-06-14
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