<?xml version='1.0'?>

<!--
SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
SPDX-License-Identifier: MIT
SPDX-FileType: DOCUMENTATION

This file is processed by the bin/SConsDoc.py module.
-->

<!DOCTYPE sconsdoc [
    <!ENTITY % scons SYSTEM "../scons.mod">
    %scons;

    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
    %builders-mod;
    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
    %functions-mod;
    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
    %tools-mod;
    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
    %variables-mod;
]>

<section id="sect-mergeflags"
         xmlns="http://www.scons.org/dbxsd/v1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
<title>Merging Options into the Environment: the &MergeFlags; Function</title>

<para>

 &SCons; &consenvs; have a &f-link-MergeFlags; method
 that merges values from a passed-in argument into the &consenv;.
 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 &consvar;.
 If the argument is a string, &MergeFlags; calls the
 &f-link-ParseFlags; method to burst it out into a
 dictionary first, then acts on the result.

 </para>

 <para>

 &MergeFlags; tries to be intelligent about merging options,
 knowing that different &consvars; may have different needs.
 When merging options to any variable
 whose name ends in <literal>PATH</literal>,
 &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."

 </para>

 <scons_example name="mergeflags_MergeFlags1">
   <file name="SConstruct" printme="1">
env = Environment()
env.Append(CCFLAGS='-option -O3 -O1')
flags = {'CCFLAGS': '-whatever -O3'}
env.MergeFlags(flags)
print("CCFLAGS:", env['CCFLAGS'])
   </file>
 </scons_example>

 <scons_output example="mergeflags_MergeFlags1" suffix="1">
    <scons_output_command>scons -Q</scons_output_command>
 </scons_output>

 <para>

 Note that the default value for &cv-link-CCFLAGS;
 <!--
 [TODO: for when we make CLVar public]
 is a <varname>CLVar</varname>,
 -->
 is an internal &SCons; object
 which automatically converts
 the options you specify as a string into a list.

 </para>

 <scons_example name="mergeflags_MergeFlags2">
   <file name="SConstruct" printme="1">
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'])
   </file>
 </scons_example>

 <scons_output example="mergeflags_MergeFlags2" suffix="1">
    <scons_output_command>scons -Q</scons_output_command>
 </scons_output>

 <para>

 Note that the default value for &cv-link-CPPPATH;
 <!--
 [TODO: for when we make CLVar public]
 is a Python list, not a <varname>CLVar</varname>,
 -->
 is a normal &Python; list,
 so you should give its values as a list
 in the dictionary you pass to the &MergeFlags; function.

 </para>

 <para>

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

 </para>

 <scons_example name="mergeflags_MergeFlags3">
   <file name="SConstruct" printme="1">
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'])
   </file>
 </scons_example>

 <scons_output example="mergeflags_MergeFlags3" suffix="1">
    <scons_output_command>scons -Q</scons_output_command>
 </scons_output>

 <para>

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

 </para>

</section>
