The CGProf browser is a simple emacs-based facility for use with
CGProf. The browser allows you to examine the CGProf measurement
output and the profiled source code at the same time. For example, if
you find a CGProf entry that looks interesting, you can use simple
browser commands to open an emacs frame showing the source code
defining that procedure. Following is a step-by-step overview of how
to use the CGProf browser:
1. Install the browser.
2. Create a browser database for your source code.
3. Create a CGProf profile.
4. Save the profile output.
5. Start the browser, using the Windows Explorer.
During a normal installation of Etch, the run-setup script is invoked, either directly (by you) or indirectly (by genall.bat). This installs a Windows Explorer association between files that end with the .cgp extension, and a browsing mode for CGProf output files, that uses GNU Emacs. The installation will only succeed if GNU Emacs is properly installed on your system.
The CGProf browser is implemented on top of the GNU Emacs tags facility, so in order to use the browser on a given set of source code, you must first create a tags database for your sources. The filename of the tags database must be of the form <ModuleName>-tags. Suppose, for example, that you have the sources for a module named "des.dll" in a directory named "des-src". You would issue the command
c:\somedir> etags --no-defines --output=des.dll-tags des-src\*.c
to create the appropriate tags database. The tags database you create must reside in the same directory as the ".cgp" file that you will create in the next section.
When you run CGProf from the standard Visual Etch environment, it creates an output window when the application run has completed. The first step in using the browser is to save the output file. Using the "File" menu of the output window, choose the item "Save Contents As..." and then specify a file name. You must ensure sure that the filename ends with the extension ".cgp".
To begin using the browser, you must use the Windows Explorer to locate the file you just saved, and then you double click on that file. This should start up GNU Emacs in the CGProf browsing mode on the file you just selected. If you are unfamiliar with GNU Emacs, we recommend you use the Emacs tutorial available as part of the Help menu in GNU Emacs before using the CGProf browser. If you want to use the CGProf browser without using the Windows Explorer, you can load by hand the elisp file that implements the browser. The following Emacs command will do this:
<Meta-x> load-file $ETCHROOT\util\ebrowse\etch-browse.el
The CGProf browsing mode sets the CGProf output to be read-only, and adds the following key and mouse bindings:
Key Function
--- --------
v view-subroutine
[mouse button 2] view-subroutine
n scroll to the next line
p scroll to the previous line
q quits viewing the CGProf output buffer (kills the
buffer, but not emacs).
The view-subroutine function causes emacs to create a new frame that contains the source code for the named function, with the cursor positioned over the place where that function is defined. You can only use the view-subroutine operation on a line that is highlighted by the browsing mode.