diff options
Diffstat (limited to 'doc/user')
55 files changed, 352 insertions, 396 deletions
diff --git a/doc/user/README b/doc/user/README index 1718f0e..5433ea2 100644 --- a/doc/user/README +++ b/doc/user/README @@ -1,4 +1,4 @@ -# Copyright (c) 2001 - 2017 The SCons Foundation +# Copyright (c) 2001 - 2019 The SCons Foundation When adding a new file, add it to main.xml and MANIFEST. diff --git a/doc/user/SConstruct b/doc/user/SConstruct index 96d6677..67a3fd5 100644 --- a/doc/user/SConstruct +++ b/doc/user/SConstruct @@ -3,7 +3,7 @@ # # -# Copyright (c) 2001 - 2017 The SCons Foundation +# Copyright (c) 2001 - 2019 The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the diff --git a/doc/user/actions.xml b/doc/user/actions.xml index 3e60a9f..24ac8cf 100644 --- a/doc/user/actions.xml +++ b/doc/user/actions.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 0d30a48..0b1187c 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/alias.xml b/doc/user/alias.xml index fee9dd1..17a1b8f 100644 --- a/doc/user/alias.xml +++ b/doc/user/alias.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/ant.xml b/doc/user/ant.xml index bd35671..ed1aac6 100644 --- a/doc/user/ant.xml +++ b/doc/user/ant.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml index 845b9e6..07d5397 100644 --- a/doc/user/build-install.xml +++ b/doc/user/build-install.xml @@ -26,7 +26,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -90,9 +90,8 @@ <title>Installing Python</title> <para> - Because &SCons; is written in Python, - you must obviously have Python installed on your system + you need to have Python installed on your system to use &SCons;. Before you try to install Python, you should check to see if Python is already @@ -102,27 +101,25 @@ or <userinput>python --version</userinput> at your system's command-line prompt. - + For Linux/Unix/MacOS/BSD type systems this looks like: </para> <screen> $ <userinput>python -V</userinput> -Python 2.5.1 +Python 3.7.1 </screen> <para> - - And on a Windows system with Python installed: - + In a cmd shell or PowerShell on a Windows system + (note PoweShell needs it spelled "python.exe" rather than "python"): </para> <screen> C:\><userinput>python -V</userinput> -Python 2.5.1 +Python 3.7.1 </screen> <para> - If Python is not installed on your system, you will see an error message stating something like "command not found" @@ -132,254 +129,70 @@ Python 2.5.1 (on Windows). In that case, you need to install Python before you can install &SCons;. - </para> <para> - The standard location for information about downloading and installing Python is <ulink url="http://www.python.org/download/">http://www.python.org/download/</ulink>. - See that page for information about - how to download and install Python on your system. - + See that page and associated links to get started. </para> <para> + For Linux systems, Python is + almost certainly available as a supported package, possibly + installed by default; this is often preferred to installing + by other means, and is easier than installing from source code. + Many such systems have separate packages for + Python 2 and Python 3. Building from source may still be a + useful option if you need a version that is not offered by + the distribution you are using. + </para> - &SCons; will work with any 2.x version of Python from 2.7 on; - 3.0 and later are not yet supported. + <para> + &SCons; will work with Python 2.7.x or with Python 3.5 or later. If you need to install Python and have a choice, - we recommend using the most recent 2.x Python version available. + we recommend using the most recent Python version available. Newer Pythons have significant improvements that help speed up the performance of &SCons;. - </para> </section> <section> - <title>Installing &SCons; From Pre-Built Packages</title> + <title>Installing &SCons;</title> <para> - - &SCons; comes pre-packaged for installation on a number of systems, - including Linux and Windows systems. - You do not need to read this entire section, - you should need to read only the section - appropriate to the type of system you're running on. - + The canonical way to install &SCons; is from the Python Package + Index (PyPi): </para> - <section> - <title>Installing &SCons; on Red Hat (and Other RPM-based) Linux Systems</title> - - <para> - - &SCons; comes in RPM (Red Hat Package Manager) format, - pre-built and ready to install on Red Hat Linux, - Fedora, - or any other Linux distribution that uses RPM. - Your distribution may - already have an &SCons; RPM built specifically for it; - many do, including SUSE, Mandrake and Fedora. - You can check for the availability of an &SCons; RPM - on your distribution's download servers, - or by consulting an RPM search site like - <ulink url="http://www.rpmfind.net/">http://www.rpmfind.net/</ulink> or - <ulink url="http://rpm.pbone.net/">http://rpm.pbone.net/</ulink>. - - </para> - - <para> - - If your distribution supports installation via - <application>yum</application>, - you should be able to install &SCons; by running: - - </para> - - <screen> -# <userinput>yum install scons</userinput> - </screen> - - <para> - - If your Linux distribution does not already have - a specific &SCons; RPM file, - you can download and install from the - generic RPM provided by the &SCons; project. - This will install the - SCons script(s) in <filename>/usr/bin</filename>, - and the SCons library modules in - <filename>/usr/lib/scons</filename>. - - </para> - - <para> - - To install from the command line, simply download the - appropriate <filename>.rpm</filename> file, - and then run: - - </para> - - <screen> -# <userinput>rpm -Uvh scons-&buildversion;-1.noarch.rpm</userinput> - </screen> - - <para> - - Or, you can use a graphical RPM package manager. - See your package manager application's documentation - for specific instructions about - how to use it to install a downloaded RPM. - - </para> - - </section> - - <section> - <title>Installing &SCons; on Debian Linux Systems</title> - - <para> - - Debian Linux systems use a different package management - format that also makes it very easy to install &SCons;. - - </para> - - <para> - - If your system is connected to the Internet, - you can install the latest official Debian package - by running: - - </para> - - <screen> -# <userinput>apt-get install scons</userinput> - </screen> - - <!-- - - <para> - - Alternatively, - you can download the Debian package built - by the &SCons; project - and install it manually by running: - - </para> - - <screen> -# <userinput>db-XXX scons-*.deb</userinput> - </screen> - - --> - - </section> - - <section> - <title>Installing &SCons; on Windows Systems</title> - - <para> - - &SCons; provides a Windows installer - that makes installation extremely easy. - Download the <filename>scons-&buildversion;.win32.exe</filename> - file from the &SCons; download page at - <ulink url="http://scons.org/pages/download.html">http://scons.org/pages/download.html</ulink>. - Then all you need to do is execute the file - (usually by clicking on its icon in Windows Explorer). - These will take you through a small - sequence of windows that will install - &SCons; on your system. - - <!-- - Things are a little more complicated - if you are using the Cygwin version of Python. - This is because Cygwin - tries to make a Windows system look more - POSIX-like (or UNIX-like or Linux-like, if you prefer) - by having the Cygwin utilities, - including Cygwin Python, - interpret file name arguments on the command line - using the forward-slash (<filename>/</filename>) - as the directory separator, - instead of the normal Windows behavior of the - backslash (<filename>\</filename>) as the directory separator. - --> - - </para> - - <!-- - - <section> - <title>Installing &SCons; on Windows Systems Without Cygwin Python</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Installing &SCons; on Windows Systems With Cygwin Python</title> - - <para> - - XXX - - </para> - - </section> - - --> - - <!-- - - XXX - don't have the kinks worked out on how to - get these to display properly in all formats, - so comment them out for now. - - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center"> - </imageobject> - </mediaobject> - </screenshot> - - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center"> - </imageobject> - </mediaobject> - </screenshot> - - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center"> - </imageobject> - </mediaobject> - </screenshot> + <screen> +% <userinput>python -m pip install scons</userinput> + </screen> - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center"> - </imageobject> - </mediaobject> - </screenshot> + <para> + If you prefer not to install to the Python system location, + or do not have privileges to do so, you can add a flag to + install to a location specific to your own account: + </para> - --> + <screen> +% <userinput>python -m pip install --user scons</userinput> + </screen> - </section> + <para> + &SCons; comes pre-packaged for installation on many Linux systems + Check your package installation system + to see if there is an &SCons; package available. + Many people prefer to install distribution-native packages if available, + as they provide a central point for management and updating. + Some distributions have two &SCons; packages available, one which + uses Python 2 and one which uses Python 3. If you need a specific + version of &SCons; that is different from the package available, + <filename>pip</filename> has a version option or you can follow + the instructions in the next section. + </para> </section> @@ -387,25 +200,21 @@ Python 2.5.1 <title>Building and Installing &SCons; on Any System</title> <para> - If a pre-built &SCons; package is not available for your system, + and installing using <filename>pip</filename> is not suitable, then you can still easily build and install &SCons; using the native Python <filename>distutils</filename> package. - </para> <para> - The first step is to download either the <filename>scons-&buildversion;.tar.gz</filename> or <filename>scons-&buildversion;.zip</filename>, which are available from the SCons download page at <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>. - </para> <para> - Unpack the archive you downloaded, using a utility like <application>tar</application> on Linux or UNIX, @@ -415,7 +224,6 @@ Python 2.5.1 usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: - </para> <screen> @@ -429,11 +237,11 @@ Python 2.5.1 install the &scons; script in the python which is used to run the setup.py's scripts directory (<filename>/usr/local/bin</filename> or - <filename>C:\Python25\Scripts</filename>), + <filename>C:\Python27\Scripts</filename>), and will install the &SCons; build engine in the corresponding library directory for the python used (<filename>/usr/local/lib/scons</filename> or - <filename>C:\Python25\scons</filename>). + <filename>C:\Python27\scons</filename>). Because these are system directories, you may need root (on Linux or UNIX) or Administrator (on Windows) privileges to install &SCons; like this. @@ -489,7 +297,7 @@ Python 2.5.1 in the <filename>/usr/lib/scons-&buildversion;</filename> or - <filename>C:\Python25\scons-&buildversion;</filename> + <filename>C:\Python27\scons-&buildversion;</filename> directory, for example. </para> diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml index d64b63d..f059bca 100644 --- a/doc/user/builders-built-in.xml +++ b/doc/user/builders-built-in.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 8fa26f6..ccffaf0 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index d26c4c6..c36d468 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -812,7 +812,7 @@ env.Foo('file') <scons_example name="builderswriting_MY_EMITTER"> <file name="SConstruct" printme="1"> -bld = Builder(action = 'my_command $SOURCES > $TARGET', +bld = Builder(action = './my_command $SOURCES > $TARGET', suffix = '.foo', src_suffix = '.input', emitter = '$MY_EMITTER') @@ -826,9 +826,6 @@ env2 = Environment(BUILDERS = {'Foo' : bld}, MY_EMITTER = modify2) env1.Foo('file1') env2.Foo('file2') -import os -env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() -env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() </file> <file name="file1.input"> file1.input @@ -848,23 +845,6 @@ cat </scons_example> - <sconstruct> -bld = Builder(action = 'my_command $SOURCES > $TARGET', - suffix = '.foo', - src_suffix = '.input', - emitter = '$MY_EMITTER') -def modify1(target, source, env): - return target, source + ['modify1.in'] -def modify2(target, source, env): - return target, source + ['modify2.in'] -env1 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify1) -env2 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify2) -env1.Foo('file1') -env2.Foo('file2') - </sconstruct> - <para> In this example, the <filename>modify1.in</filename> diff --git a/doc/user/builders.xml b/doc/user/builders.xml index c1af202..873d677 100644 --- a/doc/user/builders.xml +++ b/doc/user/builders.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/caching.xml b/doc/user/caching.xml index db2a469..bf070f9 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/chtml.xsl b/doc/user/chtml.xsl index dafc044..a7b968c 100644 --- a/doc/user/chtml.xsl +++ b/doc/user/chtml.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?>
<!--
- Copyright (c) 2001 - 2017 The SCons Foundation
+ Copyright (c) 2001 - 2019 The SCons Foundation
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 21c17c1..bb1d32b 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -317,7 +317,7 @@ if not GetOption('help'): import os num_cpu = int(os.environ.get('NUM_CPU', 2)) SetOption('num_jobs', num_cpu) -print("running with -j", GetOption('num_jobs')) +print("running with -j %s"%GetOption('num_jobs')) </file> <file name="foo.in"> foo.in @@ -1863,7 +1863,7 @@ env = Environment(variables = vars, CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) unknown = vars.UnknownVariables() if unknown: - print("Unknown variables:", unknown.keys()) + print("Unknown variables: %s"%unknown.keys()) Exit(1) env.Program('foo.c') </file> @@ -1987,17 +1987,16 @@ foo.c <para> - One of the most basic things you can control - is which targets &SCons; will build by default--that is, + You can control + which targets &SCons; will build by default - that is, when there are no targets specified on the command line. As mentioned previously, &SCons; will normally build every target - in or below the current directory - by default--that is, when you don't + in or below the current directory unless you explicitly specify one or more targets on the command line. Sometimes, however, you may want - to specify explicitly that only + to specify that only certain programs, or programs in certain directories, should be built by default. You do this with the &Default; function: @@ -2193,16 +2192,16 @@ prog2.c <para> &SCons; supports a &DEFAULT_TARGETS; variable - that lets you get at the current list of default targets. + that lets you get at the current list of default targets + specified by calls to the &Default; function or method. The &DEFAULT_TARGETS; variable has two important differences from the &COMMAND_LINE_TARGETS; variable. First, the &DEFAULT_TARGETS; variable is a list of internal &SCons; nodes, so you need to convert the list elements to strings if you want to print them or look for a specific target name. - Fortunately, you can do this easily - by using the Python <function>map</function> function - to run the list through <function>str</function>: + You can do this easily by calling the <function>str</function> + on the elements in a list comprehension: </para> @@ -2210,7 +2209,7 @@ prog2.c <file name="SConstruct" printme="1"> prog1 = Program('prog1.c') Default(prog1) -print("DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)) +print("DEFAULT_TARGETS is %s" % [str(t) for t in DEFAULT_TARGETS]) </file> <file name="prog1.c"> prog1.c @@ -2234,7 +2233,7 @@ prog1.c <para> Second, - the contents of the &DEFAULT_TARGETS; list change + the contents of the &DEFAULT_TARGETS; list changes in response to calls to the &Default; function, as you can see from the following &SConstruct; file: @@ -2244,10 +2243,10 @@ prog1.c <file name="SConstruct" printme="1"> prog1 = Program('prog1.c') Default(prog1) -print("DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)) +print("DEFAULT_TARGETS is now %s" % [str(t) for t in DEFAULT_TARGETS]) prog2 = Program('prog2.c') Default(prog2) -print("DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)) +print("DEFAULT_TARGETS is now %s" % [str(t) for t in DEFAULT_TARGETS]) </file> <file name="prog1.c"> prog1.c @@ -2338,7 +2337,7 @@ else: prog1 = Program('prog1.c') Program('prog2.c') Default(prog1) -print("BUILD_TARGETS is", map(str, BUILD_TARGETS)) +print ("BUILD_TARGETS is %s" % [str(t) for t in BUILD_TARGETS]) </file> <file name="prog1.c"> prog1.c @@ -2352,7 +2351,9 @@ prog2.c Notice how the value of &BUILD_TARGETS; changes depending on whether a target is - specified on the command line: + specified on the command line - &BUILD_TARGETS; + takes from &DEFAULT_TARGETS; + only if there are no &COMMAND_LINE_TARGETS;: </para> diff --git a/doc/user/copyright.xml b/doc/user/copyright.xml index 6971581..cc9acac 100644 --- a/doc/user/copyright.xml +++ b/doc/user/copyright.xml @@ -1,44 +1,43 @@ <?xml version='1.0'?> <!DOCTYPE sconsdoc [ - <!ENTITY % scons SYSTEM "../scons.mod"> - %scons; -]> + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + ]> <legalnotice 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"> -<!-- + <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 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: + 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 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. + 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. ---> + --> -<blockquote> - <para> + <blockquote> + <para> + SCons User's Guide Copyright (c) 2004-2019 Steven Knight + </para> + </blockquote> - SCons User's Guide Copyright (c) 2004, 2005, 2006, 2007 Steven Knight - - </para> -</blockquote> </legalnotice> diff --git a/doc/user/depends.xml b/doc/user/depends.xml index 29a79a5..bb0a142 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -517,8 +517,8 @@ cc -o hello hello.o <scons_example name="depends_function"> <file name="SConstruct" printme="1"> Program('hello.c') -def decide_if_changed(dependency, target, prev_ni): - if self.get_timestamp() != prev_ni.timestamp: +def decide_if_changed(dependency, target, prev_ni, repo_node=None): + if dependency.get_timestamp() != prev_ni.timestamp: dep = str(dependency) tgt = str(target) if specific_part_of_file_has_changed(dep, tgt): @@ -561,6 +561,13 @@ int main() { printf("Hello, world!\n"); } </para> + <para> + The fourth argument <varname>repo_node</varname>, + is the &Node; to use if it is not None when comparing &BuildInfo;. + This is typically only set when the target node only exists in a + &Repository; + </para> + <variablelist> <varlistentry> @@ -571,7 +578,7 @@ int main() { printf("Hello, world!\n"); } The <emphasis>content signature</emphasis>, or MD5 checksum, of the contents of the <varname>dependency</varname> - file the list time the ⌖ was built. + file the last time the ⌖ was built. </para> </listitem> @@ -583,7 +590,7 @@ int main() { printf("Hello, world!\n"); } <listitem> <para> The size in bytes of the <varname>dependency</varname> - file the list time the target was built. + file the last time the target was built. </para> </listitem> @@ -595,7 +602,7 @@ int main() { printf("Hello, world!\n"); } <listitem> <para> The modification time of the <varname>dependency</varname> - file the list time the ⌖ was built. + file the last time the ⌖ was built. </para> </listitem> @@ -637,7 +644,7 @@ int main() { printf("Hello, world!\n"); } <sconstruct> env = Environment() -def config_file_decider(dependency, target, prev_ni): +def config_file_decider(dependency, target, prev_ni, repo_node=None): import os.path # We always have to init the .csig value... diff --git a/doc/user/environments.xml b/doc/user/environments.xml index ea5d472..ede9bc3 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -385,9 +385,9 @@ environment, of directory names, suffixes, etc. <para> A &consenv; - is a distinct object creating within + is a distinct object created within a &SConscript; file and - and which contains values that + which contains values that affect how &SCons; decides what action to use to build a target, and even to define which targets @@ -627,7 +627,7 @@ int main() { } <scons_example name="environments_ex6"> <file name="SConstruct" printme="1"> env = Environment() -print("CC is:", env['CC']) +print("CC is: %s"%env['CC']) </file> </scons_example> @@ -721,7 +721,7 @@ for item in sorted(env.Dictionary().items()): <sconstruct> env = Environment() -print("CC is:", env.subst('$CC')) +print("CC is: %s"%env.subst('$CC')) </sconstruct> <para> @@ -738,7 +738,7 @@ print("CC is:", env.subst('$CC')) <sconstruct> env = Environment(CCFLAGS = '-DFOO') -print("CCCOM is:", env['CCCOM']) +print("CCCOM is: %s"%env['CCCOM']) </sconstruct> <para> @@ -764,7 +764,7 @@ scons: `.' is up to date. <sconstruct> env = Environment(CCFLAGS = '-DFOO') -print("CCCOM is:", env.subst('$CCCOM')) +print("CCCOM is: %s"%env.subst('$CCCOM')) </sconstruct> <para> @@ -806,7 +806,7 @@ scons: `.' is up to date. <scons_example name="environments_missing1"> <file name="SConstruct" printme="1"> env = Environment() -print("value is:", env.subst( '->$MISSING<-' )) +print("value is: %s"%env.subst( '->$MISSING<-' )) </file> </scons_example> @@ -834,7 +834,7 @@ print("value is:", env.subst( '->$MISSING<-' )) <file name="SConstruct" printme="1"> AllowSubstExceptions() env = Environment() -print("value is:", env.subst( '->$MISSING<-' )) +print("value is: %s"%env.subst( '->$MISSING<-' )) </file> </scons_example> @@ -854,7 +854,7 @@ print("value is:", env.subst( '->$MISSING<-' )) <file name="SConstruct" printme="1"> AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) env = Environment() -print("value is:", env.subst( '->${1 / 0}<-' )) +print("value is: %s"%env.subst( '->${1 / 0}<-' )) </file> </scons_example> @@ -1216,7 +1216,7 @@ int main() { } <file name="SConstruct" printme="1"> env = Environment() env.Replace(NEW_VARIABLE = 'xyzzy') -print("NEW_VARIABLE =", env['NEW_VARIABLE']) +print("NEW_VARIABLE = %s"%env['NEW_VARIABLE']) </file> </scons_example> @@ -1251,11 +1251,11 @@ print("NEW_VARIABLE =", env['NEW_VARIABLE']) <scons_example name="environments_Replace2"> <file name="SConstruct" printme="1"> env = Environment(CCFLAGS = '-DDEFINE1') -print("CCFLAGS =", env['CCFLAGS']) +print("CCFLAGS = %s"%env['CCFLAGS']) env.Program('foo.c') env.Replace(CCFLAGS = '-DDEFINE2') -print("CCFLAGS =", env['CCFLAGS']) +print("CCFLAGS = %s"%env['CCFLAGS']) env.Program('bar.c') </file> <file name="foo.c"> @@ -1375,7 +1375,7 @@ int main() { } <file name="SConstruct" printme="1"> env = Environment() env.Append(NEW_VARIABLE = 'added') -print("NEW_VARIABLE =", env['NEW_VARIABLE']) +print("NEW_VARIABLE = %s"%env['NEW_VARIABLE']) </file> </scons_example> @@ -1475,7 +1475,7 @@ int main() { } <file name="SConstruct" printme="1"> env = Environment() env.Prepend(NEW_VARIABLE = 'added') -print("NEW_VARIABLE =", env['NEW_VARIABLE']) +print("NEW_VARIABLE = %s"%env['NEW_VARIABLE']) </file> </scons_example> @@ -1630,7 +1630,7 @@ env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin' But doing so makes your &SConscript; file less portable, (although in this case that may not be a huge concern - since the directories you list are likley system-specific, anyway). + since the directories you list are likely system-specific, anyway). </para> diff --git a/doc/user/epub.xsl b/doc/user/epub.xsl index fc95c60..818a874 100644 --- a/doc/user/epub.xsl +++ b/doc/user/epub.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?>
<!--
- Copyright (c) 2001 - 2017 The SCons Foundation
+ Copyright (c) 2001 - 2019 The SCons Foundation
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
diff --git a/doc/user/errors.xml b/doc/user/errors.xml index 78b4f39..e7e611e 100644 --- a/doc/user/errors.xml +++ b/doc/user/errors.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/example.xml b/doc/user/example.xml index b1453ab..4787595 100644 --- a/doc/user/example.xml +++ b/doc/user/example.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/factories.xml b/doc/user/factories.xml index 916c269..43e417b 100644 --- a/doc/user/factories.xml +++ b/doc/user/factories.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/file-removal.xml b/doc/user/file-removal.xml index bc2d89b..fe38cf7 100644 --- a/doc/user/file-removal.xml +++ b/doc/user/file-removal.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/functions.xml b/doc/user/functions.xml index 6093395..bebc7bf 100644 --- a/doc/user/functions.xml +++ b/doc/user/functions.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/gettext.xml b/doc/user/gettext.xml index 8daf5f9..36f0419 100644 --- a/doc/user/gettext.xml +++ b/doc/user/gettext.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index f65a128..dc07e87 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/html.xsl b/doc/user/html.xsl index 2df2fee..5ff8e53 100644 --- a/doc/user/html.xsl +++ b/doc/user/html.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?>
<!--
- Copyright (c) 2001 - 2017 The SCons Foundation
+ Copyright (c) 2001 - 2019 The SCons Foundation
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
diff --git a/doc/user/install.xml b/doc/user/install.xml index 7024320..b3cb9dd 100644 --- a/doc/user/install.xml +++ b/doc/user/install.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/java.xml b/doc/user/java.xml index 73afbc7..19b51e8 100644 --- a/doc/user/java.xml +++ b/doc/user/java.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index c17bdae..e8ff44a 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -2,7 +2,7 @@ <!DOCTYPE sconsdoc [ <!ENTITY % scons SYSTEM "../scons.mod"> %scons; - + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> %builders-mod; <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -257,7 +257,7 @@ Program('program', Glob('*.c')) (see <xref linkend="chap-variants"></xref>, below) and repositories (see <xref linkend="chap-repositories"></xref>, below), - excluding some files + excluding some files and returning strings rather than Nodes. </para> @@ -311,7 +311,7 @@ Program('hello', ['hello.c']) </para> <important> - + <para> Although &SCons; functions @@ -359,7 +359,7 @@ Program('program2', common_sources + ['program2.c']) <para> One drawback to the use of a Python list - for source files is that + for source files is that each file name must be enclosed in quotes (either single quotes or double quotes). This can get cumbersome and difficult to read @@ -644,4 +644,63 @@ Program('bar', bar_files) </section> + <section> + <title>Overriding construction variables when calling a Builder</title> + + <para> + + It is possible to override or add construction variables + when calling a builder method by passing additional keyword arguments. + These overridden or added variables will only be in effect when + building the target, so they will not affect other parts of the build. + For example, if you want to add additional libraries for just one program: + + </para> + + <programlisting> +env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) + </programlisting> + + <para> + + or generate a shared library with a non-standard suffix: + + </para> + + <programlisting> +env.SharedLibrary('word', 'word.cpp', + SHLIBSUFFIX='.ocx', + LIBSUFFIXES=['.ocx']) + </programlisting> + + <para> + + It is also possible to use the <literal>parse_flags</literal> + keyword argument in an override to merge command-line + style arguments into the appropriate construction + variables (see &f-link-env-MergeFlags;). + + </para> + + <para> + + This example adds 'include' to &cv-link-CPPPATH;, + 'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;. + + </para> + + <programlisting> +env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') + </programlisting> + + <para> + + Within the call to the builder action the environment is not cloned, + instead an OverrideEnvironment() is created which is more + light weight than a whole Environment() + + </para> + + </section> + </chapter> diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml index b905923..c6b8069 100644 --- a/doc/user/libraries.xml +++ b/doc/user/libraries.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/main.xml b/doc/user/main.xml index ad2ffe8..01470cc 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -1,7 +1,7 @@ <?xml version="1.0"?> <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -74,10 +74,10 @@ <corpauthor>Steven Knight and the SCons Development Team</corpauthor> - <pubdate>2004 - 2017</pubdate> + <pubdate>2004 - 2019</pubdate> <copyright> - <year>2004 - 2017</year> + <year>2004 - 2019</year> <holder>The SCons Foundation</holder> </copyright> diff --git a/doc/user/make.xml b/doc/user/make.xml index 4f1199d..ac6db2b 100644 --- a/doc/user/make.xml +++ b/doc/user/make.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml index 36bb061..d802125 100644 --- a/doc/user/mergeflags.xml +++ b/doc/user/mergeflags.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/misc.xml b/doc/user/misc.xml index ed96625..5ade6d3 100644 --- a/doc/user/misc.xml +++ b/doc/user/misc.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -268,9 +268,9 @@ hello.c <scons_example name="misc_FindFile1a"> <file name="SConstruct" printme="1"> # one directory -print(FindFile('missing', '.')) +print("%s"%FindFile('missing', '.')) t = FindFile('exists', '.') -print(t.__class__, t) +print("%s %s"%(t.__class__, t)) </file> <file name="exists"> exists @@ -287,7 +287,7 @@ print(t.__class__, t) includes = [ '.', 'include', 'src/include'] headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] for hdr in headers: - print('%-12s' % ('%s:' % hdr), FindFile(hdr, includes)) + print('%-12s: %s'%(hdr, FindFile(hdr, includes))) </file> <file name="config.h"> exists @@ -625,4 +625,53 @@ env.Command('directory_build_info', </section> + <section> + <title>Virtual environments (virtualenvs)</title> + + <para> + + Virtualenv is a tool to create isolated Python environments. + A python application (such as SCons) may be executed within + an activated virtualenv. The activation of virtualenv modifies + current environment by defining some virtualenv-specific variables + and modifying search PATH, such that executables installed within + virtualenv's home directory are preferred over the ones installed + outside of it. + + </para> + + <para> + + Normally, SCons uses hard-coded PATH when searching for external + executables, so it always picks-up executables from these pre-defined + locations. This applies also to python interpreter, which is invoked + by some custom SCons tools or test suites. This means, when running + SCons in a virtualenv, an eventual invocation of python interpreter from + SCons script will most probably jump out of virtualenv and execute + python executable found in hard-coded SCons PATH, not the one which is + executing SCons. Some users may consider this as an inconsistency. + + </para> + + <para> + This issue may be overcome by using <literal>--enable-virtualenv</literal> + option. The option automatically imports virtualenv-related environment + variables to all created construction environment <literal>env['ENV']</literal>, + and modifies SCons PATH appropriately to prefer virtualenv's executables. + Setting environment variable <literal>SCONS_ENABLE_VIRTUALENV=1</literal> + will have same effect. If virtualenv support is enabled system-vide + by the environment variable, it may be suppressed with + <literal>--ignore-virtualenv</literal> option. + </para> + + <para> + Inside of SConscript, a global function <literal>Virtualenv</literal> is + available. It returns a path to virtualenv's home directory, or + <literal>None</literal> if SCons is not running from virtualenv. Note, + that this function returns a path even if SCons is run from an + unactivated virtualenv. + </para> + + </section> + </chapter> diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml index e627bba..da1d158 100644 --- a/doc/user/nodes.xml +++ b/doc/user/nodes.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -265,8 +265,8 @@ xyzzy = Entry('xyzzy') <file name="SConstruct" printme="1"> object_list = Object('hello.c') program_list = Program(object_list) -print("The object file is:", object_list[0]) -print("The program file is:", program_list[0]) +print("The object file is: %s"%object_list[0]) +print("The program file is: %s"%program_list[0]) </file> <file name="hello.c"> int main() { printf("Hello, world!\n"); } @@ -334,7 +334,7 @@ import os.path program_list = Program('hello.c') program_name = str(program_list[0]) if not os.path.exists(program_name): - print(program_name, "does not exist!") + print("%s does not exist!"%program_name) </file> <file name="hello.c"> int main() { printf("Hello, world!\n"); } diff --git a/doc/user/output.xml b/doc/user/output.xml index cf5776d..db16393 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml index 2367857..096d236 100644 --- a/doc/user/parseconfig.xml +++ b/doc/user/parseconfig.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml index 52cbdd7..26313ce 100644 --- a/doc/user/parseflags.xml +++ b/doc/user/parseflags.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -57,7 +57,7 @@ &SCons; construction environments have a &ParseFlags; method that takes a set of typical command-line options - and distrbutes them into the appropriate construction variables. + and distributes them into the appropriate construction variables. Historically, it was created to support the &ParseConfig; method, so it focuses on options used by the GNU Compiler Collection (GCC) for the C and C++ toolchains. diff --git a/doc/user/pdf.xsl b/doc/user/pdf.xsl index 4a81d56..0f797d3 100644 --- a/doc/user/pdf.xsl +++ b/doc/user/pdf.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?>
<!--
- Copyright (c) 2001 - 2017 The SCons Foundation
+ Copyright (c) 2001 - 2019 The SCons Foundation
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
diff --git a/doc/user/preface.xml b/doc/user/preface.xml index 443bf38..62cd47b 100644 --- a/doc/user/preface.xml +++ b/doc/user/preface.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/python.xml b/doc/user/python.xml index 82443f9..177cb5c 100644 --- a/doc/user/python.xml +++ b/doc/user/python.xml @@ -22,7 +22,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml index 6aae2e3..189a8cd 100644 --- a/doc/user/repositories.xml +++ b/doc/user/repositories.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/run.xml b/doc/user/run.xml index af28868..c9c5c6a 100644 --- a/doc/user/run.xml +++ b/doc/user/run.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 9e3ce99..e1b2249 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -410,6 +410,59 @@ kscan = Scanner(function = kfile_scan, This is important since many files get scanned in a typical build. </para> - </section> + </section> + + <section> + <title>Using scanners with Builders</title> + + <para> + + One approach for the use of scanners is with builders. + There are two optional parameters we can use with a builder + <literal>source_scanner</literal> and <literal>target_scanner</literal>. + + </para> + + <scons_example name="scanners_builders"> + <file name="SConstruct" printme="1"> + +def kfile_scan(node, env, path, arg): + contents = node.get_text_contents() + return env.File(include_re.findall(contents)) + +kscan = Scanner(function = kfile_scan, + skeys = ['.k'], + path_function = FindPathDirs('KPATH')) + +def build_function(target, source, env): + # Code to build "target" from "source" + return None + +bld = Builder(action = build_function, + suffix = '.foo', + source_scanner = kscan + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file') + + </file> + </scons_example> + + <para> + + An emitter function can modify the list of sources or targets + 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 be rebuilt (if any of + the files sourced by the scanner have changed for example). + + </para> + </section> </chapter> diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml index d0537cb..b8a903d 100644 --- a/doc/user/sconf.xml +++ b/doc/user/sconf.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/scons_title.xsl b/doc/user/scons_title.xsl index 130c6a5..21c56da 100644 --- a/doc/user/scons_title.xsl +++ b/doc/user/scons_title.xsl @@ -1,7 +1,7 @@ <?xml version="1.0"?> <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/separate.xml b/doc/user/separate.xml index bac7e4d..26500d6 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/sideeffect.xml b/doc/user/sideeffect.xml index 16dbd08..e630e4f 100644 --- a/doc/user/sideeffect.xml +++ b/doc/user/sideeffect.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/simple.xml b/doc/user/simple.xml index af7868b..43121c0 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/sourcecode.xml b/doc/user/sourcecode.xml index b3c51e4..f7cd492 100644 --- a/doc/user/sourcecode.xml +++ b/doc/user/sourcecode.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml index 248dcd3..32e575a 100644 --- a/doc/user/tasks.xml +++ b/doc/user/tasks.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/tools.xml b/doc/user/tools.xml index 0c56603..bc9f6b9 100644 --- a/doc/user/tools.xml +++ b/doc/user/tools.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index aecac57..606c727 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/variables.xml b/doc/user/variables.xml index e0d1d32..b7b8d4e 100644 --- a/doc/user/variables.xml +++ b/doc/user/variables.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/variants.xml b/doc/user/variants.xml index 1944201..8b78c2b 100644 --- a/doc/user/variants.xml +++ b/doc/user/variants.xml @@ -21,7 +21,7 @@ <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the |