External tools - EurekaLog Documentation

This is "External tools" page in EurekaLog project's options.

External tools options

Options on "External tools" page allow you to customize EurekaLog behavior for integration with other 3rd party software. This page contains options from other pages.

1. "Reduce file size" option removes relocation table from file. This reduces file's size for about 10% (however, enabling EurekaLog also increases file's size).

It's recommended to always keep this option on.

Note: this option have no effect for DLL and packages. It is also ignored for executables marked with ASLR.

Technical explanation

When you compile a DLL (or a package which is a Delphi-specific DLL in disguise), the linker includes what is known as a relocation table. This table includes information about what addresses must be fixed up by the OS loader in the (likely) event that the DLL must be loaded at a different address than its intended-at-compile/link-time base address. You see, all DLLs come with a base address that is the "ideal" loading address of that module. The OS will try to load the DLL at this address to avoid the overhead of runtime rebasing (patching the in-memory pages of the DLL forces it to be paged in from disk and prevents cross-process sharing of the DLL pages). That's why you should set the Image base option in the Linker page of the project options of DLL and package projects. The default Image base that Delphi uses is $00400000 for both applications, DLLs and packages - and thus by default all DLLs and packages will need to be rebased - as that address is reserved for the process' EXE file.

The implication is that an EXE file will always be loaded at the fixed virtual address $00400000 and that it will never need to be rebased. Alas, it doesn't really need its relocation table and we can safely remove it, shrinking the size of the .EXE without affecting its behavior or performance.

2. "Check file corruption" option adds check for file corruption in your project. If you enable this option, EurekaLog will calculate a CRC checksum of the compiled file and store it inside file. EurekaLog will also read this checksum from file on its startup (launch). If your executable was modified, EurekaLog will display an appropriate message and shutdown your application immediately:

EurekaLog detected changes in executable file

You can use this option to ensure that your code wasn't modified.

Notes:

•	CheckSum field in the IMAGE_OPTIONAL_HEADER structure is used to store CRC value inside executable file;

•	This option checks file on disk, not running process image;

•	Enabling this option will slow down loading and startup times on your executable. The bigger your executable file will be - the larger will be startup time: because the entire file must be read at startup;

•	Disabling "Compress debug info" option will produce a significantly larger executables, therefore significantly increasing CRC check time. Therefore, we do not recommend to enable "Check file corruption" option and disable "Compress debug info" option at the same time.

Turn off for digitally signed files, packers or protectors.

3. "Use speed optimizations" option enables caching of kernel information to improve performance of stack tracing.

Turn off for packers and protectors.

Note: this option will be automatically disabled when "Detalization level" option is set to "Show any (including RAW addresses)" or "Show any item belong to executable module (unknown locations within DLL)" value.

It is recommended to keep this option unchecked unless you suffer from slow work of your application.

4. "Delay call stack creation until handle stage" option postpones analyzing exception for later stages of processing.

Please, see this article for detailed explanation of delayed (deferred) call stacks.

Enable this option for better performance.

Disable this option for better detalization and compatibility.

Note: enabling some advanced features of EurekaLog (such as handling safecall exceptions, using exception filters with "Exception Kind" <> "All", etc.) may require creating call stack earlier than usual (for example: to detect if exception is raised within safecall wrapper), so this option will have no effect.

5. "Handle every SafeCall exception" option is used to catch safecall-exceptions with EurekaLog. This option is useful in COM servers, COM applications and other interface-related code.

When this option is off - safecall exceptions will be handled by default processing which usually means losing information about error location.

When this option is on - safecall exceptions will be handled by EurekaLog and then by default processing.

Usually it's a good idea to disable error dialogs and visual feedback for safecall exceptions since these exception will be handled by calling code (which will display error message).

Notes:

•	Each safecall exception is considered to be handled exception. Keep that in mind when you setup exception filters or write event handlers.

•	This option has no effect if "Catch handled exceptions" option is enabled (see below).

•	This option requires extended memory manager enabled.

•	It's a good idea to include fix for QC report #81725 when you use "Handle every SafeCall exception" option.

•

Internally, "Handle every SafeCall exception" option installs hook for ComObj.HandleSafeCallException routine (when low-level hooks are allowed) or scans exception's call stack for _HandleAutoException routine (when low-level hooks are not installed). The later can cause building call stack for all exceptions even with "deferred call stacks" option set.

Alternative for this option is to invoke EurekaLog manually from your SafeCallException handler.

See also:

•	Using EurekaLog in COM applications

6. "Catch handled exceptions" option will enable EurekaLog for all exceptions. By default EurekaLog processes only exceptions which are unhandled (see handled/unhandled terms definitions).

It's not recommended to use this option. That's because "handled" for exception means that this exception is expected and it was handled by code. Therefore, it's better to setup proper exception handling in your code. This option is used primary as last resort measure to work with "bad" code (the code which hides unhandled exceptions).

Be sure to setup proper exception filtering when you enable this option. Often it's a good idea to disable error dialogs and visual feedback for handled exceptions.

Notes:

•	You should use "Handle every SafeCall exception" option for safecall-exceptions instead of "Catch handled exceptions" option.

•	This option requires extended memory manager enabled.

7. "Capture stack only for exceptions from current module" (.csoCaptureOnlyModuleExceptions) option allows you to speed up execution by ignoring all exceptions outside of your executable module.

Since normal practice for exceptions is to handle them within the same module - exceptions usually do not leave module (i.e. they are not shared between modules). This means that you're usually interested only in exceptions from the same module. This option allows you to ignore any other exception.

Note: this option is extremely useful in applications with plug-ins (including COM modules).

It's recommended to keep this option checked when possible. Disable this option for packaged applications or other project types which includes sharing exceptions between modules.

8. "Low-level injection hooks" option allows or forbids using of low-level hooks. Low-level hooks use code injection (e.g. overwrite machine code with JMP CPU instruction).

Using low-level hooks allows EurekaLog to act automatically. Otherwise, you need to call EurekaLog manually. Additionally, using low-level hooks allows you to capture low-level information such as CPU state. Low-level hooks are also required for additional WER functionality.

It is recommended to keep this option enabled when possible. Disable it only for special cases.

Important Note: We do not recommend to change this option from default value ("Allow all") when compiling with LLVM.

Low-level hooks in external modules ("Allow all" or "Allow for external modules only"):

•	Installs hook for KiUserExceptionDispatcher (Windows 2000 only; Windows XP and above: EurekaLog uses VEH (Vectored Exception Handling)): allows EurekaLog to react on exceptions and collect CPU state;

•	Installs hook for CreateThread/ExitThread:

o	allows EurekaLog to automatically track threads (see note below);

o	allows EurekaLog to produce better multi-threading reports (e.g. indicate thread's creator, etc.);

•	Installs hook for RaiseException:

o	allows EurekaLog to better track non-Delphi exceptions (see also "Capture stack only for exceptions from current module" option);

o	allows EurekaLog to track thread name changes;

o	allows EurekaLog to build proper call stacks for LLVM software exceptions.

Disable this option (set to "Disable all") if you are using software protection tool that monitors integrity of whole process.

Disable this option (set to "Allow for current module only") if you are loading and unloading several DLLs with EurekaLog in a different order (e.g. load A.dll, load B.dll, unload A.dll, unload B.dll).

Disable this option (set to "Allow for current module only") when there are conflicts with 3rd party hooks/exception tracers from external DLLs.

Important Note: Do not disable this option for application build with LLVM. Additionally, EurekaLog will not be able to track threads when this option is disabled. It is recommended to use BeginThreadEx/TThreadEx or (for any other thread) call SetEurekaLogStateInThread function to enable EurekaLog in thread and call EThreadsManager._NotifyThreadGone function to notify EurekaLog about thread's termination.

Low-level hooks in current module ("Allow all" or "Allow for current module only"):

•	Installs hook for TObject.Destroy:

o	allows EurekaLog to track life time of exception objects (only for LLVM and Delphi 2007/C++ Builder 2007 and earlier; Delphi/C++ Builder 2009 and above (without LLVM): EurekaLog uses new SysUtils.Exception class);

o	allows EurekaLog to make better reports for memory errors;

o	allows EurekaLog to catch handled exceptions;

•	Installs hook for HandleSafeCallException: allows EurekaLog to automatically react on safecall exceptions;

•	Installs hook for TComponent.SetName: allows EurekaLog to track component names when reporting memory problems;

•	Installs hook for TThread.Execute: allows EurekaLog to automatically handle exceptions in TThread (obsolete feature);

•	Installs hook for System.@HandleAutoException: allows EurekaLog to fix issue #81725 ("TObject.SafeCallException can be not called in certain cases");

•

Installs various hooks for handle stage - as set in options (for example, VCL.Forms.TApplication.ShowException for VCL Forms application, VCL.SvcMgr.TApplication.DoHandleException for service application, etc.): allows EurekaLog to handle (process) exceptions automatically. Otherwise you will need to call EurekaLog manually.

Disable this option (set to "Allow for external modules only") if you are using software protection tool that monitors integrity of application (current module).

Important Note: Do not disable this option on Delphi/C++ Builder 2007 and earlier. Do not disable this option when compiling with LLVM. Otherwise EurekaLog will not be able to track life time of exceptions.

9. "Customize code hooks" option allows you to select code hooks specific for project type. Disable hooks for packers and protectors.

10. "Configure external tools run" option allows you to specify commands to invoke during building process. You can place a call to external tool (such as packer, protector or debug information converter).

Delphi 2009+: order of actions during project's compilation is as follows:

1.	EurekaLog pre-build event

2.	IDE pre-build event

3.	Project compile and link

4.	IDE post-build event

5.	EurekaLog link (post-processing)

6.	EurekaLog post-build event

Note: you must post-process executable with EurekaLog first, and only after this - you can post-process executable with packer/protector/digital signature tool. On the other hand, debug information converter may be run before or after EurekaLog's post-processing - it doesn't matter (as long as debug information is present and untouched).

11. "Customize debug information providers" option allows you to customize debug information reader classes ("providers"). You may want to enable additional providers to be able read debug information supplied by external tools.

12. "Customize memory manager" option allows you to customize debugging memory manager. It's highly recommended to keep "Enable extended memory manager" option turned on (you can disable other memory checking options if you want to). Installing filter on memory manager will allow EurekaLog to track life-time of exceptions objects without need to install code hooks.

Root > Integral parts > Options > Features page > External tools External tools