summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorSteven Knight <knight@baldmt.com>2004-02-17 04:58:13 (GMT)
committerSteven Knight <knight@baldmt.com>2004-02-17 04:58:13 (GMT)
commit66f555c21410aea4eead4fbd4710fddd15bb1ed1 (patch)
tree37d4b73ca811ea8c5b543c0048d6527694a94a14 /doc
parent744c41b71bd77daabd7ce8d7768a2217286d6911 (diff)
downloadSCons-66f555c21410aea4eead4fbd4710fddd15bb1ed1.zip
SCons-66f555c21410aea4eead4fbd4710fddd15bb1ed1.tar.gz
SCons-66f555c21410aea4eead4fbd4710fddd15bb1ed1.tar.bz2
Add a common tasks appendix to the user's guide. (Anthony Roach)
Diffstat (limited to 'doc')
-rw-r--r--doc/user/MANIFEST1
-rw-r--r--doc/user/main.in6
-rw-r--r--doc/user/main.sgml6
-rw-r--r--doc/user/tasks.in109
-rw-r--r--doc/user/tasks.sgml109
5 files changed, 231 insertions, 0 deletions
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index c9af4a4..9e3f7bf 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -28,5 +28,6 @@ scanners.sgml
separate.sgml
simple.sgml
sourcecode.sgml
+tasks.sgml
troubleshoot.sgml
variants.sgml
diff --git a/doc/user/main.in b/doc/user/main.in
index 1a017d3..0fcf95c 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -60,6 +60,7 @@
<!ENTITY separate SYSTEM "separate.sgml">
<!ENTITY simple SYSTEM "simple.sgml">
<!ENTITY sourcecode SYSTEM "sourcecode.sgml">
+ <!ENTITY tasks SYSTEM "tasks.sgml">
<!ENTITY troubleshoot SYSTEM "troubleshoot.sgml">
<!ENTITY variants SYSTEM "variants.sgml">
@@ -242,6 +243,11 @@
Tools()
-->
+ <appendix id="app-tasks">
+ <title>Handling Common Tasks</title>
+ &tasks;
+ </appendix>
+
<!--
<appendix id="app-example">
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
index 1a017d3..0fcf95c 100644
--- a/doc/user/main.sgml
+++ b/doc/user/main.sgml
@@ -60,6 +60,7 @@
<!ENTITY separate SYSTEM "separate.sgml">
<!ENTITY simple SYSTEM "simple.sgml">
<!ENTITY sourcecode SYSTEM "sourcecode.sgml">
+ <!ENTITY tasks SYSTEM "tasks.sgml">
<!ENTITY troubleshoot SYSTEM "troubleshoot.sgml">
<!ENTITY variants SYSTEM "variants.sgml">
@@ -242,6 +243,11 @@
Tools()
-->
+ <appendix id="app-tasks">
+ <title>Handling Common Tasks</title>
+ &tasks;
+ </appendix>
+
<!--
<appendix id="app-example">
diff --git a/doc/user/tasks.in b/doc/user/tasks.in
new file mode 100644
index 0000000..29299ab
--- /dev/null
+++ b/doc/user/tasks.in
@@ -0,0 +1,109 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003 Steven Knight
+
+ 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 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.
+
+-->
+
+<para>
+There is a common set of simple tasks that many build configurations rely
+on as they become more complex. Most build tools have special
+purpose constructs for performing these tasks, but since &SConscript;
+files are &Python; scripts, you can use more flexible built-in &Python;
+services to perform these tasks. This appendix lists a number of these
+tasks and how to implement them in &Python;.
+</para>
+
+<example>
+<title>Wildcard globbing to create a list of filenames</title>
+<programlisting>
+import glob
+files = glob.glob(wildcard)
+</programlisting>
+</example>
+
+<example>
+<title>Filename extension substitution</title>
+<programlisting>
+import os.path
+filename = os.path.splitext(filename)[0]+extension
+</programlisting>
+</example>
+
+<example>
+<title>Appending a path prefix to a list of filenames</title>
+<programlisting>
+import os.path
+filenames = [os.path.join(prefix, x) for x in filenames]
+</programlisting>
+
+<simpara>or in Python 1.5.2:</simpara>
+
+<programlisting>
+import os.path
+new_filenames = []
+for x in filenames:
+ new_filenames.append(os.path.join(prefix, x))
+</programlisting>
+</example>
+
+<example>
+<title>Substituting a path prefix with another one</title>
+<programlisting>
+if filename.find(old_prefix) == 0:
+ filename = filename.replace(old_prefix, new_prefix)
+</programlisting>
+
+<simpara>or in Python 1.5.2:</simpara>
+
+<programlisting>
+import string
+if string.find(filename, old_prefix) == 0:
+ filename = string.replace(filename, old_prefix, new_prefix)
+</programlisting>
+</example>
+
+<example>
+<title>Filtering a filename list to exclude/retain only a specific set
+of extensions</title>
+<programlisting>
+import os.path
+filenames = [x for x in filenames if os.path.splitext(x)[1] in extensions]
+</programlisting>
+
+<simpara>or in Python 1.5.2:</simpara>
+
+<programlisting>
+import os.path
+new_filenames = []
+for x in filenames:
+ if os.path.splitext(x)[1] in extensions:
+ new_filenames.append(x)
+</programlisting>
+</example>
+
+<example>
+<title>The "backtick function": run a shell command and capture the
+output</title>
+<programlisting>import os
+output = os.popen(command).read()
+</programlisting>
+</example>
diff --git a/doc/user/tasks.sgml b/doc/user/tasks.sgml
new file mode 100644
index 0000000..29299ab
--- /dev/null
+++ b/doc/user/tasks.sgml
@@ -0,0 +1,109 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003 Steven Knight
+
+ 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 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.
+
+-->
+
+<para>
+There is a common set of simple tasks that many build configurations rely
+on as they become more complex. Most build tools have special
+purpose constructs for performing these tasks, but since &SConscript;
+files are &Python; scripts, you can use more flexible built-in &Python;
+services to perform these tasks. This appendix lists a number of these
+tasks and how to implement them in &Python;.
+</para>
+
+<example>
+<title>Wildcard globbing to create a list of filenames</title>
+<programlisting>
+import glob
+files = glob.glob(wildcard)
+</programlisting>
+</example>
+
+<example>
+<title>Filename extension substitution</title>
+<programlisting>
+import os.path
+filename = os.path.splitext(filename)[0]+extension
+</programlisting>
+</example>
+
+<example>
+<title>Appending a path prefix to a list of filenames</title>
+<programlisting>
+import os.path
+filenames = [os.path.join(prefix, x) for x in filenames]
+</programlisting>
+
+<simpara>or in Python 1.5.2:</simpara>
+
+<programlisting>
+import os.path
+new_filenames = []
+for x in filenames:
+ new_filenames.append(os.path.join(prefix, x))
+</programlisting>
+</example>
+
+<example>
+<title>Substituting a path prefix with another one</title>
+<programlisting>
+if filename.find(old_prefix) == 0:
+ filename = filename.replace(old_prefix, new_prefix)
+</programlisting>
+
+<simpara>or in Python 1.5.2:</simpara>
+
+<programlisting>
+import string
+if string.find(filename, old_prefix) == 0:
+ filename = string.replace(filename, old_prefix, new_prefix)
+</programlisting>
+</example>
+
+<example>
+<title>Filtering a filename list to exclude/retain only a specific set
+of extensions</title>
+<programlisting>
+import os.path
+filenames = [x for x in filenames if os.path.splitext(x)[1] in extensions]
+</programlisting>
+
+<simpara>or in Python 1.5.2:</simpara>
+
+<programlisting>
+import os.path
+new_filenames = []
+for x in filenames:
+ if os.path.splitext(x)[1] in extensions:
+ new_filenames.append(x)
+</programlisting>
+</example>
+
+<example>
+<title>The "backtick function": run a shell command and capture the
+output</title>
+<programlisting>import os
+output = os.popen(command).read()
+</programlisting>
+</example>