Extracting Function Timings

Extracting Memory Statistics

Extracting Object Counts

Extracting Execution Times

Help Text

The func Subcommand

The scons-time func subcommand displays timing information for a specific Python function within SCons. By default, it extracts information about the _main() function, which includes the Python profiler timing for all of SCons.

The scons-time func subcommand extracts function timing information from all the specified file arguments, which should be Python profiler output files. (Normally, these would be *.prof files generated by the scons-time run subcommand, but they can actually be generated by any Python profiler invocation.) All file name arguments will be globbed for on-disk files.

If no arguments are specified, then function timing information will be extracted from all *.prof files, or the subset of them with a prefix specified by the -p option.

Options include:

-C DIRECTORY, --chdir=DIRECTORY

-f FILE, --file=FILE

-fmt=FORMAT, --format=FORMAT

--func=NAME

-h, --help

-p STRING, --prefix=STRING

-t NUMBER, --tail=NUMBER

The help Subcommand

The mem Subcommand

The scons-time mem subcommand displays how much memory SCons uses.

The scons-time mem subcommand extracts memory use information from all the specified file arguments, which should be files containing output from running SCons with the --debug=memory option. (Normally, these would be *.log files generated by the scons-time run subcommand.) All file name arguments will be globbed for on-disk files.

If no arguments are specified, then memory information will be extracted from all *.log files, or the subset of them with a prefix specified by the -p option.

-C DIR, --chdir=DIR

-f FILE, --file=FILE

-fmt=FORMAT, --format=FORMAT

-h, --help

-p STRING, --prefix=STRING

--stage=STAGE

-t NUMBER, --tail=NUMBER

The obj Subcommand

The scons-time obj subcommand displays how many objects of a specific named type are created by SCons.

The scons-time obj subcommand extracts object counts from all the specified file arguments, which should be files containing output from running SCons with the --debug=count option. (Normally, these would be *.log files generated by the scons-time run subcommand.) All file name arguments will be globbed for on-disk files.

If no arguments are specified, then object counts will be extracted from all *.log files, or the subset of them with a prefix specified by the -p option.

-C DIR, --chdir=DIR

-f FILE, --file=FILE

-fmt=FORMAT, --format=FORMAT

-h, --help

-p STRING, --prefix=STRING

--stage=STAGE

-t NUMBER, --tail=NUMBER

The run Subcommand

The configuration to be tested is specified as a list of files or directories that will be unpacked or copied into a temporary directory in which SCons will be invoked. The scons-time run subcommand understands file suffixes like .tar, .tar.gz, .tgz and .zip and will unpack their contents into a temporary directory. If more than one argument is specified, each one will be unpacked or copied into the temporary directory "on top of" the previous archives or directories, so the expectation is that multiple specified archives share the same directory layout.

Once the file or directory arguments are unpacked or copied to the temporary directory, the scons-time run subcommand runs the requested version of SCons against the configuration three times:

Startup

Full build

Rebuild

Each invocation captures the output log file and a profile.

The scons-time run subcommand supports the following options:

-f FILE, --file=FILE

-h, --help

-n, --no-exec

--number=NUMBER

When used in conjunction with the --svn=URL option, NUMBER specifies one or more comma-separated Subversion revision numbers that will be retrieved automatically from the Subversion repository at the specified URL. Ranges of delta or revision numbers may be specified be separating two numbers with a hyphen (-).

Example:

% scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 .

-p STRING, --prefix=STRING

--python=PYTHON

-q, --quiet

-s DIR, --subdir=DIR

--scons=SCONS

--svn=URL, --subversion=URL

-v, --verbose

The time Subcommand

The scons-time time subcommand displays SCons execution times as reported by the scons --debug=time option.

The scons-time time subcommand extracts SCons timing from all the specified file arguments, which should be files containing output from running SCons with the --debug=time option. (Normally, these would be *.log files generated by the scons-time run subcommand.) All file name arguments will be globbed for on-disk files.

If no arguments are specified, then execution timings will be extracted from all *.log files, or the subset of them with a prefix specified by the -p option.

-C DIR, --chdir=DIR

-f FILE, --file=FILE

-fmt=FORMAT, --format=FORMAT

-h, --help

-p STRING, --prefix=STRING

-t NUMBER, --tail=NUMBER

--which=WHICH

Example

# The project doesn't use SCons natively (yet), so we're
# timing a separate set of SConscript files that we lay
# on top of the vanilla unpacked project tarball.
arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
# The subdirectory name contains the project version number,
# so tell scons-time to chdir there before building.
subdir = 'project-1.2'
# Set the prefix so output log files and profiles are named:
#     project-000-[012].{log,prof}
#     project-001-[012].{log,prof}
# etc.
prefix = 'project'
# The SConscript files being tested don't do any SConf
# configuration, so run their normal ./configure script
# before we invoke SCons.
initial_commands = [
    './configure',
]
# Only time building the bin/project executable.
targets = 'bin/project'
# Time against SCons revisions of the branches/core branch
subversion_url = 'http://scons.tigris.org/svn/scons/branches/core'