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

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

Prev |  | Next
7.4. Using the toolpath for external Tools | Home | 8.2. Merging Options While Creating Environment: the `parse_flags` Parameter