From 72c578fd4b0b4a5a43e18594339ac4ff26c376dc Mon Sep 17 00:00:00 2001
From: Luca Falavigna <dktrkranz@debian.org>
Date: Sat, 2 Jan 2010 20:56:27 +0100
Subject: Imported Upstream version 1.2.0.d20091224

---
 doc/user/parseflags.xml | 199 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 199 insertions(+)
 create mode 100644 doc/user/parseflags.xml

(limited to 'doc/user/parseflags.xml')

diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml
new file mode 100644
index 0000000..6900291
--- /dev/null
+++ b/doc/user/parseflags.xml
@@ -0,0 +1,199 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ &SCons; has a bewildering array of construction variables
+ for different types of options when building programs.
+ Sometimes you may not know exactly which variable
+ should be used for a particular option.
+
+ </para>
+
+ <para>
+
+ &SCons; construction environments have a &ParseFlags; method
+ that takes a set of typical command-line options
+ and distrbutes them into the appropriate construction variables.
+ Historically, it was created to support the &ParseConfig; method,
+ so it focuses on options used by the GNU Compiler Collection (GCC)
+ for the C and C++ toolchains.
+
+ </para>
+
+ <para>
+
+ &ParseFlags; returns a dictionary containing the options
+ distributed into their respective construction variables.
+ Normally, this dictionary would be passed to &MergeFlags;
+ to merge the options into a &consenv;,
+ but the dictionary can be edited if desired to provide
+ additional functionality.
+ (Note that if the flags are not going to be edited,
+ calling &MergeFlags; with the options directly
+ will avoid an additional step.)
+
+ </para>
+
+ <programlisting>
+    env = Environment()
+    d = env.ParseFlags("-I/opt/include -L/opt/lib -lfoo")
+    l = d.items()
+    l.sort()
+    for k,v in l:
+        if v:
+            print k, v
+    env.MergeFlags(d)
+    env.Program('f1.c')
+ </programlisting>
+
+ <screen>
+    % <userinput>scons -Q</userinput>
+    CPPPATH ['/opt/include']
+    LIBPATH ['/opt/lib']
+    LIBS ['foo']
+    cc -o f1.o -c -I/opt/include f1.c
+    cc -o f1 f1.o -L/opt/lib -lfoo
+ </screen>
+
+ <para>
+
+ Note that if the options are limited to generic types
+ like those above,
+ they will be correctly translated for other platform types:
+
+ </para>
+
+ <screen>
+    C:\><userinput>scons -Q</userinput>
+    
+    scons: warning: No installed VCs
+    File "&lt;stdin&gt;", line 67, in __call__
+    
+    scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+    File "&lt;stdin&gt;", line 67, in __call__
+    
+    scons: warning: No installed VCs
+    File "&lt;stdin&gt;", line 67, in __call__
+    
+    scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+    File "&lt;stdin&gt;", line 67, in __call__
+    CPPPATH ['/opt/include']
+    LIBPATH ['/opt/lib']
+    LIBS ['foo']
+    cl /Fof1.obj /c f1.c /nologo /I\opt\include
+    link /nologo /OUT:f1.exe /LIBPATH:\opt\lib foo.lib f1.obj
+ </screen>
+
+ <para>
+
+ Since the assumption is that the flags are used for the GCC toolchain,
+ unrecognized flags are placed in &cv-link-CCFLAGS;
+ so they will be used for both C and C++ compiles:
+
+ </para>
+
+ <programlisting>
+    env = Environment()
+    d = env.ParseFlags("-whatever")
+    l = d.items()
+    l.sort()
+    for k,v in l:
+        if v:
+            print k, v
+    env.MergeFlags(d)
+    env.Program('f1.c')
+ </programlisting>
+
+ <screen>
+    % <userinput>scons -Q</userinput>
+    CCFLAGS -whatever
+    cc -o f1.o -c -whatever f1.c
+    cc -o f1 f1.o
+ </screen>
+
+ <para>
+
+ &ParseFlags; will also accept a (recursive) list of strings as input;
+ the list is flattened before the strings are processed:
+
+ </para>
+
+ <programlisting>
+    env = Environment()
+    d = env.ParseFlags(["-I/opt/include", ["-L/opt/lib", "-lfoo"]])
+    l = d.items()
+    l.sort()
+    for k,v in l:
+        if v:
+            print k, v
+    env.MergeFlags(d)
+    env.Program('f1.c')
+ </programlisting>
+
+ <screen>
+    % <userinput>scons -Q</userinput>
+    CPPPATH ['/opt/include']
+    LIBPATH ['/opt/lib']
+    LIBS ['foo']
+    cc -o f1.o -c -I/opt/include f1.c
+    cc -o f1 f1.o -L/opt/lib -lfoo
+ </screen>
+
+ <para>
+
+ If a string begins with a "!" (an exclamation mark, often called a bang),
+ the string is passed to the shell for execution.
+ The output of the command is then parsed:
+
+ </para>
+
+ <programlisting>
+    env = Environment()
+    d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"])
+    l = d.items()
+    l.sort()
+    for k,v in l:
+        if v:
+            print k, v
+    env.MergeFlags(d)
+    env.Program('f1.c')
+ </programlisting>
+
+ <screen>
+    % <userinput>scons -Q</userinput>
+    CPPPATH ['/opt/include']
+    LIBPATH ['/opt/lib']
+    LIBS ['foo']
+    cc -o f1.o -c -I/opt/include f1.c
+    cc -o f1 f1.o -L/opt/lib -lfoo
+ </screen>
+
+ <para>
+
+ &ParseFlags; is regularly updated for new options;
+ consult the man page for details about those currently recognized.
+
+ </para>
-- 
cgit v1.2.3