diff options
author | William Deegan <bill@baddogconsulting.com> | 2023-05-17 18:57:46 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-05-17 18:57:46 -0700 |
commit | d7ed1c6b91b93e70aae63fdd1e397a37cfec024b (patch) | |
tree | c264c319f2cec478aa555fe1904d812b6dbf4436 | |
parent | c3b4eedd1fa9e4c2d272e4b78d2657eb54ac0259 (diff) | |
parent | 27132f89fa411aae71b931138561b00549a163f8 (diff) | |
download | scons-git-master.tar.gz |
Tweak pseudo-builder in user guide
-rw-r--r-- | doc/scons.mod | 13 | ||||
-rw-r--r-- | doc/user/add-method.xml | 78 | ||||
-rw-r--r-- | doc/user/builders-writing.xml | 3 | ||||
-rw-r--r-- | doc/user/scanners.xml | 68 |
4 files changed, 81 insertions, 81 deletions
diff --git a/doc/scons.mod b/doc/scons.mod index ea1deccb6..2d3f5a434 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -92,15 +92,23 @@ <!ENTITY zip "<application xmlns='http://www.scons.org/dbxsd/v1.0'>zip</application>"> +<!-- Concepts: these are key SCons things, which may *also* be classes, etc. + but are marked here for inclusion in a glossary +--> +<!ENTITY Action "<glossterm linkend='gls-action' xmlns='http://www.scons.org/dbxsd/v1.0'>Action</glossterm>"> +<!ENTITY Builder "<glossterm linkend='gls-builder' xmlns='http://www.scons.org/dbxsd/v1.0'>Builder</glossterm>"> +<!ENTITY Builders "<glossterm linkend='gls-builder' xmlns='http://www.scons.org/dbxsd/v1.0'>Builders</glossterm>"> +<!ENTITY Scanner "<glossterm linkend='gls-scanner' xmlns='http://www.scons.org/dbxsd/v1.0'>Scanner</glossterm>"> +<!ENTITY Scanners "<glossterm linkend='gls-scanner' xmlns='http://www.scons.org/dbxsd/v1.0'>Scanners</glossterm>"> + + <!-- Classes. --> -<!ENTITY Action "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Action</classname>"> <!ENTITY ActionBase "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>ActionBase</classname>"> <!ENTITY BuildInfo "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>BuildInfo</classname>"> <!ENTITY CommandAction "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>CommandAction</classname>"> <!ENTITY FunctionAction "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>FunctionAction</classname>"> <!ENTITY ListAction "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>ListAction</classname>"> -<!ENTITY Builder "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Builder</classname>"> <!ENTITY BuilderBase "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>BuilderBase</classname>"> <!ENTITY CompositeBuilder "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>CompositeBuilder</classname>"> <!ENTITY MultiStepBuilder "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>MultiStepBuilder</classname>"> @@ -110,7 +118,6 @@ <!ENTITY Parallel "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Parallel</classname>"> <!ENTITY Node "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Node</classname>"> <!ENTITY Node_FS "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Node.FS</classname>"> -<!ENTITY Scanner "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Scanner</classname>"> <!ENTITY Sig "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Sig</classname>"> <!ENTITY Signature "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Signature</classname>"> <!ENTITY Taskmaster "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Taskmaster</classname>"> diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 7b5200ede..179be95fd 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -1,4 +1,10 @@ <?xml version='1.0'?> +<!-- +SPDX-License-Identifier: MIT + +Copyright The SCons Foundation +--> + <!DOCTYPE sconsdoc [ <!ENTITY % scons SYSTEM "../scons.mod"> %scons; @@ -18,43 +24,22 @@ 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"> -<title>Extending &SCons;: Pseudo-Builders and the AddMethod function</title> -<!-- - - 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: +<title>Extending &SCons;: Pseudo-Builders and the AddMethod function</title> - The above copyright notice and this permission notice shall be included - in all copies or substantial portions of the Software. + <para> - 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. + 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; + or otherwise processes its arguments + before calling one or more &Builders;. ---> + </para> <para> - 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 - or otherwise processes its arguments - before calling one or more &Builder;s. In the following example, we want to install the program into the standard <filename>/usr/bin</filename> directory hierarchy, @@ -69,10 +54,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 </file> <file name="hello.c"> int main() { printf("Hello, world!\n"); } @@ -89,31 +75,35 @@ int main() { printf("Hello, world!\n"); } <para> - 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 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 used in all subsequently created environments. + so it will be available in all subsequently created environments. </para> <scons_example name="addmethod_ex2"> <file name="SConstruct" printme="1"> -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() 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: </para> <scons_example name="builderswriting_ex3"> <file name="SConstruct"> 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 b9a5084a7..65389879d 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -146,15 +146,18 @@ over the file scanning rather than being called for each input line: <para> - &SCons; has built-in scanners 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 <filename>.h</filename> files that are specified - using <literal>#include</literal> lines in the source. + other files that targets built from those files depend on. + + For example, if you have a file format which uses <literal>#include</literal> + 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 + 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." </para> @@ -164,7 +167,7 @@ over the file scanning rather than being called for each input line: <para> - Suppose, for example, that we want to create a simple scanner + Suppose, for example, that we want to create a simple &Scanner; for <filename>.foo</filename> files. A <filename>.foo</filename> file contains some text that will be processed, @@ -183,7 +186,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 - <filename>re</filename> module + <systemitem>re</systemitem> module to scan for the <literal>include</literal> lines in our example: </para> @@ -203,7 +206,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 +228,7 @@ def kfile_scan(node, env, path, arg): <variablelist> <varlistentry> - <term>node</term> + <term><parameter>node</parameter></term> <listitem> <para> @@ -233,8 +236,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 <literal>str()</literal> function, - or an internal &SCons; <literal>get_text_contents()</literal> + using the <function>str</function> function, + or an internal &SCons; <methodname>get_text_contents</methodname> object method can be used to fetch the contents. </para> @@ -242,7 +245,7 @@ def kfile_scan(node, env, path, arg): </varlistentry> <varlistentry> - <term>env</term> + <term><parameter>env</parameter></term> <listitem> <para> @@ -256,13 +259,13 @@ def kfile_scan(node, env, path, arg): </varlistentry> <varlistentry> - <term>path</term> + <term><parameter>path</parameter></term> <listitem> <para> 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 +274,7 @@ def kfile_scan(node, env, path, arg): </varlistentry> <varlistentry> - <term>arg</term> + <term><parameter>arg</parameter></term> <listitem> <para> @@ -288,10 +291,10 @@ def kfile_scan(node, env, path, arg): <para> - 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 <parameter>skeys</parameter> 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 +323,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 +366,21 @@ cat </section> <section> - <title>Adding a search path to a scanner: &FindPathDirs;</title> + <title>Adding a search path to a Scanner: &FindPathDirs;</title> <para> 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 <parameter>path</parameter> argument. Path variables + Scanner as the <parameter>path</parameter> 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 +392,7 @@ cat Using &FindPathDirs; is quite easy. Continuing the above example, using <varname>KPATH</varname> 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: </para> @@ -404,7 +406,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 <literal>env['KPATH']</literal> - 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 +420,9 @@ kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('K <para> - 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: <parameter>source_scanner</parameter> and <parameter>target_scanner</parameter>. <parameter>source_scanner</parameter> is used for scanning @@ -459,16 +461,16 @@ env.Foo('file') <para> 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. </para> <para> 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). </para> </section> |