doc/user/parseconfig.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-parseconfig"
  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>Finding Installed Library Information: the &ParseConfig; Function</title>
  30
  31 <para>
  32
  33  Configuring the right options to build programs to work with
  34  libraries--especially shared libraries--that are available
  35  on POSIX systems can be complex.
  36  To help this situation,
  37  various utilities with names that end in <filename>config</filename>
  38  return the command-line options for the GNU Compiler Collection (GCC)
  39  that are needed to build and link against those libraries;
  40  for example, the command-line options
  41  to use a library named <filename>lib</filename>
  42  could be found by calling a utility named <command>lib-config</command>.
  43
  44  </para>
  45
  46  <para>
  47
  48  A more recent convention is that these options
  49  are available through the generic <command>pkg-config</command> program,
  50  providing a common framework, error handling, and the like,
  51  so that all the package creator has to do is provide the set of strings
  52  for his particular package.
  53
  54  </para>
  55
  56  <para>
  57
  58  &SCons; &consenvs; have a &f-link-ParseConfig;
  59  method that asks the host system to execute a command
  60  and then configures the appropriate &consvars; based on
  61  the output of that command.
  62  This lets you run a program like <command>pkg-config</command>
  63  or a more specific utility to help set up your build.
  64
  65  </para>
  66
  67  <scons_example name="parseconfig_ex1">
  68    <file name="SConstruct" printme="1">
  69 env = Environment()
  70 env['CPPPATH'] = ['/lib/compat']
  71 env.ParseConfig("pkg-config x11 --cflags --libs")
  72 print("CPPPATH:", env['CPPPATH'])
  73    </file>
  74  </scons_example>
  75
  76  <para>
  77
  78  &SCons; will execute the specified command string,
  79  parse the resultant flags,
  80  and add the flags to the appropriate environment variables.
  81
  82  </para>
  83
  84  <!--
  85  This is how we used to generate the screen output below, but
  86  as of (at least) Ubuntu Karmic, the pkg-config output for x11
  87  no longer reports back an include directory.  Since this is just
  88  for example anyway, we're just hard-coding the output.
  89
  90  <scons_output example="parseconfig_ex1" suffix="1">
  91     <scons_output_command>scons -Q</scons_output_command>
  92  </scons_output>
  93  -->
  94
  95  <screen>
  96 % <userinput>scons -Q</userinput>
  97 CPPPATH: ['/lib/compat', '/usr/X11/include']
  98 scons: `.' is up to date.
  99  </screen>
 100
 101  <para>
 102
 103  In the example above, &SCons; has added the include directory to
 104  &cv-link-CPPPATH;
 105  (depending on what other flags are emitted by the
 106  <filename>pkg-config</filename> command,
 107  other variables may have been extended as well.)
 108
 109  </para>
 110
 111  <para>
 112
 113  Note that the options are merged with existing options using
 114  the &f-link-MergeFlags; method,
 115  so that each option only occurs once in the &consvar;.
 116
 117  </para>
 118
 119  <scons_example name="parseconfig_ex2">
 120    <file name="SConstruct" printme="1">
 121 env = Environment()
 122 env.ParseConfig("pkg-config x11 --cflags --libs")
 123 env.ParseConfig("pkg-config x11 --cflags --libs")
 124 print("CPPPATH:", "CPPPATH:", env['CPPPATH'])
 125    </file>
 126  </scons_example>
 127
 128  <!--
 129  This is how we used to generate the screen output below, but
 130  as of (at least) Ubuntu Karmic, the pkg-config output for x11
 131  no longer reports back an include directory.  Since this is just
 132  for example anyway, we're just hard-coding the output.
 133
 134  <scons_output example="parseconfig_ex2" suffix="1">
 135     <scons_output_command>scons -Q</scons_output_command>
 136  </scons_output>
 137  -->
 138
 139  <screen>
 140 % <userinput>scons -Q</userinput>
 141 CPPPATH: ['/usr/X11/include']
 142 scons: `.' is up to date.
 143  </screen>
 144
 145 </section>