SCons/Action.xml

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