1 """SCons.Script.SConscript
3 This module defines the Python API provided to SConscript and SConstruct
9 # Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 The SCons Foundation
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:
19 # The above copyright notice and this permission notice shall be included
20 # in all copies or substantial portions of the Software.
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.
31 __revision__ = "src/engine/SCons/Script/SConscript.py 3842 2008/12/20 22:59:52 scons"
37 import SCons.Environment
40 import SCons.Node.Alias
44 import SCons.Script.Main
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.
63 #BuildTargets = TargetList()
64 #CommandLineTargets = []
67 class SConscriptReturn(Exception):
70 launch_dir = os.path.abspath(os.curdir)
74 # global exports set by Export():
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."""
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
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__:
99 return frame.f_locals, frame.f_globals
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()."""
106 loc, glob = get_calling_namespaces()
110 for export in exports:
111 if SCons.Util.is_Dict(export):
112 retval.update(export)
115 retval[export] = loc[export]
117 retval[export] = glob[export]
119 raise SCons.Errors.UserError, "Export of non-existent variable '%s'"%x
124 """A frame on the SConstruct/SConscript call stack"""
125 def __init__(self, fs, exports, sconscript):
126 self.globals = BuildDefaultGlobals()
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
136 self.sconscript = fs.File(str(sconscript))
138 # the SConstruct/SConscript call stack:
141 # For documentation on the methods in this file, see the scons man-page
143 def Return(*vars, **kw):
146 fvars = SCons.Util.flatten(vars)
148 for v in string.split(var):
149 retval.append(call_stack[-1].globals[v])
151 raise SCons.Errors.UserError, "Return of non-existent variable '%s'"%x
154 call_stack[-1].retval = retval[0]
156 call_stack[-1].retval = tuple(retval)
158 stop = kw.get('stop', True)
161 raise SConscriptReturn
164 stack_bottom = '% Stack boTTom %' # hard to define a variable w/this name :)
166 def _SConscript(fs, *files, **kw):
168 sd = fs.SConstruct_dir.rdir()
169 exports = kw.get('exports', [])
171 # evaluate each SConscript file
174 call_stack.append(Frame(fs, exports, fn))
175 old_sys_path = sys.path
177 SCons.Script.sconscript_reading = SCons.Script.sconscript_reading + 1
179 exec sys.stdin in call_stack[-1].globals
181 if isinstance(fn, SCons.Node.Node):
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)
192 _file_ = open(f.rfile().get_abspath(), "r")
193 elif f.has_src_builder():
194 # The SConscript file apparently exists in a source
195 # code management system. Build it, but then clear
196 # the builder so that it doesn't get built *again*
197 # during the actual build phase.
202 _file_ = open(f.get_abspath(), "r")
204 # Chdir to the SConscript directory. Use a path
205 # name relative to the SConstruct file so that if
206 # we're using the -f option, we're essentially
207 # creating a parallel SConscript directory structure
208 # in our local directory tree.
210 # XXX This is broken for multiple-repository cases
211 # where the SConstruct and SConscript files might be
212 # in different Repositories. For now, cross that
213 # bridge when someone comes to it.
215 src_dir = kw['src_dir']
217 ldir = fs.Dir(f.dir.get_path(sd))
219 ldir = fs.Dir(src_dir)
220 if not ldir.is_under(f.dir):
221 # They specified a source directory, but
222 # it's above the SConscript directory.
223 # Do the sensible thing and just use the
224 # SConcript directory.
225 ldir = fs.Dir(f.dir.get_path(sd))
227 fs.chdir(ldir, change_os_dir=sconscript_chdir)
229 # There was no local directory, so we should be
230 # able to chdir to the Repository directory.
231 # Note that we do this directly, not through
232 # fs.chdir(), because we still need to
233 # interpret the stuff within the SConscript file
234 # relative to where we are logically.
235 fs.chdir(ldir, change_os_dir=0)
236 # TODO Not sure how to handle src_dir here
237 os.chdir(f.rfile().dir.get_abspath())
239 # Append the SConscript directory to the beginning
240 # of sys.path so Python modules in the SConscript
241 # directory can be easily imported.
242 sys.path = [ f.dir.get_abspath() ] + sys.path
244 # This is the magic line that actually reads up
245 # and executes the stuff in the SConscript file.
246 # The locals for this frame contain the special
247 # bottom-of-the-stack marker so that any
248 # exceptions that occur when processing this
249 # SConscript can base the printed frames at this
250 # level and not show SCons internals as well.
251 call_stack[-1].globals.update({stack_bottom:1})
252 old_file = call_stack[-1].globals.get('__file__')
254 del call_stack[-1].globals['__file__']
259 exec _file_ in call_stack[-1].globals
260 except SConscriptReturn:
263 if old_file is not None:
264 call_stack[-1].globals.update({__file__:old_file})
266 SCons.Warnings.warn(SCons.Warnings.MissingSConscriptWarning,
267 "Ignoring missing SConscript '%s'" % f.path)
270 SCons.Script.sconscript_reading = SCons.Script.sconscript_reading - 1
271 sys.path = old_sys_path
272 frame = call_stack.pop()
274 fs.chdir(frame.prev_dir, change_os_dir=sconscript_chdir)
276 # There was no local directory, so chdir to the
277 # Repository directory. Like above, we do this
279 fs.chdir(frame.prev_dir, change_os_dir=0)
280 rdir = frame.prev_dir.rdir()
281 rdir._create() # Make sure there's a directory there.
283 os.chdir(rdir.get_abspath())
285 # We still couldn't chdir there, so raise the error,
286 # but only if actions are being executed.
288 # If the -n option was used, the directory would *not*
289 # have been created and we should just carry on and
290 # let things muddle through. This isn't guaranteed
291 # to work if the SConscript files are reading things
292 # from disk (for example), but it should work well
293 # enough for most configurations.
294 if SCons.Action.execute_actions:
297 results.append(frame.retval)
299 # if we only have one script, don't return a tuple
300 if len(results) == 1:
303 return tuple(results)
305 def SConscript_exception(file=sys.stderr):
306 """Print an exception stack trace just for the SConscript file(s).
307 This will show users who have Python errors where the problem is,
308 without cluttering the output with all of the internal calls leading
309 up to where we exec the SConscript."""
310 exc_type, exc_value, exc_tb = sys.exc_info()
312 while tb and not tb.tb_frame.f_locals.has_key(stack_bottom):
315 # We did not find our exec statement, so this was actually a bug
316 # in SCons itself. Show the whole stack.
318 stack = traceback.extract_tb(tb)
320 type = exc_type.__name__
321 except AttributeError:
323 if type[:11] == "exceptions.":
325 file.write('%s: %s:\n' % (type, exc_value))
326 for fname, line, func, text in stack:
327 file.write(' File "%s", line %d:\n' % (fname, line))
328 file.write(' %s\n' % text)
331 """Annotate a node with the stack frame describing the
332 SConscript file and line number that created it."""
333 tb = sys.exc_info()[2]
334 while tb and not tb.tb_frame.f_locals.has_key(stack_bottom):
337 # We did not find any exec of an SConscript file: what?!
338 raise SCons.Errors.InternalError, "could not find SConscript stack frame"
339 node.creator = traceback.extract_stack(tb)[0]
341 # The following line would cause each Node to be annotated using the
342 # above function. Unfortunately, this is a *huge* performance hit, so
343 # leave this disabled until we find a more efficient mechanism.
344 #SCons.Node.Annotate = annotate
346 class SConsEnvironment(SCons.Environment.Base):
347 """An Environment subclass that contains all of the methods that
348 are particular to the wrapper SCons interface and which aren't
349 (or shouldn't be) part of the build engine itself.
351 Note that not all of the methods of this class have corresponding
352 global functions, there are some private methods.
356 # Private methods of an SConsEnvironment.
358 def _exceeds_version(self, major, minor, v_major, v_minor):
359 """Return 1 if 'major' and 'minor' are greater than the version
360 in 'v_major' and 'v_minor', and 0 otherwise."""
361 return (major > v_major or (major == v_major and minor > v_minor))
363 def _get_major_minor_revision(self, version_string):
364 """Split a version string into major, minor and (optionally)
367 This is complicated by the fact that a version string can be
368 something like 3.2b1."""
369 version = string.split(string.split(version_string, ' ')[0], '.')
370 v_major = int(version[0])
371 v_minor = int(re.match('\d+', version[1]).group())
372 if len(version) >= 3:
373 v_revision = int(re.match('\d+', version[2]).group())
376 return v_major, v_minor, v_revision
378 def _get_SConscript_filenames(self, ls, kw):
380 Convert the parameters passed to # SConscript() calls into a list
381 of files and export variables. If the parameters are invalid,
382 throws SCons.Errors.UserError. Returns a tuple (l, e) where l
383 is a list of SConscript filenames and e is a list of exports.
391 raise SCons.Errors.UserError, \
392 "Invalid SConscript usage - no parameters"
394 if not SCons.Util.is_List(dirs):
396 dirs = map(str, dirs)
398 name = kw.get('name', 'SConscript')
400 files = map(lambda n, name = name: os.path.join(n, name), dirs)
409 exports = self.Split(ls[1])
413 raise SCons.Errors.UserError, \
414 "Invalid SConscript() usage - too many arguments"
416 if not SCons.Util.is_List(files):
419 if kw.get('exports'):
420 exports.extend(self.Split(kw['exports']))
422 variant_dir = kw.get('variant_dir') or kw.get('build_dir')
425 raise SCons.Errors.UserError, \
426 "Invalid SConscript() usage - can only specify one SConscript with a variant_dir"
427 duplicate = kw.get('duplicate', 1)
428 src_dir = kw.get('src_dir')
430 src_dir, fname = os.path.split(str(files[0]))
431 files = [os.path.join(str(variant_dir), fname)]
433 if not isinstance(src_dir, SCons.Node.Node):
434 src_dir = self.fs.Dir(src_dir)
436 if not isinstance(fn, SCons.Node.Node):
437 fn = self.fs.File(fn)
438 if fn.is_under(src_dir):
439 # Get path relative to the source directory.
440 fname = fn.get_path(src_dir)
441 files = [os.path.join(str(variant_dir), fname)]
444 kw['src_dir'] = variant_dir
445 self.fs.VariantDir(variant_dir, src_dir, duplicate)
447 return (files, exports)
450 # Public methods of an SConsEnvironment. These get
451 # entry points in the global name space so they can be called
452 # as global functions.
455 def Configure(self, *args, **kw):
456 if not SCons.Script.sconscript_reading:
457 raise SCons.Errors.UserError, "Calling Configure from Builders is not supported."
458 kw['_depth'] = kw.get('_depth', 0) + 1
459 return apply(SCons.Environment.Base.Configure, (self,)+args, kw)
461 def Default(self, *targets):
462 SCons.Script._Set_Default_Targets(self, targets)
464 def EnsureSConsVersion(self, major, minor, revision=0):
465 """Exit abnormally if the SCons version is not late enough."""
466 scons_ver = self._get_major_minor_revision(SCons.__version__)
467 if scons_ver < (major, minor, revision):
469 scons_ver_string = '%d.%d.%d' % (major, minor, revision)
471 scons_ver_string = '%d.%d' % (major, minor)
472 print "SCons %s or greater required, but you have SCons %s" % \
473 (scons_ver_string, SCons.__version__)
476 def EnsurePythonVersion(self, major, minor):
477 """Exit abnormally if the Python version is not late enough."""
479 v_major, v_minor, v_micro, release, serial = sys.version_info
480 python_ver = (v_major, v_minor)
481 except AttributeError:
482 python_ver = self._get_major_minor_revision(sys.version)[:2]
483 if python_ver < (major, minor):
484 v = string.split(sys.version, " ", 1)[0]
485 print "Python %d.%d or greater required, but you have Python %s" %(major,minor,v)
488 def Exit(self, value=0):
491 def Export(self, *vars):
493 global_exports.update(compute_exports(self.Split(var)))
495 def GetLaunchDir(self):
499 def GetOption(self, name):
500 name = self.subst(name)
501 return SCons.Script.Main.GetOption(name)
503 def Help(self, text):
504 text = self.subst(text, raw=1)
505 SCons.Script.HelpFunction(text)
507 def Import(self, *vars):
509 frame = call_stack[-1]
510 globals = frame.globals
511 exports = frame.exports
513 var = self.Split(var)
516 globals.update(global_exports)
517 globals.update(exports)
519 if exports.has_key(v):
520 globals[v] = exports[v]
522 globals[v] = global_exports[v]
524 raise SCons.Errors.UserError, "Import of non-existent variable '%s'"%x
526 def SConscript(self, *ls, **kw):
527 def subst_element(x, subst=self.subst):
528 if SCons.Util.is_List(x):
533 ls = map(subst_element, ls)
535 for key, val in kw.items():
536 if SCons.Util.is_String(val):
537 val = self.subst(val)
538 elif SCons.Util.is_List(val):
541 if SCons.Util.is_String(v):
547 files, exports = self._get_SConscript_filenames(ls, subst_kw)
548 subst_kw['exports'] = exports
549 return apply(_SConscript, [self.fs,] + files, subst_kw)
551 def SConscriptChdir(self, flag):
552 global sconscript_chdir
553 sconscript_chdir = flag
555 def SetOption(self, name, value):
556 name = self.subst(name)
557 SCons.Script.Main.SetOption(name, value)
562 SCons.Environment.Environment = SConsEnvironment
564 def Configure(*args, **kw):
565 if not SCons.Script.sconscript_reading:
566 raise SCons.Errors.UserError, "Calling Configure from Builders is not supported."
568 return apply(SCons.SConf.SConf, args, kw)
570 # It's very important that the DefaultEnvironmentCall() class stay in this
571 # file, with the get_calling_namespaces() function, the compute_exports()
572 # function, the Frame class and the SConsEnvironment.Export() method.
573 # These things make up the calling stack leading up to the actual global
574 # Export() or SConscript() call that the user issued. We want to allow
575 # users to export local variables that they define, like so:
581 # To support this, the get_calling_namespaces() function assumes that
582 # the *first* stack frame that's not from this file is the local frame
583 # for the Export() or SConscript() call.
585 _DefaultEnvironmentProxy = None
587 def get_DefaultEnvironmentProxy():
588 global _DefaultEnvironmentProxy
589 if not _DefaultEnvironmentProxy:
590 default_env = SCons.Defaults.DefaultEnvironment()
591 _DefaultEnvironmentProxy = SCons.Environment.NoSubstitutionProxy(default_env)
592 return _DefaultEnvironmentProxy
594 class DefaultEnvironmentCall:
595 """A class that implements "global function" calls of
596 Environment methods by fetching the specified method from the
597 DefaultEnvironment's class. Note that this uses an intermediate
598 proxy class instead of calling the DefaultEnvironment method
599 directly so that the proxy can override the subst() method and
600 thereby prevent expansion of construction variables (since from
601 the user's point of view this was called as a global function,
602 with no associated construction environment)."""
603 def __init__(self, method_name, subst=0):
604 self.method_name = method_name
606 self.factory = SCons.Defaults.DefaultEnvironment
608 self.factory = get_DefaultEnvironmentProxy
609 def __call__(self, *args, **kw):
611 method = getattr(env, self.method_name)
612 return apply(method, args, kw)
615 def BuildDefaultGlobals():
617 Create a dictionary containing all the default globals for
618 SConstruct and SConscript files.
622 if GlobalDict is None:
626 d = SCons.Script.__dict__
627 def not_a_module(m, d=d, mtype=type(SCons.Script)):
628 return type(d[m]) != mtype
629 for m in filter(not_a_module, dir(SCons.Script)):
632 return GlobalDict.copy()