doc/user/mergeflags.xml

   1 <!--
   2
   3   __COPYRIGHT__
   4
   5   Permission is hereby granted, free of charge, to any person obtaining
   6   a copy of this software and associated documentation files (the
   7   "Software"), to deal in the Software without restriction, including
   8   without limitation the rights to use, copy, modify, merge, publish,
   9   distribute, sublicense, and/or sell copies of the Software, and to
  10   permit persons to whom the Software is furnished to do so, subject to
  11   the following conditions:
  12
  13   The above copyright notice and this permission notice shall be included
  14   in all copies or substantial portions of the Software.
  15
  16   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  17   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  18   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20   LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23
  24 -->
  25
  26  <para>
  27
  28  &SCons; construction environments have a &MergeFlags; method
  29  that merges a dictionary of values into the construction environment.
  30  &MergeFlags; treats each value in the dictionary
  31  as a list of options such as one might pass to a command
  32  (such as a compiler or linker).
  33  &MergeFlags; will not duplicate an option
  34  if it already exists in the construction environment variable.
  35
  36  </para>
  37
  38  <para>
  39
  40  &MergeFlags; tries to be intelligent about merging options.
  41  When merging options to any variable
  42  whose name ends in <varname>PATH</varname>,
  43  &MergeFlags; keeps the leftmost occurrence of the option,
  44  because in typical lists of directory paths,
  45  the first occurrence "wins."
  46  When merging options to any other variable name,
  47  &MergeFlags; keeps the rightmost occurrence of the option,
  48  because in a list of typical command-line options,
  49  the last occurrence "wins."
  50
  51  </para>
  52
  53  <programlisting>
  54     env = Environment()
  55     env.Append(CCFLAGS = '-option -O3 -O1')
  56     flags = { 'CCFLAGS' : '-whatever -O3' }
  57     env.MergeFlags(flags)
  58     print env['CCFLAGS']
  59  </programlisting>
  60
  61  <screen>
  62     % <userinput>scons -Q</userinput>
  63     ['-option', '-O1', '-whatever', '-O3']
  64     scons: `.' is up to date.
  65  </screen>
  66
  67  <para>
  68
  69  Note that the default value for &cv-link-CCFLAGS;
  70  <!--
  71  [TODO: for when we make CLVar public]
  72  is a <varname>CLVar</varname>,
  73  -->
  74  is an internal &SCons; object
  75  which automatically converts
  76  the options we specified as a string into a list.
  77
  78  </para>
  79
  80  <programlisting>
  81     env = Environment()
  82     env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include'])
  83     flags = { 'CPPPATH' : ['/usr/opt/include', '/usr/local/include'] }
  84     env.MergeFlags(flags)
  85     print env['CPPPATH']
  86  </programlisting>
  87
  88  <screen>
  89     % <userinput>scons -Q</userinput>
  90     ['/include', '/usr/local/include', '/usr/include', '/usr/opt/include']
  91     scons: `.' is up to date.
  92  </screen>
  93
  94  <para>
  95
  96  Note that the default value for &cv-link-CPPPATH;
  97  <!--
  98  [TODO: for when we make CLVar public]
  99  is a Python list, not a <varname>CLVar</varname>,
 100  -->
 101  is a normal Python list,
 102  so we must specify its values as a list
 103  in the dictionary we pass to the &MergeFlags; function.
 104
 105  </para>
 106
 107  <para>
 108
 109  If &MergeFlags; is passed anything other than a dictionary,
 110  it calls the &ParseFlags; method to convert it into a dictionary.
 111
 112  </para>
 113
 114  <programlisting>
 115     env = Environment()
 116     env.Append(CCFLAGS = '-option -O3 -O1')
 117     env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include'])
 118     env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include')
 119     print env['CCFLAGS']
 120     print env['CPPPATH']
 121  </programlisting>
 122
 123  <screen>
 124     % <userinput>scons -Q</userinput>
 125     ['-option', '-O1', '-whatever', '-O3']
 126     ['/include', '/usr/local/include', '/usr/include', '/usr/opt/include']
 127     scons: `.' is up to date.
 128  </screen>
 129
 130  <para>
 131
 132  In the combined example above,
 133  &ParseFlags; has sorted the options into their corresponding variables
 134  and returned a dictionary for &MergeFlags; to apply
 135  to the construction variables
 136  in the specified construction environment.
 137
 138  </para>