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.
""")
(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 such 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 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 split up the
help text 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.
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 completely 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 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 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.