From 72c578fd4b0b4a5a43e18594339ac4ff26c376dc Mon Sep 17 00:00:00 2001
From: Luca Falavigna <dktrkranz@debian.org>
Date: Sat, 2 Jan 2010 20:56:27 +0100
Subject: Imported Upstream version 1.2.0.d20091224

---
 doc/user/add-method.xml | 135 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 doc/user/add-method.xml

(limited to 'doc/user/add-method.xml')

diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml
new file mode 100644
index 0000000..761765f
--- /dev/null
+++ b/doc/user/add-method.xml
@@ -0,0 +1,135 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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:
+
+  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>
+
+  The &AddMethod; function is used to add a method
+  to an environment.  It's typically used to add a "pseudo-builder,"
+  a function that looks like a &Builder; but
+  wraps up calls to multiple other &Builder;s
+  or otherwise processes its arguments
+  before calling one or more &Builder;s.
+  In the following example,
+  we want to install the program into the standard
+  <filename>/usr/bin</filename> directory hierarchy,
+  but also copy it into a local <filename>install/bin</filename>
+  directory from which a package might be built:
+
+  </para>
+
+  <programlisting>
+     def install_in_bin_dirs(env, source):
+         """Install source in both bin dirs"""
+         i1 = env.Install("$BIN", source)
+         i2 = env.Install("$LOCALBIN", source)
+         return [i1[0], i2[0]] # Return a list, like a normal builder
+     env = Environment(BIN='/usr/bin', LOCALBIN='#install/bin')
+     env.AddMethod(install_in_bin_dirs, "InstallInBinDirs")
+     env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs     
+  </programlisting>
+
+  <para>
+  This produces the following:
+  </para>
+
+  <screen>
+    % <userinput>scons -Q /</userinput>
+    cc -o hello.o -c hello.c
+    cc -o hello hello.o
+    Install file: "hello" as "/usr/bin/hello"
+    Install file: "hello" as "install/bin/hello"
+  </screen>
+
+  <para>
+
+  As mentioned, a psuedo-builder also provides more flexibility
+  in parsing arguments than you can get with a &Builder;.
+  The next example shows a pseudo-builder with a
+  named argument that modifies the filename, and a separate argument
+  for the resource file (rather than having the builder figure it out
+  by file extension).  This example also demonstrates using the global
+  &AddMethod; function to add a method to the global Environment class,
+  so it will be used in all subsequently created environments.
+
+  </para>
+
+  <programlisting>
+     def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
+         """Build the test program;
+         prepends "test_" to src and target,
+         and puts target into testdir."""
+         srcfile = "test_%s.c" % testfile
+         target = "%s/test_%s" % (testdir, testfile)
+         if env['PLATFORM'] == 'win32':
+             resfile = env.RES(resourcefile)
+             p = env.Program(target, [srcfile, resfile])
+         else:
+             p = env.Program(target, srcfile)
+         return p
+     AddMethod(Environment, BuildTestProg)
+
+     env = Environment()
+     env.BuildTestProg('stuff', resourcefile='res.rc')
+  </programlisting>
+
+  <para>
+  This produces the following on Linux:
+  </para>
+
+  <screen>
+    % <userinput>scons -Q</userinput>
+    cc -o test_stuff.o -c test_stuff.c
+    cc -o tests/test_stuff test_stuff.o
+  </screen>
+
+  <para>
+  And the following on Windows:
+  </para>
+
+  <screen>
+    C:\><userinput>scons -Q</userinput>
+    
+    scons: warning: No installed VCs
+    File "&lt;stdin&gt;", line 67, in __call__
+    
+    scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+    File "&lt;stdin&gt;", line 67, in __call__
+    
+    scons: warning: No installed VCs
+    File "&lt;stdin&gt;", line 67, in __call__
+    
+    scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+    File "&lt;stdin&gt;", line 67, in __call__
+    rc /fores.res res.rc
+    cl /Fotest_stuff.obj /c test_stuff.c /nologo
+    link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res
+  </screen>
+
+  <para>
+  Using &AddMethod; is better than just adding an instance method
+  to a &consenv; because it gets called as a proper method,
+  and because &AddMethod; provides for copying the method
+  to any clones of the &consenv; instance.
+  </para>
-- 
cgit v1.2.3