Chapter 9. Controlling Build Output
Prev |  | Next

## Chapter 9. Controlling Build Output

A key aspect of creating a usable build configuration is providing useful output from the build, so its users can readily understand what the build is doing and get information about how to control the build. SCons provides several ways of controlling output from the build configuration to help make the build more useful and understandable.

## 9.1. Providing Build Help: the `Help` Function

It's often very useful to be able to give users some help that describes the specific targets, build options, etc., that can be used for your build. SCons provides the `Help` function to allow you to specify this help text:

    Help("""
    Type: 'scons program' to build the production program,
          'scons debug' to build the debug version.
    """)

Optionally, you can specify the `append` flag:

    Help("""
    Type: 'scons program' to build the production program,
          'scons debug' to build the debug version.
    """, append=True)

(Note the above use of the Python triple-quote syntax, which comes in very handy for specifying multi-line strings like help text.)

When the `SConstruct` or `SConscript` files contain a call to the `Help` function, the specified help text will be displayed in response to the SCons `-h` option:

    % scons -h
    scons: Reading SConscript files ...
    scons: done reading SConscript files.

    Type: 'scons program' to build the production program,
          'scons debug' to build the debug version.

    Use scons -H for help about SCons built-in command-line options.

The `SConscript` files may contain multiple calls to the `Help` function, in which case the specified text(s) will be concatenated when displayed. This allows you to define fragments of help text together with the corresponding feature, even if spread across multiple `SConscript` files. In this situation, the order in which the `SConscript` files are called will determine the order in which the `Help` functions are called, which will determine the order in which the various bits of text will get concatenated.

Calling `Help("text")` overwrites the help text that otherwise would be collected from any command-line options defined in `AddOption` calls. To preserve the `AddOption` help text, add the `append=True` keyword argument when calling `Help`. This also preserves the option help for the scons command itself. To preserve only the `AddOption` help, also add the `local_only=True` keyword argument. (This only matters the first time you call `Append`, on any subsequent calls the text you passed is added to the existing help text).

Another use would be to make the help text conditional on some variable. For example, suppose you only want to display a line about building a Windows-only version of a program when actually run on Windows. The following `SConstruct` file:

    env = Environment()

    Help("\nType: 'scons program' to build the production program.\n")

    if env['PLATFORM'] == 'win32':
        Help("\nType: 'scons windebug' to build the Windows debug version.\n")

Will display the complete help text on Windows:

    C:\>scons -h
    scons: Reading SConscript files ...
    scons: done reading SConscript files.

    Type: 'scons program' to build the production program.

    Type: 'scons windebug' to build the Windows debug version.

    Use scons -H for help about SCons built-in command-line options.

But only show the relevant option on a Linux or UNIX system:

    % scons -h
    scons: Reading SConscript files ...
    scons: done reading SConscript files.

    Type: 'scons program' to build the production program.

    Use scons -H for help about SCons built-in command-line options.

If there is no `Help` text in the `SConstruct` or `SConscript` files, SCons will revert to displaying its standard list that describes the SCons command-line options. This list is also always displayed whenever the `-H` option is used.

Prev |  | Next
8.4. Finding Installed Library Information: the `ParseConfig` Function | Home | 9.2. Controlling How SCons Prints Build Commands: the `$*COMSTR` Variables