================================================================================ STEP: An Framework for the Efficient Encoding of General Trace Data ================================================================================ Introduction: ------------- This is a pre-release version of STEP, prepared to coincide with the first public presentation of the system at PASTE 2002. STEP is free software, currently distributed under the terms of the GNU General Public License (GPL). Consult the accompanying license.html or COPYING.txt files for further details. STEP is currently maintained by Rhodes Brown and is distributed through McGill University's Sable Research Group at: http://www.sable.mcgill.ca/step/ A number of documents relating to STEP can be found at this URL, including a copy of the PASTE 2002 paper, and Rhodes' M.Sc. thesis on the system (coming soon). If you have questions or comments regarding STEP, please send them to rhodesb@sable.mcgill.ca. System Requirements: -------------------- STEP was developed and tested under the Debian GNU/Linux (i386) operating system using Sun's Java^TM 2 Platform, Standard Edition (J2SE) version 1.4. In theory, STEP should work under any OS that supports the Java 2 environment. However, if you encounter difficulty, please submit a bug report. Rebuilding the stepc compiler and STEP library classes requires version 1.4 of the Java Development Kit, since the new assertion mechanism is used to implement a number of validation checks, eg. "javac -source 1.4 ..." at compile time, and "java -ea ..." at run-time. You will probably want to use the included Ant build.xml file to regenerate the various components, documentation or examples. Ant is a tool similar to the well-known GNU make, but for Java. With an appropriate script to run Ant installed, you can simply type "ant" for a full rebuild, or "ant step" and "ant stepc" to build the classes for particular components. Type "ant -projecthelp" to get a list of the various targets. Rebuilding the stepc parser requires the SableCC parser generator. Some of the example classes depend on Soot (a bytecode instrumenter) and EVolve (a visualization system). Future examples may also use JIL (a system for annotating Java sources). To build these targets, you will need 'sablecc.jar', 'soot.jar', etc. in your $HOME/lib directory. You can obtain all of the above mentioned software for "free" at the following locations: Debian GNU/Linux: www.debian.org Sun J2SE: java.sun.com/j2se/1.4/ Ant: jakarta.apache.org/ant/ SableCC: www.sablecc.org Soot: www.sable.mcgill.ca/soot/ EVolve: www.sable.mcgill.ca/evolve/ JIL: www.sable.mcgill.ca/jil/ Usage: ------ If you are simply interested in trying out the stepc compiler, you can use the pre-packaged jar version, eg. java -jar lib/stepc-x.y.z.jar Classes for the examples mentioned below are also pre-packaged in the 'lib/step_examples-x.y.z.jar' file. For example, the Adapt converter can be run with: java -classpath lib/step_examples-x.y.z.jar example.AdaptToStep ... You can substitute new record definitions by compiling them with 1) stepc & 2) javac, then pre-pending their location to the classpath, eg. 1. java -jar lib/stepc-x.y.z.jar --java foo.sdl bar.sdl ... 2. javac Foo.java Bar.java ... 3. java -classpath .:lib/step_examples-x.y.z.jar example.AdaptToStep ... To see STEP-DL definitions for records on the current classpath, use the stepc.StepdlEmitter, eg. java -classpath .:lib/stepc-x.y.z.jar stepc.StepdlEmitter Foo Bar ... To run the EVolve and/or Soot examples, you'll need to add to your classpath, eg. java -classpath lib/step_examples-x.y.z.jar:$HOME/lib/evolve.jar EVolveDemo Examples: --------- JVMPI / Adapt ------------- Tools to convert to and from Bruno Dufour's Adapt format are in the 'example' Java package. The file 'sdl/jvmpi.sdl' contains STEP-DL definitions for the various JVMPI events. The Java interface sources can be generated explicitly by invoking stepc, or by building the 'example' Ant target. To convert from an Adapt trace, use: java example.AdaptToStep Adapt.dat This will read a file called "Adapt.dat" and generate a STEP file called "Adapt.dat.step". To convert back, use: java example.StepToAdapt Adapt.dat.step Based on a version of Adapt from late August 2002, definitions for the events o, O, a, A, g, G, m, M, v, V, & i should be functional -- although the instruction (i) version is untested. You can get a "profile" dump for most of the encoding strategies by adding "-Dstep.encoding.profile=true" to the java command line arguments. This is useful for tuning the strategies, and also for getting a summary of the event mix. Soot ---- An example using Soot transformations to profile allocations, method use and field accesses is provided in the *Profiler.java example files. Transformed programs require the ProfileCollector class to write out STEP records. STEP-DL definitions for the record types are in the 'sdl/soot.sdl' file. Note that this file (combined with the 'sdl/java.sdl' file) use C-Preprocessor macros, thus the file must be fed through cpp before compiling it with stepc. Regular Soot users will recognize that the Profiler class is a wrapper over soot.Main that adds the various instrumenters as part of the Jimple Transformation Pack (jtp). EVolve ------ A simple example that implements an EVolve data source is given in the EVolveDemo.java file. Currently the example only works with OBJEC_ALLOC records (see the JVMPI/Adapt example above). Miscellanea: ------------ * The integrated gzipping of data is disabled by default, since there is something funny going on with the java.util.zip.GZIPxx streams.