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 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