Installation and setup

Follow the instructions here.

• "pat.dll" or "pat.so", the agent library.
• "Pat.jar", the Java package that allows communication of Java classes with the agent library.
• "perfdump.jar", a Java project that dumps received performance events to CSV files.
• "perftest.jar", a Java project that is used during development to test the functionalities of the agent library.
• "drill.war", a Java web application project that is used to show the results of an analysis run. This package can be deployed on any regular J2EE webserver, like Tomcat.

In order to build the native library from the sources on Windows, you need to have a compiler available that can build the sources. Microsoft Visual C++ 6.0 was used to compile the version in the binary package. For this environment, the .dsw and .dsp files are included in the source distribution.

Before you begin building, the "directories" inside "Tools | Options" need to be set up. One "include" directory link needs to point to the "include" directory in the JDK1.5.0 distribution. Depending on your platform, you also need to include either the "win32" or "linux" directory that contains platform-specific definitions. Finally, point one of the "linking" directories to the "lib" directory of the JDK1.5.0, otherwise you get errors about unresolved references. These settings should build the project nicely. Perhaps you need to include the files again.

Altogether, should things fail, there are at the moment no specific pre-processor definitions or optimisations done. The shared library has been built with very simple settings, so if you set up an environment for a different compiler, things should work without too much effort.

In order to build the native library from the sources on Linux, you need to have a compiler available and the make program. The native library on these UNIX systems is compiled using a simple Makefile. The Makefile depends on the environment variables "OSNAME", "J2SDK" and "OPT". Set "OSNAME" to a platform that is supported in the Makefile. Set "J2SDK" to the directory where the JDK 1.5.0 is installed. It is needed for include files. "make clean" cleans the object files from the directory. "make" builds the library. If you want to build an optimised release, specify "OPT=true" on the make command line: (e.g. make OPT=true).

Building the Java classes

I've used "Eclipse" for development. If you lack any IDE environment and don't want to bother downloading any large package, the Java classes can also be compiled using java without too many problems. The "Pat.java" file inside the "bootstrap" directory needs to be compiled and wrapped inside a "Pat.jar" java package. The Pat.java file was created in the default package, so does not have to be put in a subdirectory tree.

The only other thing you need to do and which might take a little bit more time is compiling the "perfdump" Java classes. Compile the classes from the "src" directory and later zip all the generated class files ( with directory, starting from "com" ) into a large zip file. That should do it.

The web application can be built by executing "ant clean", followed by "ant". This creates the web application archive in the "dist" directory.

If you have taken Patty in binary form, simply un-zip the downloaded binaries to a separate directory. When the "java" process starts up, it needs to have the shared library ( "pat.dll" on Windows, "libpat.so" on other OS's ) on the path or library path.

With java, you have the option to either include the shared library on the library path ( "PATH" on Windows, "LD_LIBRARY_PATH" or "SHLIB_PATH" on UNIX ), or you can specify the library to be included through the option "-Djava.library.path=<path-to-patty.library>".

When classes are instrumented, these need to create a reference to a Patty-generated "java" class that calls native methods. These native methods are used to pass through class and method identifiers during method execution. The class is contained in "Pat.jar" and needs to be put on the classpath by adding the option "-Xbootclasspath/a:Pat.jar". Of course, the file "Pat.jar" should be in a location where the java.exe process can find it. It can be in the working directory, or you can specify a full path to the jar file.

Download or install a J2EE webserver ( e.g: Tomcat 5.5 ) and copy the "drill" web archive file to the "deploy" directory under "server". For other webservers than Tomcat, please consult the documentation. It should be a similar action to simply copy the file and run the webserver. The standard port that this deployment is running on for listening to 'events' is 5005. This configuration can be changed inside the 'web.xml' file inside the "drill" web application archive file. This file is located in the "WEB-INF" directory.

Summary:

• Download patty with these instructions.
• Unpack the zip-file to a certain location.
• Make sure the shared library is on the library path.
• Make sure the "Pat.jar" file is on a location where it can be found.
• Install a JSP/Java webserver like Tomcat 5.5.
• Configure the port number in web.xml of the 'drill' web application archive file and deploy it on the webserver.
• Run it.

Follow the instructions on this page.

After any application is run, point your browser to the machine where you installed the Tomcat deployment and 'drill' and go to the first page. ( this will be a URL like "http://%lt;machine-name>/drill/" or "http://%lt;machine-name>/drilldebug/"). Hit "recalculate", which recalculates method execution times and contention. Then browse the results.