Stepping into the VCL source

by Kent Reisdorph
In the article, 揢sing the VCL source to track down bugs,?Brent Knigge explained a situation where the VCL was not acting as he expected. He said that he examined the VCL source to find the cause of the problem. What many C++Builder programmers do not realize is that they can step into the VCL source while debugging. I抣l explain how to do that in this article.

Preparing to step into the VCL
Obviously, stepping through the VCL is only possible if you have the VCL source to begin with. The Standard version of C++Builder does not come with the VCL source, so stepping through the VCL is not an option with that version of the product. If you have C++Builder Professional or Enterprise (formerly called the Client/Server version) you can step through the VCL source, provided that you elected to install the VCL source when you installed C++Builder, and provided you have properly set up your project options. The default project options don抰 allow you to step into the source, but this is easy to remedy with a few mouse clicks.

The steps required to set up a project to allow stepping into the VCL differ with the various versions of C++Builder. For C++Builder 1, you only need to go to the Linker page of the Project Options dialog and check the Link debug version of VCL check box.

For C++Builder 3, 4, and 5, setting up a project to allow stepping into the VCL is a two-step process. First open the Project Options dialog. On the Linker page, check the Use debug libraries option. On the Packages page, uncheck the Build with runtime packages option. You must build the application without runtime packages because the VCL packages do not contain debug information. The debug information is only built into the debug library (LIB) files for the VCL.

After you have made the changes to the project options, rebuild your application.

A simple test
Once you have the project set up to use the debug libraries, stepping into the VCL source is easy. For a quick test of this theory, start a new application and set the project options as explained in the previous section. Place a button on the form and put this code in the button抯 OnClick event handler:

Top = 20;
Set a breakpoint on this line of code and run the application. When the debugger stops at the breakpoint, press F7 to step into the VCL. You should find yourself at this function in CONTROLS.PAS:

procedure TControl.SetTop(Value: Integer);
begin
SetBounds(FLeft, Value, FWidth, FHeight);
Include(FScalingFlags, sfTop);
end;
From this point you can continue to step into the VCL methods to find out where a particular problem lies. The C++Builder debugger is smart enough to allow you to inspect variables and objects, even though the VCL source is Object Pascal.

In some cases you may find that you have stepped into assembly code. If you are familiar with assembly programming this probably won抰 concern you in the least. However, if you don抰 read assembly, you can usually continue stepping through the assembly code until you get to some source code that you understand.

Conclusion
Stepping through the VCL source can be extremely valuable when trying to track down a bug. It is unlikely (but not completely out of the question) that you will find a bug in the VCL. However, examining VCL variables and objects may help you spot a problem in your own code. This technique goes beyond just the VCL itself, since it applies to third party component libraries as well. That assumes, of course, that those third party libraries were built with debug information, and that you have the source for the library. In some cases you may need to rebuild third party component packages and LIB files to include debug information.