5 Permission is hereby granted, free of charge, to any person obtaining
6 a copy of this software and associated documentation files (the
7 "Software"), to deal in the Software without restriction, including
8 without limitation the rights to use, copy, modify, merge, publish,
9 distribute, sublicense, and/or sell copies of the Software, and to
10 permit persons to whom the Software is furnished to do so, subject to
11 the following conditions:
13 The above copyright notice and this permission notice shall be included
14 in all copies or substantial portions of the Software.
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
17 KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
18 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 This chapter will take you through the basic steps
29 of installing &SCons; on your system,
30 and building &SCons; if you don't have a
31 pre-built package available
32 (or simply prefer the flexibility of building it yourself).
33 Before that, however, this chapter will also describe the basic steps
34 involved in installing Python on your system,
35 in case that is necessary.
36 Fortunately, both &SCons; and Python
37 are very easy to install on almost any system,
38 and Python already comes installed on many systems.
46 Lastly, this chapter also contains a section that
47 provides a brief overview of the Python programming language,
48 which is the language used to implement &SCons;,
49 and which forms the basis of the &SCons; configuration files.
50 Becoming familiar with some Python concepts will make it easier
51 to understand many of the examples in this User's Guide.
52 Nevertheless, it <emphasis>is</emphasis> possible
53 to configure simple &SCons; builds without knowing Python,
54 so you can skip this section if you
55 want to dive in and pick up things
56 by example- -or, of course, if you are
57 already familiar with Python.
64 <title>Installing Python</title>
68 Because &SCons; is written in Python,
69 you must obviously have Python installed on your system
71 Before you try to install Python,
72 you should check to see if Python is already
73 available on your system by typing
74 <userinput>python</userinput>
75 at your system's command-line prompt.
76 You should see something like the following
77 on a UNIX or Linux system that has Python installed:
82 $ <userinput>python</userinput>
83 Python 2.2.2 (#1, Feb 24 2003, 19:13:11)
84 [GCC 3.2.2 20030222 (Red Hat Linux 3.2.2-4)] on linux2
85 Type "help", "copyright", "credits" or "license" for more information.
86 >>> <userinput>^D</userinput>
91 And on a Windows system with Python installed:
96 C:\><userinput>python</userinput>
97 Python 2.2.2 (#34, Apr 9 2002, 19:34:33) [MSC 32 bit (Intel)] on win32
98 Type "help", "copyright", "credits" or "license" for more information.
99 >>> <userinput>^Z</userinput>
104 The <prompt>>>></prompt> is the input prompt
105 for the Python interpreter.
106 The <userinput>^D</userinput> and <userinput>^Z</userinput>
107 represent the CTRL-D and CTRL-Z characters
108 that you will need to type to get out of the interpreter
109 before proceeding to installing &SCons;.
115 If Python is not installed on your system,
116 you will see an error message
117 stating something like "command not found"
119 or "'python' is not recognized
120 as an internal or external command, operable progam or batch file"
122 In that case, you need to install Python
123 before you can install &SCons;.
129 The standard location for information
130 about downloading and installing Python is
131 <ulink url="http://www.python.org/download/">http://www.python.org/download/</ulink>.
132 See that page for information about
133 how to download and install Python on your system.
140 <title>Installing &SCons; From Pre-Built Packages</title>
144 &SCons; comes pre-packaged for installation on a number of systems,
145 including Linux and Windows systems.
146 You do not need to read this entire section,
147 you should only need to read the section
148 appropriate to the type of system you're running on.
153 <title>Installing &SCons; on Red Hat (and Other RPM-based) Linux Systems</title>
157 &SCons; comes in RPM (Red Hat Package Manager) format,
158 pre-built and ready to install on Red Hat Linux,
159 or any other Linux distribution that uses RPM.
160 Your distribution may
161 already have an &SCons; RPM built specifically for it;
162 many do, including SuSe, Mandrake and Fedora.
163 You can check for the availability of an &SCons; RPM
164 on your distribution's download servers,
165 or by consulting an RPM search site like
166 <ulink url="http://www.rpmfind.net/">http://www.rpmfind.net/</ulink> or
167 <ulink url="http://rpm.pbone.net/">http://rpm.pbone.net/</ulink>.
173 If your Linux distribution does not already have
174 a specific &SCons; RPM file,
175 you can download and install from the
176 generic RPM provided by the &SCons; project.
177 This will install the
178 SCons script(s) in <filename>/usr/bin</filename>,
179 and the SCons library modules in
180 <filename>/usr/lib/scons</filename>.
186 To install from the command line, simply download the
187 appropriate <filename>.rpm</filename> file,
193 # <userinput>rpm -Uvh scons-0.96-1.noarch.rpm</userinput>
198 Or, you can use a graphical RPM package manager
199 like <application>gnorpm</application>.
200 See your package manager application's documention
201 for specific instructions about
202 how to use it to install a downloaded RPM.
209 <title>Installing &SCons; on Debian Linux Systems</title>
213 Debian Linux systems use a different package management
214 format that also makes it very easy to install &SCons;.
220 If your system is connected to the Internet,
221 you can install the latest official Debian package
227 # <userinput>apt-get install scons</userinput>
235 you can download the Debian package built
236 by the &SCons; project
237 and install it manually by running:
242 # <userinput>db-XXX scons-*.deb</userinput>
250 <title>Installing &SCons; on Windows Systems</title>
254 &SCons; provides a Windows installer
255 that makes installation extremely easy.
256 Download the <filename>scons-0.95.win32.exe</filename>
257 file from the &SCons; download page at
258 <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
259 Then all you need to do is execute the file
260 (usually by clicking on its icon in Windows Explorer).
261 These will take you through a small
262 sequence of windows that will install
263 &SCons; on your system.
266 Things are a little more complicated
267 if you are using the Cygwin version of Python.
268 This is because Cygwin
269 tries to make a Windows system look more
270 POSIX-like (or UNIX-like or Linux-like, if you prefer)
271 by having the Cygwin utilities,
272 including Cygwin Python,
273 interpret file name arguments on the command line
274 using the forward-slash (<filename>/</filename>)
275 as the directory separator,
276 instead of the normal Windows behavior of the
277 backslash (<filename>\</filename>) as the directory separator.
285 <title>Installing &SCons; on Windows Systems Without Cygwin Python</title>
296 <title>Installing &SCons; on Windows Systems With Cygwin Python</title>
310 XXX - don't have the kinks worked out on how to
311 get these to display properly in all formats,
312 so comment them out for now.
317 <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center">
325 <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center">
333 <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center">
341 <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
353 <title>Building and Installing &SCons; on Any System</title>
357 If a pre-built &SCons; package is not available for your system,
358 then you can still easily build and install &SCons; using the native
359 Python <filename>distutils</filename> package.
365 The first step is to download either the
366 <filename>scons-__VERSION__.tar.gz</filename>
367 or <filename>scons-__VERSION__.zip</filename>,
368 which are available from the SCons download page at
369 <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
375 Unpack the archive you downloaded,
376 using a utility like <application>tar</application>
378 or <application>WinZip</application> on Windows.
379 This will create a directory called
380 <filename>scons-__VERSION__</filename>,
381 usually in your local directory.
382 Then change your working directory to that directory
383 and install &SCons; by executing the following commands:
388 # <userinput>cd scons-__VERSION__</userinput>
389 # <userinput>python setup.py install</userinput>
394 This will build &SCons;,
395 install the <application>scons</application> script
396 in the default system scripts directory
397 (<filename>/usr/local/bin</filename> or
398 <filename>C:\Python2.2\Scripts</filename>),
399 and will install the &SCons; build engine
400 in an appropriate stand-alone library directory
401 (<filename>/usr/local/lib/scons</filename> or
402 <filename>C:\Python2.2\scons</filename>).
403 Because these are system directories,
404 you may need root (on Linux or UNIX) or Administrator (on Windows)
405 privileges to install &SCons; like this.
410 <title>Building and Installing &SCons; Without Administrative Privileges</title>
414 If you don't have the right privileges to install &SCons;
415 in a system location,
416 you can install it in a location of your choosing
417 by specifying the <literal>--prefix=</literal> option:
422 # <userinput>python setup.py install --prefix=$HOME</userinput>
427 This would install &SCons; in appropriate locations
428 relative to the user's <literal>$HOME</literal> directory,
429 the <application>scons</application> script in
430 <filename>$HOME/bin</filename>
431 and the build engine in
432 <filename>$HOME/lib/scons</filename>.
433 You may, of course, specify any other location you prefer.
442 <title>Building and Installing &SCons; in the Standard Python Library Directories</title>
455 <title>Building and Installing Multiple Versions of &SCons; Side-by-Side</title>
459 The &SCons; <filename>setup.py</filename> script
460 has some extensions that support
461 easy installation of multiple versions of &SCons;
462 in side-by-side locations.
463 This makes it easier to download and
464 experiment with different versions of &SCons;
465 before moving your official build process to a new version,
472 To install &SCons; in a version-specific location,
473 add the <option>--version-lib</option> option
474 when you call <filename>setup.py</filename>:
479 # <userinput>python setup.py install --version-lib</userinput>
484 This will install the &SCons; build engine
486 <filename>/usr/lib/scons-__VERSION__</filename>
488 <filename>C:\Python2.2\scons-__VERSION__</filename>
489 directory, for example.
490 You can also specify <option>--prefix=</option>,
491 in which case <filename>setup.py</filename>
492 will install the build engine
493 in a version-specific directory
494 relative to the specified prefix.
500 If you use the <option>--version-lib</option> option
501 the first time you install &SCons;,
502 you do not need to specify it each time you install
504 The &SCons; <filename>setup.py</filename> script
505 will detect the version-specific directory name(s)
506 and assume you want to install all versions
507 in version-specific directories.
508 You can override that assumption in the future
509 by explicitly specifying the <option>--standalone-lib</option> option.
520 <title>Python Basics</title>
524 This section will provide a brief overview of
525 the Python programming language.
526 Skip this section if you are already familiar with Python
527 (or you're really intent on diving into &SCons;
528 and just picking up things as you go).
534 Python has a lot of good
535 documentation freely available on-line
536 to help you get started.
537 The standard tutorial is available at XXX.
544 Python is very easy to pick up.
550 Python variables must be assigned to before they can be referenced.
556 Assignment is like most programming languages:
565 Function calls look like most language function calls:
573 Define functions like so:
575 def func(arg1, arg2):
578 The number of parameters
584 Strings can be enclosed in single quotes or double quotes,
585 backslashes are used to escape characters,
586 triple-quote syntax lets you include quotes and newlines,
587 raw strings begin with 'r'.
593 Lists are enclosed in square brackets,
594 list items are separated by commas.
595 List references use square brackets and integer index values,
596 slice notation lets you select, delete or replace a range.
602 Dictionaries (hashes) are enclosed in curly brackets,
603 : separates keys from values,
605 Dictionary values are referenced using square brackets.
611 Access class attributes (including methods) using a '.'.
617 if: statements look like
619 elif: statements look like
621 else: statements look like
627 for: statements look like
629 while: statements look like
631 break statements look like
633 continue statements look like