Merge commit 'upstream/1.2.0.d20091224'

1 files changed, 719 insertions, 0 deletions

diff --git a/doc/user/build-install.in b/doc/user/build-install.in
new file mode 100644
index 0000000..ab289b1
--- /dev/null
+++ b/doc/user/build-install.in
@@ -0,0 +1,719 @@
+<!--
+
+  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>
+
+  This chapter will take you through the basic steps
+  of installing &SCons; on your system,
+  and building &SCons; if you don't have a
+  pre-built package available
+  (or simply prefer the flexibility of building it yourself).
+  Before that, however, this chapter will also describe the basic steps
+  involved in installing Python on your system,
+  in case that is necessary.
+  Fortunately, both &SCons; and Python
+  are very easy to install on almost any system,
+  and Python already comes installed on many systems.
+
+  </para>
+
+  <!--
+
+  <para>
+
+  Lastly, this chapter also contains a section that
+  provides a brief overview of the Python programming language,
+  which is the language used to implement &SCons;,
+  and which forms the basis of the &SCons; configuration files.
+  Becoming familiar with some Python concepts will make it easier
+  to understand many of the examples in this User's Guide.
+  Nevertheless, it <emphasis>is</emphasis> possible
+  to configure simple &SCons; builds without knowing Python,
+  so you can skip this section if you
+  want to dive in and pick up things
+  by example- -or, of course, if you are 
+  already familiar with Python.
+
+  </para>
+
+  -->
+
+  <section>
+  <title>Installing Python</title>
+
+    <para>
+
+    Because &SCons; is written in Python,
+    you must obviously have Python installed on your system
+    to use &SCons;.
+    Before you try to install Python,
+    you should check to see if Python is already
+    available on your system  by typing
+    <userinput>python -V</userinput>
+    (capital 'V')
+    or
+    <userinput>python --version</userinput>
+    at your system's command-line prompt.
+
+    </para>
+
+    <screen>
+       $ <userinput>python -V</userinput>
+       Python 2.5.1
+    </screen>
+
+    <para>
+
+    And on a Windows system with Python installed:
+
+    </para>
+
+    <screen>
+       C:\><userinput>python -V</userinput>
+       Python 2.5.1
+    </screen>
+
+    <para>
+
+    If Python is not installed on your system,
+    you will see an error message
+    stating something like "command not found"
+    (on UNIX or Linux)
+    or "'python' is not recognized
+    as an internal or external command, operable progam or batch file"
+    (on Windows).
+    In that case, you need to install Python
+    before you can install &SCons;.
+
+    </para>
+
+    <para>
+
+    (Note that the <option>-V</option> option
+    was added to Python version 2.0,
+    so if your system only has an earlier version available
+    you may see an
+    <literal>"Unknown option: -V"</literal>
+    error message.)
+
+    </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.
+
+    </para>
+
+    <para>
+
+    &SCons; will work with any version of Python from 1.5.2 or later.
+    If you need to install Python and have a choice,
+    we recommend using the most recent Python 2.5 version available.
+    Python 2.5 has significant improvements
+    that help speed up the performance of &SCons;.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Installing &SCons; From Pre-Built Packages</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.
+
+    </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-1.2.0.d20091224-1.noarch.rpm</userinput>
+      </screen>
+
+      <para>
+
+      Or, you can use a graphical RPM package manager.
+      See your package manager application's documention
+      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-1.2.0.d20091224.win32.exe</filename>
+      file from the &SCons; download page at
+      <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</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>
+
+      <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
+        </imageobject>
+      </mediaobject>
+      </screenshot>
+
+      -->
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Building and Installing &SCons; on Any System</title>
+
+    <para>
+
+    If a pre-built &SCons; package is not available for your system,
+    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-1.2.0.d20091224.tar.gz</filename>
+    or <filename>scons-1.2.0.d20091224.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,
+    or <application>WinZip</application> on Windows.
+    This will create a directory called
+    <filename>scons-1.2.0.d20091224</filename>,
+    usually in your local directory.
+    Then change your working directory to that directory
+    and install &SCons; by executing the following commands:
+
+    </para>
+
+    <screen>
+      # <userinput>cd scons-1.2.0.d20091224</userinput>
+      # <userinput>python setup.py install</userinput>
+    </screen>
+
+    <para>
+
+    This will build &SCons;,
+    install the &scons; script
+    in the default system scripts directory
+    (<filename>/usr/local/bin</filename> or
+    <filename>C:\Python25\Scripts</filename>),
+    and will install the &SCons; build engine
+    in an appropriate stand-alone library directory
+    (<filename>/usr/local/lib/scons</filename> or
+    <filename>C:\Python25\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.
+
+    </para>
+
+    <!--
+
+    <section>
+    <title>Building and Installing &SCons; in the Standard Python Library Directories</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+    </section>
+
+    -->
+
+    <section>
+    <title>Building and Installing Multiple Versions of &SCons; Side-by-Side</title>
+
+      <para>
+
+      The &SCons; <filename>setup.py</filename> script
+      has some extensions that support
+      easy installation of multiple versions of &SCons;
+      in side-by-side locations.
+      This makes it easier to download and
+      experiment with different versions of &SCons;
+      before moving your official build process to a new version,
+      for example.
+
+      </para>
+
+      <para>
+
+      To install &SCons; in a version-specific location,
+      add the <option>--version-lib</option> option
+      when you call <filename>setup.py</filename>:
+
+      </para>
+
+      <screen>
+        # <userinput>python setup.py install --version-lib</userinput>
+      </screen>
+
+      <para>
+
+      This will install the &SCons; build engine
+      in the
+      <filename>/usr/lib/scons-1.2.0.d20091224</filename>
+      or
+      <filename>C:\Python25\scons-1.2.0.d20091224</filename>
+      directory, for example.
+
+      </para>
+
+      <para>
+
+      If you use the <option>--version-lib</option> option
+      the first time you install &SCons;,
+      you do not need to specify it each time you install
+      a new version.
+      The &SCons; <filename>setup.py</filename> script
+      will detect the version-specific directory name(s)
+      and assume you want to install all versions
+      in version-specific directories.
+      You can override that assumption in the future
+      by explicitly specifying the <option>--standalone-lib</option> option.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Installing &SCons; in Other Locations</title>
+
+      <para>
+
+      You can install &SCons; in locations other than
+      the default by specifying the <option>--prefix=</option> option:
+
+      </para>
+
+      <screen>
+        # <userinput>python setup.py install --prefix=/opt/scons</userinput>
+      </screen>
+
+      <para>
+
+      This would
+      install the <application>scons</application> script in
+      <filename>/opt/scons/bin</filename>
+      and the build engine in 
+      <filename>/opt/scons/lib/scons</filename>,
+
+      </para>
+
+      <para>
+
+      Note that you can specify both the <option>--prefix=</option>
+      and the <option>--version-lib</option> options
+      at the same type,
+      in which case <filename>setup.py</filename>
+      will install the build engine
+      in a version-specific directory
+      relative to the specified prefix.
+      Adding <option>--version-lib</option> to the
+      above example would install the build engine in
+      <filename>/opt/scons/lib/scons-1.2.0.d20091224</filename>.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Building and Installing &SCons; Without Administrative Privileges</title>
+
+      <para>
+
+      If you don't have the right privileges to install &SCons;
+      in a system location,
+      simply use the <literal>--prefix=</literal> option
+      to install it in a location of your choosing.
+      For example,
+      to install &SCons; in appropriate locations
+      relative to the user's <literal>$HOME</literal> directory,
+      the &scons; script in
+      <filename>$HOME/bin</filename>
+      and the build engine in 
+      <filename>$HOME/lib/scons</filename>,
+      simply type:
+
+      </para>
+
+      <screen>
+        $ <userinput>python setup.py install --prefix=$HOME</userinput>
+      </screen>
+
+      <para>
+
+      You may, of course, specify any other location you prefer,
+      and may use the <option>--version-lib</option> option
+      if you would like to install version-specific directories
+      relative to the specified prefix.
+
+      </para>
+
+      <para>
+
+      This can also be used to experiment with a newer
+      version of &SCons; than the one installed
+      in your system locations.
+      Of course, the location in which you install the
+      newer version of the &scons; script
+      (<filename>$HOME/bin</filename> in the above example)
+      must be configured in your &PATH; variable
+      before the directory containing
+      the system-installed version
+      of the &scons; script.
+
+      </para>
+
+    </section>
+
+  </section>
+
+  <!--
+
+  <section>
+  <title>Python Basics</title>
+
+    <para>
+
+    This section will provide a brief overview of
+    the Python programming language.
+    Skip this section if you are already familiar with Python
+    (or you're really intent on diving into &SCons;
+    and just picking up things as you go).
+
+    </para>
+
+    <para>
+
+    Python has a lot of good
+    documentation freely available on-line
+    to help you get started.
+    The standard tutorial is available at XXX.
+
+
+    </para>
+
+    <para>
+
+    Python is very easy to pick up.
+
+    </para>
+
+    <para>
+
+    Python variables must be assigned to before they can be referenced.
+
+    </para>
+
+    <para>
+
+    Assignment is like most programming languages:
+
+    x = 1 + 2
+    z = 3 * x
+
+    </para>
+
+    <para>
+
+    Function calls look like most language function calls:
+
+    a = f(g)
+
+    </para>
+
+    <para>
+
+    Define functions like so:
+
+        def func(arg1, arg2):
+            return arg1 * arg 2
+
+    The number of parameters
+
+    </para>
+
+    <para>
+
+    Strings can be enclosed in single quotes or double quotes,
+    backslashes are used to escape characters,
+    triple-quote syntax lets you include quotes and newlines,
+    raw strings begin with 'r'.
+
+    </para>
+
+    <para>
+
+    Lists are enclosed in square brackets,
+    list items are separated by commas.
+    List references use square brackets and integer index values,
+    slice notation lets you select, delete or replace a range.
+
+    </para>
+
+    <para>
+
+    Dictionaries (hashes) are enclosed in curly brackets,
+    : separates keys from values,
+    , separates items.
+    Dictionary values are referenced using square brackets.
+
+    </para>
+
+    <para>
+
+    Access class attributes (including methods) using a '.'.
+
+    </para>
+
+    <para>
+
+    if: statements look like
+
+    elif: statements look like
+
+    else: statements look like
+
+    </para>
+
+    <para>
+
+    for: statements look like
+
+    while: statements look like
+
+    break statements look like
+    
+    continue statements look like
+
+    </para>
+
+    <para>
+
+    pass
+
+    </para>
+
+  </section>
+
+  -->