Getting Started

This guide will take you through the basic steps to get you up and running with DelphiXPG. It covers,

• Creating a XPG project
• Parsing the project
• Navigating through the XRef
• Performing a global edit
• View soure code changes
• Adding profile code to your project
• Saving modified source
• Build, run and collect profiling data
• Viewing profile data
• Removing profile data

The project we will be using in this tutorial is the Threads demo project supplied with Delphi. This is normally found in the Demos sub-directory of the Delphi installation root.

DelphiXPG does not process DFMs stored in binary format, only in text format. Binary format files can be converted to text format automatically while being parsed, but first DelphiXPG has to be configured for the location of convert.exe. This is a command-line utility supplied by Borland to convert DFMs from binary to text and visa versa. To configure DelphiXPG to use this tool see Binary DFMs

Create a XPG project

This section shows you how to create a simple project.

To create a new project click on the "New Project" tool button or select File/New Project from the main menu. This displays the new projects properties dialog.

Click on the "Project" browse button, this opens a file open dialog, navigate to the Demos\Threads directory and select file "thrddemo.dpr", click the "Open" button.

We will ignore setting the other project options for this tutorial, click "Ok" to complete creation of this project.

Parse the project

The project now needs to be parsed to collect cross-reference information. Click the parse tool button or select Project/Parse from the main menu.

While the project is being parsed a dialog is displayed showing the current progress.

Click the "Close" button when the parse is complete.

Navigate through the XRef

Once the project has been parsed cross-reference information is displayed for the project.

The form is divided into the following areas,

• Unit list
• Object data
• XRef list
• Source

Unit list

The unit list contains all the units parsed for this project.

To view a unit's cross-reference click on the units drop down list and select the desired item.

Object data

Object information for the currently selected unit is displayed in the Object area, this has two lists. The first is a tree that groups items by catagory e.g. Classes, Records, Methods... The second is an alphabetical list of identifiers.

Selecting an item from either displays its cross-reference details.

XRef list

The XRef list holds all the references for the selected item in the object area.

Each XRef item in the list has the following information,

• Unit the item is referenced from.
• Line number within unit.
• Column within line.
• Type of reference.

Selecting an item in the XRef list causes the source for the referencing unit to be displayed in the source area and the referencing item highlighted.

Source

The source area shows the source for the selected item in the XRef list and highlights the reference in the source.

Select SORTTHDS from the units list and open Classes/TBubbleSort/Methods and select sort. Now click the XRefs list and select the "Implementation" item. You should see something like this.

Right-clicking on "VisualSwap" identifier in the source area displays a popup menu, from this select "Find Context" to display the "Context Info" form showing you the definition for this item. Clicking the "Go" button will jump to its definition. This type of navigation is also possible from DFMs.

Performing a global edit

In this section we will perform a global edit to an identifier, this is a very useful time saving facility when modifying identifiers that have multiple references across serveral units and DFMs.

Select THSORT from the units drop down list then open the "Class" item in the object tree and finally select TThreadSortForm.

You can see from the XRef list there are five cross-reference items, one from ThrdDemo, three from ThSort.pas and one from ThSort.dfm.

Now right click the selected item in the object tree and select "Global Edit" from the pop up menu. The global edit dialog appears.

This dialog displays the current identifier and lists which units reference it and how many times.

In the dialog set "New Identifier" to "TMyThreadSortForm" and click the "Edit" button. You should see the item has changed in the object tree and in the source.

View soure code changes

Once the source has been modified it is useful to see what has changed and that the change is correct.

Units that have been changed have the "Show Changes" tool button and menu item enabled, they also show the change picture in the units list.

Select a unit that has been changed and click the "Show Changes" tool button.

The change form is displayed.

This form allows you to navigate through the changes, press Ctrl-N for the next difference and Ctrl-P for the previous one.

Add profiling code to your project

Profiling allows you to find bottle necks in an applications processing by recording the method calls during a run. The collected data can be analysed/viewed within DelphiXPG.

Before profiling data can be collected code must be added to you application to record the method calls. This code can be automatically insterted for you by clicking on the "Insert Profiling Code" tool button.

Click this button to add profiling code to the ThrdDemo application.

Click the "Show Changes" tool button to view changes to the source. Thw changes will consist of the global edit performed before and inserted profiling code.

The inserted profiling code declares external methods that can be found in XPGProfile.dll and calls to these methods at the beginning and end of each method e.g.

procedure TMyThreadSortForm.BubbleSortBoxPaint(Sender: TObject);
begin
{$IFDEF XPGPROFILE} XPGMethodStart($1004000C8B1A9);try{$ENDIF}

  PaintArray(BubbleSortBox, BubbleSortArray);

{$IFDEF XPGPROFILE} finally XPGMethodFinish($1004000C8B1A9);end;{$ENDIF}
end;

However, profiling is not started automatically, you must manually insert calls "XPGStartProfiling" and "XPGStopProfilingPrompt". This allows you to profile individual sections of code outputing the results to seperate files.

In the "Thread Sorting Demo" we will want to start profiling once the user clicks the "Start Sorting" button and stop profiling once all the threads have finished.

To insert these calls select THSORT from the units drop down list and click Edit/Open In Editor from the menu. This displays the source in an editor allowing you to insert the code. Search down to the "StartBtnClick" method and insert the call,

  {$IFDEF XPGPROFILE}XPGStartProfiling(true);{$ENDIF}
  

in the indicated place. The code is wrapped in a conditional allowing profiling to be switched on and off. The parameter indicates the application will be running multiple threads.

Now insert code to stop collection of profiling data, search down to the "ThreadDone" method and insert the call,

	{$IFDEF XPGPROFILE}XPGStopProfilingPrompt('thrddemo.prof');{$ENDIF}
  

in the indicated place. The parameter is the location where the collected profiling information is stored.

To view source changes in the editor select File/Show Changes.

Save these changes by clicking File/Update and Exit. Note (1) the project is reparsed when the changes are saved (2) the changes update the source stored in DelphiXPG, they have not been committed to disk.

Save modified source

Before the application can be built and run we need to save the source changes to disk. To do this select File/Save All from the main menu. The save dialog is displayed.

Click the "Save" button.

Building, running and collecting profile data

Open the project in Delphi so that it can be built, but first you need to define the conditional "XPGPROFILE" so that the profiling code will be compiled into the application. To do this select Project/Options from the main menu, in the Directories/Conditionals tab set "Conditional defines" to "XPGPROFILE".

Now build the project by selecting "Project/Build ThrdDemo".

Now run the ThrdDemo application, when the lists have been sorted a SaveDialog is displayed for a location where to store the collected data, enter "ThrdDemo.prof" and click Save.

View profile data

To view profile data start DelphiXPG if not already started and load the ThrdDemo project. Now click the "View profile data" button.

An open dialog appears, select file "thrddemo.prof" and click open. A new "Profiler" tab appears showing the profile data.

The "Profiler" tab has three sub tabs,

• General
• Consolidated
• Threads

General

The general tab shows the following information,

• Location of profile data file.
• Date and time data was collected.
• Duration of run.
• Time spent in user code.
• Time spent in profiler code.
• Number of threads.
• Status of load.

Note: You may notice in this example that the run duration is significantly less than the sum of user and profiler code time. The reason for this is the use of TThread.Synchronize which injects a method call into the main VCL thread causing its time to be duplicated. There are ways to resolve this issue detailed in the main documentation, see XPGThreadSuspend.

Consolidated

The consolidated view gives processing times summed over the threads, it has two sub tabs. One for drilling down from Module to Class to Method to Called Method, the second lists all methods.

Note: Clicking on a column title allows you to sort data into an ascending or descending sequence.

Threads

The Threads view gives processing time by thread. Like the Consolidated view it has two sub tabs allowing you to drill down to a method or view all method calls.

Remove profile data

To remove profiling code from ThrdDemo first load it into DelphiXPG and parse it. Once this has been done click the "Remove Profiling Code" tool button.

Source code changes can be viewed by selecting a unit and clicking the "Show Changes" tool button.

Once you are satisfied with the changes you can save them using the "Save All" tool button.