Debug information page - EurekaLog Documentation

This is "Debug information" page in EurekaLog project's options.

Debug information options

Options on "Debug information" page allow you to customize EurekaLog's debug information options.

1. "Debug information" option indicate if debug information info should be added. Debug information is necessary to build a human-readable call-stack and get textual descriptions of code's locations.

•	"Do not add/inject EurekaLog debug information": use this value if you plan to use debug information in other format. Do not forget to add/enable the corresponding debug info provider;

•

"Add EurekaLog debug information": use this value to create the .edbg file. EurekaLog will be activated only when .edbg file is present. This value is also useful when IDE debugger is unable to recognize the modified executable. Or you can use it for post-processing digitally signed/protected executables (see also).

•	"Inject EurekaLog debug information" (default): use this value for most usage cases (recommended). This value will produce self-contained executable.

2. "Strip embedded non-EurekaLog debug info" option would remove non-EurekaLog debug information from your executables. Examples of stripped debug information are: TDS (TD32), DWARF.

This is useful, if you plan to distribute the file to your end users. In that case you want your file have EurekaLog and EurekaLog's debug information, but do not need other debug information, which you are likely to use during debugging from IDE.

Checked: remove (strip) debug information in formats like TDS/TD32, DWARF, etc. We recommend to enable this option for production (e.g. Release build configuration).

Unchecked: do nothing. Disable this option for local debugging (development, e.g. Debug build configuration).

Notes:

•

Enabling this option may significantly decrease size of a compiled executable, because EurekaLog will remove very large debug information data block. Please note that you may lose ability to debug your executable in your IDE (local debugging). Enabling this option should not change/affect behavior of EurekaLog in your executables, because EurekaLog uses its own debug information format (by default).

•	Do not enable this option if you are using EurekaLog with disabled EurekaLog debug information - e.g. when the "Debug information" option (see above) is set to the "Do not add/inject EurekaLog debug information" value. Otherwise EurekaLog will have no debug info to work with.

•	Consider disabling additional debug info providers when this option is enabled.

3. "Compress debug information" option will pack (compress) EurekaLog's options and debug information before injecting it into executable.

Enabling this option will produce smaller executables, but will add post-processing time (used for compression) and longer startup time (used for decompression).

Disable this option to get faster post-processing and startup, but significantly larger executables.

Memory footprint may vary depending on your actual data. We recommend to check memory usage with both positions.

Note: if your project is extremely large - then we recommend to disable "Check file for corruption" option too. Otherwise, CRC check may take too long for larger executables.

Here is a sample data: a 40 Mb executable has about 22 Mb .map file. This .map file is processed by EurekaLog to produce a total of 7 Mb (uncompressed) debug information, which consists of:

•	2 Mb of symbol names (e.g. unit names, class names, routines names);

•	4 Mb of procedures records

•	1 Mb of unit and lines records

This debug information can be compressed into 3.5 Mb, therefore difference between uncompressed and compressed debug information is 4.5 Mb, meaning:

•	"Compress debug information" option enabled: 43.5 Mb .exe

•	"Compress debug information" option disabled: 47 Mb .exe

4. "Cache symbols names on load" option will cache symbol names in memory (RAM). Symbol names are human-readable unit names, class names, routines names. If this option is disabled then symbol names will be saved to disk. A small memory cache will still be used to cache names stored on disk.

Enabling this option will increase memory usage (to store cache), but will improve run-time performance, because names will be copied from memory, no disk access required.

Disabling this option will decrease memory usage, but will also decrease run-time performance due to disk access to read (load) individual symbol names.

We recommend to disable this option for larger projects. On smaller project this option does not make much difference.

Note: this option has no effect if "Compress debug information" option is disabled, because debug information will be stored in executable in a ready to use form, there will be no need to decompress it.

In the example above (see description for "Compress debug information" option): names information occupies 2 Mb for 40 Mb .exe.

5. "Store all names" option is a default behavior. It will save all symbols names in injected debug information: units names, classes names, routines names.

This option provides the best detalization.

"Store all names" option is used

We recommend to use this option when possible. Only use the following two options for shareware-like applications.

6. "Store unit names only" option disables storing names of classes, methods, functions and procedures inside executables. Unit names and line numbers are still saved.

Enable this option to minimize executable size and increase shareware protection.

Disable this option for best detalization.

Important Note: Be aware that class and routine names are lost forever!

"Store unit names only" option is used

See Searching bug's location article for more information. See this article for more information about using line offsets.

7. "Store all names externally" option will completely remove all names from injected debug information. All names will be stored in a new file, which has same name as your project, but with *.elsym extension.

Note: this option disables "Debug information encryption password" option below, because no names will be stored inside executable (e.g. nothing to encrypt).

Important Note: Be aware that your executable will no longer be self-sufficient!

When this option is enabled:

•	EurekaLog will not store any symbol names in your executable;

•	Symbol names will be offloaded to a standalone file with *.elsym extension;

The file is placed into %APPDATA%\Neos Eureka S.r.l\EurekaLog\Symbols\ folder, for example: C:\Users\UserName\AppData\Roaming\Neos Eureka S.r.l\EurekaLog\Symbols\41C93167855F44A388459CD68A452E49_Project138.exe_2017_11_16_00_34.elsym. This folder is used as common database to store symbols for all compiled executable. EurekaLog Viewer will use this location to find a matching .elsym file when viewing a report without names. A compilation ID (41C93167855F44A388459CD68A452E49 in the example above) is used as prefix. It is used for searching. The rest of file name (Project138.exe_2017_11_16_00_34 in the example above) is used only for your convenience - for example, to locate and delete unnecessary files. It is not used for searching and could be deleted (e.g. 41C93167855F44A388459CD68A452E49.elsym is sufficient);

Additionally, for your convenience, a copy of this file is placed to output folder - for example, C:\Projects\Win32\Debug\Project138.elsym for C:\Projects\Win32\Debug\Project138.exe. You can deploy Project138.elsym file to target machines if you want to have readable names on the target machine. This is optional, you don't have to deploy .elsym files for your executable to work.

Hint: you can check IDs by using EurekaLog PE Analyzer tool included with EurekaLog:

PE Analyzer tool will show you ID of the project (stays unchanged)

and ID of the build / compilation (changes on each recompile)

Summary:

•	Do not deploy .elsym files to your customers (names will be not available)

•	Keep collection of .elsym files in your %APPDATA% on your developer's machine (for Viewer)

•	[Optionally] You can deploy .elsym file to selected machines (names will be available)

Important Note: A new *.elsym file is created in %APPDATA%\Neos Eureka S.r.l\EurekaLog\Symbols\ folder for each compilation. If you compile a lot - this folder will grow in size fast. You have to manage it by yourself. For example, you can delete unnecessary files, keeping only *.elsym files for your public releases (e.g. you have to track your compilation IDs for your releases). Or you can enable "Store all names externally" option only when you are compiling a public build. See also: Different EurekaLog settings for Debug and Release build configurations.

Note: you will see symbol names unencrypted when running executable on developer machine by default, because *.elsym file will be present.

Anyway, EurekaLog's-enabled executable will load symbol names from a matching .elsym file (assuming it was found).

"Store all names externally" option is used and the matching .elsym file is present

If no .elsym file was found - EurekaLog will not be able to display symbol names. Instead, the report is encoded for further completion.

"Store all names externally" option is used and the matching .elsym file is NOT present

Such report can be loaded into EurekaLog Viewer, which will be able to decode it and load all missed symbols (again, assuming that Viewer can find a matching .elsym file). For this reason - you have to keep a copy of .elsym file in the above mentioned %APPDATA% folder, so Viewer can find it.

Note: a note for shareware developers: while names for missing .elsym case may look like they are encrypted - it is not. No real symbol name is stored inside executable, therefore there is nothing to encrypt. The "encrypted" text simply encodes the IDs of the symbol name, such as: 41C93167855F44A388459CD68A452E49 and 172110. This is compilation ID and symbol index. This is what was encoded. No real symbol name was used.

8. "Debug information encryption password" option specifies optional password to encrypt all names in the injected debug information. EurekaLog uses TEA cipher to encrypt all debug information. This option can be combined with "Store all names" option or "Store unit names only" option.

If you set this option - you will not be able to view call stacks and assembly info in bug reports, it will be encrypted. To view encrypted report - you must use EurekaLog Viewer tool and specify password.

Use this option if you don't want for end-users to view information about your executable.

"Debug information encryption password" option is set

Note: you will see symbol names unencrypted when running executable on developer machine by default. Passwords are cached on developer's machine at HKEY_CURRENT_USER\Software\EurekaLab\Viewer\7.0\Passwords and HKEY_CURRENT_USER\Software\EurekaLab\Viewer\7.0\Hashes. A project ID is used for identification. See "Presaved password" option below.

Notes:

•

While it looks very similar to "Store all names externally" option - it is very different. In case of "Debug information encryption password" option - call stack actually encrypts real symbol names (such as Button1Click), which can be decrypted if password is known. E.g. real symbol names will be stored in your executable (in encrypted form).

•	Executable will be self-sufficient, no additional external files will be created.

•	When combined with "Store unit names only" option: class and routines names will be filled with dummy values.

•	This option has no effect is "Store all names externally" option is enabled.

•	Empty password does not mean that debug information will be injected in clear text. It still will be encrypted (with default password). Empty password just allows you to view this information in error dialogs and bug reports in clear text. Non-empty password will prevent that.

•

You can also supply a valid password to application at run-time to decrypt debug information on the go. When valid password is supplied - call stack in bug report and dialog will be displayed as clear text, even though debug information will still be stored encrypted. Currently there are three methods to specify decryption password at run-time:

EurekaLog automatically caches debug information passwords on your developer machine (that is - on PC which was used to edit/save settings with password). That way call stacks will always be decrypted on your developer machine, because EurekaLog will retrieve decryption password from cache. Running your application on any other machine (e.g. production, clients, etc.) will show encrypted call stacks, because no decryption password is available. See also "Presaved password" option below.

o	Use OnPasswordRequest event. You can either ask user, read registry, or return hard-coded password (however, do not hard-code passwords for production!).

o	Use --el_password=your-password command-line option when launching your application.

Hint: caching passwords on developer's machine means that you can use large, complex, random passwords without having to memorize it.

9. "Presaved password" option enables local password cache on current machine. This option is global, not project-specific, and is not stored in project options.

Checked: Enable local password cache. Encrypted executables will run as unencrypted.

Unchecked: Disable local password cache. Encrypted executables will run as encrypted.

This option does not affect compiled executables. E.g. password-protected executables are always compiled as encrypted. We recommend to enable local cache to simplify local debugging. Disable local cache for testing purposes.

Note: this option have no effect if debug information password is not set.

10. "Trade memory for speed" option controls how ecc32/emake post-process your executable. This option does NOT affect your compiled executable.

Enabling this option will use more memory during post-processing, but post-processing will be faster. It is recommended for smaller projects.

Disabling this option will use less memory during post-processing, but post-processing will be slower. It is recommend for extremely large projects (e.g. when you have out of memory errors).

Root > Integral parts > Options > Features page > Debug information page Debug information page