src/engine/SCons/Environment.xml

   1 <!--
   2 __COPYRIGHT__
   3
   4 This file is processed by the bin/SConsDoc.py module.
   5 See its __doc__ string for a discussion of the format.
   6 -->
   7 <cvar name="BUILDERS">
   8 <summary>
   9 A dictionary mapping the names of the builders
  10 available through this environment
  11 to underlying Builder objects.
  12 Builders named
  13 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
  14 are available by default.
  15 If you initialize this variable when an
  16 Environment is created:
  17
  18 <example>
  19 env = Environment(BUILDERS = {'NewBuilder' : foo})
  20 </example>
  21
  22 the default Builders will no longer be available.
  23 To use a new Builder object in addition to the default Builders,
  24 add your new Builder object like this:
  25
  26 <example>
  27 env = Environment()
  28 env.Append(BUILDERS = {'NewBuilder' : foo})
  29 </example>
  30
  31 or this:
  32
  33 <example>
  34 env = Environment()
  35 env['BUILDERS]['NewBuilder'] = foo
  36 </example>
  37 </summary>
  38 </cvar>
  39
  40 <cvar name="Dir">
  41 <summary>
  42 A function that converts a string
  43 into a Dir instance relative to the target being built.
  44 </summary>
  45 </cvar>
  46
  47 <cvar name="ENV">
  48 <summary>
  49 A dictionary of environment variables
  50 to use when invoking commands. When
  51 &cv-ENV; is used in a command all list
  52 values will be joined using the path separator and any other non-string
  53 values will simply be coerced to a string.
  54 Note that, by default,
  55 &scons;
  56 does
  57 <emphasis>not</emphasis>
  58 propagate the environment in force when you
  59 execute
  60 &scons;
  61 to the commands used to build target files.
  62 This is so that builds will be guaranteed
  63 repeatable regardless of the environment
  64 variables set at the time
  65 &scons;
  66 is invoked.
  67
  68 If you want to propagate your
  69 environment variables
  70 to the commands executed
  71 to build target files,
  72 you must do so explicitly:
  73
  74 <example>
  75 import os
  76 env = Environment(ENV = os.environ)
  77 </example>
  78
  79 Note that you can choose only to propagate
  80 certain environment variables.
  81 A common example is
  82 the system
  83 <envar>PATH</envar>
  84 environment variable,
  85 so that
  86 &scons;
  87 uses the same utilities
  88 as the invoking shell (or other process):
  89
  90 <example>
  91 import os
  92 env = Environment(ENV = {'PATH' : os.environ['PATH']})
  93 </example>
  94 </summary>
  95 </cvar>
  96
  97 <cvar name="File">
  98 <summary>
  99 A function that converts a string into a File instance relative to the
 100 target being built.
 101 </summary>
 102 </cvar>
 103
 104 <cvar name="SCANNERS">
 105 <summary>
 106 A list of the available implicit dependency scanners.
 107 New file scanners may be added by
 108 appending to this list,
 109 although the more flexible approach
 110 is to associate scanners
 111 with a specific Builder.
 112 See the sections "Builder Objects"
 113 and "Scanner Objects,"
 114 below, for more information.
 115 </summary>
 116 </cvar>
 117
 118 <cvar name="SOURCE">
 119 <summary>
 120 A reserved variable name
 121 that may not be set or used in a construction environment.
 122 (See "Variable Substitution," below.)
 123 </summary>
 124 </cvar>
 125
 126 <cvar name="SOURCES">
 127 <summary>
 128 A reserved variable name
 129 that may not be set or used in a construction environment.
 130 (See "Variable Substitution," below.)
 131 </summary>
 132 </cvar>
 133
 134 <cvar name="TARGET">
 135 <summary>
 136 A reserved variable name
 137 that may not be set or used in a construction environment.
 138 (See "Variable Substitution," below.)
 139 </summary>
 140 </cvar>
 141
 142 <cvar name="TARGETS">
 143 <summary>
 144 A reserved variable name
 145 that may not be set or used in a construction environment.
 146 (See "Variable Substitution," below.)
 147 </summary>
 148 </cvar>
 149
 150 <cvar name="TOOLS">
 151 <summary>
 152 A list of the names of the Tool specifications
 153 that are part of this construction environment.
 154 </summary>
 155 </cvar>