Chapter 8. Automatically Putting Command-line Options into their Construction Variables

This chapter describes the MergeFlags, ParseFlags, and ParseConfig methods of a construction environment, as well as the parse_flags keyword argument to methods that construct environments.

8.1. Merging Options into the Environment: the MergeFlags Function

SCons construction environments have a MergeFlags method that merges values from a passed-in argument into the construction environment. If the argument is a dictionary, MergeFlags treats each value in the dictionary as a list of options you would pass to a command (such as a compiler or linker). MergeFlags will not duplicate an option if it already exists in the construction variable. If the argument is a string, MergeFlags calls the ParseFlags method to burst it out into a dictionary first, then acts on the result.

MergeFlags tries to be intelligent about merging options, knowing that different construction variables may have different needs. When merging options to any variable whose name ends in PATH, MergeFlags keeps the leftmost occurrence of the option, because in typical lists of directory paths, the first occurrence "wins." When merging options to any other variable name, MergeFlags keeps the rightmost occurrence of the option, because in a list of typical command-line options, the last occurrence "wins."

env = Environment()
env.Append(CCFLAGS='-option -O3 -O1')
flags = {'CCFLAGS': '-whatever -O3'}
env.MergeFlags(flags)
print("CCFLAGS:", env['CCFLAGS'])
   
% scons -Q
CCFLAGS: ['-option', '-O1', '-whatever', '-O3']
scons: `.' is up to date.

Note that the default value for $CCFLAGS is an internal SCons object which automatically converts the options you specify as a string into a list.

env = Environment()
env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include'])
flags = {'CPPPATH': ['/usr/opt/include', '/usr/local/include']}
env.MergeFlags(flags)
print("CPPPATH:", env['CPPPATH'])
   
% scons -Q
CPPPATH: ['/include', '/usr/local/include', '/usr/include', '/usr/opt/include']
scons: `.' is up to date.

Note that the default value for $CPPPATH is a normal Python list, so you should give its values as a list in the dictionary you pass to the MergeFlags function.

If MergeFlags is passed anything other than a dictionary, it calls the ParseFlags method to convert it into a dictionary.

env = Environment()
env.Append(CCFLAGS='-option -O3 -O1')
env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include'])
env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include')
print("CCFLAGS:", env['CCFLAGS'])
print("CPPPATH:", env['CPPPATH'])
   
% scons -Q
CCFLAGS: ['-option', '-O1', '-whatever', '-O3']
CPPPATH: ['/include', '/usr/local/include', '/usr/include', '/usr/opt/include']
scons: `.' is up to date.

In the combined example above, ParseFlags has sorted the options into their corresponding variables and returned a dictionary for MergeFlags to apply to the construction variables in the specified construction environment.