Instructions for building, editing, and debugging the TPTP RAC and piAgent on Windows.
By Allan Pratt, apratt@us.ibm.com
August
30, 2005
These instructions are for TPTP 4.0, but the later versions are probably the same. These instructions apply to people who want to use Microsoft Visual Studio to edit, build, and debug the RAC and piAgent interactively, not to people who want to use nmake for an automated build.
Get the sources from CVS. If you don't have an authorized CVS login, use the "pserver" protocol and anonymous access:
You should see the repository at this point. The "pserver" protocol lets you read but not write.
Open the "platform" subtree of the HEAD or branch you want and check out the project called org.eclipse.tptp.platform.agentcontroller.
You'll find the RAC under src-native/collection/framework. You'll find piAgent under src-native/collection/collectors/native/java_profiler.
To build the RAC you need some packages that it depends on. Get CBE-SDK from somewhere; I forget where I got mine. The one I got had files dated 7/18/2005. Also get Xerces-C version 2.4.0. The version I got was xerces-c2_4_0-windows_nt-msvc_60.
Pick a directory where these dependencies will go. For the sake of this article, I'll call it %DEPENDS%.
Unpack the ZIPs those packages come in so you have two directories: %DEPENDS%\CBE-SDK (which contains "include" and "lib" subdirectories) and %DEPENDS%\xerces2.4.0 (which also contains "include" and "lib" subdirectories).
You also need the "include" directory from a Java JDK. Put a JDK into %DEPENDS%\java such that the directory %DEPENDS%\java\include exists. This is for jni.h and jvmpi.h.
Now you need to configure your environment and start Microsoft Visual Studio to do the build. You might want to create a batch file that does this:
Now, from a shell window where the environment has been modified as above, run "msdev -useenv" to start Visual Studio in a mode where it will pick up the shell window's environment settings, rather than ignoring them.
Inside Visual Studio, open the workspace file for building the RAC:
Make sure "RAServer" is the active project and the active configuration is "RAServer - Win32 Debug" (or "Release"), and press F7 to build.
The result of this build step is some files in the "bin" directory under framework\WinBuild. You can copy these files to an existing, working RAC installation directory to use and debug your new RAC. Stop the RAC if it's running and copy *.exe, *.dll, and *.pdb from the WinBuild\bin directory to the %RASERVER_HOME%\bin, and restart the RAC.
Instead of starting the RAC by running RAServer from a command line, run "msdev RAServer.exe" to start it under the Visual Studio debugger.
You can also do this: somewhere in the RAC at a point you consider interesting, insert a call to "DebugBreak();" which causes the program to stop and offer to open a debugger. I often make this call conditional: if the file "C:\rac_debug" exists, then call DebugBreak(). This lets me decide I want to attach a debugger regardless of how the RAC gets started. Be sure to remove this code later, since it's temporary debug code and it's Windows-only.
The environment variable setup for piAgent is just like the setup for the RAC. Start Visual Studio the same way, with "msdev -useenv" after setting the environment variables.
Open this workspace file: src-native\collection\collectors\native\WinBuild\WinBuild.dsw
Set the active project to java_profiler, set the active configuration to "java_profiler - Win32 Debug" (or "Release"), and build with F7.
The result of the build is a new set of files in the bin directory of the WinBuild directory. (This isn't the same WinBuild directory as the RAC project.) Copy piAgent.dll and piAgent.pdb to the %RASERVER_HOME%\bin directory of an installed, working RAC. Now when you run any Java program with profiling you will get your new piAgent.dll.
I always use the DebugBreak() trick to get control in piAgent, since the target process gets started so indirectly (through the RAC). See the section "Debugging the newly built RAC" for how this works.
I find I have to build the RAC before I can build piAgent, so even if my goal is to change only piAgent, I start by building the RAC. Maybe I could use a RAC SDK installation if I were smarter. But I only have to build the RAC once as part of setting up my piAgent build environment, so I haven't bothered to work out the shortcut.
The Eclipse install doesn't do this, but some third-party products based on Eclipse will put a copy of piAgent.dll and some RAC libraries into your Windows\System32 directory during their install. IBM's Rational Application Developer ("RAD") product install does this, for example. You need to find those and delete or rename them - otherwise, because of Windows library search rules, the versions from System32 will be picked up instead of your changed versions in %RASERVER_HOME%\bin.
I created some batch files to help me: one to set up the environment variables ("setpath"), one to start Visual Studio with the right arguments ("vc6"), and one to copy the products of the build from the WinBuild\bin directories to the %RASERVER_HOME%\bin ("update"). So my workflow is like this:
A new Visual Studio instance comes up the first time a given instance of java.exe hits DebugBreak(). If you tell it to remember its state as you close it, then things like breakpoins you've set will persist across sessions.