src/engine/SCons/Script/SConscript.py

   1 """SCons.Script.SConscript
   2
   3 This module defines the Python API provided to SConscript and SConstruct
   4 files.
   5
   6 """
   7
   8 #
   9 # __COPYRIGHT__
  10 #
  11 # Permission is hereby granted, free of charge, to any person obtaining
  12 # a copy of this software and associated documentation files (the
  13 # "Software"), to deal in the Software without restriction, including
  14 # without limitation the rights to use, copy, modify, merge, publish,
  15 # distribute, sublicense, and/or sell copies of the Software, and to
  16 # permit persons to whom the Software is furnished to do so, subject to
  17 # the following conditions:
  18 #
  19 # The above copyright notice and this permission notice shall be included
  20 # in all copies or substantial portions of the Software.
  21 #
  22 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  23 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  24 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  25 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  26 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  27 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  28 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  29 #
  30 from __future__ import generators  ### KEEP FOR COMPATIBILITY FIXERS
  31
  32 __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
  33
  34 import SCons
  35 import SCons.Action
  36 import SCons.Builder
  37 import SCons.Defaults
  38 import SCons.Environment
  39 import SCons.Errors
  40 import SCons.Node
  41 import SCons.Node.Alias
  42 import SCons.Node.FS
  43 import SCons.Platform
  44 import SCons.SConf
  45 import SCons.Script.Main
  46 import SCons.Tool
  47 import SCons.Util
  48
  49 import os
  50 import os.path
  51 import re
  52 import sys
  53 import traceback
  54 import types
  55 import UserList
  56
  57 # The following variables used to live in this module.  Some
  58 # SConscript files out there may have referred to them directly as
  59 # SCons.Script.SConscript.*.  This is now supported by some special
  60 # handling towards the bottom of the SConscript.__init__.py module.
  61 #Arguments = {}
  62 #ArgList = []
  63 #BuildTargets = TargetList()
  64 #CommandLineTargets = []
  65 #DefaultTargets = []
  66
  67 class SConscriptReturn(Exception):
  68     pass
  69
  70 launch_dir = os.path.abspath(os.curdir)
  71
  72 GlobalDict = None
  73
  74 # global exports set by Export():
  75 global_exports = {}
  76
  77 # chdir flag
  78 sconscript_chdir = 1
  79
  80 def get_calling_namespaces():
  81     """Return the locals and globals for the function that called
  82     into this module in the current call stack."""
  83     try: 1/0
  84     except ZeroDivisionError:
  85         # Don't start iterating with the current stack-frame to
  86         # prevent creating reference cycles (f_back is safe).
  87         frame = sys.exc_info()[2].tb_frame.f_back
  88
  89     # Find the first frame that *isn't* from this file.  This means
  90     # that we expect all of the SCons frames that implement an Export()
  91     # or SConscript() call to be in this file, so that we can identify
  92     # the first non-Script.SConscript frame as the user's local calling
  93     # environment, and the locals and globals dictionaries from that
  94     # frame as the calling namespaces.  See the comment below preceding
  95     # the DefaultEnvironmentCall block for even more explanation.
  96     while frame.f_globals.get("__name__") == __name__:
  97         frame = frame.f_back
  98
  99     return frame.f_locals, frame.f_globals
 100
 101
 102 def compute_exports(exports):
 103     """Compute a dictionary of exports given one of the parameters
 104     to the Export() function or the exports argument to SConscript()."""
 105
 106     loc, glob = get_calling_namespaces()
 107
 108     retval = {}
 109     try:
 110         for export in exports:
 111             if SCons.Util.is_Dict(export):
 112                 retval.update(export)
 113             else:
 114                 try:
 115                     retval[export] = loc[export]
 116                 except KeyError:
 117                     retval[export] = glob[export]
 118     except KeyError, x:
 119         raise SCons.Errors.UserError, "Export of non-existent variable '%s'"%x
 120
 121     return retval
 122
 123 class Frame:
 124     """A frame on the SConstruct/SConscript call stack"""
 125     def __init__(self, fs, exports, sconscript):
 126         self.globals = BuildDefaultGlobals()
 127         self.retval = None
 128         self.prev_dir = fs.getcwd()
 129         self.exports = compute_exports(exports)  # exports from the calling SConscript
 130         # make sure the sconscript attr is a Node.
 131         if isinstance(sconscript, SCons.Node.Node):
 132             self.sconscript = sconscript
 133         elif sconscript == '-':
 134             self.sconscript = None
 135         else:
 136             self.sconscript = fs.File(str(sconscript))
 137
 138 # the SConstruct/SConscript call stack:
 139 call_stack = []
 140
 141 # For documentation on the methods in this file, see the scons man-page
 142
 143 def Return(*vars, **kw):
 144     retval = []
 145     try:
 146         fvars = SCons.Util.flatten(vars)
 147         for var in fvars:
 148             for v in var.split():
 149                 retval.append(call_stack[-1].globals[v])
 150     except KeyError, x:
 151         raise SCons.Errors.UserError, "Return of non-existent variable '%s'"%x
 152
 153     if len(retval) == 1:
 154         call_stack[-1].retval = retval[0]
 155     else:
 156         call_stack[-1].retval = tuple(retval)
 157
 158     stop = kw.get('stop', True)
 159
 160     if stop:
 161         raise SConscriptReturn
 162
 163
 164 stack_bottom = '% Stack boTTom %' # hard to define a variable w/this name :)
 165
 166 def _SConscript(fs, *files, **kw):
 167     top = fs.Top
 168     sd = fs.SConstruct_dir.rdir()
 169     exports = kw.get('exports', [])
 170
 171     # evaluate each SConscript file
 172     results = []
 173     for fn in files:
 174         call_stack.append(Frame(fs, exports, fn))
 175         old_sys_path = sys.path
 176         try:
 177             SCons.Script.sconscript_reading = SCons.Script.sconscript_reading + 1
 178             if fn == "-":
 179                 exec sys.stdin in call_stack[-1].globals
 180             else:
 181                 if isinstance(fn, SCons.Node.Node):
 182                     f = fn
 183                 else:
 184                     f = fs.File(str(fn))
 185                 _file_ = None
 186
 187                 # Change directory to the top of the source
 188                 # tree to make sure the os's cwd and the cwd of
 189                 # fs match so we can open the SConscript.
 190                 fs.chdir(top, change_os_dir=1)
 191                 if f.rexists():
 192                     actual = f.rfile()
 193                     _file_ = open(actual.get_abspath(), "r")
 194                 elif f.srcnode().rexists():
 195                     actual = f.srcnode().rfile()
 196                     _file_ = open(actual.get_abspath(), "r")
 197                 elif f.has_src_builder():
 198                     # The SConscript file apparently exists in a source
 199                     # code management system.  Build it, but then clear
 200                     # the builder so that it doesn't get built *again*
 201                     # during the actual build phase.
 202                     f.build()
 203                     f.built()
 204                     f.builder_set(None)
 205                     if f.exists():
 206                         _file_ = open(f.get_abspath(), "r")
 207                 if _file_:
 208                     # Chdir to the SConscript directory.  Use a path
 209                     # name relative to the SConstruct file so that if
 210                     # we're using the -f option, we're essentially
 211                     # creating a parallel SConscript directory structure
 212                     # in our local directory tree.
 213                     #
 214                     # XXX This is broken for multiple-repository cases
 215                     # where the SConstruct and SConscript files might be
 216                     # in different Repositories.  For now, cross that
 217                     # bridge when someone comes to it.
 218                     try:
 219                         src_dir = kw['src_dir']
 220                     except KeyError:
 221                         ldir = fs.Dir(f.dir.get_path(sd))
 222                     else:
 223                         ldir = fs.Dir(src_dir)
 224                         if not ldir.is_under(f.dir):
 225                             # They specified a source directory, but
 226                             # it's above the SConscript directory.
 227                             # Do the sensible thing and just use the
 228                             # SConcript directory.
 229                             ldir = fs.Dir(f.dir.get_path(sd))
 230                     try:
 231                         fs.chdir(ldir, change_os_dir=sconscript_chdir)
 232                     except OSError:
 233                         # There was no local directory, so we should be
 234                         # able to chdir to the Repository directory.
 235                         # Note that we do this directly, not through
 236                         # fs.chdir(), because we still need to
 237                         # interpret the stuff within the SConscript file
 238                         # relative to where we are logically.
 239                         fs.chdir(ldir, change_os_dir=0)
 240                         os.chdir(actual.dir.get_abspath())
 241
 242                     # Append the SConscript directory to the beginning
 243                     # of sys.path so Python modules in the SConscript
 244                     # directory can be easily imported.
 245                     sys.path = [ f.dir.get_abspath() ] + sys.path
 246
 247                     # This is the magic line that actually reads up
 248                     # and executes the stuff in the SConscript file.
 249                     # The locals for this frame contain the special
 250                     # bottom-of-the-stack marker so that any
 251                     # exceptions that occur when processing this
 252                     # SConscript can base the printed frames at this
 253                     # level and not show SCons internals as well.
 254                     call_stack[-1].globals.update({stack_bottom:1})
 255                     old_file = call_stack[-1].globals.get('__file__')
 256                     try:
 257                         del call_stack[-1].globals['__file__']
 258                     except KeyError:
 259                         pass
 260                     try:
 261                         try:
 262                             exec _file_ in call_stack[-1].globals
 263                         except SConscriptReturn:
 264                             pass
 265                     finally:
 266                         if old_file is not None:
 267                             call_stack[-1].globals.update({__file__:old_file})
 268                 else:
 269                     SCons.Warnings.warn(SCons.Warnings.MissingSConscriptWarning,
 270                              "Ignoring missing SConscript '%s'" % f.path)
 271
 272         finally:
 273             SCons.Script.sconscript_reading = SCons.Script.sconscript_reading - 1
 274             sys.path = old_sys_path
 275             frame = call_stack.pop()
 276             try:
 277                 fs.chdir(frame.prev_dir, change_os_dir=sconscript_chdir)
 278             except OSError:
 279                 # There was no local directory, so chdir to the
 280                 # Repository directory.  Like above, we do this
 281                 # directly.
 282                 fs.chdir(frame.prev_dir, change_os_dir=0)
 283                 rdir = frame.prev_dir.rdir()
 284                 rdir._create()  # Make sure there's a directory there.
 285                 try:
 286                     os.chdir(rdir.get_abspath())
 287                 except OSError, e:
 288                     # We still couldn't chdir there, so raise the error,
 289                     # but only if actions are being executed.
 290                     #
 291                     # If the -n option was used, the directory would *not*
 292                     # have been created and we should just carry on and
 293                     # let things muddle through.  This isn't guaranteed
 294                     # to work if the SConscript files are reading things
 295                     # from disk (for example), but it should work well
 296                     # enough for most configurations.
 297                     if SCons.Action.execute_actions:
 298                         raise e
 299
 300             results.append(frame.retval)
 301
 302     # if we only have one script, don't return a tuple
 303     if len(results) == 1:
 304         return results[0]
 305     else:
 306         return tuple(results)
 307
 308 def SConscript_exception(file=sys.stderr):
 309     """Print an exception stack trace just for the SConscript file(s).
 310     This will show users who have Python errors where the problem is,
 311     without cluttering the output with all of the internal calls leading
 312     up to where we exec the SConscript."""
 313     exc_type, exc_value, exc_tb = sys.exc_info()
 314     tb = exc_tb
 315     while tb and stack_bottom not in tb.tb_frame.f_locals:
 316         tb = tb.tb_next
 317     if not tb:
 318         # We did not find our exec statement, so this was actually a bug
 319         # in SCons itself.  Show the whole stack.
 320         tb = exc_tb
 321     stack = traceback.extract_tb(tb)
 322     try:
 323         type = exc_type.__name__
 324     except AttributeError:
 325         type = str(exc_type)
 326         if type[:11] == "exceptions.":
 327             type = type[11:]
 328     file.write('%s: %s:\n' % (type, exc_value))
 329     for fname, line, func, text in stack:
 330         file.write('  File "%s", line %d:\n' % (fname, line))
 331         file.write('    %s\n' % text)
 332
 333 def annotate(node):
 334     """Annotate a node with the stack frame describing the
 335     SConscript file and line number that created it."""
 336     tb = sys.exc_info()[2]
 337     while tb and stack_bottom not in tb.tb_frame.f_locals:
 338         tb = tb.tb_next
 339     if not tb:
 340         # We did not find any exec of an SConscript file: what?!
 341         raise SCons.Errors.InternalError, "could not find SConscript stack frame"
 342     node.creator = traceback.extract_stack(tb)[0]
 343
 344 # The following line would cause each Node to be annotated using the
 345 # above function.  Unfortunately, this is a *huge* performance hit, so
 346 # leave this disabled until we find a more efficient mechanism.
 347 #SCons.Node.Annotate = annotate
 348
 349 class SConsEnvironment(SCons.Environment.Base):
 350     """An Environment subclass that contains all of the methods that
 351     are particular to the wrapper SCons interface and which aren't
 352     (or shouldn't be) part of the build engine itself.
 353
 354     Note that not all of the methods of this class have corresponding
 355     global functions, there are some private methods.
 356     """
 357
 358     #
 359     # Private methods of an SConsEnvironment.
 360     #
 361     def _exceeds_version(self, major, minor, v_major, v_minor):
 362         """Return 1 if 'major' and 'minor' are greater than the version
 363         in 'v_major' and 'v_minor', and 0 otherwise."""
 364         return (major > v_major or (major == v_major and minor > v_minor))
 365
 366     def _get_major_minor_revision(self, version_string):
 367         """Split a version string into major, minor and (optionally)
 368         revision parts.
 369
 370         This is complicated by the fact that a version string can be
 371         something like 3.2b1."""
 372         version = version_string.split(' ')[0].split('.')
 373         v_major = int(version[0])
 374         v_minor = int(re.match('\d+', version[1]).group())
 375         if len(version) >= 3:
 376             v_revision = int(re.match('\d+', version[2]).group())
 377         else:
 378             v_revision = 0
 379         return v_major, v_minor, v_revision
 380
 381     def _get_SConscript_filenames(self, ls, kw):
 382         """
 383         Convert the parameters passed to # SConscript() calls into a list
 384         of files and export variables.  If the parameters are invalid,
 385         throws SCons.Errors.UserError. Returns a tuple (l, e) where l
 386         is a list of SConscript filenames and e is a list of exports.
 387         """
 388         exports = []
 389
 390         if len(ls) == 0:
 391             try:
 392                 dirs = kw["dirs"]
 393             except KeyError:
 394                 raise SCons.Errors.UserError, \
 395                       "Invalid SConscript usage - no parameters"
 396
 397             if not SCons.Util.is_List(dirs):
 398                 dirs = [ dirs ]
 399             dirs = list(map(str, dirs))
 400
 401             name = kw.get('name', 'SConscript')
 402
 403             files = [os.path.join(n, name) for n in dirs]
 404
 405         elif len(ls) == 1:
 406
 407             files = ls[0]
 408
 409         elif len(ls) == 2:
 410
 411             files   = ls[0]
 412             exports = self.Split(ls[1])
 413
 414         else:
 415
 416             raise SCons.Errors.UserError, \
 417                   "Invalid SConscript() usage - too many arguments"
 418
 419         if not SCons.Util.is_List(files):
 420             files = [ files ]
 421
 422         if kw.get('exports'):
 423             exports.extend(self.Split(kw['exports']))
 424
 425         variant_dir = kw.get('variant_dir') or kw.get('build_dir')
 426         if variant_dir:
 427             if len(files) != 1:
 428                 raise SCons.Errors.UserError, \
 429                     "Invalid SConscript() usage - can only specify one SConscript with a variant_dir"
 430             duplicate = kw.get('duplicate', 1)
 431             src_dir = kw.get('src_dir')
 432             if not src_dir:
 433                 src_dir, fname = os.path.split(str(files[0]))
 434                 files = [os.path.join(str(variant_dir), fname)]
 435             else:
 436                 if not isinstance(src_dir, SCons.Node.Node):
 437                     src_dir = self.fs.Dir(src_dir)
 438                 fn = files[0]
 439                 if not isinstance(fn, SCons.Node.Node):
 440                     fn = self.fs.File(fn)
 441                 if fn.is_under(src_dir):
 442                     # Get path relative to the source directory.
 443                     fname = fn.get_path(src_dir)
 444                     files = [os.path.join(str(variant_dir), fname)]
 445                 else:
 446                     files = [fn.abspath]
 447                 kw['src_dir'] = variant_dir
 448             self.fs.VariantDir(variant_dir, src_dir, duplicate)
 449
 450         return (files, exports)
 451
 452     #
 453     # Public methods of an SConsEnvironment.  These get
 454     # entry points in the global name space so they can be called
 455     # as global functions.
 456     #
 457
 458     def Configure(self, *args, **kw):
 459         if not SCons.Script.sconscript_reading:
 460             raise SCons.Errors.UserError, "Calling Configure from Builders is not supported."
 461         kw['_depth'] = kw.get('_depth', 0) + 1
 462         return SCons.Environment.Base.Configure(self, *args, **kw)
 463
 464     def Default(self, *targets):
 465         SCons.Script._Set_Default_Targets(self, targets)
 466
 467     def EnsureSConsVersion(self, major, minor, revision=0):
 468         """Exit abnormally if the SCons version is not late enough."""
 469         scons_ver = self._get_major_minor_revision(SCons.__version__)
 470         if scons_ver < (major, minor, revision):
 471             if revision:
 472                 scons_ver_string = '%d.%d.%d' % (major, minor, revision)
 473             else:
 474                 scons_ver_string = '%d.%d' % (major, minor)
 475             print "SCons %s or greater required, but you have SCons %s" % \
 476                   (scons_ver_string, SCons.__version__)
 477             sys.exit(2)
 478
 479     def EnsurePythonVersion(self, major, minor):
 480         """Exit abnormally if the Python version is not late enough."""
 481         try:
 482             v_major, v_minor, v_micro, release, serial = sys.version_info
 483             python_ver = (v_major, v_minor)
 484         except AttributeError:
 485             python_ver = self._get_major_minor_revision(sys.version)[:2]
 486         if python_ver < (major, minor):
 487             v = sys.version.split(" ", 1)[0]
 488             print "Python %d.%d or greater required, but you have Python %s" %(major,minor,v)
 489             sys.exit(2)
 490
 491     def Exit(self, value=0):
 492         sys.exit(value)
 493
 494     def Export(self, *vars, **kw):
 495         for var in vars:
 496             global_exports.update(compute_exports(self.Split(var)))
 497         global_exports.update(kw)
 498
 499     def GetLaunchDir(self):
 500         global launch_dir
 501         return launch_dir
 502
 503     def GetOption(self, name):
 504         name = self.subst(name)
 505         return SCons.Script.Main.GetOption(name)
 506
 507     def Help(self, text):
 508         text = self.subst(text, raw=1)
 509         SCons.Script.HelpFunction(text)
 510
 511     def Import(self, *vars):
 512         try:
 513             frame = call_stack[-1]
 514             globals = frame.globals
 515             exports = frame.exports
 516             for var in vars:
 517                 var = self.Split(var)
 518                 for v in var:
 519                     if v == '*':
 520                         globals.update(global_exports)
 521                         globals.update(exports)
 522                     else:
 523                         if v in exports:
 524                             globals[v] = exports[v]
 525                         else:
 526                             globals[v] = global_exports[v]
 527         except KeyError,x:
 528             raise SCons.Errors.UserError, "Import of non-existent variable '%s'"%x
 529
 530     def SConscript(self, *ls, **kw):
 531         def subst_element(x, subst=self.subst):
 532             if SCons.Util.is_List(x):
 533                 x = list(map(subst, x))
 534             else:
 535                 x = subst(x)
 536             return x
 537         ls = list(map(subst_element, ls))
 538         subst_kw = {}
 539         for key, val in kw.items():
 540             if SCons.Util.is_String(val):
 541                 val = self.subst(val)
 542             elif SCons.Util.is_List(val):
 543                 result = []
 544                 for v in val:
 545                     if SCons.Util.is_String(v):
 546                         v = self.subst(v)
 547                     result.append(v)
 548                 val = result
 549             subst_kw[key] = val
 550
 551         files, exports = self._get_SConscript_filenames(ls, subst_kw)
 552         subst_kw['exports'] = exports
 553         return _SConscript(self.fs, *files, **subst_kw)
 554
 555     def SConscriptChdir(self, flag):
 556         global sconscript_chdir
 557         sconscript_chdir = flag
 558
 559     def SetOption(self, name, value):
 560         name = self.subst(name)
 561         SCons.Script.Main.SetOption(name, value)
 562
 563 #
 564 #
 565 #
 566 SCons.Environment.Environment = SConsEnvironment
 567
 568 def Configure(*args, **kw):
 569     if not SCons.Script.sconscript_reading:
 570         raise SCons.Errors.UserError, "Calling Configure from Builders is not supported."
 571     kw['_depth'] = 1
 572     return SCons.SConf.SConf(*args, **kw)
 573
 574 # It's very important that the DefaultEnvironmentCall() class stay in this
 575 # file, with the get_calling_namespaces() function, the compute_exports()
 576 # function, the Frame class and the SConsEnvironment.Export() method.
 577 # These things make up the calling stack leading up to the actual global
 578 # Export() or SConscript() call that the user issued.  We want to allow
 579 # users to export local variables that they define, like so:
 580 #
 581 #       def func():
 582 #           x = 1
 583 #           Export('x')
 584 #
 585 # To support this, the get_calling_namespaces() function assumes that
 586 # the *first* stack frame that's not from this file is the local frame
 587 # for the Export() or SConscript() call.
 588
 589 _DefaultEnvironmentProxy = None
 590
 591 def get_DefaultEnvironmentProxy():
 592     global _DefaultEnvironmentProxy
 593     if not _DefaultEnvironmentProxy:
 594         default_env = SCons.Defaults.DefaultEnvironment()
 595         _DefaultEnvironmentProxy = SCons.Environment.NoSubstitutionProxy(default_env)
 596     return _DefaultEnvironmentProxy
 597
 598 class DefaultEnvironmentCall:
 599     """A class that implements "global function" calls of
 600     Environment methods by fetching the specified method from the
 601     DefaultEnvironment's class.  Note that this uses an intermediate
 602     proxy class instead of calling the DefaultEnvironment method
 603     directly so that the proxy can override the subst() method and
 604     thereby prevent expansion of construction variables (since from
 605     the user's point of view this was called as a global function,
 606     with no associated construction environment)."""
 607     def __init__(self, method_name, subst=0):
 608         self.method_name = method_name
 609         if subst:
 610             self.factory = SCons.Defaults.DefaultEnvironment
 611         else:
 612             self.factory = get_DefaultEnvironmentProxy
 613     def __call__(self, *args, **kw):
 614         env = self.factory()
 615         method = getattr(env, self.method_name)
 616         return method(*args, **kw)
 617
 618
 619 def BuildDefaultGlobals():
 620     """
 621     Create a dictionary containing all the default globals for
 622     SConstruct and SConscript files.
 623     """
 624
 625     global GlobalDict
 626     if GlobalDict is None:
 627         GlobalDict = {}
 628
 629         import SCons.Script
 630         d = SCons.Script.__dict__
 631         def not_a_module(m, d=d, mtype=type(SCons.Script)):
 632              return type(d[m]) != mtype
 633         for m in filter(not_a_module, dir(SCons.Script)):
 634              GlobalDict[m] = d[m]
 635
 636     return GlobalDict.copy()
 637
 638 # Local Variables:
 639 # tab-width:4
 640 # indent-tabs-mode:nil
 641 # End:
 642 # vim: set expandtab tabstop=4 shiftwidth=4: