Package SCons :: Package Script :: Module SConscript'
[hide private]
[frames] | no frames]

Source Code for Module SCons.Script.SConscript'

  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 (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation 
 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   
 31  __revision__ = "src/engine/SCons/Script/SConscript.py 4720 2010/03/24 03:14:11 jars" 
 32   
 33  import SCons 
 34  import SCons.Action 
 35  import SCons.Builder 
 36  import SCons.Defaults 
 37  import SCons.Environment 
 38  import SCons.Errors 
 39  import SCons.Node 
 40  import SCons.Node.Alias 
 41  import SCons.Node.FS 
 42  import SCons.Platform 
 43  import SCons.SConf 
 44  import SCons.Script.Main 
 45  import SCons.Tool 
 46  import SCons.Util 
 47   
 48  import os 
 49  import os.path 
 50  import re 
 51  import string 
 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 string.split(var): 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 not tb.tb_frame.f_locals.has_key(stack_bottom): 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 not tb.tb_frame.f_locals.has_key(stack_bottom): 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 = string.split(string.split(version_string, ' ')[0], '.') 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 = map(str, dirs) 400 401 name = kw.get('name', 'SConscript') 402 403 files = map(lambda n, name = name: os.path.join(n, name), 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 apply(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 = string.split(sys.version, " ", 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 exports.has_key(v): 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 = map(subst, x) 534 else: 535 x = subst(x) 536 return x
537 ls = 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 apply(_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 apply(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 apply(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: 643