src/engine/SCons/Action.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="IMPLICIT_COMMAND_DEPENDENCIES">
   8 <summary>
   9 Controls whether or not SCons will
  10 add implicit dependencies for the commands
  11 executed to build targets.
  12
  13 By default, SCons will add
  14 to each target
  15 an implicit dependency on the command
  16 represented by the first argument on any
  17 command line it executes.
  18 The specific file for the dependency is
  19 found by searching the
  20 <varname>PATH</varname>
  21 variable in the
  22 <varname>ENV</varname>
  23 environment used to execute the command.
  24
  25 If the construction variable
  26 &cv-IMPLICIT_COMMAND_DEPENDENCIES;
  27 is set to a false value
  28 (<literal>None</literal>,
  29 <literal>False</literal>,
  30 <literal>0</literal>,
  31 etc.),
  32 then the implicit dependency will
  33 not be added to the targets
  34 built with that construction environment.
  35
  36 <example>
  37 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
  38 </example>
  39 </summary>
  40 </cvar>
  41
  42 <cvar name="PRINT_CMD_LINE_FUNC">
  43 <summary>
  44 A Python function used to print the command lines as they are executed
  45 (assuming command printing is not disabled by the
  46 <option>-q</option>
  47 or
  48 <option>-s</option>
  49 options or their equivalents).
  50 The function should take four arguments:
  51 <varname>s</varname>,
  52 the command being executed (a string),
  53 <varname>target</varname>,
  54 the target being built (file node, list, or string name(s)),
  55 <varname>source</varname>,
  56 the source(s) used (file node, list, or string name(s)), and
  57 <varname>env</varname>,
  58 the environment being used.
  59
  60 The function must do the printing itself.  The default implementation,
  61 used if this variable is not set or is None, is:
  62 <example>
  63 def print_cmd_line(s, target, source, env):
  64   sys.stdout.write(s + "\n")
  65 </example>
  66
  67 Here's an example of a more interesting function:
  68
  69 <example>
  70 def print_cmd_line(s, target, source, env):
  71    sys.stdout.write("Building %s -> %s...\n" %
  72     (' and '.join([str(x) for x in source]),
  73      ' and '.join([str(x) for x in target])))
  74 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
  75 env.Program('foo', 'foo.c')
  76 </example>
  77
  78 This just prints "Building <varname>targetname</varname> from <varname>sourcename</varname>..." instead
  79 of the actual commands.
  80 Such a function could also log the actual commands to a log file,
  81 for example.
  82 </summary>
  83 </cvar>
  84
  85 <cvar name="SPAWN">
  86 <summary>
  87 A command interpreter function that will be called to execute command line
  88 strings. The function must expect the following arguments:
  89
  90 <example>
  91 def spawn(shell, escape, cmd, args, env):
  92 </example>
  93
  94 <varname>sh</varname>
  95 is a string naming the shell program to use.
  96 <varname>escape</varname>
  97 is a function that can be called to escape shell special characters in
  98 the command line.
  99 <varname>cmd</varname>
 100 is the path to the command to be executed.
 101 <varname>args</varname>
 102 is the arguments to the command.
 103 <varname>env</varname>
 104 is a dictionary of the environment variables
 105 in which the command should be executed.
 106 </summary>
 107 </cvar>