summaryrefslogtreecommitdiff
path: root/doc/user/build-install.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/build-install.xml')
-rw-r--r--doc/user/build-install.xml719
1 files changed, 719 insertions, 0 deletions
diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml
new file mode 100644
index 0000000..ab289b1
--- /dev/null
+++ b/doc/user/build-install.xml
@@ -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>
+
+ -->