1 files changed, 163 insertions, 0 deletions
diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml
new file mode 100644
index 0000000..7ac567d
--- /dev/null
+++ b/doc/user/parseconfig.xml
@@ -0,0 +1,163 @@
+<?xml version='1.0'?>
+<!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-parseconfig"
+         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>Finding Installed Library Information: the &ParseConfig; Function</title>
+
+<!--
+
+  Copyright (c) 2001 - 2014 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>
+
+ Configuring the right options to build programs to work with
+ libraries--especially shared libraries--that are available
+ on POSIX systems can be very complicated.
+ To help this situation,
+ various utilies with names that end in <filename>config</filename>
+ return the command-line options for the GNU Compiler Collection (GCC)
+ that are needed to use these libraries;
+ for example, the command-line options
+ to use a library named <filename>lib</filename>
+ would be found by calling a utility named <filename>lib-config</filename>.
+
+ </para>
+
+ <para>
+
+ A more recent convention is that these options
+ are available from the generic <filename>pkg-config</filename> program,
+ which has common framework, error handling, and the like,
+ so that all the package creator has to do is provide the set of strings
+ for his particular package.
+
+ </para>
+
+ <para>
+
+ &SCons; construction environments have a &ParseConfig; method
+ that executes a <filename>*config</filename> utility
+ (either <filename>pkg-config</filename> or a
+ more specific utility)
+ and configures the appropriate construction variables
+ in the environment
+ based on the command-line options
+ returned by the specified command.
+
+ </para>
+
+ <scons_example name="parseconfig_ex1">
+   <file name="SConstruct" printme="1">
+env = Environment()
+env['CPPPATH'] = ['/lib/compat']
+env.ParseConfig("pkg-config x11 --cflags --libs")
+print env['CPPPATH']
+   </file>
+ </scons_example>
+
+ <para>
+
+ &SCons; will execute the specified command string,
+ parse the resultant flags,
+ and add the flags to the appropriate environment variables.
+
+ </para>
+
+ <!--
+ This is how we used to generate the screen output below, but
+ as of (at least) Ubuntu Karmic, the pkg-config output for x11
+ no longer reports back an include directory.  Since this is just
+ for example anyway, we're just hard-coding the output.
+
+ <scons_output example="parseconfig_ex1" suffix="1">
+    <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
+ -->
+
+ <screen>
+% <userinput>scons -Q</userinput>
+['/lib/compat', '/usr/X11/include']
+scons: `.' is up to date.
+ </screen>
+
+ <para>
+
+ In the example above, &SCons; has added the include directory to
+ <varname>CPPPATH</varname>.
+ (Depending upon what other flags are emitted by the
+ <filename>pkg-config</filename> command,
+ other variables may have been extended as well.)
+
+ </para>
+
+ <para>
+
+ Note that the options are merged with existing options using
+ the &MergeFlags; method,
+ so that each option only occurs once in the construction variable:
+
+ </para>
+
+ <scons_example name="parseconfig_ex2">
+   <file name="SConstruct" printme="1">
+env = Environment()
+env.ParseConfig("pkg-config x11 --cflags --libs")
+env.ParseConfig("pkg-config x11 --cflags --libs")
+print env['CPPPATH']
+   </file>
+ </scons_example>
+
+ <!--
+ This is how we used to generate the screen output below, but
+ as of (at least) Ubuntu Karmic, the pkg-config output for x11
+ no longer reports back an include directory.  Since this is just
+ for example anyway, we're just hard-coding the output.
+
+ <scons_output example="parseconfig_ex2" suffix="1">
+    <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
+ -->
+
+ <screen>
+% <userinput>scons -Q</userinput>
+['/usr/X11/include']
+scons: `.' is up to date.
+ </screen>
+
+</section>