doc/user/ENV.in

   1
   2 <!--
   3
   4   __COPYRIGHT__
   5
   6   Permission is hereby granted, free of charge, to any person obtaining
   7   a copy of this software and associated documentation files (the
   8   "Software"), to deal in the Software without restriction, including
   9   without limitation the rights to use, copy, modify, merge, publish,
  10   distribute, sublicense, and/or sell copies of the Software, and to
  11   permit persons to whom the Software is furnished to do so, subject to
  12   the following conditions:
  13
  14   The above copyright notice and this permission notice shall be included
  15   in all copies or substantial portions of the Software.
  16
  17   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  18   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  19   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  20   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  21   LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  22   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  23   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  24
  25 -->
  26
  27   <para>
  28
  29     When &SCons; builds a target file,
  30     it does not execute the commands with
  31     the same external environment
  32     that you used to execute &SCons;.
  33     Instead, it uses the dictionary
  34     stored in the &cv-link-ENV; construction variable
  35     as the external environment
  36     for executing commands.
  37
  38   </para>
  39
  40   <para>
  41
  42     The most important ramification of this behavior
  43     is that the &PATH; environment variable,
  44     which controls where the operating system
  45     will look for commands and utilities,
  46     is not the same as in the external environment
  47     from which you called &SCons;.
  48     This means that &SCons; will not, by default,
  49     necessarily find all of the tools
  50     that you can execute from the command line.
  51
  52   </para>
  53
  54   <para>
  55
  56     The default value of the &PATH; environment variable
  57     on a POSIX system
  58     is <literal>/usr/local/bin:/bin:/usr/bin</literal>.
  59     The default value of the &PATH; environment variable
  60     on a Windows system comes from the Windows registry
  61     value for the command interpreter.
  62     If you want to execute any commands--compilers, linkers, etc.--that
  63     are not in these default locations,
  64     you need to set the &PATH; value
  65     in the &cv-ENV; dictionary
  66     in your construction environment.
  67
  68   </para>
  69
  70   <para>
  71
  72     The simplest way to do this is to initialize explicitly
  73     the value when you create the construction environment;
  74     this is one way to do that:
  75
  76   </para>
  77
  78   <sconstruct>
  79     path = ['/usr/local/bin', '/bin', '/usr/bin']
  80     env = Environment(ENV = {'PATH' : path})
  81   </sconstruct>
  82
  83   <para>
  84
  85   Assign a dictionary to the &cv-ENV;
  86   construction variable in this way
  87   completely resets the external environment
  88   so that the only variable that will be
  89   set when external commands are executed
  90   will be the &PATH; value.
  91   If you want to use the rest of
  92   the values in &cv-ENV; and only
  93   set the value of &PATH;,
  94   the most straightforward way is probably:
  95
  96   </para>
  97
  98   <sconstruct>
  99     env['ENV']['PATH'] = ['/usr/local/bin', '/bin', '/usr/bin']
 100   </sconstruct>
 101
 102   <para>
 103
 104   Note that &SCons; does allow you to define
 105   the directories in the &PATH; in a string,
 106   separated by the pathname-separator character
 107   for your system (':' on POSIX systems, ';' on Windows):
 108
 109   </para>
 110
 111   <sconstruct>
 112     env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin'
 113   </sconstruct>
 114
 115   <para>
 116
 117   But doing so makes your &SConscript; file less portable,
 118   (although in this case that may not be a huge concern
 119   since the directories you list are likley system-specific, anyway).
 120
 121   </para>
 122
 123   <!--
 124
 125   <scons_example name="ex1">
 126     <file name="SConstruct" printme="1">
 127     env = Environment()
 128     env.Command('foo', [], '__ROOT__/usr/bin/printenv.py')
 129     </file>
 130     <file name="__ROOT__/usr/bin/printenv.py" chmod="0755">
 131     #!/usr/bin/env python
 132     import os
 133     import sys
 134     if len(sys.argv) > 1:
 135         keys = sys.argv[1:]
 136     else:
 137         keys = os.environ.keys()
 138         keys.sort()
 139     for key in keys:
 140         print "    " + key + "=" + os.environ[key]
 141     </file>
 142   </scons_example>
 143
 144   <para>
 145
 146   </para>
 147
 148   <scons_output example="ex1">
 149     <scons_output_command>scons -Q</scons_output_command>
 150   </scons_output>
 151
 152   -->
 153
 154   <section>
 155   <title>Propagating &PATH; From the External Environment</title>
 156
 157     <para>
 158
 159     You may want to propagate the external &PATH;
 160     to the execution environment for commands.
 161     You do this by initializing the &PATH;
 162     variable with the &PATH; value from
 163     the <literal>os.environ</literal>
 164     dictionary,
 165     which is Python's way of letting you
 166     get at the external environment:
 167
 168     </para>
 169
 170     <sconstruct>
 171       import os
 172       env = Environment(ENV = {'PATH' : os.environ['PATH']})
 173     </sconstruct>
 174
 175     <para>
 176
 177     Alternatively, you may find it easier
 178     to just propagate the entire external
 179     environment to the execution environment
 180     for commands.
 181     This is simpler to code than explicity
 182     selecting the &PATH; value:
 183
 184     </para>
 185
 186     <sconstruct>
 187       import os
 188       env = Environment(ENV = os.environ)
 189     </sconstruct>
 190
 191     <para>
 192
 193     Either of these will guarantee that
 194     &SCons; will be able to execute
 195     any command that you can execute from the command line.
 196     The drawback is that the build can behave
 197     differently if it's run by people with
 198     different &PATH; values in their environment--for example,
 199     both the <literal>/bin</literal> and
 200     <literal>/usr/local/bin</literal> directories
 201     have different &cc; commands,
 202     then which one will be used to compile programs
 203     will depend on which directory is listed
 204     first in the user's &PATH; variable.
 205
 206     </para>
 207
 208   </section>