To protect your data, the CISO officer has suggested users to enable GitLab 2FA as soon as possible.

Commit cc613f56 authored by steveb-oss's avatar steveb-oss
Browse files

[svn r475] Improved instructions etc

parent afc17dd7
The DaCapo Benchmark Suite
--------------------------
This benchmark suite is intend as a tool for the the memory management
research community. It consists of a set of open source, real world
applications with non-trivial memory loads.
Last updated 2009-06-26
This benchmark suite is intend as a tool for the research community. It
consists of a set of open source, real world applications with non-trivial
memory loads.
Guidelines for use
------------------
......@@ -14,52 +16,65 @@ When quoting results in publications, the authors strongly request that
credit in academic research.
For more information see the Dacapo Benchmark web page,
http://www-ali.cs.umass.edu/DaCapo/gcbm.html
http://dacapobench.org
Building
--------
The easiest way to obtain the benchmark suite is to download the pre-built
jar file from the DaCapo Benchmark web site above. If, however, you want
to build from source read on:
jar file from the DaCapo Benchmark web site above.
If, however, you want to build from source read on...
The suite is built using ant. You will need the following tools:
- ant (you need to install this yourself if you don't already have it http://ant.apache.org)
- javacc (included in our tools directory, or download at http://javacc.dev.java.net/)
- maven (included in our tools directory, or download at http://maven.apache.org/download.html)
The suite is built using ant, from a build.xml in this directory. The most
useful targets are:
IMPORTANT: before trying to build the suite:
dist (default) - build the dacapo jar file from sources
sourcedist - Download sources and build
1. Set your JAVA_HOME environment variable appropriately
2. Copy default.properties to local.properties and edit it
for your environment.
3. Ensure maven (mvn) is in your execution path. You can use
the version that we include in our tools directory if you wish.
We have had some problems with older versions of maven.
Note the suite will currently only build using a Java 1.4 compatible SDK,
although the resulting jar file will happily run under the Sun 1.5 VM.
For more information, invoke ant with the help target in the benchmarks
directory ("ant help").
Some external tools are required to build the suite. These include
- ant http://ant.apache.org/
- javacc http://javacc.dev.java.net/
Directories
Structure: Files and Directories
-----------
src Source files for the DaCapo test harness
harness The benchmark harness
stub Stub files to allow the test harness to compile
This directory includes all of the source code for the DaCapo harness,
which is used to invoke the benchmarks, validate output, etc.
bms The benchmarks
sources Source distributions for the packages used in
the benchmark suite. All files in this directory
can be downloaded using the ant target 'sources'.
bms/<bm>/src Source written by the DaCapo group to drive the benchmark <bm>
bms/<bm>/downloads MD5 sums for each of the requisite downloads. These are used to
cache the downloads (avoiding re-downloading on each build)
bms/<bm>/data Directory containing any data used to drive the benchmark
bms/<bm>/<bm>.cnf Configuration file for <bm>
bms/<bm>/<bm>.patch Patches against the orginal sources (if any)
bms/<bm>/build.xml Local build file for <bm>
bms/<bm>/build [Directory where building occurs. This is only created at build time]
bms/<bm>/dist [Directory where the result of the build goes. This is only created at build time]
originals
Source distributions for packages that are not available
publicly (currently only 'ps').
patches Some of the packages require minor changes to work in the
benchmark suite. These patches are applied to the source
distributions before they are compiled.
libs Common code used by one or more benchmarks.
cnf Configuration files that tell the test harness how to run each
of the benchmarks.
Each of these directories more or less mirror the bm directories.
data Test data
License
......
<!--
* Ant build file for the DaCapo benchmark suite.
*
* Public targets are
* - dist (default) compile from source and create the dacapo jar file.
* External tools required (apart from a JDK and Ant)
* - make
* - javacc, assumed to be on the path, with library files in
* /usr/share/javacc/lib
-->
<project name="DacapoBenchmarks" default="dist" basedir=".">
<description>Dacapo benchmarks</description>
<property name="toolsdir" location="../tools"/>
<target name="help">
<echo>Building the DaCapo benchmark suite.
Prerequisites:
- javacc (http://javacc.dev.java.net/)
- maven (http://maven.apache.org/)
For convinience, both are included in the tools directory:
${toolsdir}
Building:
1. Set your JAVA_HOME environment variable appropriately:
On Mac OS X:
export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Home
On Ubuntu 9.04:
export JAVA_HOME=/usr/lib/jvm/java-6-sun
2. Copy default.properties to local.properties and edit it
for your environment.
3. Ensure maven (mvn) is in your execution path. You can use
the version that we include in our tools directory if you wish.
On unix/MacOS X:
export PATH=${toolsdir}/apache-maven-2.1.0/bin:$PATH
We have had some problems with older versions of maven.
4. Run ant:
ant [builds all benchmarks]
ant bm [builds a specific benchmark, bm]
ant help [this help message]
</echo>
</target>
<property file="local.properties"/>
<property file="default.properties"/>
......
......@@ -8,6 +8,6 @@
# before this file, and will thus override these defaults
#
make=/usr/bin/make
javacchome=/usr/share/java
javacchome=${toolsdir}/javacc-4.2
java14.lib=/usr/lib/j2se/1.4/jre/lib
java14.compile.classpath=${java14.lib}/rt.jar;${java14.lib}/jce.jar;${java14.lib}/jsse.jar
Copyright (c) 2006, Sun Microsystems, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the Sun Microsystems, Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
#!/bin/sh
JAR="`dirname $0`/lib/javacc.jar"
case "`uname`" in
CYGWIN*) JAR="`cygpath --windows -- "$JAR"`" ;;
esac
java -classpath "$JAR" javacc "$@"
@echo off
java -classpath "%~f0\..\lib\javacc.jar" javacc %1 %2 %3 %4 %5 %6 %7 %8 %9
#!/bin/sh
JAR="`dirname $0`/lib/javacc.jar"
case "`uname`" in
CYGWIN*) JAR="`cygpath --windows -- "$JAR"`" ;;
esac
java -classpath "$JAR" jjdoc "$@"
@echo off
java -classpath "%~f0\..\lib\javacc.jar" jjdoc %1 %2 %3 %4 %5 %6 %7 %8 %9
#!/bin/sh
####################################################################
#
# Copyright (C) 2006 Andrew Tomazos <andrew@tomazos.com>
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
####################################################################
#
# jjrun 1.0d1
#
# - Build and execute a JavaCC .jj file in one command
#
# - Requires javacc, java, make and sh
#
# - TODO: If you use something other than SimpleCharStream you
# will need to modify the OBJECTS variable below
#
# - TODO: Only tested on GNU/Linux
#
####################################################################
# $PROGFILE: This programs file path
PROGFILE=$0
# $VERSION: This programs version
VERSION=1.0d1
# $PROGNAME: This programs name
PROGNAME=`basename $0`
# If project not specified output usage and exit
if [ ! $1 ]
then
echo "USAGE: $PROGNAME <jjfile>"
exit 1
fi
# $PROJECT: The jj file to run
PROJECT=`basename $1 .jj`
# $MAKEFILE: An automatically generated makefile
MAKEFILE=$PROJECT.mk
# $FORCE: forces the regeneration of the makefile
FORCE=$2
# If the specified project does not exist than exit
if [ ! -f $PROJECT.jj ]
then
echo ERROR: $PROGNAME: File not found $PROJECT.jj
exit 1
fi
# If forcing makefile regeneration than delete the makefile
if [ $FORCE ]
then
rm $MAKEFILE
fi
# If the makefile does not exist than generate it
if [ ! -f $MAKEFILE ]
then
echo $PROGNAME: Generating $MAKEFILE...
#### START jjrun_makefile_header_here_doc
cat > $MAKEFILE <<jjrun_makefile_header_here_doc
# Automatically generated makefile for $PROJECT by $PROGNAME $VERSION
# Copyright (C) 2006 Andrew Tomazos <andrew@tomazos.com>
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
# ${PROJECT}: Name of the project
PROJECT=$PROJECT
# ${MAKEFILE}: Filename of this makefile
MAKEFILE=$MAKEFILE
# ${PROGFILE}: Filepath of $PROGNAME
PROGFILE=$PROGFILE
jjrun_makefile_header_here_doc
#### END jjrun_makefile_header_here_doc
#### START jjrun_makefile_main_here_doc
cat >> $MAKEFILE <<'jjrun_makefile_main_here_doc'
# ${JJ}: The original .jj file
JJ=${PROJECT}.jj
# ${AUTOGENS}: The automatically generated classed of javacc
AUTOGENS= \
${PROJECT} \
${PROJECT}Constants \
${PROJECT}TokenManager
# ${BOILERS}: The boilerplate classes generated by javacc
BOILERS= \
SimpleCharStream \
ParseException \
Token \
TokenMgrError
# ${OBJECTS}: The names of the classes output by javacc
OBJECTS=${AUTOGENS} ${BOILERS}
# ${BOILERSOURCES}: The boilerplater sources files output by javacc
BOILERSOURCES=$(addsuffix .java, ${BOILERS})
# ${SOURCES}: The source files output by javacc
SOURCES=$(addsuffix .java, ${OBJECTS})
# ${CLASSES}: The class files compiled with javac from the output of javacc
CLASSES=$(addsuffix .class, ${OBJECTS})
# ${MANIFEST}: filename of the manifest for the final jar file
MANIFEST=${PROJECT}.mf
# ${JAR}: filename of the final jar file
JAR=${PROJECT}.jar
# make build rule to make JAR
build: ${JAR}
# make ${JAR}: build the jar file
${JAR}: ${SOURCES} ${MANIFEST}
@echo ${MAKEFILE}: Building ${JAR}...
javac ${SOURCES}
jar cvfm ${JAR} ${MANIFEST} ${CLASSES}
rm ${CLASSES}
# make clean: remove all generated jar files
clean:
@echo ${MAKEFILE}: Cleaning ${PROJECT}...
@-rm ${JAR} ${SOURCES} ${MANIFEST}
# make ${SOURCES}: compile the jj file into java sources
${SOURCES}: ${JJ}
@echo ${MAKEFILE}: Compiling ${JJ}...
@javacc ${JJ}
touch -c ${BOILERSOURCES}
# make ${MANIFEST}: rule to make
${MANIFEST}:
@echo ${MAKEFILE}: Creating manifest...
@echo Manifest-Version: 1.0 > ${MANIFEST}
@echo Main-Class: ${PROJECT} >> ${MANIFEST}
${MAKEFILE}: ${PROGFILE}
@echo ${MAKEFILE}: Regenerating ${MAKEFILE}
@${PROGFILE} ${PROJECT} FORCE
jjrun_makefile_main_here_doc
# END jjrun_makefile_main_here_doc
fi
# If this was a forced regeneration than stop here
if [ $FORCE ]
then
exit 0
fi
# Execute the makefile to rebuild the jar file if necessary
echo $PROGNAME: Executing $MAKEFILE...
make -f $MAKEFILE
# Execute the jar file
echo $PROGNAME: Executing $PROJECT.jar...
java -jar $PROJECT.jar
#!/bin/sh
JAR="`dirname $0`/lib/javacc.jar"
case "`uname`" in
CYGWIN*) JAR="`cygpath --windows -- "$JAR"`" ;;
esac
java -classpath "$JAR" jjtree "$@"
@echo off
java -classpath "%~f0\..\lib\javacc.jar" jjtree %1 %2 %3 %4 %5 %6 %7 %8 %9
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<!--
Copyright (c) 2006, Sun Microsystems, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the Sun Microsystems, Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
-->
<head>
<title>JavaCC: CharStream Classes MiniTutorial</title>
<!-- Changed by: Michael Van De Vanter, 14-Jan-2003 -->
</head>
<body bgcolor="#FFFFFF" >
<h1>JavaCC [tm]: CharStream Classes MiniTutorial</h1>
<p>
This document describes in some detail the methods of the CharStream
classes. Note that some of the details may not be relevant for the
CharStream interface (to be used with USER_CHAR_STREAM).
</p>
<p>
There are 4 different kinds of char stream classes that are generated
based on combinations of various options.
</p>
<ul>
<li> <h3>ASCII_CharStream</h3>
Generated when neither of the two options - <tt>UNICODE_INPUT</tt>
or <tt>JAVA_UNICODE_ESCAPE</tt> is set.
<p>
This class treats the input as a stream of 1-byte (ISO-LATIN1)
characters. Note that this class can also be used to parse
binary files. It just reads a byte and returns it as a 16 bit
quantity to the lexical analyzer. So any character returned by
this class will be in the range <tt>'\u0000'-'\u00ff'</tt>.
</p>
</li>
<li> <h3>ASCII_UCodeESC_CharStream</h3>
Generated when the option <tt>JAVA_UNICODE_ESCAPE</tt> is set
and the <tt>UNICODE_INPUT</tt> option is not set.
<p>
This class treats the input as a stream of 1-byte characters.
However, the special escape sequence
</p>
<p>
<tt>("\\\\")* "\\" ("u")+</tt> - (<i>odd number of backslahes followed
by one or more 'u's.</i>)
</p>
<p>
is treated as a tag indicating that the next 4 bytes following
the tag will be hexadecimal digits forming a 4-digit hex number
whose value will be treated as the value of the character at the
position indicated by the first backslash. Note that this value
can be anything in the range <tt>0x0-0xffff</tt>.
</p>
</li>
<li> <h3>UCode_CharStream</h3>
Generated when the option <tt>UNICODE_INPUT</tt> is set and
the option <tt>JAVA_UNICODE_ESCAPE</tt> is not set.
<p>
This class treats the input as a stream of 2-byte characters. So
it reads 2 bytes <tt>b1</tt> and <tt>b2</tt> and returns them as
a single character using the expression <tt> b1 &lt;&lt; 8 | b2 </tt>
assuming bigendian order. So in particular all the characters in
the range <tt>0x00-0xff</tt> are assumed to be stored as 2 bytes
with the first (higher-order) byte being 0.
</p>
</li>
<li> <h3>UCode_UCodeESC_CharStream</h3>
Generated when both the options <tt>UNICODE_INPUT</tt> and
<tt>JAVA_UNICODE_ESCAPE</tt> are set.
<p>
This class input is a stream of 2-byte characters (just
like the UCode_CharStream class) and the special escape sequence
</p>
<p>
<tt>("\\\\")* "\\" ("u")+</tt> - (<i>odd number of backslahes followed
by one or more 'u's.</i>)
</p>
<p>
is treated as a tag indicating that the next 4 2-byte characters
following the tag will be hexadecimal digits forming a 4-digit hex
number whose value will be treated as the value of the character at the
position indicated by the first backslash. Note that this value
can be any value in the range <tt>0x0-0xffff</tt>. Also note that
the backslash(es) and u(s) are all assumed to be given as 2-byte
characters (with the higher order byte value being 0).
</p>
</li>
</ul>
<h4>
Note : None of the above classes can be used to read characters in a
mixed mode, i.e., some characters given as 1-byte characters and others
as 2-byte characters. To do this, you need to set USER_CHAR_STREAM
option to true and define your own char stream.
</h4>
<hr />
<p>
(Throughout the following, we use the notation XXXCharStream that stands
for any of the above described 4 classes.)
</p>
<h3>Constructors</h3>
<ul>
<li><tt>
public XXXCharStream(java.io.InputStream dstream,
int startline, int startcolumn)
</tt>
<p>
Takes an input stream, starting line and column numbers and constructs a
CharStream object. It also creates buffers of initial size 4K for buffering the
characters and also for line and column numbers for each of those characters.
</p>
</li>
<li><tt> public XXXCharStream(java.io.InputStream dstream,
int startline, int startcolumn, int buffersize)
</tt>
<p>
Takes an input stream, starting line and column numbers and constructs a
CharStream object. It also creates buffers of initial size <tt>buffsize</tt> for buffering the
characters and also for line and column numbers for each of those characters.
</p>
<p>
So when you have an estimate on the maximum size of any token that can occur,
you can use that size to optimize the buffer sizes. Note, however, that
these sizes are only initial sizes and they will be expanded as and when
needed (in 2K steps).
</p>
</li>
</ul>
<h3>Methods</h3>
<p>
All the following methods will be static or nonstatic depending on
whether the STATIC option is true or false at the generation time. Also only
those methods that users can use in their lexical actions (using the
<tt>input_stream</tt> variable of the lexical analyzer) are documented
here. Rest of the (public) methods are very tightly coupled with the
implementation of the lexical analyzer and thus <b> should not </b> be
used in lexical actions. In the future when we adopt version 1.1 of the Java [tm] programming language, we will
streamline this by making that part of the interface an innerclass to
the lexical analyzer.
</p>
<ul>
<li> <tt>public final char readChar() throws java.io.IOException</tt>
<p>
This method returns the next "character" in the input according
to the rules of the CharStream class as described above. It will
throw <tt>java.io.IOException</tt> if it reaches EOF during the
process of "constructing" the character. It also updates the line
and column number and buffers the character for any possible
backtracking that may be required later. It also stores the line
and column numbers for the same purpose.
</p>
</li>
<li> <tt> public final int getBeginLine() </tt>