summaryrefslogtreecommitdiff
path: root/doc/user
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/README2
-rw-r--r--doc/user/SConstruct2
-rw-r--r--doc/user/actions.xml2
-rw-r--r--doc/user/add-method.xml2
-rw-r--r--doc/user/alias.xml2
-rw-r--r--doc/user/ant.xml2
-rw-r--r--doc/user/build-install.xml292
-rw-r--r--doc/user/builders-built-in.xml2
-rw-r--r--doc/user/builders-commands.xml2
-rw-r--r--doc/user/builders-writing.xml24
-rw-r--r--doc/user/builders.xml2
-rw-r--r--doc/user/caching.xml2
-rw-r--r--doc/user/chtml.xsl2
-rw-r--r--doc/user/command-line.xml37
-rw-r--r--doc/user/copyright.xml55
-rw-r--r--doc/user/depends.xml21
-rw-r--r--doc/user/environments.xml32
-rw-r--r--doc/user/epub.xsl2
-rw-r--r--doc/user/errors.xml2
-rw-r--r--doc/user/example.xml2
-rw-r--r--doc/user/factories.xml2
-rw-r--r--doc/user/file-removal.xml2
-rw-r--r--doc/user/functions.xml2
-rw-r--r--doc/user/gettext.xml2
-rw-r--r--doc/user/hierarchy.xml2
-rw-r--r--doc/user/html.xsl2
-rw-r--r--doc/user/install.xml2
-rw-r--r--doc/user/java.xml2
-rw-r--r--doc/user/less-simple.xml69
-rw-r--r--doc/user/libraries.xml2
-rw-r--r--doc/user/main.xml6
-rw-r--r--doc/user/make.xml2
-rw-r--r--doc/user/mergeflags.xml2
-rw-r--r--doc/user/misc.xml57
-rw-r--r--doc/user/nodes.xml8
-rw-r--r--doc/user/output.xml2
-rw-r--r--doc/user/parseconfig.xml2
-rw-r--r--doc/user/parseflags.xml4
-rw-r--r--doc/user/pdf.xsl2
-rw-r--r--doc/user/preface.xml2
-rw-r--r--doc/user/python.xml2
-rw-r--r--doc/user/repositories.xml2
-rw-r--r--doc/user/run.xml2
-rw-r--r--doc/user/scanners.xml57
-rw-r--r--doc/user/sconf.xml2
-rw-r--r--doc/user/scons_title.xsl2
-rw-r--r--doc/user/separate.xml2
-rw-r--r--doc/user/sideeffect.xml2
-rw-r--r--doc/user/simple.xml2
-rw-r--r--doc/user/sourcecode.xml2
-rw-r--r--doc/user/tasks.xml2
-rw-r--r--doc/user/tools.xml2
-rw-r--r--doc/user/troubleshoot.xml2
-rw-r--r--doc/user/variables.xml2
-rw-r--r--doc/user/variants.xml2
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 &gt; $TARGET',
+bld = Builder(action = './my_command $SOURCES &gt; $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 &gt; $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 &target; was built.
+ file the last time the &target; 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 &target; was built.
+ file the last time the &target; 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&lt;-' ))
+print("value is: %s"%env.subst( '->$MISSING&lt;-' ))
</file>
</scons_example>
@@ -834,7 +834,7 @@ print("value is:", env.subst( '->$MISSING&lt;-' ))
<file name="SConstruct" printme="1">
AllowSubstExceptions()
env = Environment()
-print("value is:", env.subst( '->$MISSING&lt;-' ))
+print("value is: %s"%env.subst( '->$MISSING&lt;-' ))
</file>
</scons_example>
@@ -854,7 +854,7 @@ print("value is:", env.subst( '->$MISSING&lt;-' ))
<file name="SConstruct" printme="1">
AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
env = Environment()
-print("value is:", env.subst( '->${1 / 0}&lt;-' ))
+print("value is: %s"%env.subst( '->${1 / 0}&lt;-' ))
</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