02 November, 2012

Using EurekaLog with Delphi Personal/Turbo/Starter editions

Borland/CodeGear/Embarcadero has several very limited editions of Delphi and C++ Builder which are designed for beginners and IT hobbyists. This article discusses possible pitfalls in using EurekaLog on these IDEs:
  • Delphi 7 Personal
  • Turbo Delphi/C++Builder Explorer
  • Turbo Delphi/C++Builder Professional
  • Delphi/C++Builder XE/XE2/XE3 Starter


Important Note: please see most recent version of this documentation here.

Common information

EurekaLog installer contains precompiled .dcu and .obj files. These files are used when you compile your applications. Therefore, there is no requirement to has command-line compiler in IDE.

Note: EurekaLog installer also contains .pas files, but they are used only as reference. .pas files are not used for projects compilation by default. Owners of Enterprise (full source-code) edition of EurekaLog can delete .dcu/.obj files and use .pas files instead. Users of Trial and owners of Professional edition are not able to compile .pas files (because they contain only interface sections, but not implementation).

EurekaLog is compiled against the latest service/update pack for each IDE, so be sure to install the latest available update for your IDE before installing EurekaLog. You can get the latest update for your IDE from your EDN account under "My registered user downloads" section.

EurekaLog requires processing of compiled executables (post-processing). Typically this is done by installing IDE extension to handle this issue automatically. See for more info. Therefore your IDE must have ability to install 3rd party extensions.

However, there is a second way to achieve this - by calling EurekaLog command-line tools manually. You don't need to install IDE extensions for this way. More on this below.

There are no limitations on number of supported IDEs in EurekaLog, so you can install EurekaLog for, say, Delphi 7 Personal, Turbo Delphi and Delphi XE3 Starter simultaneously.

Delphi 7 Personal, Turbo Delphi Explorer and Delphi XE3 Starter in EurekaLog installer
This will install all necessary files for the selected IDEs:
  1. Set of precompiled .dcu files for each selected IDE
  2. IDE expert and run-time package for each IDE (.bpl)
  3. Command-line tools for each IDE (ecc32.exe/emake.exe)
  4. Single set of common source files (.pas)

All these files are the same as files for Delphi Professional/Enterprise/Architect/Ultimate. There are no differences in installing EurekaLog for, say, Turbo Delphi and Delphi 2006 Professional.

Notes:
  • Personal, Turbo and Starter IDE's editions can be installed on the single machine.
  • You can not install two Turbo's or two Starter's on the same machine. So, you can not have Delphi and C++ Builder personalities for the same IDE.
  • It's important to not confuse Turbo Explorer and Turbo Professional editions of Delphi and C++ Builder. These IDEs has significantly different limitations for installing EurekaLog.

Turbo Professional and Starter editions

Both Turbo Professional and Starter editions of Delphi and C++ Builder allow to install and use 3rd party IDE extensions. Therefore you don't need any special actions to use EurekaLog in these IDEs. Just install EurekaLog as usual. You will see EurekaLog menu items in IDE. All your project will be post-processed automatically.

Turbo Explorer and Personal editions

Turbo Explorer edition do not allow you to install 3rd party IDE extensions. EurekaLog will install all necessary files (as outlined above), however IDE will refuse to load EurekaLog's IDE expert:

Turbo Explorer refuses to load EurekaLog IDE expert due to licensing limitations
Therefore EurekaLog menu items will be unavailable. Automatic post-processing of your projects (required for EurekaLog to function) will be disabled.

Delphi 7 Personal edition allows you to install 3rd party IDE extensions. However, it lacks required components (.bpl packages) for EurekaLog IDE Expert.

Delphi Personal reports that EurekaLog IDE expert is unable to load due to missing components
(This error message may be confusing, as it reports "missing file" issue as if it is related to EurekaLogExpert.bpl file. This is wrong interpretation: EurekaLogExpert.bpl file exists. This error message says that EurekaLogExpert.bpl is unable to load because its required files are not found - such as soaprtl70.bpl, etc.)

Again, IDE features of EurekaLog will be inaccessible (unless you have missed Delphi 7 .bpl files from somewhere else).

Note: You can remove EurekaLog IDE expert by using "Start/Programs/EurekaLog 7/Manage" menu item and clicking on "EurekaLog 7 without IDE expert" button under your IDE name.

Workaround for Turbo Explorer/Personal editions

The workaround is explained in great details in our help here (specifically, see "Post-processing without (re)compilation" section). Let's do only a quick overview in this article and provide a practical example.

The example will use Delphi 7 Personal, but the same things should be applicable to other IDEs.

First, you need to create a new application and add necessary EurekaLog's units to your application. Use "Project/View Source" command to open .dpr file and add at least EMemLeaks, EResLeaks and ExceptionLog7 units to your uses clause:

Adding EurekaLog code to your project
Important note: order of units is important. These units must be listed first - as shown above.

These are the minimum units for EurekaLog to work correctly. However, you may want to add more units - such as EDialogWinAPIMSClassic for error dialog in MS Classic style, EAppVCL for hooks on Forms unit, EDebugExports to show functions from DLLs in call stacks, ESendAPIMantis to submit bug reports to Mantis bug tracker, etc.

Typical units for VCL forms application
Second, you need to setup project options for debugging. Please see "Configuring project" article. That article will explain what options are required - you should enable them for your project.

Third, you need to create configuration for EurekaLog. Use "Start/Programs/EurekaLog 7/Tools/Settings Editor" menu item to launch standalone editor for EurekaLog settings. Setup EurekaLog options as you desire and click on "Save" button to save all options to .eof file.

Now you can place a button in your application to raise exception (to test EurekaLog) and compile your application. It's better to make a "build" for first time, not just "compile". Your project will be compiled with EurekaLog and debugging options, but EurekaLog will be in disabled state. You can run your application, it will be fully functional, but exceptions will be handled by RTL/VCL, not by EurekaLog.

Application with disabled EurekaLog
Final step is to post-process your executable. This step should inject debug information and EurekaLog's options into your executable. To do that - create text file with .bat extension (say, "Build.bat") and with the following content:

@echo off
"C:\Program Files\Borland\Delphi7\Bin\ecc32.exe" "--el_alter_exe=C:\Program Files\Borland\Delphi7\Projects\Project1.dpr;C:\Program Files\Borland\Delphi7\Projects\Project1.exe" "--el_config=C:\Program Files\Borland\Delphi7\Projects\Project1.eof"
pause

Notes:
  • Adjust file names and paths as necessary; 
  • You can also use relative file paths; 
  • Exact location of .bat file does not matter - as long as all file paths point to correct files; 
  • Typically you place .dpr/.eof/.bat files in the same folder; 
  • Last command (pause) is optional.

Now you have to run this .bat file each time after compiling your project.

Successful post-processing by ecc32.exe tool
Run your application now. If you do everything correctly - EurekaLog will be active, and exceptions will be handled by EurekaLog.

Same application after post-processing: EurekaLog is active

Additional limitations

Unaccessible functions
Some auxiliary EurekaLog functions may be unaccessible. For example, EurekaLog uses SOAP protocol to submit bug reports to Mantis bug tracker. SOAP is not available in Delphi 7 Personal. Thus, you will not be able to submit reports to Mantis with API. You have to use e-mail or web posting.

Debugging
Obviously, you will not be able to debug your applications if you do manual post-processing (Delphi Personal and Turbo Explorer). That's because you have to compile your project, then call .bat file to post-process, then run the project. But this last step (running) will rebuild your project if you run it under debugger. So, you have the following options:
  1. (For EurekaLog) Compile -> post-process -> run outside of IDE
  2. (For debugging) Compile -> run under debugger
  3. (For both) Upgrade your IDE
Note: this limitation is true only for older IDEs. Newer IDEs has build events for project, so you may call ecc32/emake from these build events.