Once the lab environment has been set up, one needs to run the experiment and record the data necessary to be able to reproduce the experiment later. The tool labrun accomplishes this. There are three main tasks performed by labrun
In its simplest form, labrun is executed in a directory containing the source code for the experiment's executable. For example:
labrun steiner -v closed 41 30will cause the following two things to happen:
The labrun tool will generally create at least two files:
one that contains the output of the experiment (the .out file) and
another that records the information about the environment in which the output
was created (the .log file; see Section ).
Additionally, a file with extension
.err may be generated if the experiment program writes output to
the error stream. The .out and .err files are generated only
if the program writes output to the standard output and standard error
streams, respectively. The .log file is always generated. The names
of the generated files all have the same format:
<exp_name>-<date and time>.<ext>,
<date and time> has the format
<exp_name> is, by default, the
name of the executable used by logrun.
By default, these files are
created in a subdirectory lab_log in the current directory.
For the example above, the name of the log file would be something like
./lab_log/steiner-2002-05-21-093412.log. This file is also
accessible as ./lab_log/current.log, which is a link to the most
recent log file.
Such a ``current'' link is created for each of the three possible
files generated by labrun, thus making it easier to examine the results
of the last experiment or to observe the progress of the current experiment as
it is running.
Some of the options available for labrun allow one to specify
<date and time>to use in the files created.
labrun --cvs .:/home/hert/src --log ../lab --name example --tag closed_41_30 steiner -v closed 41 30will check if the code in the current directory as well as the directory /home/hert/src is up to date and, if so, will execute the program steiner in the current directory. It will place the created log and output files in a subdirectory lab in the current directory's parent directory, creating this subdirectory if it does not already exist. The files created will use example for
<exp_name>and closed_41_30 instead of
<date and time>in the name. Thus the name of the log file for this experiment would be
Other options for labrun allow one to indicate: that no CVS directories should be checked; that the program should be executed in a different directory; that a specific version of the source code should be used instead of the current one (particularly useful in conjunction with labmex); additional things to be recorded in the .log file; that all output from the experiment should be recorded in a single file (the .log file) instead of spread over possibly three files (the .log, .out, and .err files); and that the experiment should be run in the background and should notify the user upon completion.
Options may also be specified via a local or global resource file (Section ). Such resource files are searched for when processing the input for labrun and, if present, the information recorded there will be used to augment the input provided at the command line. In cases of conflict, command-line arguments take precedence over data provided in the local labrc file, which takes precedence over data provided in the global .labrc file.