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 -V</userinput>
77 <userinput>python --version</userinput>
78 at your system's command-line prompt.
83 $ <userinput>python -V</userinput>
89 And on a Windows system with Python installed:
94 C:\><userinput>python -V</userinput>
100 If Python is not installed on your system,
101 you will see an error message
102 stating something like "command not found"
104 or "'python' is not recognized
105 as an internal or external command, operable progam or batch file"
107 In that case, you need to install Python
108 before you can install &SCons;.
114 (Note that the <option>-V</option> option
115 was added to Python version 2.0,
116 so if your system only has an earlier version available
118 <literal>"Unknown option: -V"</literal>
125 The standard location for information
126 about downloading and installing Python is
127 <ulink url="http://www.python.org/download/">http://www.python.org/download/</ulink>.
128 See that page for information about
129 how to download and install Python on your system.
135 &SCons; will work with any version of Python from 1.5.2 or later.
136 If you need to install Python and have a choice,
137 we recommend using the most recent Python 2.5 version available.
138 Python 2.5 has significant improvements
139 that help speed up the performance of &SCons;.
146 <title>Installing &SCons; From Pre-Built Packages</title>
150 &SCons; comes pre-packaged for installation on a number of systems,
151 including Linux and Windows systems.
152 You do not need to read this entire section,
153 you should need to read only the section
154 appropriate to the type of system you're running on.
159 <title>Installing &SCons; on Red Hat (and Other RPM-based) Linux Systems</title>
163 &SCons; comes in RPM (Red Hat Package Manager) format,
164 pre-built and ready to install on Red Hat Linux,
166 or any other Linux distribution that uses RPM.
167 Your distribution may
168 already have an &SCons; RPM built specifically for it;
169 many do, including SUSE, Mandrake and Fedora.
170 You can check for the availability of an &SCons; RPM
171 on your distribution's download servers,
172 or by consulting an RPM search site like
173 <ulink url="http://www.rpmfind.net/">http://www.rpmfind.net/</ulink> or
174 <ulink url="http://rpm.pbone.net/">http://rpm.pbone.net/</ulink>.
180 If your distribution supports installation via
181 <application>yum</application>,
182 you should be able to install &SCons; by running:
187 # <userinput>yum install scons</userinput>
192 If your Linux distribution does not already have
193 a specific &SCons; RPM file,
194 you can download and install from the
195 generic RPM provided by the &SCons; project.
196 This will install the
197 SCons script(s) in <filename>/usr/bin</filename>,
198 and the SCons library modules in
199 <filename>/usr/lib/scons</filename>.
205 To install from the command line, simply download the
206 appropriate <filename>.rpm</filename> file,
212 # <userinput>rpm -Uvh scons-__VERSION__-1.noarch.rpm</userinput>
217 Or, you can use a graphical RPM package manager.
218 See your package manager application's documention
219 for specific instructions about
220 how to use it to install a downloaded RPM.
227 <title>Installing &SCons; on Debian Linux Systems</title>
231 Debian Linux systems use a different package management
232 format that also makes it very easy to install &SCons;.
238 If your system is connected to the Internet,
239 you can install the latest official Debian package
245 # <userinput>apt-get install scons</userinput>
253 you can download the Debian package built
254 by the &SCons; project
255 and install it manually by running:
260 # <userinput>db-XXX scons-*.deb</userinput>
268 <title>Installing &SCons; on Windows Systems</title>
272 &SCons; provides a Windows installer
273 that makes installation extremely easy.
274 Download the <filename>scons-__VERSION__.win32.exe</filename>
275 file from the &SCons; download page at
276 <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>.
277 Then all you need to do is execute the file
278 (usually by clicking on its icon in Windows Explorer).
279 These will take you through a small
280 sequence of windows that will install
281 &SCons; on your system.
284 Things are a little more complicated
285 if you are using the Cygwin version of Python.
286 This is because Cygwin
287 tries to make a Windows system look more
288 POSIX-like (or UNIX-like or Linux-like, if you prefer)
289 by having the Cygwin utilities,
290 including Cygwin Python,
291 interpret file name arguments on the command line
292 using the forward-slash (<filename>/</filename>)
293 as the directory separator,
294 instead of the normal Windows behavior of the
295 backslash (<filename>\</filename>) as the directory separator.
303 <title>Installing &SCons; on Windows Systems Without Cygwin Python</title>
314 <title>Installing &SCons; on Windows Systems With Cygwin Python</title>
328 XXX - don't have the kinks worked out on how to
329 get these to display properly in all formats,
330 so comment them out for now.
335 <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center">
343 <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center">
351 <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center">
359 <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
371 <title>Building and Installing &SCons; on Any System</title>
375 If a pre-built &SCons; package is not available for your system,
376 then you can still easily build and install &SCons; using the native
377 Python <filename>distutils</filename> package.
383 The first step is to download either the
384 <filename>scons-__VERSION__.tar.gz</filename>
385 or <filename>scons-__VERSION__.zip</filename>,
386 which are available from the SCons download page at
387 <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
393 Unpack the archive you downloaded,
394 using a utility like <application>tar</application>
396 or <application>WinZip</application> on Windows.
397 This will create a directory called
398 <filename>scons-__VERSION__</filename>,
399 usually in your local directory.
400 Then change your working directory to that directory
401 and install &SCons; by executing the following commands:
406 # <userinput>cd scons-__VERSION__</userinput>
407 # <userinput>python setup.py install</userinput>
412 This will build &SCons;,
413 install the &scons; script
414 in the python which is used to run the setup.py's scripts directory
415 (<filename>/usr/local/bin</filename> or
416 <filename>C:\Python25\Scripts</filename>),
417 and will install the &SCons; build engine
418 in the corresponding library directory for the python used
419 (<filename>/usr/local/lib/scons</filename> or
420 <filename>C:\Python25\scons</filename>).
421 Because these are system directories,
422 you may need root (on Linux or UNIX) or Administrator (on Windows)
423 privileges to install &SCons; like this.
430 <title>Building and Installing &SCons; in the Standard Python Library Directories</title>
443 <title>Building and Installing Multiple Versions of &SCons; Side-by-Side</title>
447 The &SCons; <filename>setup.py</filename> script
448 has some extensions that support
449 easy installation of multiple versions of &SCons;
450 in side-by-side locations.
451 This makes it easier to download and
452 experiment with different versions of &SCons;
453 before moving your official build process to a new version,
460 To install &SCons; in a version-specific location,
461 add the <option>--version-lib</option> option
462 when you call <filename>setup.py</filename>:
467 # <userinput>python setup.py install --version-lib</userinput>
472 This will install the &SCons; build engine
474 <filename>/usr/lib/scons-__VERSION__</filename>
476 <filename>C:\Python25\scons-__VERSION__</filename>
477 directory, for example.
483 If you use the <option>--version-lib</option> option
484 the first time you install &SCons;,
485 you do not need to specify it each time you install
487 The &SCons; <filename>setup.py</filename> script
488 will detect the version-specific directory name(s)
489 and assume you want to install all versions
490 in version-specific directories.
491 You can override that assumption in the future
492 by explicitly specifying the <option>--standalone-lib</option> option.
499 <title>Installing &SCons; in Other Locations</title>
503 You can install &SCons; in locations other than
504 the default by specifying the <option>--prefix=</option> option:
509 # <userinput>python setup.py install --prefix=/opt/scons</userinput>
515 install the <application>scons</application> script in
516 <filename>/opt/scons/bin</filename>
517 and the build engine in
518 <filename>/opt/scons/lib/scons</filename>,
524 Note that you can specify both the <option>--prefix=</option>
525 and the <option>--version-lib</option> options
527 in which case <filename>setup.py</filename>
528 will install the build engine
529 in a version-specific directory
530 relative to the specified prefix.
531 Adding <option>--version-lib</option> to the
532 above example would install the build engine in
533 <filename>/opt/scons/lib/scons-__VERSION__</filename>.
540 <title>Building and Installing &SCons; Without Administrative Privileges</title>
544 If you don't have the right privileges to install &SCons;
545 in a system location,
546 simply use the <literal>--prefix=</literal> option
547 to install it in a location of your choosing.
549 to install &SCons; in appropriate locations
550 relative to the user's <literal>$HOME</literal> directory,
551 the &scons; script in
552 <filename>$HOME/bin</filename>
553 and the build engine in
554 <filename>$HOME/lib/scons</filename>,
560 $ <userinput>python setup.py install --prefix=$HOME</userinput>
565 You may, of course, specify any other location you prefer,
566 and may use the <option>--version-lib</option> option
567 if you would like to install version-specific directories
568 relative to the specified prefix.
574 This can also be used to experiment with a newer
575 version of &SCons; than the one installed
576 in your system locations.
577 Of course, the location in which you install the
578 newer version of the &scons; script
579 (<filename>$HOME/bin</filename> in the above example)
580 must be configured in your &PATH; variable
581 before the directory containing
582 the system-installed version
583 of the &scons; script.
594 <title>Python Basics</title>
598 This section will provide a brief overview of
599 the Python programming language.
600 Skip this section if you are already familiar with Python
601 (or you're really intent on diving into &SCons;
602 and just picking up things as you go).
608 Python has a lot of good
609 documentation freely available on-line
610 to help you get started.
611 The standard tutorial is available at XXX.
618 Python is very easy to pick up.
624 Python variables must be assigned to before they can be referenced.
630 Assignment is like most programming languages:
639 Function calls look like most language function calls:
647 Define functions like so:
649 def func(arg1, arg2):
652 The number of parameters
658 Strings can be enclosed in single quotes or double quotes,
659 backslashes are used to escape characters,
660 triple-quote syntax lets you include quotes and newlines,
661 raw strings begin with 'r'.
667 Lists are enclosed in square brackets,
668 list items are separated by commas.
669 List references use square brackets and integer index values,
670 slice notation lets you select, delete or replace a range.
676 Dictionaries (hashes) are enclosed in curly brackets,
677 : separates keys from values,
679 Dictionary values are referenced using square brackets.
685 Access class attributes (including methods) using a '.'.
691 if: statements look like
693 elif: statements look like
695 else: statements look like
701 for: statements look like
703 while: statements look like
705 break statements look like
707 continue statements look like