src/engine/SCons/Action.py

   1 """SCons.Action
   2
   3 This encapsulates information about executing any sort of action that
   4 can build one or more target Nodes (typically files) from one or more
   5 source Nodes (also typically files) given a specific Environment.
   6
   7 The base class here is ActionBase.  The base class supplies just a few
   8 OO utility methods and some generic methods for displaying information
   9 about an Action in response to the various commands that control printing.
  10
  11 The heavy lifting is handled by subclasses for the different types of
  12 actions we might execute:
  13
  14     CommandAction
  15     CommandGeneratorAction
  16     FunctionAction
  17     ListAction
  18
  19 The subclasses supply the following public interface methods used by
  20 other modules:
  21
  22     __call__()
  23         THE public interface, "calling" an Action object executes the
  24         command or Python function.  This also takes care of printing
  25         a pre-substitution command for debugging purposes.
  26
  27     get_contents()
  28         Fetches the "contents" of an Action for signature calculation.
  29         This is what the Sig/*.py subsystem uses to decide if a target
  30         needs to be rebuilt because its action changed.
  31
  32     genstring()
  33         Returns a string representation of the Action *without* command
  34         substitution, but allows a CommandGeneratorAction to generate
  35         the right action based on the specified target, source and env.
  36         This is used by the Signature subsystem (through the Executor)
  37         to compare the actions used to build a target last time and
  38         this time.
  39
  40 Subclasses also supply the following methods for internal use within
  41 this module:
  42
  43     __str__()
  44         Returns a string representation of the Action *without* command
  45         substitution.  This is used by the __call__() methods to display
  46         the pre-substitution command whenever the --debug=presub option
  47         is used.
  48
  49     strfunction()
  50         Returns a substituted string representation of the Action.
  51         This is used by the ActionBase.show() command to display the
  52         command/function that will be executed to generate the target(s).
  53
  54     execute()
  55         The internal method that really, truly, actually handles the
  56         execution of a command or Python function.  This is used so
  57         that the __call__() methods can take care of displaying any
  58         pre-substitution representations, and *then* execute an action
  59         without worrying about the specific Actions involved.
  60
  61 There is a related independent ActionCaller class that looks like a
  62 regular Action, and which serves as a wrapper for arbitrary functions
  63 that we want to let the user specify the arguments to now, but actually
  64 execute later (when an out-of-date check determines that it's needed to
  65 be executed, for example).  Objects of this class are returned by an
  66 ActionFactory class that provides a __call__() method as a convenient
  67 way for wrapping up the functions.
  68
  69 """
  70
  71 #
  72 # __COPYRIGHT__
  73 #
  74 # Permission is hereby granted, free of charge, to any person obtaining
  75 # a copy of this software and associated documentation files (the
  76 # "Software"), to deal in the Software without restriction, including
  77 # without limitation the rights to use, copy, modify, merge, publish,
  78 # distribute, sublicense, and/or sell copies of the Software, and to
  79 # permit persons to whom the Software is furnished to do so, subject to
  80 # the following conditions:
  81 #
  82 # The above copyright notice and this permission notice shall be included
  83 # in all copies or substantial portions of the Software.
  84 #
  85 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  86 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  87 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  88 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  89 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  90 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  91 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  92 #
  93
  94 __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
  95
  96 import os
  97 import os.path
  98 import re
  99 import string
 100 import sys
 101
 102 from SCons.Debug import logInstanceCreation
 103 import SCons.Errors
 104 import SCons.Util
 105
 106 class _Null:
 107     pass
 108
 109 _null = _Null
 110
 111 print_actions = 1
 112 execute_actions = 1
 113 print_actions_presub = 0
 114
 115 default_ENV = None
 116
 117 def rfile(n):
 118     try:
 119         return n.rfile()
 120     except AttributeError:
 121         return n
 122
 123 def _actionAppend(act1, act2):
 124     # This function knows how to slap two actions together.
 125     # Mainly, it handles ListActions by concatenating into
 126     # a single ListAction.
 127     a1 = Action(act1)
 128     a2 = Action(act2)
 129     if a1 is None or a2 is None:
 130         raise TypeError, "Cannot append %s to %s" % (type(act1), type(act2))
 131     if isinstance(a1, ListAction):
 132         if isinstance(a2, ListAction):
 133             return ListAction(a1.list + a2.list)
 134         else:
 135             return ListAction(a1.list + [ a2 ])
 136     else:
 137         if isinstance(a2, ListAction):
 138             return ListAction([ a1 ] + a2.list)
 139         else:
 140             return ListAction([ a1, a2 ])
 141
 142 class CommandGenerator:
 143     """
 144     Wraps a command generator function so the Action() factory
 145     function can tell a generator function from a function action.
 146     """
 147     def __init__(self, generator):
 148         self.generator = generator
 149
 150     def __add__(self, other):
 151         return _actionAppend(self, other)
 152
 153     def __radd__(self, other):
 154         return _actionAppend(other, self)
 155
 156 def _do_create_action(act, *args, **kw):
 157     """This is the actual "implementation" for the
 158     Action factory method, below.  This handles the
 159     fact that passing lists to Action() itself has
 160     different semantics than passing lists as elements
 161     of lists.
 162
 163     The former will create a ListAction, the latter
 164     will create a CommandAction by converting the inner
 165     list elements to strings."""
 166
 167     if isinstance(act, ActionBase):
 168         return act
 169     if SCons.Util.is_List(act):
 170         return apply(CommandAction, (act,)+args, kw)
 171     if isinstance(act, CommandGenerator):
 172         return apply(CommandGeneratorAction, (act.generator,)+args, kw)
 173     if callable(act):
 174         return apply(FunctionAction, (act,)+args, kw)
 175     if SCons.Util.is_String(act):
 176         var=SCons.Util.get_environment_var(act)
 177         if var:
 178             # This looks like a string that is purely an Environment
 179             # variable reference, like "$FOO" or "${FOO}".  We do
 180             # something special here...we lazily evaluate the contents
 181             # of that Environment variable, so a user could put something
 182             # like a function or a CommandGenerator in that variable
 183             # instead of a string.
 184             lcg = LazyCmdGenerator(var)
 185             return apply(CommandGeneratorAction, (lcg,)+args, kw)
 186         commands = string.split(str(act), '\n')
 187         if len(commands) == 1:
 188             return apply(CommandAction, (commands[0],)+args, kw)
 189         else:
 190             listCmdActions = map(lambda x: CommandAction(x), commands)
 191             return apply(ListAction, (listCmdActions,)+args, kw)
 192     return None
 193
 194 def Action(act, strfunction=_null, varlist=[], presub=_null):
 195     """A factory for action objects."""
 196     if SCons.Util.is_List(act):
 197         acts = map(lambda x, s=strfunction, v=varlist, ps=presub:
 198                           _do_create_action(x, strfunction=s, varlist=v, presub=ps),
 199                    act)
 200         acts = filter(lambda x: not x is None, acts)
 201         if len(acts) == 1:
 202             return acts[0]
 203         else:
 204             return ListAction(acts, strfunction=strfunction, varlist=varlist, presub=presub)
 205     else:
 206         return _do_create_action(act, strfunction=strfunction, varlist=varlist, presub=presub)
 207
 208 class ActionBase:
 209     """Base class for actions that create output objects."""
 210     def __init__(self, strfunction=_null, presub=_null, **kw):
 211         if not strfunction is _null:
 212             self.strfunction = strfunction
 213         if presub is _null:
 214             self.presub = print_actions_presub
 215         else:
 216             self.presub = presub
 217
 218     def __cmp__(self, other):
 219         return cmp(self.__dict__, other.__dict__)
 220
 221     def __call__(self, target, source, env,
 222                                errfunc=None,
 223                                presub=_null,
 224                                show=_null,
 225                                execute=_null):
 226         if not SCons.Util.is_List(target):
 227             target = [target]
 228         if not SCons.Util.is_List(source):
 229             source = [source]
 230         if presub is _null:  presub = self.presub
 231         if show is _null:  show = print_actions
 232         if execute is _null:  execute = execute_actions
 233         if presub:
 234             t = string.join(map(str, target), 'and')
 235             l = string.join(self.presub_lines(env), '\n  ')
 236             out = "Building %s with action(s):\n  %s\n" % (t, l)
 237             sys.stdout.write(out)
 238         if show and self.strfunction:
 239             s = self.strfunction(target, source, env)
 240             if s:
 241                 sys.stdout.write(s + '\n')
 242         if execute:
 243             stat = self.execute(target, source, env)
 244             if stat and errfunc:
 245                 errfunc(stat)
 246             return stat
 247         else:
 248             return 0
 249
 250     def presub_lines(self, env):
 251         # CommandGeneratorAction needs a real environment
 252         # in order to return the proper string here, since
 253         # it may call LazyCmdGenerator, which looks up a key
 254         # in that env.  So we temporarily remember the env here,
 255         # and CommandGeneratorAction will use this env
 256         # when it calls its __generate method.
 257         self.presub_env = env
 258         lines = string.split(str(self), '\n')
 259         self.presub_env = None      # don't need this any more
 260         return lines
 261
 262     def genstring(self, target, source, env):
 263         return str(self)
 264
 265     def get_actions(self):
 266         return [self]
 267
 268     def __add__(self, other):
 269         return _actionAppend(self, other)
 270
 271     def __radd__(self, other):
 272         return _actionAppend(other, self)
 273
 274 def _string_from_cmd_list(cmd_list):
 275     """Takes a list of command line arguments and returns a pretty
 276     representation for printing."""
 277     cl = []
 278     for arg in map(str, cmd_list):
 279         if ' ' in arg or '\t' in arg:
 280             arg = '"' + arg + '"'
 281         cl.append(arg)
 282     return string.join(cl)
 283
 284 class CommandAction(ActionBase):
 285     """Class for command-execution actions."""
 286     def __init__(self, cmd, **kw):
 287         # Cmd list can actually be a list or a single item...basically
 288         # anything that we could pass in as the first arg to
 289         # Environment.subst_list().
 290         if __debug__: logInstanceCreation(self)
 291         apply(ActionBase.__init__, (self,), kw)
 292         self.cmd_list = cmd
 293
 294     def __str__(self):
 295         return str(self.cmd_list)
 296
 297     def strfunction(self, target, source, env):
 298         cmd_list = env.subst_list(self.cmd_list, 0, target, source)
 299         return string.join(map(_string_from_cmd_list, cmd_list), "\n")
 300
 301     def execute(self, target, source, env):
 302         """Execute a command action.
 303
 304         This will handle lists of commands as well as individual commands,
 305         because construction variable substitution may turn a single
 306         "command" into a list.  This means that this class can actually
 307         handle lists of commands, even though that's not how we use it
 308         externally.
 309         """
 310         import SCons.Util
 311
 312         escape = env.get('ESCAPE', lambda x: x)
 313
 314         if env.has_key('SHELL'):
 315             shell = env['SHELL']
 316         else:
 317             raise SCons.Errors.UserError('Missing SHELL construction variable.')
 318
 319         # for SConf support (by now): check, if we want to pipe the command
 320         # output to somewhere else
 321         if env.has_key('PIPE_BUILD'):
 322             pipe_build = 1
 323             if env.has_key('PSPAWN'):
 324                 pspawn = env['PSPAWN']
 325             else:
 326                 raise SCons.Errors.UserError('Missing PSPAWN construction variable.')
 327             if env.has_key('PSTDOUT'):
 328                 pstdout = env['PSTDOUT']
 329             else:
 330                 raise SCons.Errors.UserError('Missing PSTDOUT construction variable.')
 331             if env.has_key('PSTDERR'):
 332                 pstderr = env['PSTDERR']
 333             else:
 334                 raise SCons.Errors.UserError('Missing PSTDOUT construction variable.')
 335         else:
 336             pipe_build = 0
 337             if env.has_key('SPAWN'):
 338                 spawn = env['SPAWN']
 339             else:
 340                 raise SCons.Errors.UserError('Missing SPAWN construction variable.')
 341
 342         cmd_list = env.subst_list(self.cmd_list, 0, target, source)
 343         for cmd_line in cmd_list:
 344             if len(cmd_line):
 345                 try:
 346                     ENV = env['ENV']
 347                 except KeyError:
 348                     global default_ENV
 349                     if not default_ENV:
 350                         import SCons.Environment
 351                         default_ENV = SCons.Environment.Environment()['ENV']
 352                     ENV = default_ENV
 353
 354                 # ensure that the ENV values are all strings:
 355                 for key, value in ENV.items():
 356                     if SCons.Util.is_List(value):
 357                         # If the value is a list, then we assume
 358                         # it is a path list, because that's a pretty
 359                         # common list like value to stick in an environment
 360                         # variable:
 361                         value = SCons.Util.flatten(value)
 362                         ENV[key] = string.join(map(str, value), os.pathsep)
 363                     elif not SCons.Util.is_String(value):
 364                         # If it isn't a string or a list, then
 365                         # we just coerce it to a string, which
 366                         # is proper way to handle Dir and File instances
 367                         # and will produce something reasonable for
 368                         # just about everything else:
 369                         ENV[key] = str(value)
 370
 371                 # Escape the command line for the command
 372                 # interpreter we are using
 373                 cmd_line = SCons.Util.escape_list(cmd_line, escape)
 374                 if pipe_build:
 375                     ret = pspawn( shell, escape, cmd_line[0], cmd_line,
 376                                   ENV, pstdout, pstderr )
 377                 else:
 378                     ret = spawn(shell, escape, cmd_line[0], cmd_line, ENV)
 379                 if ret:
 380                     return ret
 381         return 0
 382
 383     def get_contents(self, target, source, env, dict=None):
 384         """Return the signature contents of this action's command line.
 385
 386         This strips $(-$) and everything in between the string,
 387         since those parts don't affect signatures.
 388         """
 389         cmd = self.cmd_list
 390         if SCons.Util.is_List(cmd):
 391             cmd = string.join(map(str, cmd))
 392         else:
 393             cmd = str(cmd)
 394         return env.subst_target_source(cmd, SCons.Util.SUBST_SIG, target, source, dict)
 395
 396 class CommandGeneratorAction(ActionBase):
 397     """Class for command-generator actions."""
 398     def __init__(self, generator, **kw):
 399         if __debug__: logInstanceCreation(self)
 400         apply(ActionBase.__init__, (self,), kw)
 401         self.generator = generator
 402
 403     def __generate(self, target, source, env, for_signature):
 404         # ensure that target is a list, to make it easier to write
 405         # generator functions:
 406         if not SCons.Util.is_List(target):
 407             target = [target]
 408
 409         ret = self.generator(target=target, source=source, env=env, for_signature=for_signature)
 410         gen_cmd = Action(ret)
 411         if not gen_cmd:
 412             raise SCons.Errors.UserError("Object returned from command generator: %s cannot be used to create an Action." % repr(ret))
 413         return gen_cmd
 414
 415     def strfunction(self, target, source, env):
 416         if not SCons.Util.is_List(source):
 417             source = [source]
 418         rsources = map(rfile, source)
 419         act = self.__generate(target, source, env, 0)
 420         if act.strfunction:
 421             return act.strfunction(target, rsources, env)
 422         else:
 423             return None
 424
 425     def __str__(self):
 426         try:
 427             env = self.presub_env or {}
 428         except AttributeError:
 429             env = {}
 430         act = self.__generate([], [], env, 0)
 431         return str(act)
 432
 433     def genstring(self, target, source, env):
 434         return str(self.__generate(target, source, env, 0))
 435
 436     def execute(self, target, source, env):
 437         rsources = map(rfile, source)
 438         act = self.__generate(target, source, env, 0)
 439         return act.execute(target, source, env)
 440
 441     def get_contents(self, target, source, env, dict=None):
 442         """Return the signature contents of this action's command line.
 443
 444         This strips $(-$) and everything in between the string,
 445         since those parts don't affect signatures.
 446         """
 447         return self.__generate(target, source, env, 1).get_contents(target, source, env, dict=None)
 448
 449 class LazyCmdGenerator:
 450     """This is not really an Action, although it kind of looks like one.
 451     This is really a simple callable class that acts as a command
 452     generator.  It holds on to a key into an Environment dictionary,
 453     then waits until execution time to see what type it is, then tries
 454     to create an Action out of it."""
 455     def __init__(self, var):
 456         if __debug__: logInstanceCreation(self)
 457         self.var = SCons.Util.to_String(var)
 458
 459     def strfunction(self, target, source, env):
 460         try:
 461             return env[self.var]
 462         except KeyError:
 463             # The variable reference substitutes to nothing.
 464             return ''
 465
 466     def __str__(self):
 467         return 'LazyCmdGenerator: %s'%str(self.var)
 468
 469     def __call__(self, target, source, env, for_signature):
 470         try:
 471             return env[self.var]
 472         except KeyError:
 473             # The variable reference substitutes to nothing.
 474             return ''
 475
 476     def __cmp__(self, other):
 477         return cmp(self.__dict__, other.__dict__)
 478
 479 class FunctionAction(ActionBase):
 480     """Class for Python function actions."""
 481
 482     def __init__(self, execfunction, **kw):
 483         if __debug__: logInstanceCreation(self)
 484         self.execfunction = execfunction
 485         apply(ActionBase.__init__, (self,), kw)
 486         self.varlist = kw.get('varlist', [])
 487
 488     def function_name(self):
 489         try:
 490             return self.execfunction.__name__
 491         except AttributeError:
 492             try:
 493                 return self.execfunction.__class__.__name__
 494             except AttributeError:
 495                 return "unknown_python_function"
 496
 497     def strfunction(self, target, source, env):
 498         def array(a):
 499             def quote(s):
 500                 return '"' + str(s) + '"'
 501             return '[' + string.join(map(quote, a), ", ") + ']'
 502         name = self.function_name()
 503         tstr = array(target)
 504         sstr = array(source)
 505         return "%s(%s, %s)" % (name, tstr, sstr)
 506
 507     def __str__(self):
 508         return "%s(env, target, source)" % self.function_name()
 509
 510     def execute(self, target, source, env):
 511         rsources = map(rfile, source)
 512         return self.execfunction(target=target, source=rsources, env=env)
 513
 514     def get_contents(self, target, source, env, dict=None):
 515         """Return the signature contents of this callable action.
 516
 517         By providing direct access to the code object of the
 518         function, Python makes this extremely easy.  Hooray!
 519         """
 520         try:
 521             # "self.execfunction" is a function.
 522             contents = str(self.execfunction.func_code.co_code)
 523         except AttributeError:
 524             # "self.execfunction" is a callable object.
 525             try:
 526                 contents = str(self.execfunction.__call__.im_func.func_code.co_code)
 527             except AttributeError:
 528                 try:
 529                     # See if execfunction will do the heavy lifting for us.
 530                     gc = self.execfunction.get_contents
 531                 except AttributeError:
 532                     # This is weird, just do the best we can.
 533                     contents = str(self.execfunction)
 534                 else:
 535                     contents = gc(target, source, env, dict)
 536         return contents + env.subst(string.join(map(lambda v: '${'+v+'}',
 537                                                      self.varlist)))
 538
 539 class ListAction(ActionBase):
 540     """Class for lists of other actions."""
 541     def __init__(self, list, **kw):
 542         if __debug__: logInstanceCreation(self)
 543         apply(ActionBase.__init__, (self,), kw)
 544         self.list = map(lambda x: Action(x), list)
 545
 546     def get_actions(self):
 547         return self.list
 548
 549     def __str__(self):
 550         s = []
 551         for l in self.list:
 552             s.append(str(l))
 553         return string.join(s, "\n")
 554
 555     def strfunction(self, target, source, env):
 556         s = []
 557         for l in self.list:
 558             if l.strfunction:
 559                 x = l.strfunction(target, source, env)
 560                 if not SCons.Util.is_List(x):
 561                     x = [x]
 562                 s.extend(x)
 563         return string.join(s, "\n")
 564
 565     def execute(self, target, source, env):
 566         for l in self.list:
 567             r = l.execute(target, source, env)
 568             if r:
 569                 return r
 570         return 0
 571
 572     def get_contents(self, target, source, env, dict=None):
 573         """Return the signature contents of this action list.
 574
 575         Simple concatenation of the signatures of the elements.
 576         """
 577         dict = SCons.Util.subst_dict(target, source)
 578         return string.join(map(lambda x, t=target, s=source, e=env, d=dict:
 579                                       x.get_contents(t, s, e, d),
 580                                self.list),
 581                            "")
 582
 583 class ActionCaller:
 584     """A class for delaying calling an Action function with specific
 585     (positional and keyword) arguments until the Action is actually
 586     executed.
 587
 588     This class looks to the rest of the world like a normal Action object,
 589     but what it's really doing is hanging on to the arguments until we
 590     have a target, source and env to use for the expansion.
 591     """
 592     def __init__(self, parent, args, kw):
 593         self.parent = parent
 594         self.args = args
 595         self.kw = kw
 596     def get_contents(self, target, source, env, dict=None):
 597         actfunc = self.parent.actfunc
 598         try:
 599             # "self.actfunc" is a function.
 600             contents = str(actfunc.func_code.co_code)
 601         except AttributeError:
 602             # "self.actfunc" is a callable object.
 603             try:
 604                 contents = str(actfunc.__call__.im_func.func_code.co_code)
 605             except AttributeError:
 606                 # No __call__() method, so it might be a builtin
 607                 # or something like that.  Do the best we can.
 608                 contents = str(actfunc)
 609         return contents
 610     def subst_args(self, target, source, env):
 611         return map(lambda x, e=env, t=target, s=source:
 612                           e.subst(x, 0, t, s),
 613                    self.args)
 614     def subst_kw(self, target, source, env):
 615         kw = {}
 616         for key in self.kw.keys():
 617             kw[key] = env.subst(self.kw[key], 0, target, source)
 618         return kw
 619     def __call__(self, target, source, env):
 620         args = self.subst_args(target, source, env)
 621         kw = self.subst_kw(target, source, env)
 622         return apply(self.parent.actfunc, args, kw)
 623     def strfunction(self, target, source, env):
 624         args = self.subst_args(target, source, env)
 625         kw = self.subst_kw(target, source, env)
 626         return apply(self.parent.strfunc, args, kw)
 627
 628 class ActionFactory:
 629     """A factory class that will wrap up an arbitrary function
 630     as an SCons-executable Action object.
 631
 632     The real heavy lifting here is done by the ActionCaller class.
 633     We just collect the (positional and keyword) arguments that we're
 634     called with and give them to the ActionCaller object we create,
 635     so it can hang onto them until it needs them.
 636     """
 637     def __init__(self, actfunc, strfunc):
 638         self.actfunc = actfunc
 639         self.strfunc = strfunc
 640     def __call__(self, *args, **kw):
 641         ac = ActionCaller(self, args, kw)
 642         return Action(ac, strfunction=ac.strfunction)