4.7. Customizing output

The SCons API supports the ability to customize, redirect, or suppress its printed output through user-defined functions. SCons has several pre-defined points in its build process at which it calls a function to (potentially) print output. User-defined functions can be specified for these call-back points when Build or Cleanis invoked:

	env.Build(target = '.',
	       on_analysis = dump_dependency,
	       pre_update = my_print_command,
	       post_update = my_error_handler)
	       on_error = my_error_handler)

The specific call-back points are:


Called for every object, immediately after the object has been analyzed to see if it's out-of-date. Typically used to print a trace of considered objects for debugging of unexpected dependencies.


Called for every object that has been determined to be out-of-date before its update function or command is executed. Typically used to print the command being called to update a target.


Called for every object after its update function or command has been executed. Typically used to report that a top-level specified target is up-to-date or was not remade.


Called for every error returned by an update function or command. Typically used to report errors with some string that will be identifiable to build-analysis tools.

Functions for each of these call-back points all take the same arguments:

	my_dump_dependency(target, level, status, update, dependencies)

where the arguments are:


The target object being considered.


Specifies how many levels the dependency analysis has recursed in order to consider the target. A value of 0 specifies a top-level target (that is, one passed to the Build or Clean method). Objects which a top-level target is directly dependent upon have a level of <1>, their direct dependencies have a level of <2>, etc. Typically used to indent output to reflect the recursive levels.


A string specifying the current status of the target ("unknown", "built", "error", "analyzed", etc.). A complete list will be enumerated and described during implementation.


The command line or function name that will be (or has been) executed to update the target.


A list of direct dependencies of the target.