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 7b5200ede..86297de7a 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 v1.2.1 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 ea1deccb6..ebe0e6f48 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 86297de7a..d25ba9a23 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 v1.2.1 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 d25ba9a23..7c59bf21f 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 b9a5084a7..1e2234257 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 v1.2.1 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 ebe0e6f48..2d3f5a434 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 a53e70e07..97ca36f9f 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 1e2234257..9a0a1d34a 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 v1.2.1 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 7c59bf21f..179be95fd 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 v1.2.1 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 9a0a1d34a..65389879d 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 v1.2.1