10.1.1. Not Having to Specify Command-Line Options Each Time: the SCONSFLAGS Environment Variable

Users may find themselves supplying the same command-line options every time they run SCons. For example, you might find it saves time to specify a value of -j 2 to have SCons run up to two build commands in parallel. To avoid having to type -j 2 by hand every time, you can set the external environment variable SCONSFLAGS to a string containing command-line options that you want SCons to use.

If, for example, you're using a POSIX shell that's compatible with the Bourne shell, and you always want SCons to use the -Q option, you can set the SCONSFLAGS environment as follows:

        % scons
        scons: Reading SConscript files ...
        scons: done reading SConscript files.
        scons: Building targets ...
            ... [build output] ...
        scons: done building targets.
        % export SCONSFLAGS="-Q"
        % scons
            ... [build output] ...
      

Users of csh-style shells on POSIX systems can set the SCONSFLAGS environment as follows:

        $ setenv SCONSFLAGS "-Q"
      

Windows users may typically want to set the SCONSFLAGS in the appropriate tab of the System Properties window.

10.1.2. Getting Values Set by Command-Line Options: the GetOption Function

SCons provides the GetOption function to get the values set by the various command-line options. One common use of this is to check whether or not the -h or --help option has been specified. Normally, SCons does not print its help text until after it has read all of the SConscript files, because it's possible that help text has been added by some subsidiary SConscript file deep in the source tree hierarchy. Of course, reading all of the SConscript files takes extra time.

If you know that your configuration does not define any additional help text in subsidiary SConscript files, you can speed up the command-line help available to users by using the GetOption function to load the subsidiary SConscript files only if the the user has not specified the -h or --help option, like so:

        if not GetOption('help'):
            SConscript('src/SConscript', export='env')
      

In general, the string that you pass to the GetOption function to fetch the value of a command-line option setting is the same as the "most common" long option name (beginning with two hyphen characters), although there are some exceptions. The list of SCons command-line options and the GetOption strings for fetching them, are available in the Section 10.1.4 section, below.

10.1.3. Setting Values of Command-Line Options: the SetOption Function

You can also set the values of SCons command-line options from within the SConscript files by using the SetOption function. The strings that you use to set the values of SCons command-line options are available in the Section 10.1.4 section, below.

One use of the SetOption function is to specify a value for the -j or --jobs option, so that users get the improved performance of a parallel build without having to specify the option by hand. A complicating factor is that a good value for the -j option is somewhat system-dependent. One rough guideline is that the more processors your system has, the higher you want to set the -j value, in order to take advantage of the number of CPUs.

For example, suppose the administrators of your development systems have standardized on setting a NUM_CPU environment variable to the number of processors on each system. A little bit of Python code to access the environment variable and the SetOption function provide the right level of flexibility:

        import os
        num_cpu = int(os.environ.get('NUM_CPU', 2))
        SetOption('num_jobs', num_cpu)
        print "running with -j", GetOption('num_jobs')
      

The above snippet of code sets the value of the --jobs option to the value specified in the $NUM_CPU environment variable. (This is one of the exception cases where the string is spelled differently from the from command-line option. The string for fetching or setting the --jobs value is num_jobs for historical reasons.) The code in this example prints the num_jobs value for illustrative purposes. It uses a default value of 2 to provide some minimal parallelism even on single-processor systems:

        % scons -Q
        running with -j 2
        scons: `.' is up to date.
      

But if the $NUM_CPU environment variable is set, then we use that for the default number of jobs:

        % export NUM_CPU="4"
        % scons -Q
        running with -j 4
        scons: `.' is up to date.
      

But any explicit -j or --jobs value the user specifies an the command line is used first, regardless of whether or not the $NUM_CPU environment variable is set:

        % scons -Q -j 7
        running with -j 7
        scons: `.' is up to date.
        % export NUM_CPU="4"
        % scons -Q -j 3
        running with -j 3
        scons: `.' is up to date.
      

10.1.4. Strings for Getting or Setting Values of SCons Command-Line Options

The strings that you can pass to the GetOption and SetOption functions usually correspond to the first long-form option name (beginning with two hyphen characters: --), after replacing any remaining hyphen characters with underscores.

The full list of strings and the variables they correspond to is as follows:

10.1.5. Adding Custom Command-Line Options: the AddOption Function

SCons also allows you to define your own command-line options with the AddOption function. The AddOption function takes the same arguments as the optparse.add_option function from the standard Python library. [1] Once you have added a custom command-line option with the AddOption function, the value of the option (if any) is immediately available using the standard GetOption function. (The value can also be set using SetOption, although that's not very useful in practice because a default value can be specified in directly in the AddOption call.)

One useful example of using this functionality is to provide a --prefix for users:

        AddOption('--prefix',
                  dest='prefix',
                  type='string',
                  nargs=1,
                  action='store',
                  metavar='DIR',
                  help='installation prefix')

        env = Environment(PREFIX = GetOption('prefix'))

        installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in')
        Default(installed_foo)
      

The above code uses the GetOption function to set the $PREFIX construction variable to any value that the user specifies with a command-line option of --prefix. Because $PREFIX will expand to a null string if it's not initialized, running SCons without the option of --prefix will install the file in the /usr/bin/ directory:

        % scons -Q -n
        Install file: "foo.in" as "/usr/bin/foo.in"
      

But specifying --prefix=/tmp/install on the command line causes the file to be installed in the /tmp/install/usr/bin/ directory:

        % scons -Q -n --prefix=/tmp/install
        Install file: "foo.in" as "/tmp/install/usr/bin/foo.in"