4.7. Customizing output
Prev Chapter 4. Build Engine API Next

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:

on_analysis

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.

pre_update

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.

post_update

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.

on_error

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:

target

The target object being considered.

level

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.

status

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

update

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

dependencies

A list of direct dependencies of the target.

Prev Up Next
4.6. Targets Home 4.8. Separate source and build trees