SCons/Action.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 Copyright The SCons Foundation
   4
   5 This file is processed by the bin/SConsDoc.py module.
   6 See its __doc__ string for a discussion of the format.
   7 -->
   8
   9 <!DOCTYPE sconsdoc [
  10 <!ENTITY % scons SYSTEM '../doc/scons.mod'>
  11 %scons;
  12 <!ENTITY % builders-mod SYSTEM '../doc/generated/builders.mod'>
  13 %builders-mod;
  14 <!ENTITY % functions-mod SYSTEM '../doc/generated/functions.mod'>
  15 %functions-mod;
  16 <!ENTITY % tools-mod SYSTEM '../doc/generated/tools.mod'>
  17 %tools-mod;
  18 <!ENTITY % variables-mod SYSTEM '../doc/generated/variables.mod'>
  19 %variables-mod;
  20 ]>
  21
  22 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  23           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  24           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  25
  26 <cvar name="IMPLICIT_COMMAND_DEPENDENCIES">
  27 <summary>
  28 <para>
  29 Controls whether or not &SCons; will
  30 add implicit dependencies for the commands
  31 executed to build targets.
  32 </para>
  33
  34 <para>
  35 By default, &SCons; will add to each target
  36 an implicit dependency on the command
  37 represented by the first argument of any
  38 command line it executes (which is typically
  39 the command itself). By setting such
  40 a dependency, &SCons; can determine that
  41 a target should be rebuilt if the command changes,
  42 such as when a compiler is upgraded to a new version.
  43 The specific file for the dependency is
  44 found by searching the
  45 <varname>PATH</varname>
  46 variable in the
  47 <varname>ENV</varname> dictionary
  48 in the &consenv; used to execute the command.
  49 The default is the same as
  50 setting the &consvar;
  51 &cv-IMPLICIT_COMMAND_DEPENDENCIES;
  52 to a True-like value (<quote>true</quote>,
  53 <quote>yes</quote>,
  54 or <quote>1</quote> - but not a number
  55 greater than one, as that has a different meaning).
  56 </para>
  57
  58 <para>
  59 Action strings can be segmented by the
  60 use of an AND operator, <literal>&amp;&amp;</literal>.
  61 In a segemented string, each segment is a separate
  62 <quote>command line</quote>, these are run
  63 sequentially until one fails or the entire
  64 sequence has been executed. If an
  65 action string is segmented, then the selected
  66 behavior of &cv-IMPLICIT_COMMAND_DEPENDENCIES;
  67 is applied to each segment.
  68 </para>
  69
  70 <para>
  71 If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
  72 is set to a False-like value
  73 (<quote>none</quote>,
  74 <quote>false</quote>,
  75 <quote>no</quote>,
  76 <quote>0</quote>,
  77 etc.),
  78 then the implicit dependency will
  79 not be added to the targets
  80 built with that &consenv;.
  81 </para>
  82
  83 <para>
  84 If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
  85 is set to <quote>2</quote> or higher,
  86 then that number of arguments in the command line
  87 will be scanned for relative or absolute paths.
  88 If any are present, they will be added as
  89 implicit dependencies to the targets built
  90 with that &consenv;.
  91 The first argument in the command line will be
  92 searched for using the <varname>PATH</varname>
  93 variable in the <varname>ENV</varname> dictionary
  94 in the &consenv; used to execute the command.
  95 The other arguments will only be found if they
  96 are absolute paths or valid paths relative
  97 to the working directory.
  98 </para>
  99
 100 <para>
 101 If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
 102 is set to <quote>all</quote>,
 103 then all arguments in the command line will be
 104 scanned for relative or absolute paths.
 105 If any are present, they will be added as
 106 implicit dependencies to the targets built
 107 with that &consenv;.
 108 The first argument in the command line will be
 109 searched for using the <varname>PATH</varname>
 110 variable in the <varname>ENV</varname> dictionary
 111 in the &consenv; used to execute the command.
 112 The other arguments will only be found if they
 113 are absolute paths or valid paths relative
 114 to the working directory.
 115 </para>
 116
 117 <example_commands>
 118 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES=False)
 119 </example_commands>
 120 </summary>
 121 </cvar>
 122
 123 <cvar name="PRINT_CMD_LINE_FUNC">
 124 <summary>
 125 <para>
 126 A Python function used to print the command lines as they are executed
 127 (assuming command printing is not disabled by the
 128 <option>-q</option>
 129 or
 130 <option>-s</option>
 131 options or their equivalents).
 132 The function must accept four arguments:
 133 <varname>s</varname>,
 134 <varname>target</varname>,
 135 <varname>source</varname> and
 136 <varname>env</varname>.
 137 <varname>s</varname>
 138 is a string showing the command being executed,
 139 <varname>target</varname>,
 140 is the target being built (file node, list, or string name(s)),
 141 <varname>source</varname>,
 142 is the source(s) used (file node, list, or string name(s)),
 143 and <varname>env</varname>
 144 is the environment being used.
 145 </para>
 146
 147 <para>
 148 The function must do the printing itself.
 149 The default implementation,
 150 used if this variable is not set or is <constant>None</constant>,
 151 is to just print the string, as in:
 152 </para>
 153 <example_commands>
 154 def print_cmd_line(s, target, source, env):
 155     sys.stdout.write(s + "\n")
 156 </example_commands>
 157
 158 <para>
 159 Here is an example of a more interesting function:
 160 </para>
 161
 162 <example_commands>
 163 def print_cmd_line(s, target, source, env):
 164     sys.stdout.write(
 165         "Building %s -> %s...\n"
 166         % (
 167             ' and '.join([str(x) for x in source]),
 168             ' and '.join([str(x) for x in target]),
 169         )
 170     )
 171
 172 env = Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
 173 env.Program('foo', ['foo.c', 'bar.c'])
 174 </example_commands>
 175
 176 <para>
 177 This prints:
 178 </para>
 179
 180 <screen>
 181 ...
 182 scons: Building targets ...
 183 Building bar.c -> bar.o...
 184 Building foo.c -> foo.o...
 185 Building foo.o and bar.o -> foo...
 186 scons: done building targets.
 187 </screen>
 188
 189 <para>
 190 Another example could be a function that logs the actual commands to a file.
 191 </para>
 192 </summary>
 193 </cvar>
 194
 195 <cvar name="SPAWN">
 196 <summary>
 197 <para>
 198 A command interpreter function that will be called to execute command line
 199 strings. The function must accept five arguments:
 200 </para>
 201
 202 <example_commands>
 203 def spawn(shell, escape, cmd, args, env):
 204 </example_commands>
 205
 206 <para>
 207 <varname>shell</varname>
 208 is a string naming the shell program to use,
 209 <varname>escape</varname>
 210 is a function that can be called to escape shell special characters in
 211 the command line,
 212 <varname>cmd</varname>
 213 is the path to the command to be executed,
 214 <varname>args</varname>
 215 holds the arguments to the command and
 216 <varname>env</varname>
 217 is a dictionary of environment variables
 218 defining the execution environment in which the command should be executed.
 219 </para>
 220 </summary>
 221 </cvar>
 222
 223 <cvar name="SHELL_ENV_GENERATORS">
 224   <summary>
 225     <para>
 226 A hook allowing the execution environment to be modified prior
 227 to the actual execution of a command line from an action
 228 via the spawner function defined by &cv-link-SPAWN;.
 229 Allows substitution based on targets and sources,
 230 as well as values from the &consenv;,
 231 adding extra environment variables, etc.
 232     </para>
 233
 234     <para>
 235 The value must be a list (or other iterable)
 236 of functions which each generate or
 237 alter the execution environment dictionary.
 238 The first function will be passed a copy of the initial execution environment
 239 (&cv-link-ENV; in the current &consenv;);
 240 the dictionary returned by that function is passed to the next,
 241 until the iterable is exhausted and the result returned
 242 for use by the command spawner.
 243 The original execution environment is not modified.
 244     </para>
 245
 246     <para>
 247 Each function provided in &cv-SHELL_ENV_GENERATORS; must accept four
 248 arguments and return a dictionary:
 249 <varname>env</varname> is the &consenv; for this action;
 250 <varname>target</varname> is the list of targets associated with this action;
 251 <varname>source</varname> is the list of sources associated with this action;
 252 and <varname>shell_env</varname> is the current dictionary after iterating
 253 any previous &cv-SHELL_ENV_GENERATORS; functions
 254 (this can be compared to the original execution environment,
 255 which is available as <literal>env['ENV']</literal>, to detect any changes).
 256     </para>
 257
 258     <para>Example:</para>
 259     <example_commands>
 260 def custom_shell_env(env, target, source, shell_env):
 261     """customize shell_env if desired"""
 262     if str(target[0]) == 'special_target':
 263         shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=target, source=source)
 264     return shell_env
 265
 266 env["SHELL_ENV_GENERATORS"] = [custom_shell_env]
 267     </example_commands>
 268
 269   <para><emphasis>Available since 4.4</emphasis></para>
 270   </summary>
 271 </cvar>
 272
 273 </sconsdoc>