Add a timings/Java configuration to time simple Java compilation.

Update timings/README.txt with doc of how to add timing configurations.

5 files changed, 195 insertions, 0 deletions

diff --git a/timings/Java/SConstruct b/timings/Java/SConstruct
new file mode 100644
index 00000000..62945625
--- /dev/null
+++ b/timings/Java/SConstruct
@@ -0,0 +1,25 @@
+#
+# __COPYRIGHT__
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+env = Environment()
+env.Java('classes', 'src')
diff --git a/timings/Java/TimeSCons-run.py b/timings/Java/TimeSCons-run.py
new file mode 100644
index 00000000..9414d57c
--- /dev/null
+++ b/timings/Java/TimeSCons-run.py
@@ -0,0 +1,55 @@
+#
+# __COPYRIGHT__
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+"""
+This configuration times simple Java compilation.
+
+We create $JAVA_COUNT on-disk Java files in a 'src' subdirectory,
+and the SConstruct file builds them.  That's it.
+"""
+
+import TestSCons
+
+# Full-build time of just under 10 seconds on ubuntu-timings slave,
+# as determined by bin/calibrate.py on 21 May 2010:
+#
+# run   1:  14.564:  JAVA_COUNT=100
+# run   2:   9.692:  JAVA_COUNT=68
+# run   3:   9.654:  JAVA_COUNT=68
+# run   4:   9.635:  JAVA_COUNT=68
+
+test = TestSCons.TimeSCons(variables={'JAVA_COUNT':68})
+
+test.subdir('src')
+
+contents = """\
+package src;
+public class j%04d {}
+"""
+
+for d in range(test.variables['JAVA_COUNT']):
+    test.write(['src', 'j%04d.java' % d], contents % d)
+
+test.main()
+
+test.pass_test()
diff --git a/timings/Java/config.js b/timings/Java/config.js
new file mode 100644
index 00000000..c0d688e6
--- /dev/null
+++ b/timings/Java/config.js
@@ -0,0 +1,3 @@
+var Config = {
+  'title': "timings/Java",
+};
diff --git a/timings/README.txt b/timings/README.txt
index e612aa1f..443d235b 100644
--- a/timings/README.txt
+++ b/timings/README.txt
@@ -32,3 +32,114 @@ in-line data.  This is typically done when it's necessary to create
 hundreds of identical input files or directories before running the
 timing test, to avoid cluttering our SCM system with hundreds of otherwise
 meaningless files.
+
+
+STRUCTURE OF A TIMING CONFIGURATION
+===================================
+
+A timing configuration should be in a subdirectory and should contain
+at least the following three files:
+
+    TimeSCons-run.py
+
+        The script that controls the timing run.  It looks a lot
+        like the test scripts (since it uses the same infrastructure)
+        except that you instantiate TestSCons.TimeSCons object, not a
+        TestSCons.TestSCons object.
+
+        Typically you want to initialize the object with a "variables"
+        dict containing one or more parameters whose values control the
+        scale of the configuration.  This would typically be the number
+        of source files, directories to scan, etc.  The TimeSCons-run.py
+        script can then use the value of those variables to generate that
+        many copies of input source files, or directories, or what have,
+        from in-line data, instead of having to check in a couple hundred
+        files for a large configuration.
+
+        These variables get passed to the timed SCons invocation as
+        ARGUMENT= arguments on the command line, so the SConstruct
+        file can use it to loop through the right number of files /
+        directories / what have you.
+
+    SConstruct
+
+        This is the actual SCons configuration that gets tested.  It has
+        access to the variable(s) that control the configuration as
+        ARGUMENTS from the command line.
+
+        It's possible for the SConstruct file to do additional set up of
+        input files and the like, but in general that should be kept to
+        a minimum.  We want what the SConscript file does to be dominated
+        by the actual execution we're timing, not initialization stuff,
+        so most initialization is better left in TimeSCons-run.py.
+
+    config.js
+
+        This gives our buildbot information about the timing configuration
+        (specifically, the title) for display.
+
+Note that it's perfectly acceptable to check in additional files that
+may be necessary for your configuration.  They'll get copied to the
+temporary directory used to run the timing.
+
+
+CALIBRATING YOUR TIMING CONFIGURATION
+=====================================
+
+One goal we have for timing configurations is that they should take
+about 10 seconds to run on our buildbot timing system, which is an older,
+slower system than most.
+
+Per above, you presumably defined one or more variables that control the
+"size" of your configuration:  the number of input files, directories,
+etc.  The timing infrastructure actually reports the value of these
+variables in a way that lets us automate the process of adjusting the
+variable values to run within a specified amount of time.
+
+The bin/calibrate.py will run your configuration repeatedly, adjusting
+the value(s) of the variable(s) that control your configuration until
+it gets three successive runs that take between 9.5 and 10.0 seconds
+(by default, options let you adjust the range):
+
+    $ python bin/calibrate.py timings/MyNewTimingConfiguration/TimeSCons-run.py
+    run   1:   3.124:  TARGET_COUNT=50
+    run   2:  11.936:  TARGET_COUNT=160
+    run   3:   9.175:  TARGET_COUNT=134
+    run   4:  10.489:  TARGET_COUNT=146
+    run   5:   9.798:  TARGET_COUNT=139
+    run   6:   9.695:  TARGET_COUNT=139
+    run   7:   9.670:  TARGET_COUNT=139
+    $
+
+If you have multiple variables, it will adjust *all* of the variables
+on each run.  In other words, the proportion between your variables will
+remain (relatively) constant.
+
+Of course, this needs to be run on a quiet system for the numbers
+to converge.  And what you really need to do before committing a
+configuration is run bin/calibrate.py on the actual system that runs
+our Buildbot timings.  For that, see Bill Deegan or Steven Knight.
+
+Once you have "good" values for your variables, put them in your
+TimeSCons-run.py and you should be good to go.  Note that we've started a
+convention of also pasting the run output from calibrate.py into comments
+in the TimeSCons-run.py, just to preserve some of the historical context
+that led to certain values being chosen.
+
+
+ADDING A NEW TIMING CONFIGURATION
+=================================
+
+In addition to creating a subdirectory with at least the pieces listed
+above in the "STRUCTURE" section and "CALIBRATING" your variable(s),
+you need to update the following file in this directory:
+
+    index.html
+
+        Add an entry to the test_map dictionary for the subdirectory
+        you just created.
+
+That should be it before checkin.  After checkin, one of the Buildbot
+administrators (currently Bill Deegan or Steven Knight) needs to update
+and restart the Buildbot master so that it will start executing the
+build step to run the new timing configuration.
diff --git a/timings/index.html b/timings/index.html
index 40738321..cd4bc8b8 100644
--- a/timings/index.html
+++ b/timings/index.html
@@ -49,6 +49,7 @@
         };
         var test_map = {
             'CPPPATH': 'CPPPATH',
+            'Java': 'Java',
             'JTimer': 'JTimer',
             'hundred': 'hundred',
         };