07 April, 2009

Compiling from the command Line

One of the areas where questions often arise is in compilation from the command line. So I thought we would have a closer look at how command line compilation works, why it is needed and what the various options are available when you need to use it.

ECC32

ECC32.exe is the command line compiler that EurekaLog uses. It replaces DCC32.exe which is the normal Borland/CodeGear/Embarcadero compiler. For C++ Builder the EurekaLog compiler is called EMAKE.exe and this article applies to both. When ECC32 is called it will compile your project and then add the EurekaLog settings and debug information to the application. Any parameters you pass to ECC32 are passed onto DCC32 as in a normal compilation. So ECC32 can be used just like DCC32 and you can find plenty of information on these standard parameters in the Delphi help file.

A simple command line in this case would look like:
ECC32 "Project1.dpr"

EurekaLog settings

ECC32 also has it's own set of parameters governing how EurekaLog is incorporated into the application. Normally you would activate EurekaLog from within the Delphi IDE and set the various options in the EurekaLog settings dialog. These settings are then stored as part of your project and used by ECC32 during compilation. One of ECC32's own parameters allows you to define which settings are to be used while compiling. Now to use this option we are first going to need a settings file and the easiest way to achieve this is by using the EurekaLog settings dialog within the IDE to select the options you require and then selecting the Export button.


This will create a file containing your chosen settings. To use the settings in this file you can pass the settings file name to ECC32 and the command line would look something like this:
ECC32 "Project1.dpr" --el_config"Project1.eof"

where Project1.eof is the settings file we exported earlier.

Without compiling

One option that we have available is to just add the EurekaLog features to an application that is already compiled. This can be useful in situations where 3rd party build tools are not able to directly run ECC32. To achieve this we just need to use another EurekaLog command line parameter --el_alter_exe. Again we can just point ECC32 to the Delphi project where it will get it's settings and optionally supply the compiled application's file name. Here is how the command line would look given that our application has already been compiled and we just want to add EurekaLog's features:
ECC32 --el_alter_exe"Project1.dpr"

If you want to specify the complied application's file name use:
ECC32 --el_alter_exe"Project1.dpr;Project1.exe"
You may also need to specify absolute or relative paths to files in some cases.

Minimum parameters needed

When you are compiling your project just using DCC32 and then using the el_alter_exe option afterwards to add EurekaLog there is a minimum set of flags needed to get EurekaLog to work. You also need to tell the compiler where ExceptionLog.pas is so it can be included as part of the compiling process. The command line for DCC32 would in this case look like:
DCC32 -U' + AppDir + '" -GD -$D+

where AppDir is the path to ExceptionLog.pas. -GD option enables generations of detailed map-file and -$D+ option enables debug information.

Using ECC32 with automated builds

Direct calling of ECC32 rather than using standard EurekaLog expert is often used in automated build scenarios. Many EurekaLog users setup a build server where they can build working project automatically without calling IDE. Usually it involves usage some sort of make program or bat-files. In all those cases compilation is performed by calling DCC32 directly. The EurekaLog expert is not used, so it has no chances in adding EurekaLog's magic to application.

In those cases you need to manually add a call to ECC32. If you use some sort of batch file - then just replace a call to DCC32 with call to ECC32. Alternatively, you can add a call to ECC32 with --el_alter_exe parameter later. The newest Delphi versions comes with Build events feature, which can be very handy. For example, the simplest way to use ECC32 with MS-Build program in the latest Delphi version is to add a call to ECC32 to Post-Build event. Just add something like:
ECC32 --el_alter_exe"Project1.dproj;Project1.exe"

to Post-build event in your project's options (not EurekaLog project's options) and you are done. Post-build events located at "Project"/"Options"/"Build events".