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.
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.