diff options
author | Steven Knight <knight@baldmt.com> | 2004-08-16 13:43:09 (GMT) |
---|---|---|
committer | Steven Knight <knight@baldmt.com> | 2004-08-16 13:43:09 (GMT) |
commit | 74e2a97dc2ed0412ffb1a9c6dc810c1a1c4a4e67 (patch) | |
tree | 82a4927ce94fa90b9798accd2cfdbffb88ab2d51 /doc/user/build-install.sgml | |
parent | 9a0aa47145dbaa02eccac8ba23c498a4e2a3a098 (diff) | |
download | SCons-74e2a97dc2ed0412ffb1a9c6dc810c1a1c4a4e67.zip SCons-74e2a97dc2ed0412ffb1a9c6dc810c1a1c4a4e67.tar.gz SCons-74e2a97dc2ed0412ffb1a9c6dc810c1a1c4a4e67.tar.bz2 |
Branch for documentation changes.
Diffstat (limited to 'doc/user/build-install.sgml')
-rw-r--r-- | doc/user/build-install.sgml | 605 |
1 files changed, 605 insertions, 0 deletions
diff --git a/doc/user/build-install.sgml b/doc/user/build-install.sgml new file mode 100644 index 0000000..164aabe --- /dev/null +++ b/doc/user/build-install.sgml @@ -0,0 +1,605 @@ +<!-- + + __COPYRIGHT__ + + 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</userinput> + at your system's command-line prompt. + You should see something like the following + on a UNIX or Linux system that has Python installed: + + </para> + + <screen> + $ <userinput>python</userinput> + Python 2.2.2 (#1, Feb 24 2003, 19:13:11) + [GCC 3.2.2 20030222 (Red Hat Linux 3.2.2-4)] on linux2 + Type "help", "copyright", "credits" or "license" for more information. + >>> <userinput>^D</userinput> + </screen> + + <para> + + And on a Windows system with Python installed: + + </para> + + <screen> + C:\><userinput>python</userinput> + Python 2.2.2 (#34, Apr 9 2002, 19:34:33) [MSC 32 bit (Intel)] on win32 + Type "help", "copyright", "credits" or "license" for more information. + >>> <userinput>^Z</userinput> + </screen> + + <para> + + The <prompt>>>></prompt> is the input prompt + for the Python interpreter. + The <userinput>^D</userinput> and <userinput>^Z</userinput> + represent the CTRL-D and CTRL-Z characters + that you will need to type to get out of the interpreter + before proceeding to installing &SCons;. + + </para> + + <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> + + 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> + + </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 only need to read 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, + 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 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-0.96-1.noarch.rpm</userinput> + </screen> + + <para> + + Or, you can use a graphical RPM package manager + like <application>gnorpm</application>. + 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-0.95.win32.exe</filename> + file from the &SCons; download page at + <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>. + Then all you need to 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> + + --> + + </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-__VERSION__.tar.gz</filename> + or <filename>scons-__VERSION__.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-__VERSION__</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-__VERSION__</userinput> + # <userinput>python setup.py install</userinput> + </screen> + + <para> + + This will build &SCons;, + install the <application>scons</application> script + in the default system scripts directory + (<filename>/usr/local/bin</filename> or + <filename>C:\Python2.2\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:\Python2.2\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; Without Administrative Privileges</title> + + <para> + + If you don't have the right privileges to install &SCons; + in a system location, + you can install it in a location of your choosing + by specifying the <literal>--prefix=</literal> option: + + </para> + + <screen> + # <userinput>python setup.py install --prefix=$HOME</userinput> + </screen> + + <para> + + This would install &SCons; in appropriate locations + relative to the user's <literal>$HOME</literal> directory, + the <application>scons</application> script in + <filename>$HOME/bin</filename> + and the build engine in + <filename>$HOME/lib/scons</filename>. + You may, of course, specify any other location you prefer. + + </para> + + </section> + + <!-- + + <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-__VERSION__</filename> + or + <filename>C:\Python2.2\scons-__VERSION__</filename> + directory, for example. + You can also specify <option>--prefix=</option>, + in which case <filename>setup.py</filename> + will install the build engine + in a version-specific directory + relative to the specified prefix. + + </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> + + <!-- + + <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> + + --> |