doc/user/parseflags.xml

   1 <?xml version='1.0'?>
   2
   3 <!--
   4 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   5 SPDX-License-Identifier: MIT
   6 SPDX-FileType: DOCUMENTATION
   7
   8 This file is processed by the bin/SConsDoc.py module.
   9 -->
  10
  11 <!DOCTYPE sconsdoc [
  12     <!ENTITY % scons SYSTEM "../scons.mod">
  13     %scons;
  14
  15     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
  16     %builders-mod;
  17     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
  18     %functions-mod;
  19     <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
  20     %tools-mod;
  21     <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
  22     %variables-mod;
  23 ]>
  24
  25 <section id="sect-parseflags"
  26          xmlns="http://www.scons.org/dbxsd/v1.0"
  27          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  28          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  29 <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title>
  30
  31 <para>
  32
  33  &SCons; has a bewildering array of &consvars;
  34  for different types of options when building programs.
  35  Sometimes you may not know exactly which variable
  36  should be used for a particular option.
  37
  38  </para>
  39
  40  <para>
  41
  42  &SCons; &consenvs; have a &f-link-ParseFlags; method
  43  that takes a set of typical command-line options
  44  and distributes them into the appropriate &consvars;
  45  Historically, it was created to support the &f-link-ParseConfig; method,
  46  so it focuses on options used by the GNU Compiler Collection (GCC)
  47  for the C and C++ toolchains.
  48
  49  </para>
  50
  51  <para>
  52
  53  &ParseFlags; returns a dictionary containing the options
  54  distributed into their respective &consvars;.
  55  Normally, this dictionary would then be passed to &f-link-MergeFlags;
  56  to merge the options into a &consenv;,
  57  but the dictionary can be edited if desired to provide
  58  additional functionality.
  59  (Note that if the flags are not going to be edited,
  60  calling &MergeFlags; with the options directly
  61  will avoid an additional step.)
  62
  63  </para>
  64
  65  <scons_example name="parseflags_ex1">
  66    <file name="SConstruct" printme="1">
  67 env = Environment()
  68 d = env.ParseFlags("-I/opt/include -L/opt/lib -lfoo")
  69 for k, v in sorted(d.items()):
  70     if v:
  71         print(k, v)
  72 env.MergeFlags(d)
  73 env.Program("f1.c")
  74    </file>
  75    <file name="f1.c">
  76 int main() { return 0; }
  77    </file>
  78  </scons_example>
  79
  80  <scons_output example="parseflags_ex1" os="posix" suffix="1">
  81     <scons_output_command>scons -Q</scons_output_command>
  82  </scons_output>
  83
  84  <para>
  85
  86  Note that if the options are limited to generic types
  87  like those above,
  88  they will be correctly translated for other platform types:
  89
  90  </para>
  91
  92  <scons_output example="parseflags_ex1" os="win32" suffix="2">
  93     <scons_output_command>scons -Q</scons_output_command>
  94  </scons_output>
  95
  96  <para>
  97
  98  Since the assumption is that the flags are used for the GCC toolchain,
  99  unrecognized flags are placed in &cv-link-CCFLAGS;
 100  so they will be used for both C and C++ compiles:
 101
 102  </para>
 103
 104  <scons_example name="parseflags_ex2">
 105    <file name="SConstruct" printme="1">
 106 env = Environment()
 107 d = env.ParseFlags("-whatever")
 108 for k, v in sorted(d.items()):
 109     if v:
 110         print(k, v)
 111 env.MergeFlags(d)
 112 env.Program("f1.c")
 113    </file>
 114    <file name="f1.c">
 115 void main() { return 0; }
 116    </file>
 117  </scons_example>
 118
 119  <scons_output example="parseflags_ex2" suffix="1">
 120     <scons_output_command>scons -Q</scons_output_command>
 121  </scons_output>
 122
 123  <para>
 124
 125  &ParseFlags; will also accept a (recursive) list of strings as input;
 126  the list is flattened before the strings are processed:
 127
 128  </para>
 129
 130  <scons_example name="parseflags_ex3">
 131    <file name="SConstruct" printme="1">
 132 env = Environment()
 133 d = env.ParseFlags(["-I/opt/include", ["-L/opt/lib", "-lfoo"]])
 134 for k, v in sorted(d.items()):
 135     if v:
 136         print(k, v)
 137 env.MergeFlags(d)
 138 env.Program("f1.c")
 139    </file>
 140    <file name="f1.c">
 141 void main() { return 0; }
 142    </file>
 143  </scons_example>
 144
 145  <scons_output example="parseflags_ex3" suffix="1">
 146     <scons_output_command>scons -Q</scons_output_command>
 147  </scons_output>
 148
 149  <para>
 150
 151  If a string begins with an exclamation mark (<literal>!</literal>),
 152  the string is passed to the shell for execution.
 153  The output of the command is then parsed:
 154
 155  </para>
 156
 157  <scons_example name="parseflags_ex4">
 158    <file name="SConstruct" printme="1">
 159 env = Environment()
 160 d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"])
 161 for k, v in sorted(d.items()):
 162     if v:
 163         print(k, v)
 164 env.MergeFlags(d)
 165 env.Program("f1.c")
 166    </file>
 167    <file name="f1.c">
 168 void main() { return 0; }
 169    </file>
 170  </scons_example>
 171
 172  <scons_output example="parseflags_ex4" suffix="1">
 173     <scons_output_command>scons -Q</scons_output_command>
 174  </scons_output>
 175
 176  <para>
 177
 178  &ParseFlags; is regularly updated for new options;
 179  consult the man page for details about those currently recognized.
 180
 181  </para>
 182
 183 </section>