From 961ddffc1f598e37c1cf1e1316d6a79ae7d99fcc Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 11 Feb 2023 09:40:40 -0700 Subject: Tweak pseudo-builder in user guide [skip appveyor] Minor fiddling - example format, headers, wordings tweaks Signed-off-by: Mats Wichmann --- doc/user/add-method.xml | 73 ++++++++++++++++++++----------------------------- 1 file changed, 29 insertions(+), 44 deletions(-) diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 7b5200e..86297de 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -1,4 +1,10 @@ + + %scons; @@ -18,43 +24,17 @@ xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd"> -Extending &SCons;: Pseudo-Builders and the AddMethod function - - +Extending &SCons;: Pseudo-Builders and the AddMethod function - The &AddMethod; function is used to add a method - to an environment. It's typically used to add a "pseudo-builder," - a function that looks like a &Builder; but - wraps up calls to multiple other &Builder;s + The &f-link-AddMethod; function is used to add a method + to an environment. It is typically used to add a "pseudo-builder," + a function that looks like a Builder but + wraps up calls to multiple other Builder's or otherwise processes its arguments - before calling one or more &Builder;s. + before calling one or more Builders. In the following example, we want to install the program into the standard /usr/bin directory hierarchy, @@ -69,10 +49,11 @@ def install_in_bin_dirs(env, source): """Install source in both bin dirs""" i1 = env.Install("$BIN", source) i2 = env.Install("$LOCALBIN", source) - return [i1[0], i2[0]] # Return a list, like a normal builder + return [i1[0], i2[0]] # Return a list, like a normal builder + env = Environment(BIN='__ROOT__/usr/bin', LOCALBIN='#install/bin') env.AddMethod(install_in_bin_dirs, "InstallInBinDirs") -env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs +env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs int main() { printf("Hello, world!\n"); } @@ -89,31 +70,35 @@ int main() { printf("Hello, world!\n"); } - As mentioned, a pseudo-builder also provides more flexibility - in parsing arguments than you can get with a &Builder;. + A pseudo-builder is useful because it provides more flexibility + in parsing arguments than you can get with a standard Builder method. The next example shows a pseudo-builder with a named argument that modifies the filename, and a separate argument for the resource file (rather than having the builder figure it out by file extension). This example also demonstrates using the global &AddMethod; function to add a method to the global Environment class, - so it will be used in all subsequently created environments. + so it will be available in all subsequently created environments. -def BuildTestProg(env, testfile, resourcefile, testdir="tests"): - """Build the test program; - prepends "test_" to src and target, - and puts target into testdir.""" - srcfile = "test_%s.c" % testfile - target = "%s/test_%s" % (testdir, testfile) - if env['PLATFORM'] == 'win32': +def BuildTestProg(env, testfile, resourcefile="", testdir="tests"): + """Build the test program. + + Prepends "test_" to src and target and puts the target into testdir. + If the build is running on Windows, also make use of a resource file, + if supplied. + """ + srcfile = f"test_{testfile}.c" + target = f"{testdir}/test_{testfile}" + if env['PLATFORM'] == 'win32' and resourcefile: resfile = env.RES(resourcefile) p = env.Program(target, [srcfile, resfile]) else: p = env.Program(target, srcfile) return p + AddMethod(Environment, BuildTestProg) env = Environment() -- cgit v0.12 From cdd4bb3ec9f665c13473792ee0f5f34f1261c76d Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 21 Feb 2023 08:59:41 -0700 Subject: Restore markup of Builder in PR 4299 [skip appveyor] The add-method chapter now has entity references to &Builder; back. The markup for &Builder; is changed from to , as used it's a concept, and there is no actual class named Builder anyway. Signed-off-by: Mats Wichmann --- doc/scons.mod | 4 ++-- doc/user/add-method.xml | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/scons.mod b/doc/scons.mod index ea1decc..ebe0e6f 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -100,7 +100,7 @@ CommandAction"> FunctionAction"> ListAction"> -Builder"> +Builder"> BuilderBase"> CompositeBuilder"> MultiStepBuilder"> @@ -110,7 +110,7 @@ Parallel"> Node"> Node.FS"> -Scanner"> +Scanner"> Sig"> Signature"> Taskmaster"> diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 86297de..d25ba9a 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -31,10 +31,10 @@ Copyright The SCons Foundation The &f-link-AddMethod; function is used to add a method to an environment. It is typically used to add a "pseudo-builder," - a function that looks like a Builder but - wraps up calls to multiple other Builder's + a function that looks like a &Builder; but + wraps up calls to multiple other &Builder;'s or otherwise processes its arguments - before calling one or more Builders. + before calling one or more &Builder;s. In the following example, we want to install the program into the standard /usr/bin directory hierarchy, @@ -71,7 +71,7 @@ int main() { printf("Hello, world!\n"); } A pseudo-builder is useful because it provides more flexibility - in parsing arguments than you can get with a standard Builder method. + in parsing arguments than you can get with a standard &Builder;. The next example shows a pseudo-builder with a named argument that modifies the filename, and a separate argument for the resource file (rather than having the builder figure it out -- cgit v0.12 From 959e35788a8a6aa418c97cb55221c70b9cc15fe5 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 22 Feb 2023 09:43:58 -0700 Subject: User Guide fixups [skip appveyor] For add-method chapter, plus the following scanners chapter, normalize usage a little: the first mention in any given section uses the marked-up form &Builder; and &Scanner;, which contain index references, subsequent ones do not. Only references to Scanner as a concept are capitalized, things like "scanner function" were left alone. Signed-off-by: Mats Wichmann --- doc/user/add-method.xml | 4 ++-- doc/user/scanners.xml | 62 ++++++++++++++++++++++++------------------------- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index d25ba9a..7c59bf2 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -32,9 +32,9 @@ Copyright The SCons Foundation The &f-link-AddMethod; function is used to add a method to an environment. It is typically used to add a "pseudo-builder," a function that looks like a &Builder; but - wraps up calls to multiple other &Builder;'s + wraps up calls to multiple other Builders or otherwise processes its arguments - before calling one or more &Builder;s. + before calling one or more Builders. In the following example, we want to install the program into the standard /usr/bin directory hierarchy, diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index b9a5084..1e22342 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -146,15 +146,16 @@ over the file scanning rather than being called for each input line: - &SCons; has built-in scanners that know how to look in + &SCons; has routines that know how to look in C/C++, Fortran, D, IDL, LaTeX, Python and SWIG source files for information about - other files that targets built from those files depend on--for example, - in the case of files that use the C preprocessor, + other files that targets built from those files depend on - + for example, in the case of files that use the C preprocessor, the .h files that are specified using #include lines in the source. + Such a routine is called a &Scanner;. You can use the same mechanisms that &SCons; uses to create - its built-in scanners to write scanners of your own for file types + its built-in Scanners to write Scanners of your own for file types that &SCons; does not know how to scan "out of the box." @@ -164,7 +165,7 @@ over the file scanning rather than being called for each input line: - Suppose, for example, that we want to create a simple scanner + Suppose, for example, that we want to create a simple &Scanner; for .foo files. A .foo file contains some text that will be processed, @@ -183,7 +184,7 @@ include filename.foo Scanning a file will be handled by a Python function that you must supply. Here is a function that will use the Python - re module + re module to scan for the include lines in our example: @@ -203,7 +204,7 @@ def kfile_scan(node, env, path, arg): It is important to note that you have to return a list of File nodes from the scanner function, simple strings for the file names won't do. As in the examples we are showing here, - you can use the &File; + you can use the &f-link-File; function of your current &consenv; in order to create nodes on the fly from a sequence of file names with relative paths. @@ -225,7 +226,7 @@ def kfile_scan(node, env, path, arg): - node + node @@ -233,8 +234,8 @@ def kfile_scan(node, env, path, arg): An &SCons; node object representing the file being scanned. The path name to the file can be used by converting the node to a string - using the str() function, - or an internal &SCons; get_text_contents() + using the str function, + or an internal &SCons; get_text_contents object method can be used to fetch the contents. @@ -242,7 +243,7 @@ def kfile_scan(node, env, path, arg): - env + env @@ -256,13 +257,13 @@ def kfile_scan(node, env, path, arg): - path + path A list of directories that form the search path for included files - for this scanner. + for this Scanner. This is how &SCons; handles the &cv-link-CPPPATH; and &cv-link-LIBPATH; variables. @@ -271,7 +272,7 @@ def kfile_scan(node, env, path, arg): - arg + arg @@ -288,10 +289,10 @@ def kfile_scan(node, env, path, arg): - A Scanner object is created using the &f-link-Scanner; function, + A scanner object is created using the &f-link-Scanner; function, which typically takes an skeys argument - to associate a file suffix with this scanner. - The Scanner object must then be associated with the + to associate a file suffix with this Scanner. + The scanner object must then be associated with the &cv-link-SCANNERS; &consvar; in the current &consenv;, typically by using the &f-link-Append; method: @@ -320,7 +321,6 @@ def kfile_scan(node, env, path): return env.File(includes) kscan = Scanner(function=kfile_scan, skeys=['.k']) - env = Environment(ENV={'PATH': '__ROOT__/usr/local/bin'}) env.Append(SCANNERS=kscan) @@ -364,21 +364,21 @@ cat
- Adding a search path to a scanner: &FindPathDirs; + Adding a search path to a Scanner: &FindPathDirs; If the build tool in question will use a path variable to search - for included files or other dependencies, then the Scanner will + for included files or other dependencies, then the &Scanner; will need to take that path variable into account as well - &cv-link-CPPPATH; and &cv-link-LIBPATH; are used this way, for example. The path to search is passed to your - scanner as the path argument. Path variables + Scanner as the path argument. Path variables may be lists of nodes, semicolon-separated strings, or even contain &consvars; which need to be expanded. &SCons; provides the &f-link-FindPathDirs; function which returns a callable to expand a given path (given as a SCons &consvar; - name) to a list of paths at the time the scanner is called. + name) to a list of paths at the time the Scanner is called. Deferring evaluation until that point allows, for instance, the path to contain &cv-link-TARGET; references which differ for each file scanned. @@ -390,7 +390,7 @@ cat Using &FindPathDirs; is quite easy. Continuing the above example, using KPATH as the &consvar; with the search path (analogous to &cv-link-CPPPATH;), we just modify the call to - the &Scanner; factory function to include a path keyword arg: + the &f-link-Scanner; factory function to include a path keyword arg: @@ -404,7 +404,7 @@ kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('K &FindPathDirs; returns a callable object that, when called, will essentially expand the elements in env['KPATH'] - and tell the scanner to search in those dirs. It will also properly + and tell the Scanner to search in those dirs. It will also properly add related repository and variant dirs to the search list. As a side note, the returned method stores the path in an efficient way so lookups are fast even when variable substitutions may be needed. @@ -418,9 +418,9 @@ kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('K - One approach for introducing scanners into the build is in - conjunction with a Builder. There are two relvant optional - parameters we can use when creating a builder: + One approach for introducing a &Scanner; into the build is in + conjunction with a &Builder;. There are two relvant optional + parameters we can use when creating a Builder: source_scanner and target_scanner. source_scanner is used for scanning @@ -459,16 +459,16 @@ env.Foo('file') An emitter function can modify the list of sources or targets - passed to the action function when the builder is triggered. + passed to the action function when the Builder is triggered. A scanner function will not affect the list of sources or targets - seen by the builder during the build action. The scanner function - will however affect if the builder should rebuild (if any of - the files sourced by the scanner have changed for example). + seen by the Builder during the build action. The scanner function + will however affect if the Builder should rebuild (if any of + the files sourced by the Scanner have changed for example).
-- cgit v0.12 From 7923bb984986831f6696ae966e3297cce7e96316 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 23 Feb 2023 10:15:26 -0700 Subject: UGuide; tweak Scanner intro again [skip appveyor] Put back the previous wording, now with glossary entry that also defines the plural form Scanners (there is still no actual glossary) Signed-off-by: Mats Wichmann --- doc/scons.mod | 13 ++++++++++--- doc/user/builders-writing.xml | 3 ++- doc/user/scanners.xml | 3 +-- 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/doc/scons.mod b/doc/scons.mod index ebe0e6f..2d3f5a4 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -92,15 +92,23 @@ zip"> + +Action"> +Builder"> +Builders"> +Scanner"> +Scanners"> + + -Action"> ActionBase"> BuildInfo"> CommandAction"> FunctionAction"> ListAction"> -Builder"> BuilderBase"> CompositeBuilder"> MultiStepBuilder"> @@ -110,7 +118,6 @@ Parallel"> Node"> Node.FS"> -Scanner"> Sig"> Signature"> Taskmaster"> diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index a53e70e..97ca36f 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -222,13 +222,14 @@ hello.c To be able to use both our own defined &Builder; objects and the default &Builder; objects in the same &consenv;, you can either add to the &cv-link-BUILDERS; variable - using the &Append; function: + using the &f-link-Append; function: import os + env = Environment() env.AppendENVPath('PATH', os.getcwd()) bld = Builder(action='foobuild < $SOURCE > $TARGET') diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 1e22342..9a0a1d3 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -146,14 +146,13 @@ over the file scanning rather than being called for each input line: - &SCons; has routines that know how to look in + &SCons; has built-in &Scanners; that know how to look in C/C++, Fortran, D, IDL, LaTeX, Python and SWIG source files for information about other files that targets built from those files depend on - for example, in the case of files that use the C preprocessor, the .h files that are specified using #include lines in the source. - Such a routine is called a &Scanner;. You can use the same mechanisms that &SCons; uses to create its built-in Scanners to write Scanners of your own for file types that &SCons; does not know how to scan "out of the box." -- cgit v0.12 From aed512b9626a44e19b0368f241ca504cffa01a22 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 11 Nov 2021 15:12:01 -0700 Subject: Use pathlib in runtest In the past, there have been some mismatches between how tests are specified and how they are found. testlist files, excludelist files and command-line specifications should be agnostic to operating system conventions. For example, typing "runtest.py foo/bar" on windows will produce paths like foo/bar\test.py, which is hard to match and painful to read, it should obviously match discovered foo\bar\test.py. Test information should be output using the native path separator for consistency. Using pathlib lets these be normalized - stored in a common format and output in the expected format. Adding this normalization of course broke some tests, which either intentionally or through omission expected some portion of a path to be UNIX-style. Specifically these five: test\runtest\baseline\fail.py test\runtest\baseline\no_result.py test\runtest\simple\fail.py test\runtest\simple\no_result.py test\runtest\simple\pass.py test\runtest\testargv.py This was fixed and a general cleanup/reformat performed on the runtest tests. Signed-off-by: Mats Wichmann --- CHANGES.txt | 2 + runtest.py | 126 ++++++++++++++++++------------------- test/runtest/SCons.py | 17 +++-- test/runtest/baseline/combined.py | 29 ++++----- test/runtest/baseline/fail.py | 27 ++++---- test/runtest/baseline/no_result.py | 38 ++++++----- test/runtest/baseline/pass.py | 17 +++-- test/runtest/faillog.py | 17 +++-- test/runtest/no_faillog.py | 26 ++++---- test/runtest/print_time.py | 28 ++++----- test/runtest/python.py | 25 ++++---- test/runtest/retry.py | 22 ++++--- test/runtest/simple/combined.py | 28 ++++----- test/runtest/simple/fail.py | 25 ++++---- test/runtest/simple/no_result.py | 31 +++++---- test/runtest/simple/pass.py | 18 +++--- test/runtest/testargv.py | 42 ++++++------- test/runtest/testlistfile.py | 24 +++---- test/runtest/xml/output.py | 32 ++++------ 19 files changed, 281 insertions(+), 293 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index d4ad973..5ad76b8 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -23,6 +23,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER calls dunder method __call__. Invoke instance directly." - Python 3.9 dropped the alias base64.decodestring, deprecated since 3.1. Only used in msvs.py. Use base64.decodebytes instead. + - SCons test runner now uses pathlib to normalize and compare paths + to test files. RELEASE 4.5.2 - Sun, 21 Mar 2023 14:08:29 -0700 diff --git a/runtest.py b/runtest.py index a2ece7e..46cdc7b 100755 --- a/runtest.py +++ b/runtest.py @@ -14,22 +14,17 @@ This script adds SCons/ and testing/ directories to PYTHONPATH, performs test discovery and processes tests according to options. """ -# TODO: normalize requested and testlist/exclude paths for easier comparison. -# e.g.: "runtest foo/bar" on windows will produce paths like foo/bar\test.py -# this is hard to match with excludelists, and makes those both os.sep-specific -# and command-line-typing specific. - import argparse -import glob +import itertools import os -import stat import subprocess import sys import tempfile import threading import time from abc import ABC, abstractmethod -from pathlib import Path +from io import StringIO +from pathlib import Path, PurePath, PureWindowsPath from queue import Queue cwd = os.getcwd() @@ -39,7 +34,7 @@ scons = None catch_output = False suppress_output = False -script = os.path.basename(sys.argv[0]) +script = PurePath(sys.argv[0]).name usagestr = """\ %(script)s [OPTIONS] [TEST ...] """ % locals() @@ -388,11 +383,13 @@ else: class RuntestBase(ABC): """ Base class for tests """ - def __init__(self, path, num, spe=None): - self.path = path - self.num = num + _ids = itertools.count(1) # to geenerate test # automatically + + def __init__(self, path, spe=None): + self.path = str(path) + self.testno = next(self._ids) self.stdout = self.stderr = self.status = None - self.abspath = os.path.abspath(path) + self.abspath = path.absolute() self.command_args = [] self.command_str = "" self.test_time = self.total_time = 0 @@ -404,7 +401,7 @@ class RuntestBase(ABC): break @abstractmethod - def execute(self): + def execute(self, env): pass @@ -547,7 +544,7 @@ if sys.platform == 'win32': # Windows doesn't support "shebang" lines directly (the Python launcher # and Windows Store version do, but you have to get them launched first) # so to directly launch a script we depend on an assoc for .py to work. - # Some systems may have none, and in some cases IDE programs take over + # Some systems may have none, and in some cases IDE programs take over # the assoc. Detect this so the small number of tests affected can skip. try: python_assoc = get_template_command('.py') @@ -564,7 +561,7 @@ if '_JAVA_OPTIONS' in os.environ: # ---[ test discovery ]------------------------------------ -# This section figures which tests to run. +# This section figures out which tests to run. # # The initial testlist is made by reading from the testlistfile, # if supplied, or by looking at the test arguments, if supplied, @@ -587,10 +584,15 @@ if '_JAVA_OPTIONS' in os.environ: # Test exclusions, if specified, are then applied. -def scanlist(testlist): +def scanlist(testfile): """ Process a testlist file """ - tests = [t.strip() for t in testlist if not t.startswith('#')] - return [t for t in tests if t] + data = StringIO(testfile.read_text()) + tests = [t.strip() for t in data.readlines() if not t.startswith('#')] + # in order to allow scanned lists to work whether they use forward or + # backward slashes, first create the object as a PureWindowsPath which + # accepts either, then use that to make a Path object to use for + # comparisons like "file in scanned_list". + return [Path(PureWindowsPath(t)) for t in tests if t] def find_unit_tests(directory): @@ -602,7 +604,8 @@ def find_unit_tests(directory): continue for fname in filenames: if fname.endswith("Tests.py"): - result.append(os.path.join(dirpath, fname)) + result.append(Path(dirpath, fname)) + return sorted(result) @@ -617,79 +620,74 @@ def find_e2e_tests(directory): # Slurp in any tests in exclude lists excludes = [] if ".exclude_tests" in filenames: - p = Path(dirpath).joinpath(".exclude_tests") - # TODO simplify when Py3.5 dropped - if sys.version_info.major == 3 and sys.version_info.minor < 6: - excludefile = p.resolve() - else: - excludefile = p.resolve(strict=True) - with excludefile.open() as f: - excludes = scanlist(f) + excludefile = Path(dirpath, ".exclude_tests").resolve() + excludes = scanlist(excludefile) for fname in filenames: - if fname.endswith(".py") and fname not in excludes: - result.append(os.path.join(dirpath, fname)) + if fname.endswith(".py") and Path(fname) not in excludes: + result.append(Path(dirpath, fname)) return sorted(result) # initial selection: +# if we have a testlist file read that, else hunt for tests. unittests = [] endtests = [] if args.testlistfile: - with args.testlistfile.open() as f: - tests = scanlist(f) + tests = scanlist(args.testlistfile) else: testpaths = [] - if args.all: - testpaths = ['SCons', 'test'] - elif args.testlist: - testpaths = args.testlist - - for tp in testpaths: - # Clean up path so it can match startswith's below - # remove leading ./ or .\ - if tp.startswith('.') and tp[1] in (os.sep, os.altsep): - tp = tp[2:] - - for path in glob.glob(tp): - if os.path.isdir(path): - if path.startswith(('SCons', 'testing')): + if args.all: # -a flag + testpaths = [Path('SCons'), Path('test')] + elif args.testlist: # paths given on cmdline + testpaths = [Path(PureWindowsPath(t)) for t in args.testlist] + + for path in testpaths: + # Clean up path removing leading ./ or .\ + name = str(path) + if name.startswith('.') and name[1] in (os.sep, os.altsep): + path = path.with_name(tn[2:]) + + if path.exists(): + if path.is_dir(): + if path.parts[0] == "SCons" or path.parts[0] == "testing": unittests.extend(find_unit_tests(path)) - elif path.startswith('test'): + elif path.parts[0] == 'test': endtests.extend(find_e2e_tests(path)) + # else: TODO: what if user pointed to a dir outside scons tree? else: - if path.endswith("Tests.py"): + if path.match("*Tests.py"): unittests.append(path) - elif path.endswith(".py"): + elif path.match("*.py"): endtests.append(path) - tests = sorted(unittests + endtests) + tests = sorted(unittests + endtests) # Remove exclusions: if args.e2e_only: - tests = [t for t in tests if not t.endswith("Tests.py")] + tests = [t for t in tests if not t.match("*Tests.py")] if args.unit_only: - tests = [t for t in tests if t.endswith("Tests.py")] + tests = [t for t in tests if t.match("*Tests.py")] if args.excludelistfile: - with args.excludelistfile.open() as f: - excludetests = scanlist(f) + excludetests = scanlist(args.excludelistfile) tests = [t for t in tests if t not in excludetests] +# did we end up with any tests? if not tests: sys.stderr.write(parser.format_usage() + """ -error: no tests were found. - Tests can be specified on the command line, read from a file with - the -f/--file option, or discovered with -a/--all to run all tests. +error: no tests matching the specification were found. + See "Test selection options" in the help for details on + how to specify and/or exclude tests. """) sys.exit(1) # ---[ test processing ]----------------------------------- -tests = [Test(t, n + 1) for n, t in enumerate(tests)] +tests = [Test(t) for t in tests] if args.list_only: for t in tests: - sys.stdout.write(t.path + "\n") + print(t.path) sys.exit(0) if not args.python: @@ -702,7 +700,7 @@ os.environ["python_executable"] = args.python if args.print_times: def print_time(fmt, tm): - sys.stdout.write(fmt % tm) + print(fmt % tm) else: @@ -739,7 +737,7 @@ def log_result(t, io_lock=None): print(t.stdout) if t.stderr: print(t.stderr) - print_time("Test execution time: %.1f seconds\n", t.test_time) + print_time("Test execution time: %.1f seconds", t.test_time) finally: if io_lock: io_lock.release() @@ -778,8 +776,8 @@ def run_test(t, io_lock=None, run_async=True): if args.printcommand: if args.print_progress: t.headline += "%d/%d (%.2f%s) %s\n" % ( - t.num, total_num_tests, - float(t.num) * 100.0 / float(total_num_tests), + t.testno, total_num_tests, + float(t.testno) * 100.0 / float(total_num_tests), "%", t.command_str, ) @@ -843,7 +841,7 @@ else: # --- all tests are complete by the time we get here --- if tests: tests[0].total_time = time_func() - total_start_time - print_time("Total execution time for all tests: %.1f seconds\n", tests[0].total_time) + print_time("Total execution time for all tests: %.1f seconds", tests[0].total_time) passed = [t for t in tests if t.status == 0] fail = [t for t in tests if t.status == 1] diff --git a/test/runtest/SCons.py b/test/runtest/SCons.py index 20c4c64..fc4c3e0 100644 --- a/test/runtest/SCons.py +++ b/test/runtest/SCons.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Verify that we find tests under the SCons/ tree only if they end @@ -46,17 +45,17 @@ test.write_passing_test(['SCons', 'passTests.py']) test.write_passing_test(['SCons', 'suite', 'pass.py']) test.write_passing_test(['SCons', 'suite', 'passTests.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(src_passTests_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {src_passTests_py} PASSING TEST STDOUT -%(pythonstring)s%(pythonflags)s %(src_suite_passTests_py)s +{pythonstring}{pythonflags} {src_suite_passTests_py} PASSING TEST STDOUT -""" % locals() +""" expect_stderr = """\ PASSING TEST STDERR PASSING TEST STDERR -""" % locals() +""" test.run(arguments='-k SCons', stdout=expect_stdout, stderr=expect_stderr) diff --git a/test/runtest/baseline/combined.py b/test/runtest/baseline/combined.py index 228d42d..00ce85b 100644 --- a/test/runtest/baseline/combined.py +++ b/test/runtest/baseline/combined.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test a combination of a passing test, failing test, and no-result @@ -42,27 +41,24 @@ test_pass_py = os.path.join('test', 'pass.py') test = TestRuntest.TestRuntest() test.subdir('test') - test.write_failing_test(['test', 'fail.py']) - test.write_no_result_test(['test', 'no_result.py']) - test.write_passing_test(['test', 'pass.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(test_fail_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_fail_py} FAILING TEST STDOUT -%(pythonstring)s%(pythonflags)s %(test_no_result_py)s +{pythonstring}{pythonflags} {test_no_result_py} NO RESULT TEST STDOUT -%(pythonstring)s%(pythonflags)s %(test_pass_py)s +{pythonstring}{pythonflags} {test_pass_py} PASSING TEST STDOUT Failed the following test: -\t%(test_fail_py)s +\t{test_fail_py} NO RESULT from the following test: -\t%(test_no_result_py)s -""" % locals() +\t{test_no_result_py} +""" expect_stderr = """\ FAILING TEST STDERR @@ -70,10 +66,7 @@ NO RESULT TEST STDERR PASSING TEST STDERR """ -test.run(arguments='-k -b . test', - status=1, - stdout=expect_stdout, - stderr=expect_stderr) +test.run(arguments='-k -b . test', status=1, stdout=expect_stdout, stderr=expect_stderr) test.pass_test() diff --git a/test/runtest/baseline/fail.py b/test/runtest/baseline/fail.py index e2aff4a..2268dce 100644 --- a/test/runtest/baseline/fail.py +++ b/test/runtest/baseline/fail.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,38 +22,39 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test how we handle a failing test specified on the command line. """ +import os + import TestRuntest pythonstring = TestRuntest.pythonstring pythonflags = TestRuntest.pythonflags +test_fail_py = os.path.join('test', 'fail.py') test = TestRuntest.TestRuntest() test.subdir('test') - test.write_failing_test(['test', 'fail.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s test/fail.py +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_fail_py} FAILING TEST STDOUT -""" % locals() +""" expect_stderr = """\ FAILING TEST STDERR """ -test.run(arguments='-k -b . test/fail.py', - status=1, - stdout=expect_stdout, - stderr=expect_stderr) +test.run( + arguments='-k -b . test/fail.py', + status=1, + stdout=expect_stdout, + stderr=expect_stderr, +) test.pass_test() diff --git a/test/runtest/baseline/no_result.py b/test/runtest/baseline/no_result.py index d00f536..ce6f20c 100644 --- a/test/runtest/baseline/no_result.py +++ b/test/runtest/baseline/no_result.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,43 +22,45 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test how we handle a no-results test specified on the command line. """ +import os + import TestRuntest pythonstring = TestRuntest.pythonstring pythonflags = TestRuntest.pythonflags +test_no_result_py = os.path.join('test', 'no_result.py') test = TestRuntest.TestRuntest() - test.subdir('test') - test.write_no_result_test(['test', 'no_result.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s test/no_result.py +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_no_result_py} NO RESULT TEST STDOUT -""" % locals() +""" expect_stderr = """\ NO RESULT TEST STDERR """ -test.run(arguments='--no-ignore-skips -k -b . test/no_result.py', - status=2, - stdout=expect_stdout, - stderr=expect_stderr) +test.run( + arguments='--no-ignore-skips -k -b . test/no_result.py', + status=2, + stdout=expect_stdout, + stderr=expect_stderr, +) -test.run(arguments='-k -b . test/no_result.py', - status=0, - stdout=expect_stdout, - stderr=expect_stderr) +test.run( + arguments='-k -b . test/no_result.py', + status=0, + stdout=expect_stdout, + stderr=expect_stderr, +) test.pass_test() diff --git a/test/runtest/baseline/pass.py b/test/runtest/baseline/pass.py index 481fc97..c31a6d6 100644 --- a/test/runtest/baseline/pass.py +++ b/test/runtest/baseline/pass.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test how we handle a passing test specified on the command line. @@ -42,18 +41,16 @@ test.subdir('test') test.write_passing_test(['test', 'pass.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(test_pass_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_pass_py} PASSING TEST STDOUT -""" % locals() +""" expect_stderr = """\ PASSING TEST STDERR """ -test.run(arguments='-k -b . test', - stdout=expect_stdout, - stderr=expect_stderr) +test.run(arguments='-k -b . test', stdout=expect_stdout, stderr=expect_stderr) test.pass_test() diff --git a/test/runtest/faillog.py b/test/runtest/faillog.py index e2ca67e..f23b90b 100644 --- a/test/runtest/faillog.py +++ b/test/runtest/faillog.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test a list of tests in failed_tests.log to run with the --retry option @@ -42,15 +41,15 @@ test.subdir('test') test.write_failing_test(test_fail_py) test.write_passing_test(test_pass_py) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(test_fail_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_fail_py} FAILING TEST STDOUT -%(pythonstring)s%(pythonflags)s %(test_pass_py)s +{pythonstring}{pythonflags} {test_pass_py} PASSING TEST STDOUT Failed the following test: -\t%(test_fail_py)s -""" % locals() +\t{test_fail_py} +""" expect_stderr = """\ FAILING TEST STDERR diff --git a/test/runtest/no_faillog.py b/test/runtest/no_faillog.py index db17c8e..174ab48 100644 --- a/test/runtest/no_faillog.py +++ b/test/runtest/no_faillog.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test a list of tests in failed_tests.log to run with the --retry option @@ -42,19 +41,22 @@ test.subdir('test') test.write_failing_test(test_fail_py) test.write_passing_test(test_pass_py) -test.write('failed_tests.log', """\ -%(test_fail_py)s -""" % locals()) +test.write( + 'failed_tests.log', + f"""\ +{test_fail_py} +""", +) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(test_fail_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_fail_py} FAILING TEST STDOUT -%(pythonstring)s%(pythonflags)s %(test_pass_py)s +{pythonstring}{pythonflags} {test_pass_py} PASSING TEST STDOUT Failed the following test: -\t%(test_fail_py)s -""" % locals() +\t{test_fail_py} +""" expect_stderr = """\ FAILING TEST STDERR diff --git a/test/runtest/print_time.py b/test/runtest/print_time.py index 834d2ae..3d49a97 100644 --- a/test/runtest/print_time.py +++ b/test/runtest/print_time.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test a combination of a passing test, failing test, and no-result @@ -41,30 +40,30 @@ test_fail_py = re.escape(os.path.join('test', 'fail.py')) test_no_result_py = re.escape(os.path.join('test', 'no_result.py')) test_pass_py = re.escape(os.path.join('test', 'pass.py')) -test = TestRuntest.TestRuntest(match = TestCmd.match_re) +test = TestRuntest.TestRuntest(match=TestCmd.match_re) test.subdir('test') test.write_failing_test(['test', 'fail.py']) test.write_no_result_test(['test', 'no_result.py']) test.write_passing_test(['test', 'pass.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(test_fail_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_fail_py} FAILING TEST STDOUT Test execution time: \\d+.\\d seconds -%(pythonstring)s%(pythonflags)s %(test_no_result_py)s +{pythonstring}{pythonflags} {test_no_result_py} NO RESULT TEST STDOUT Test execution time: \\d+.\\d seconds -%(pythonstring)s%(pythonflags)s %(test_pass_py)s +{pythonstring}{pythonflags} {test_pass_py} PASSING TEST STDOUT Test execution time: \\d+.\\d seconds Total execution time for all tests: \\d+.\\d seconds Failed the following test: -\t%(test_fail_py)s +\t{test_fail_py} NO RESULT from the following test: -\t%(test_no_result_py)s -""" % locals() +\t{test_no_result_py} +""" expect_stderr = """\ FAILING TEST STDERR @@ -72,10 +71,7 @@ NO RESULT TEST STDERR PASSING TEST STDERR """ -test.run(arguments='-k -t test', - status=1, - stdout=expect_stdout, - stderr=expect_stderr) +test.run(arguments='-k -t test', status=1, stdout=expect_stdout, stderr=expect_stderr) test.pass_test() diff --git a/test/runtest/python.py b/test/runtest/python.py index abd4f0c..dbb24ca 100644 --- a/test/runtest/python.py +++ b/test/runtest/python.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test that the -P option lets us specify a Python version to use. @@ -46,26 +45,26 @@ head, dir = os.path.split(head) # python version then in use, which could be different pythonflags = TestRuntest.pythonflags -# We have to normalize the python path here, because some installations don't like -# getting called with "/bin/../bin/python" as first argument, e.g. Fedora 17 Desktop. +# We have to normalize the python path here, because some installations +# don't like getting called with "/bin/../bin/python" as first argument, +# e.g. Fedora 17 Desktop. mypython = os.path.normpath(os.path.join(head, dir, os.path.pardir, dir, python)) test.subdir('test') - test.write_passing_test(['test', 'pass.py']) -expect_stdout = """\ -%(mypython)s%(pythonflags)s %(test_pass_py)s +expect_stdout = f"""\ +{mypython}{pythonflags} {test_pass_py} PASSING TEST STDOUT -""" % locals() +""" expect_stderr = """\ PASSING TEST STDERR """ -test.run(arguments=['-k','-P', mypython, 'test'], - stdout=expect_stdout, - stderr=expect_stderr) +test.run( + arguments=['-k', '-P', mypython, 'test'], stdout=expect_stdout, stderr=expect_stderr +) test.pass_test() diff --git a/test/runtest/retry.py b/test/runtest/retry.py index 4280152..0c5beb6 100644 --- a/test/runtest/retry.py +++ b/test/runtest/retry.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test a list of tests in failed_tests.log to run with the --retry option @@ -45,14 +44,17 @@ test.write_failing_test(['test', 'fail.py']) test.write_no_result_test(['test', 'no_result.py']) test.write_passing_test(['test', 'pass.py']) -test.write('failed_tests.log', """\ -%(test_fail_py)s -""" % locals()) +test.write( + 'failed_tests.log', + f"""\ +{test_fail_py} +""", +) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(test_fail_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_fail_py} FAILING TEST STDOUT -""" % locals() +""" expect_stderr = """\ FAILING TEST STDERR diff --git a/test/runtest/simple/combined.py b/test/runtest/simple/combined.py index a54e57c..e594c50 100644 --- a/test/runtest/simple/combined.py +++ b/test/runtest/simple/combined.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test a combination of a passing test, failing test, and no-result @@ -45,20 +44,20 @@ test.write_failing_test(test_fail_py) test.write_no_result_test(test_no_result_py) test.write_passing_test(test_pass_py) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(test_fail_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_fail_py} FAILING TEST STDOUT -%(pythonstring)s%(pythonflags)s %(test_no_result_py)s +{pythonstring}{pythonflags} {test_no_result_py} NO RESULT TEST STDOUT -%(pythonstring)s%(pythonflags)s %(test_pass_py)s +{pythonstring}{pythonflags} {test_pass_py} PASSING TEST STDOUT Failed the following test: -\t%(test_fail_py)s +\t{test_fail_py} NO RESULT from the following test: -\t%(test_no_result_py)s -""" % locals() +\t{test_no_result_py} +""" expect_stderr = """\ FAILING TEST STDERR @@ -66,12 +65,7 @@ NO RESULT TEST STDERR PASSING TEST STDERR """ -test.run( - arguments='-k test', - status=1, - stdout=expect_stdout, - stderr=expect_stderr -) +test.run(arguments='-k test', status=1, stdout=expect_stdout, stderr=expect_stderr) test.must_exist('failed_tests.log') test.must_contain('failed_tests.log', test_fail_py) diff --git a/test/runtest/simple/fail.py b/test/runtest/simple/fail.py index f26f00e..5e1979a 100644 --- a/test/runtest/simple/fail.py +++ b/test/runtest/simple/fail.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,38 +22,35 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test how we handle a failing test specified on the command line. """ +import os + import TestRuntest pythonstring = TestRuntest.pythonstring pythonflags = TestRuntest.pythonflags +test_fail_py = os.path.join('test', 'fail.py') test = TestRuntest.TestRuntest() - test.subdir('test') - test.write_failing_test(['test', 'fail.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s test/fail.py +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_fail_py} FAILING TEST STDOUT -""" % locals() +""" expect_stderr = """\ FAILING TEST STDERR """ -test.run(arguments='-k test/fail.py', - status=1, - stdout=expect_stdout, - stderr=expect_stderr) +test.run( + arguments='-k test/fail.py', status=1, stdout=expect_stdout, stderr=expect_stderr +) test.pass_test() diff --git a/test/runtest/simple/no_result.py b/test/runtest/simple/no_result.py index 33f28e4..beb82b0 100644 --- a/test/runtest/simple/no_result.py +++ b/test/runtest/simple/no_result.py @@ -27,35 +27,40 @@ Test how we handle a no-results test specified on the command line. """ +import os + import TestRuntest pythonstring = TestRuntest.pythonstring pythonflags = TestRuntest.pythonflags +test_no_result_py = os.path.join('test', 'no_result.py') test = TestRuntest.TestRuntest() - test.subdir('test') - test.write_no_result_test(['test', 'no_result.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s test/no_result.py +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_no_result_py} NO RESULT TEST STDOUT -""" % locals() +""" expect_stderr = """\ NO RESULT TEST STDERR """ -test.run(arguments='--no-ignore-skips -k test/no_result.py', - status=2, - stdout=expect_stdout, - stderr=expect_stderr) +test.run( + arguments='--no-ignore-skips -k test/no_result.py', + status=2, + stdout=expect_stdout, + stderr=expect_stderr, +) -test.run(arguments='-k test/no_result.py', - status=0, - stdout=expect_stdout, - stderr=expect_stderr) +test.run( + arguments='-k test/no_result.py', + status=0, + stdout=expect_stdout, + stderr=expect_stderr, +) test.pass_test() diff --git a/test/runtest/simple/pass.py b/test/runtest/simple/pass.py index 7ceb9a0..408ef4c 100644 --- a/test/runtest/simple/pass.py +++ b/test/runtest/simple/pass.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,29 +22,27 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test how we handle a passing test specified on the command line. """ +import os + import TestRuntest pythonstring = TestRuntest.pythonstring pythonflags = TestRuntest.pythonflags +test_pass_py = os.path.join('test', 'pass.py') test = TestRuntest.TestRuntest() - test.subdir('test') - test.write_passing_test(['test', 'pass.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s test/pass.py +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_pass_py} PASSING TEST STDOUT -""" % locals() +""" expect_stderr = """\ PASSING TEST STDERR diff --git a/test/runtest/testargv.py b/test/runtest/testargv.py index 22e57e8..20dcdc8 100644 --- a/test/runtest/testargv.py +++ b/test/runtest/testargv.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test subdir args for runtest.py, for example: @@ -38,34 +37,35 @@ import TestRuntest test = TestRuntest.TestRuntest() test.subdir('test', ['test', 'subdir']) -files = {} -files['pythonstring'] = TestRuntest.pythonstring -files['pythonflags'] = TestRuntest.pythonflags +pythonstring = TestRuntest.pythonstring +pythonflags = TestRuntest.pythonflags -files['one'] = os.path.join('test/subdir', 'test_one.py') -files['two'] = os.path.join('test/subdir', 'two.py') -files['three'] = os.path.join('test', 'test_three.py') +one = os.path.join('test', 'subdir', 'test_one.py') +two = os.path.join('test', 'subdir', 'two.py') +three = os.path.join('test', 'test_three.py') -test.write_passing_test(files['one']) -test.write_passing_test(files['two']) -test.write_passing_test(files['three']) +test.write_passing_test(['test', 'subdir', 'test_one.py']) +test.write_passing_test(['test', 'subdir', 'two.py']) +test.write_passing_test(['test', 'test_three.py']) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(one)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {one} PASSING TEST STDOUT -%(pythonstring)s%(pythonflags)s %(two)s +{pythonstring}{pythonflags} {two} PASSING TEST STDOUT -""" % files +""" expect_stderr = """\ PASSING TEST STDERR PASSING TEST STDERR """ -test.run(arguments = '--no-progress test/subdir', - status = 0, - stdout = expect_stdout, - stderr = expect_stderr) +test.run( + arguments='--no-progress test/subdir', + status=0, + stdout=expect_stdout, + stderr=expect_stderr, +) test.pass_test() diff --git a/test/runtest/testlistfile.py b/test/runtest/testlistfile.py index 5c956b8..e5d85b8 100644 --- a/test/runtest/testlistfile.py +++ b/test/runtest/testlistfile.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test a list of tests to run in a file specified with the -f option. @@ -46,15 +45,18 @@ test.write_failing_test(['test', 'fail.py']) test.write_no_result_test(['test', 'no_result.py']) test.write_passing_test(['test', 'pass.py']) -test.write('t.txt', """\ -#%(test_fail_py)s -%(test_pass_py)s -""" % locals()) +test.write( + 't.txt', + f"""\ +#{test_fail_py} +{test_pass_py} +""", +) -expect_stdout = """\ -%(pythonstring)s%(pythonflags)s %(test_pass_py)s +expect_stdout = f"""\ +{pythonstring}{pythonflags} {test_pass_py} PASSING TEST STDOUT -""" % locals() +""" expect_stderr = """\ PASSING TEST STDERR diff --git a/test/runtest/xml/output.py b/test/runtest/xml/output.py index cd20dbd..66ec656 100644 --- a/test/runtest/xml/output.py +++ b/test/runtest/xml/output.py @@ -1,6 +1,8 @@ #!/usr/bin/env python # -# __COPYRIGHT__ +# MIT License +# +# Copyright The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -20,9 +22,6 @@ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" """ Test writing XML output to a file. @@ -34,8 +33,7 @@ import re import TestCmd import TestRuntest -test = TestRuntest.TestRuntest(match = TestCmd.match_re, - diff = TestCmd.diff_re) +test = TestRuntest.TestRuntest(match=TestCmd.match_re, diff=TestCmd.diff_re) pythonstring = re.escape(TestRuntest.pythonstring) pythonflags = TestRuntest.pythonflags @@ -44,22 +42,18 @@ test_no_result_py = re.escape(os.path.join('test', 'no_result.py')) test_pass_py = re.escape(os.path.join('test', 'pass.py')) test.subdir('test') - test.write_fake_scons_source_tree() - test.write_failing_test(['test', 'fail.py']) - test.write_no_result_test(['test', 'no_result.py']) - test.write_passing_test(['test', 'pass.py']) -test.run(arguments = '--xml xml.out test', status=1) +test.run(arguments='--xml xml.out test', status=1) -expect = """\ +expect = f"""\ - %(test_fail_py)s - %(pythonstring)s%(pythonflags)s %(test_fail_py)s + {test_fail_py} + {pythonstring}{pythonflags} {test_fail_py} 1 FAILING TEST STDOUT @@ -68,8 +62,8 @@ expect = """\ - %(test_no_result_py)s - %(pythonstring)s%(pythonflags)s %(test_no_result_py)s + {test_no_result_py} + {pythonstring}{pythonflags} {test_no_result_py} 2 NO RESULT TEST STDOUT @@ -78,8 +72,8 @@ expect = """\ - %(test_pass_py)s - %(pythonstring)s%(pythonflags)s %(test_pass_py)s + {test_pass_py} + {pythonstring}{pythonflags} {test_pass_py} 0 PASSING TEST STDOUT @@ -89,7 +83,7 @@ expect = """\ -""" % locals() +""" # Just strip carriage returns so the regular expression matching works. contents = test.read('xml.out') -- cgit v0.12 From c31c4d7032eede7eb7389c79a9a602da17487811 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 19 Apr 2023 08:40:20 -0600 Subject: runtest: add additional test of os.sep usage Make sure test lists with "foreign" separator still cause the correct discovery/usage. Signed-off-by: Mats Wichmann --- test/runtest/pathseps.py | 78 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 test/runtest/pathseps.py diff --git a/test/runtest/pathseps.py b/test/runtest/pathseps.py new file mode 100644 index 0000000..10d86b2 --- /dev/null +++ b/test/runtest/pathseps.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python +# +# MIT License +# +# Copyright The SCons Foundation +# +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, +# distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to +# the following conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +""" +Make sure different path separators don't break things. +Backslashes should be okay on POSIX, forwards slashes on win32, +and combinations should cause no problems. +""" + +import os.path + +import TestRuntest + +# the "expected" paths are generated os-native +test_one_py = os.path.join('test', 'subdir', 'test1.py') +test_two_py = os.path.join('test', 'subdir', 'test2.py') +test_three_py = os.path.join('test', 'subdir', 'test3.py') +test_four_py = os.path.join('test', 'subdir', 'test4.py') + +test = TestRuntest.TestRuntest() +# create files for discovery +testdir = "test/subdir".split("/") +test.subdir(testdir[0], testdir) +test.write_passing_test(testdir + ['test1.py']) +test.write_passing_test(testdir + ['test2.py']) +test.write_passing_test(testdir + ['test3.py']) +test.write_passing_test(testdir + ['test4.py']) + +# discover tests using testlist file with various combinations of slashes +test.write( + 'testlist.txt', + r""" +test/subdir/test1.py +test\subdir/test2.py +test/subdir\test3.py +test\subdir\test4.py +""", +) + +# expect the discovered files to all be os-native +expect_stdout = f"""\ +{test_one_py} +{test_two_py} +{test_three_py} +{test_four_py} +""" + +test.run(arguments="-k -l -f testlist.txt", stdout=expect_stdout, stderr=None) + +test.pass_test() + +# Local Variables: +# tab-width:4 +# indent-tabs-mode:nil +# End: +# vim: set expandtab tabstop=4 shiftwidth=4: -- cgit v0.12 From faa271d1dd379d5fe46ca2742f5a83e54ea4f36c Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 8 May 2023 08:05:06 -0600 Subject: add RELEASE entry for runtest changes [skip ci] Signed-off-by: Mats Wichmann --- RELEASE.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/RELEASE.txt b/RELEASE.txt index c2244f2..bafda47 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -64,7 +64,11 @@ DOCUMENTATION DEVELOPMENT ----------- -- List visible changes in the way SCons is developed +- SCons test runner now uses pathlib to normalize and compare paths + to test files, which allows test lists, exclude lists, and tests on + the command line to "not care" about the OS convention for pathname + separators. + Thanks to the following contributors listed below for their contributions to this release. ========================================================================================== -- cgit v0.12 From d723812004c1e88c5bfab37b454b7164f5b4ae00 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 8 May 2023 12:55:27 -0600 Subject: Put back Builder entityref in UG add-method [skip appveyor] Entity reference &Builder;s was turned to plain text in a few places. Restored, this time using existing pluralized entity name &Builders;. Also twiddled a little wording in same User Guide chapter. Signed-off-by: Mats Wichmann --- doc/user/add-method.xml | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 7c59bf2..179be95 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -32,9 +32,14 @@ Copyright The SCons Foundation The &f-link-AddMethod; function is used to add a method to an environment. It is typically used to add a "pseudo-builder," a function that looks like a &Builder; but - wraps up calls to multiple other Builders + wraps up calls to multiple other &Builders; or otherwise processes its arguments - before calling one or more Builders. + before calling one or more &Builders;. + + + + + In the following example, we want to install the program into the standard /usr/bin directory hierarchy, @@ -70,11 +75,11 @@ int main() { printf("Hello, world!\n"); } - A pseudo-builder is useful because it provides more flexibility - in parsing arguments than you can get with a standard &Builder;. + A pseudo-builder is useful because it gives you more flexibility + parsing arguments than you can get with a standard &Builder;. The next example shows a pseudo-builder with a - named argument that modifies the filename, and a separate argument - for the resource file (rather than having the builder figure it out + named argument that modifies the filename, and a separate optional + argument for a resource file (rather than having the builder figure it out by file extension). This example also demonstrates using the global &AddMethod; function to add a method to the global Environment class, so it will be available in all subsequently created environments. -- cgit v0.12 From d6c4a4236512d1310ca5cfe990bd0af71dfe89a9 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 16 May 2023 09:23:33 -0600 Subject: Doc fiddling - Alias, Action, Decider [skip appveyor] * Signature of Alias() now matches implementation to avoid problem if kwargs used * Case of Alias with no targets is mentioned in text (was already shown in example) * Now mention that Action([item]) does not return a ListAction - previously implied that if arg was a list, a ListAction was *always* returned * Mention default Decider and sort the names of available decider functions, and add version marking. * Minor fiddling with Alias.py docstrings. Signed-off-by: Mats Wichmann --- CHANGES.txt | 7 +++ RELEASE.txt | 7 +-- SCons/Action.py | 55 ++++++++++--------- SCons/Environment.xml | 142 ++++++++++++++++++++++++++++++-------------------- doc/man/scons.xml | 12 +++-- doc/user/caching.xml | 2 +- 6 files changed, 134 insertions(+), 91 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 5ad76b8..6e8e677 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -25,6 +25,13 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER Only used in msvs.py. Use base64.decodebytes instead. - SCons test runner now uses pathlib to normalize and compare paths to test files. + - Minor doc fixes: signature of Alias() now matches implementation + to avoid problem if kwargs used; case of Alias with no targets is + mentioned in text (was already shown in example); now mention that + Action([item]) does not return a ListAction - previously implied + that if arg was a list, a ListAction was *always* returned; mention + default Decider and sort the names of available decider functions, + and add a version marking. Minor fiddling with Alias.py docstrings. RELEASE 4.5.2 - Sun, 21 Mar 2023 14:08:29 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index bafda47..5cef731 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -57,9 +57,10 @@ PACKAGING DOCUMENTATION ------------- -- List any significant changes to the documentation (not individual - typo fixes, even if they're mentioned in src/CHANGES.txt to give - the contributor credit) +- Aligned manpage signature for Alias function to match implementation - + if the previous *targets* parameter had been used as a keyword argument, + the results would be incorrect (does not apply to positional argument + usage, which had no problem). DEVELOPMENT ----------- diff --git a/SCons/Action.py b/SCons/Action.py index 3f1a24e..fcc6f3f 100644 --- a/SCons/Action.py +++ b/SCons/Action.py @@ -148,9 +148,8 @@ def default_exitstatfunc(s): strip_quotes = re.compile(r'^[\'"](.*)[\'"]$') -def _callable_contents(obj): - """Return the signature contents of a callable Python object. - """ +def _callable_contents(obj) -> bytearray: + """Return the signature contents of a callable Python object.""" try: # Test if obj is a method. return _function_contents(obj.__func__) @@ -170,7 +169,7 @@ def _callable_contents(obj): return _function_contents(obj) -def _object_contents(obj): +def _object_contents(obj) -> bytearray: """Return the signature contents of any Python object. We have to handle the case where object contains a code object @@ -210,8 +209,10 @@ def _object_contents(obj): # the best we can. return bytearray(repr(obj), 'utf-8') +# TODO: docstrings for _code_contents and _function_contents +# do not render well with Sphinx. Consider reworking. -def _code_contents(code, docstring=None): +def _code_contents(code, docstring=None) -> bytearray: r"""Return the signature contents of a code object. By providing direct access to the code object of the @@ -223,7 +224,7 @@ def _code_contents(code, docstring=None): recompilations from moving a Python function. See: - - https://docs.python.org/2/library/inspect.html + - https://docs.python.org/3/library/inspect.html - http://python-reference.readthedocs.io/en/latest/docs/code/index.html For info on what each co\_ variable provides @@ -243,7 +244,6 @@ def _code_contents(code, docstring=None): co_code - Returns a string representing the sequence of bytecode instructions. """ - # contents = [] # The code contents depends on the number of local variables @@ -281,8 +281,9 @@ def _code_contents(code, docstring=None): return contents -def _function_contents(func): - """ +def _function_contents(func) -> bytearray: + """Return the signature contents of a function. + The signature is as follows (should be byte/chars): < _code_contents (see above) from func.__code__ > ,( comma separated _object_contents for function argument defaults) @@ -293,11 +294,7 @@ def _function_contents(func): - func.__code__ - The code object representing the compiled function body. - func.__defaults__ - A tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value - func.__closure__ - None or a tuple of cells that contain bindings for the function's free variables. - - :Returns: - Signature contents of a function. (in bytes) """ - contents = [_code_contents(func.__code__, func.__doc__)] # The function contents depends on the value of defaults arguments @@ -439,16 +436,13 @@ def _do_create_keywords(args, kw): def _do_create_action(act, kw): - """This is the actual "implementation" for the - Action factory method, below. This handles the - fact that passing lists to Action() itself has - different semantics than passing lists as elements - of lists. - - The former will create a ListAction, the latter - will create a CommandAction by converting the inner - list elements to strings.""" + """The internal implementation for the Action factory method. + This handles the fact that passing lists to :func:`Action` itself has + different semantics than passing lists as elements of lists. + The former will create a :class:`ListAction`, the latter will create a + :class:`CommandAction by converting the inner list elements to strings. + """ if isinstance(act, ActionBase): return act @@ -491,13 +485,22 @@ def _do_create_action(act, kw): return None -def _do_create_list_action(act, kw): - """A factory for list actions. Convert the input list into Actions - and then wrap them in a ListAction.""" +# TODO: from __future__ import annotations once we get to Python 3.7 base, +# to avoid quoting the defined-later classname +def _do_create_list_action(act, kw) -> "ListAction": + """A factory for list actions. + + Convert the input list *act* into Actions and then wrap them in a + :class:`ListAction`. If *act* has only a single member, return that + member, not a *ListAction*. This is intended to allow a contained + list to specify a command action without being processed into a + list action. + """ acts = [] for a in act: aa = _do_create_action(a, kw) - if aa is not None: acts.append(aa) + if aa is not None: + acts.append(aa) if not acts: return ListAction([]) elif len(acts) == 1: diff --git a/SCons/Environment.xml b/SCons/Environment.xml index f87e883..2b4c4af 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -351,9 +351,9 @@ to be performed after the specified target has been built. -The specified action(s) may be +action may be an Action object, or anything that -can be converted into an Action object +can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. @@ -364,6 +364,13 @@ the action may be called multiple times, once after each action that generates one or more targets in the list. + + +foo = Program('foo.c') +# remove execute permission from binary: +AddPostAction(foo, Chmod('$TARGET', "a-x")) + + @@ -379,9 +386,9 @@ to be performed before the specified target is built. -The specified action(s) may be +action may be an Action object, or anything that -can be converted into an Action object +can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. @@ -426,21 +433,35 @@ file into an object file. -(alias, [targets, [action]]) +(alias, [source, [action]]) -Creates one or more phony targets that -expand to one or more other targets. -An optional +Creates a phony target (or targets) that +can be used as references to zero or more other targets, +as specified by the optional source +parameter. +alias and +source +may each be a string or Node object, +or a list of strings or Node objects; +if Nodes are used for +alias +they must be Alias nodes. +The optional action -(command) -or list of actions -can be specified that will be executed +parameter specifies an action or list of actions +that will be executed whenever the any of the alias targets are out-of-date. -Returns the Node object representing the alias, -which exists outside of any file system. -This Node object, or the alias name, + + + +Returns a list of Alias Node objects representing the alias(es), +which exist outside of any physical file system. + + + +The alias name, or an Alias Node object, may be used as a dependency of any other target, including another alias. &f-Alias; @@ -593,7 +614,7 @@ giving an easy way to enter multiple macros in one addition. Use an = to specify a valued macro. -A tuple is treated as a valued macro. +A tuple is treated as a valued macro. Use the value None if the macro should not have a value. It is an error to supply more than two elements in such a tuple. @@ -1238,8 +1259,8 @@ so you normally don't need to create directories by hand. -Creates a Configure object for integrated -functionality similar to GNU autoconf. +Creates a &Configure; object for integrated +functionality similar to GNU autoconf. See the manpage section "Configure Contexts" for a complete explanation of the arguments and behavior. @@ -1265,50 +1286,24 @@ that will be applied: -"timestamp-newer" - - -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is newer than the target file's timestamp. -This is the behavior of the classic Make utility, -and -make -can be used a synonym for -timestamp-newer. - - - - -"timestamp-match" - - -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is different than the -timestamp recorded the last time the target was built. -This provides behavior very similar to the classic Make utility -(in particular, files are not opened up so that their -contents can be checksummed) -except that the target will also be rebuilt if a -dependency file has been restored to a version with an -earlier -timestamp, such as can happen when restoring files from backup archives. - - - - "content" Specifies that a target shall be considered out of date and rebuilt if the dependency's content has changed since the last time the target was built, -as determined be performing an checksum -on the dependency's contents +as determined by performing a checksum +on the dependency's contents using the selected hash function, and comparing it to the checksum recorded the last time the target was built. -MD5 -can be used as a synonym for -content, but it is deprecated. +content is the default decider. + + +Changed in version 4.1: +The decider was renamed to content +since the hash function is now selectable. +The former name, MD5, +can still be used as a synonym, but is deprecated. @@ -1339,9 +1334,44 @@ that runs a build, updates a file, and runs the build again, all within a single second. -MD5-timestamp -can be used as a synonym for -content-timestamp, but it is deprecated. + + +Changed in version 4.1: +The decider was renamed to content-timestamp +since the hash function is now selectable. +The former name, MD5-timestamp, +can still be used as a synonym, but is deprecated. + + + + +"timestamp-newer" + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is newer than the target file's timestamp. +This is the behavior of the classic Make utility, +and +make +can be used a synonym for +timestamp-newer. + + + + +"timestamp-match" + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is different than the +timestamp recorded the last time the target was built. +This provides behavior very similar to the classic Make utility +(in particular, files are not opened up so that their +contents can be checksummed) +except that the target will also be rebuilt if a +dependency file has been restored to a version with an +earlier +timestamp, such as can happen when restoring files from backup archives. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index e79a267..b070dcb 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1216,7 +1216,7 @@ small block-size slows down the build considerably. The default value is to use a chunk size of 64 kilobytes, which should be appropriate for most uses. -New in version 4.2. +New in version 4.1. @@ -1256,7 +1256,7 @@ For example, uses a SConsign database named .sconsign_sha256.dblite. -New in version 4.2. +New in version 4.1. @@ -3961,7 +3961,7 @@ it will not be added again. The default is False. library can be a list of library names, or None (the default if the argument is omitted). If the former, symbol is checked against -each library name in order, returning +each library name in order, returning (and reporting success) on the first successful test; if the latter, it is checked with the current value of &cv-LIBS; @@ -6526,9 +6526,11 @@ env.Command( -The behavior of Chmod is limited on Windows, +The behavior of Chmod is limited on Windows +and on WebAssembly platforms, see the notes in the Python documentation for -os.chmod, which is the underlying function. + +os.chmod, which is the underlying function. diff --git a/doc/user/caching.xml b/doc/user/caching.xml index 69368d7..f00bd69 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -129,7 +129,7 @@ CacheDir('/usr/local/build_cache') A few inside details: &SCons; tracks two main kinds of cryptographic hashes: a &contentsig;, which is a hash of the contents of a file participating in the - build (depepdencies as well as targets); + build (dependencies as well as targets); and a &buildsig;, which is a hash of the elements needed to build a target, such as the command line, the contents of the sources, and possibly information about -- cgit v0.12 From 27132f89fa411aae71b931138561b00549a163f8 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Wed, 17 May 2023 18:57:26 -0700 Subject: Minor update to scanner description --- doc/user/scanners.xml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 9a0a1d3..6538987 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -149,10 +149,13 @@ over the file scanning rather than being called for each input line: &SCons; has built-in &Scanners; that know how to look in C/C++, Fortran, D, IDL, LaTeX, Python and SWIG source files for information about - other files that targets built from those files depend on - - for example, in the case of files that use the C preprocessor, - the .h files that are specified - using #include lines in the source. + other files that targets built from those files depend on. + + For example, if you have a file format which uses #include + to specify files which should be included into the source file + when it is processed, you can use an existing scanner already + included in &SCons;. + You can use the same mechanisms that &SCons; uses to create its built-in Scanners to write Scanners of your own for file types that &SCons; does not know how to scan "out of the box." -- cgit v0.12