timings/README.txt

   1 # __COPYRIGHT__
   2
   3 This directory contains timing configurations for SCons.
   4
   5 Each configuration exists in a subdirectory.  The controlling script
   6 is named TimeSCons-run.py for the configuration.  The TimeSCons-run.py
   7 scripts use TestSCons.TimeSCons, a subclass of TestSCons.TestSCons (both
   8 defined in ../testing/framework/TestSCons.py), to manage execution of the
   9 timing runs.
  10
  11 Unlike the TestSCons.TestSCons base class, the TestSCons.TimeSCons
  12 subclass copies the contents of its containing directory to the temporary
  13 working directory.  (It avoids copying the .svn directory, and any files
  14 or directories that start with the string "TimeSCons-".)  This allows
  15 the timing configuration files to be checked in directly to our source
  16 code management system, instead of requiring that they be created from
  17 in-line data inside the script.
  18
  19 The simplest-possible TimeSCons-run.py script would look like:
  20
  21     import TestSCons
  22     TestSCons.TimeSCons().main()
  23
  24 The above script would end up executing a SConstruct file configuration
  25 in a temporary directory.  The main() method is the standard interface
  26 for a timing run.  See its docstring for precisely what it does.
  27
  28 Although the TestSCons.TimeSCons subclass copies its directory contents to
  29 a temporary working directory for the timing run, because it is a subclass
  30 of TestSCons.TestSCons, it *can* also create files or directories from
  31 in-line data.  This is typically done when it's necessary to create
  32 hundreds of identical input files or directories before running the
  33 timing test, to avoid cluttering our SCM system with hundreds of otherwise
  34 meaningless files.
  35
  36
  37 STRUCTURE OF A TIMING CONFIGURATION
  38 ===================================
  39
  40 A timing configuration should be in a subdirectory and should contain
  41 at least the following three files:
  42
  43     TimeSCons-run.py
  44
  45         The script that controls the timing run.  It looks a lot
  46         like the test scripts (since it uses the same infrastructure)
  47         except that you instantiate TestSCons.TimeSCons object, not a
  48         TestSCons.TestSCons object.
  49
  50         Typically you want to initialize the object with a "variables"
  51         dict containing one or more parameters whose values control the
  52         scale of the configuration.  This would typically be the number
  53         of source files, directories to scan, etc.  The TimeSCons-run.py
  54         script can then use the value of those variables to generate that
  55         many copies of input source files, or directories, or what have,
  56         from in-line data, instead of having to check in a couple hundred
  57         files for a large configuration.
  58
  59         These variables get passed to the timed SCons invocation as
  60         ARGUMENT= arguments on the command line, so the SConstruct
  61         file can use it to loop through the right number of files /
  62         directories / what have you.
  63
  64     SConstruct
  65
  66         This is the actual SCons configuration that gets tested.  It has
  67         access to the variable(s) that control the configuration as
  68         ARGUMENTS from the command line.
  69
  70         It's possible for the SConstruct file to do additional set up of
  71         input files and the like, but in general that should be kept to
  72         a minimum.  We want what the SConscript file does to be dominated
  73         by the actual execution we're timing, not initialization stuff,
  74         so most initialization is better left in TimeSCons-run.py.
  75
  76     config.js
  77
  78         This gives our buildbot information about the timing configuration
  79         (specifically, the title) for display.
  80
  81 Note that it's perfectly acceptable to check in additional files that
  82 may be necessary for your configuration.  They'll get copied to the
  83 temporary directory used to run the timing.
  84
  85
  86 RUNNING YOUR TIMING CONFIGURATION
  87 =================================
  88
  89 Because the TimeSCons.py module is a subclass of the whole TestSCons
  90 hierarchy, you use a normal runtest.py invocation to run the timings
  91 configuration:
  92
  93     $ python runtest.py timings/Configuration/TimeSCons-run.py
  94
  95 This runs the entire timing configuration, which actually runs SCons
  96 itself three times:
  97
  98     1)  First, with the --help option, to exit immediately after
  99         reading the SConscript file(s).  This allows us to get a
 100         rough independent measurement of how much startup cost is
 101         involved in this configuration, so that the amount can be
 102         discounted from the
 103
 104     2)  A full build.
 105
 106     3)  An rebuild of the full build, which is presumably up-to-date.
 107
 108 When you execute runtest.py from the command line, the  output of
 109 each SCons run is printed on standard output.  (Note this means
 110 that the output can get pretty large if the timing configuration
 111 involves thousands of files.)
 112
 113 The collected memory and time statistics for each run are printed
 114 on standard output, each with the prefix "TRACE:".  These are the
 115 lines that the buildbot grabs to collect the timing statistics for
 116 the graphs available on the web site.
 117
 118
 119 CALIBRATING YOUR TIMING CONFIGURATION
 120 =====================================
 121
 122 One goal we have for timing configurations is that they should take
 123 about 10 seconds to run on our buildbot timing system, which is an older,
 124 slower system than most.
 125
 126 Per above, you presumably defined one or more variables that control the
 127 "size" of your configuration:  the number of input files, directories,
 128 etc.  The timing infrastructure actually reports the value of these
 129 variables in a way that lets us automate the process of adjusting the
 130 variable values to run within a specified amount of time.
 131
 132 The bin/calibrate.py will run your configuration repeatedly, adjusting
 133 the value(s) of the variable(s) that control your configuration until
 134 it gets three successive runs that take between 9.5 and 10.0 seconds
 135 (by default, options let you adjust the range):
 136
 137     $ python bin/calibrate.py timings/MyNewTimingConfiguration/TimeSCons-run.py
 138     run   1:   3.124:  TARGET_COUNT=50
 139     run   2:  11.936:  TARGET_COUNT=160
 140     run   3:   9.175:  TARGET_COUNT=134
 141     run   4:  10.489:  TARGET_COUNT=146
 142     run   5:   9.798:  TARGET_COUNT=139
 143     run   6:   9.695:  TARGET_COUNT=139
 144     run   7:   9.670:  TARGET_COUNT=139
 145     $
 146
 147 If you have multiple variables, it will adjust *all* of the variables
 148 on each run.  In other words, the proportion between your variables will
 149 remain (relatively) constant.
 150
 151 Of course, this needs to be run on a quiet system for the numbers
 152 to converge.  And what you really need to do before committing a
 153 configuration is run bin/calibrate.py on the actual system that runs
 154 our Buildbot timings.  For that, see Bill Deegan or Steven Knight.
 155
 156 Once you have "good" values for your variables, put them in your
 157 TimeSCons-run.py and you should be good to go.  Note that we've started a
 158 convention of also pasting the run output from calibrate.py into comments
 159 in the TimeSCons-run.py, just to preserve some of the historical context
 160 that led to certain values being chosen.
 161
 162
 163 ADDING A NEW TIMING CONFIGURATION
 164 =================================
 165
 166 In addition to creating a subdirectory with at least the pieces listed
 167 above in the "STRUCTURE" section and "CALIBRATING" your variable(s),
 168 you need to update the following file in this directory:
 169
 170     index.html
 171
 172         Add an entry to the test_map dictionary for the subdirectory
 173         you just created.
 174
 175 That should be it before checkin.  After checkin, one of the Buildbot
 176 administrators (currently Bill Deegan or Steven Knight) needs to update
 177 and restart the Buildbot master so that it will start executing the
 178 build step to run the new timing configuration.