1 """SCons.Script.SConscript
2
3 This module defines the Python API provided to SConscript and SConstruct
4 files.
5
6 """
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30 __revision__ = "src/engine/SCons/Script/SConscript.py 3a41ed6b288cee8d085373ad7fa02894e1903864 2019-01-23 17:30:35 bdeegan"
31
32 import SCons
33 import SCons.Action
34 import SCons.Builder
35 import SCons.Defaults
36 import SCons.Environment
37 import SCons.Errors
38 import SCons.Node
39 import SCons.Node.Alias
40 import SCons.Node.FS
41 import SCons.Platform
42 import SCons.SConf
43 import SCons.Script.Main
44 import SCons.Tool
45 import SCons.Util
46
47 from . import Main
48
49 import collections
50 import os
51 import os.path
52 import re
53 import sys
54 import traceback
55 import time
56
59
60 launch_dir = os.path.abspath(os.curdir)
61
62 GlobalDict = None
63
64
65 global_exports = {}
66
67
68 sconscript_chdir = 1
69
71 """Return the locals and globals for the function that called
72 into this module in the current call stack."""
73 try: 1//0
74 except ZeroDivisionError:
75
76
77 frame = sys.exc_info()[2].tb_frame.f_back
78
79
80
81
82
83
84
85
86 while frame.f_globals.get("__name__") == __name__:
87 frame = frame.f_back
88
89 return frame.f_locals, frame.f_globals
90
91
93 """Compute a dictionary of exports given one of the parameters
94 to the Export() function or the exports argument to SConscript()."""
95
96 loc, glob = get_calling_namespaces()
97
98 retval = {}
99 try:
100 for export in exports:
101 if SCons.Util.is_Dict(export):
102 retval.update(export)
103 else:
104 try:
105 retval[export] = loc[export]
106 except KeyError:
107 retval[export] = glob[export]
108 except KeyError as x:
109 raise SCons.Errors.UserError("Export of non-existent variable '%s'"%x)
110
111 return retval
112
114 """A frame on the SConstruct/SConscript call stack"""
115 - def __init__(self, fs, exports, sconscript):
116 self.globals = BuildDefaultGlobals()
117 self.retval = None
118 self.prev_dir = fs.getcwd()
119 self.exports = compute_exports(exports)
120
121 if isinstance(sconscript, SCons.Node.Node):
122 self.sconscript = sconscript
123 elif sconscript == '-':
124 self.sconscript = None
125 else:
126 self.sconscript = fs.File(str(sconscript))
127
128
129 call_stack = []
130
131
132
152
153
154 stack_bottom = '% Stack boTTom %'
155
184
186 top = fs.Top
187 sd = fs.SConstruct_dir.rdir()
188 exports = kw.get('exports', [])
189
190
191 results = []
192 for fn in files:
193 call_stack.append(Frame(fs, exports, fn))
194 old_sys_path = sys.path
195 try:
196 SCons.Script.sconscript_reading = SCons.Script.sconscript_reading + 1
197 if fn == "-":
198 exec(sys.stdin.read(), call_stack[-1].globals)
199 else:
200 if isinstance(fn, SCons.Node.Node):
201 f = fn
202 else:
203 f = fs.File(str(fn))
204 _file_ = None
205
206
207
208
209 fs.chdir(top, change_os_dir=1)
210 if f.rexists():
211 actual = f.rfile()
212 _file_ = open(actual.get_abspath(), "rb")
213 elif f.srcnode().rexists():
214 actual = f.srcnode().rfile()
215 _file_ = open(actual.get_abspath(), "rb")
216 elif f.has_src_builder():
217
218
219
220
221 f.build()
222 f.built()
223 f.builder_set(None)
224 if f.exists():
225 _file_ = open(f.get_abspath(), "rb")
226 if _file_:
227
228
229
230
231
232
233
234
235
236
237 try:
238 src_dir = kw['src_dir']
239 except KeyError:
240 ldir = fs.Dir(f.dir.get_path(sd))
241 else:
242 ldir = fs.Dir(src_dir)
243 if not ldir.is_under(f.dir):
244
245
246
247
248 ldir = fs.Dir(f.dir.get_path(sd))
249 try:
250 fs.chdir(ldir, change_os_dir=sconscript_chdir)
251 except OSError:
252
253
254
255
256
257
258 fs.chdir(ldir, change_os_dir=0)
259 os.chdir(actual.dir.get_abspath())
260
261
262
263
264 sys.path = [ f.dir.get_abspath() ] + sys.path
265
266
267
268
269
270
271
272
273 call_stack[-1].globals.update({stack_bottom:1})
274 old_file = call_stack[-1].globals.get('__file__')
275 try:
276 del call_stack[-1].globals['__file__']
277 except KeyError:
278 pass
279 try:
280 try:
281
282 if Main.print_time:
283 time1 = time.time()
284 exec(compile(_file_.read(), _file_.name, 'exec'),
285 call_stack[-1].globals)
286 except SConscriptReturn:
287 pass
288 finally:
289 if Main.print_time:
290 time2 = time.time()
291 print('SConscript:%s took %0.3f ms' % (f.get_abspath(), (time2 - time1) * 1000.0))
292
293 if old_file is not None:
294 call_stack[-1].globals.update({__file__:old_file})
295 else:
296 handle_missing_SConscript(f, kw.get('must_exist', None))
297
298 finally:
299 SCons.Script.sconscript_reading = SCons.Script.sconscript_reading - 1
300 sys.path = old_sys_path
301 frame = call_stack.pop()
302 try:
303 fs.chdir(frame.prev_dir, change_os_dir=sconscript_chdir)
304 except OSError:
305
306
307
308 fs.chdir(frame.prev_dir, change_os_dir=0)
309 rdir = frame.prev_dir.rdir()
310 rdir._create()
311 try:
312 os.chdir(rdir.get_abspath())
313 except OSError as e:
314
315
316
317
318
319
320
321
322
323 if SCons.Action.execute_actions:
324 raise e
325
326 results.append(frame.retval)
327
328
329 if len(results) == 1:
330 return results[0]
331 else:
332 return tuple(results)
333
335 """Print an exception stack trace just for the SConscript file(s).
336 This will show users who have Python errors where the problem is,
337 without cluttering the output with all of the internal calls leading
338 up to where we exec the SConscript."""
339 exc_type, exc_value, exc_tb = sys.exc_info()
340 tb = exc_tb
341 while tb and stack_bottom not in tb.tb_frame.f_locals:
342 tb = tb.tb_next
343 if not tb:
344
345
346 tb = exc_tb
347 stack = traceback.extract_tb(tb)
348 try:
349 type = exc_type.__name__
350 except AttributeError:
351 type = str(exc_type)
352 if type[:11] == "exceptions.":
353 type = type[11:]
354 file.write('%s: %s:\n' % (type, exc_value))
355 for fname, line, func, text in stack:
356 file.write(' File "%s", line %d:\n' % (fname, line))
357 file.write(' %s\n' % text)
358
360 """Annotate a node with the stack frame describing the
361 SConscript file and line number that created it."""
362 tb = sys.exc_info()[2]
363 while tb and stack_bottom not in tb.tb_frame.f_locals:
364 tb = tb.tb_next
365 if not tb:
366
367 raise SCons.Errors.InternalError("could not find SConscript stack frame")
368 node.creator = traceback.extract_stack(tb)[0]
369
370
371
372
373
374
376 """An Environment subclass that contains all of the methods that
377 are particular to the wrapper SCons interface and which aren't
378 (or shouldn't be) part of the build engine itself.
379
380 Note that not all of the methods of this class have corresponding
381 global functions, there are some private methods.
382 """
383
384
385
386
388 """Return 1 if 'major' and 'minor' are greater than the version
389 in 'v_major' and 'v_minor', and 0 otherwise."""
390 return (major > v_major or (major == v_major and minor > v_minor))
391
393 """Split a version string into major, minor and (optionally)
394 revision parts.
395
396 This is complicated by the fact that a version string can be
397 something like 3.2b1."""
398 version = version_string.split(' ')[0].split('.')
399 v_major = int(version[0])
400 v_minor = int(re.match('\d+', version[1]).group())
401 if len(version) >= 3:
402 v_revision = int(re.match('\d+', version[2]).group())
403 else:
404 v_revision = 0
405 return v_major, v_minor, v_revision
406
408 """
409 Convert the parameters passed to SConscript() calls into a list
410 of files and export variables. If the parameters are invalid,
411 throws SCons.Errors.UserError. Returns a tuple (l, e) where l
412 is a list of SConscript filenames and e is a list of exports.
413 """
414 exports = []
415
416 if len(ls) == 0:
417 try:
418 dirs = kw["dirs"]
419 except KeyError:
420 raise SCons.Errors.UserError("Invalid SConscript usage - no parameters")
421
422 if not SCons.Util.is_List(dirs):
423 dirs = [ dirs ]
424 dirs = list(map(str, dirs))
425
426 name = kw.get('name', 'SConscript')
427
428 files = [os.path.join(n, name) for n in dirs]
429
430 elif len(ls) == 1:
431
432 files = ls[0]
433
434 elif len(ls) == 2:
435
436 files = ls[0]
437 exports = self.Split(ls[1])
438
439 else:
440
441 raise SCons.Errors.UserError("Invalid SConscript() usage - too many arguments")
442
443 if not SCons.Util.is_List(files):
444 files = [ files ]
445
446 if kw.get('exports'):
447 exports.extend(self.Split(kw['exports']))
448
449 variant_dir = kw.get('variant_dir') or kw.get('build_dir')
450 if variant_dir:
451 if len(files) != 1:
452 raise SCons.Errors.UserError("Invalid SConscript() usage - can only specify one SConscript with a variant_dir")
453 duplicate = kw.get('duplicate', 1)
454 src_dir = kw.get('src_dir')
455 if not src_dir:
456 src_dir, fname = os.path.split(str(files[0]))
457 files = [os.path.join(str(variant_dir), fname)]
458 else:
459 if not isinstance(src_dir, SCons.Node.Node):
460 src_dir = self.fs.Dir(src_dir)
461 fn = files[0]
462 if not isinstance(fn, SCons.Node.Node):
463 fn = self.fs.File(fn)
464 if fn.is_under(src_dir):
465
466 fname = fn.get_path(src_dir)
467 files = [os.path.join(str(variant_dir), fname)]
468 else:
469 files = [fn.get_abspath()]
470 kw['src_dir'] = variant_dir
471 self.fs.VariantDir(variant_dir, src_dir, duplicate)
472
473 return (files, exports)
474
475
476
477
478
479
480
486
489
491 """Exit abnormally if the SCons version is not late enough."""
492
493 if SCons.__version__ == '__' + 'VERSION__':
494 SCons.Warnings.warn(SCons.Warnings.DevelopmentVersionWarning,
495 "EnsureSConsVersion is ignored for development version")
496 return
497 scons_ver = self._get_major_minor_revision(SCons.__version__)
498 if scons_ver < (major, minor, revision):
499 if revision:
500 scons_ver_string = '%d.%d.%d' % (major, minor, revision)
501 else:
502 scons_ver_string = '%d.%d' % (major, minor)
503 print("SCons %s or greater required, but you have SCons %s" % \
504 (scons_ver_string, SCons.__version__))
505 sys.exit(2)
506
508 """Exit abnormally if the Python version is not late enough."""
509 if sys.version_info < (major, minor):
510 v = sys.version.split()[0]
511 print("Python %d.%d or greater required, but you have Python %s" %(major,minor,v))
512 sys.exit(2)
513
514 - def Exit(self, value=0):
516
517 - def Export(self, *vars, **kw):
521
525
529
530 - def Help(self, text, append=False):
533
535 try:
536 frame = call_stack[-1]
537 globals = frame.globals
538 exports = frame.exports
539 for var in vars:
540 var = self.Split(var)
541 for v in var:
542 if v == '*':
543 globals.update(global_exports)
544 globals.update(exports)
545 else:
546 if v in exports:
547 globals[v] = exports[v]
548 else:
549 globals[v] = global_exports[v]
550 except KeyError as x:
551 raise SCons.Errors.UserError("Import of non-existent variable '%s'"%x)
552
554 """Execute SCons configuration files.
555
556 Parameters:
557 *ls (str or list): configuration file(s) to execute.
558
559 Keyword arguments:
560 dirs (list): execute SConscript in each listed directory.
561 name (str): execute script 'name' (used only with 'dirs').
562 exports (list or dict): locally export variables the
563 called script(s) can import.
564 variant_dir (str): mirror sources needed for the build in
565 a variant directory to allow building in it.
566 duplicate (bool): physically duplicate sources instead of just
567 adjusting paths of derived files (used only with 'variant_dir')
568 (default is True).
569 must_exist (bool): fail if a requested script is missing
570 (default is False, default is deprecated).
571
572 Returns:
573 list of variables returned by the called script
574
575 Raises:
576 UserError: a script is not found and such exceptions are enabled.
577 """
578
579 if 'build_dir' in kw:
580 msg = """The build_dir keyword has been deprecated; use the variant_dir keyword instead."""
581 SCons.Warnings.warn(SCons.Warnings.DeprecatedBuildDirWarning, msg)
582 def subst_element(x, subst=self.subst):
583 if SCons.Util.is_List(x):
584 x = list(map(subst, x))
585 else:
586 x = subst(x)
587 return x
588 ls = list(map(subst_element, ls))
589 subst_kw = {}
590 for key, val in kw.items():
591 if SCons.Util.is_String(val):
592 val = self.subst(val)
593 elif SCons.Util.is_List(val):
594 result = []
595 for v in val:
596 if SCons.Util.is_String(v):
597 v = self.subst(v)
598 result.append(v)
599 val = result
600 subst_kw[key] = val
601
602 files, exports = self._get_SConscript_filenames(ls, subst_kw)
603 subst_kw['exports'] = exports
604 return _SConscript(self.fs, *files, **subst_kw)
605
609
613
614
615
616
617 SCons.Environment.Environment = SConsEnvironment
618
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640 _DefaultEnvironmentProxy = None
641
648
650 """A class that implements "global function" calls of
651 Environment methods by fetching the specified method from the
652 DefaultEnvironment's class. Note that this uses an intermediate
653 proxy class instead of calling the DefaultEnvironment method
654 directly so that the proxy can override the subst() method and
655 thereby prevent expansion of construction variables (since from
656 the user's point of view this was called as a global function,
657 with no associated construction environment)."""
658 - def __init__(self, method_name, subst=0):
665 env = self.factory()
666 method = getattr(env, self.method_name)
667 return method(*args, **kw)
668
669
671 """
672 Create a dictionary containing all the default globals for
673 SConstruct and SConscript files.
674 """
675
676 global GlobalDict
677 if GlobalDict is None:
678 GlobalDict = {}
679
680 import SCons.Script
681 d = SCons.Script.__dict__
682 def not_a_module(m, d=d, mtype=type(SCons.Script)):
683 return not isinstance(d[m], mtype)
684 for m in filter(not_a_module, dir(SCons.Script)):
685 GlobalDict[m] = d[m]
686
687 return GlobalDict.copy()
688
689
690
691
692
693
694