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 Robert P.J. Day has suggested using "python -V",
83 but that's not supported in 1.5.2, so we're going
84 to leave this as is for now.
88 $ <userinput>python</userinput>
89 Python 2.2.2 (#1, Feb 24 2003, 19:13:11)
90 [GCC 3.2.2 20030222 (Red Hat Linux 3.2.2-4)] on linux2
91 Type "help", "copyright", "credits" or "license" for more information.
92 >>> <userinput>^D</userinput>
97 And on a Windows system with Python installed:
102 C:\><userinput>python</userinput>
103 Python 2.2.2 (#34, Apr 9 2002, 19:34:33) [MSC 32 bit (Intel)] on win32
104 Type "help", "copyright", "credits" or "license" for more information.
105 >>> <userinput>^Z</userinput>
110 The <prompt>>>></prompt> is the input prompt
111 for the Python interpreter.
112 The <userinput>^D</userinput> and <userinput>^Z</userinput>
113 represent the CTRL-D and CTRL-Z characters
114 that you will need to type to get out of the interpreter
115 before proceeding to installing &SCons;.
121 If Python is not installed on your system,
122 you will see an error message
123 stating something like "command not found"
125 or "'python' is not recognized
126 as an internal or external command, operable progam or batch file"
128 In that case, you need to install Python
129 before you can install &SCons;.
135 The standard location for information
136 about downloading and installing Python is
137 <ulink url="http://www.python.org/download/">http://www.python.org/download/</ulink>.
138 See that page for information about
139 how to download and install Python on your system.
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 only need to read 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 Linux distribution does not already have
181 a specific &SCons; RPM file,
182 you can download and install from the
183 generic RPM provided by the &SCons; project.
184 This will install the
185 SCons script(s) in <filename>/usr/bin</filename>,
186 and the SCons library modules in
187 <filename>/usr/lib/scons</filename>.
193 To install from the command line, simply download the
194 appropriate <filename>.rpm</filename> file,
200 # <userinput>rpm -Uvh scons-0.96-1.noarch.rpm</userinput>
205 Or, you can use a graphical RPM package manager
206 like <application>gnorpm</application>.
207 See your package manager application's documention
208 for specific instructions about
209 how to use it to install a downloaded RPM.
216 <title>Installing &SCons; on Debian Linux Systems</title>
220 Debian Linux systems use a different package management
221 format that also makes it very easy to install &SCons;.
227 If your system is connected to the Internet,
228 you can install the latest official Debian package
234 # <userinput>apt-get install scons</userinput>
242 you can download the Debian package built
243 by the &SCons; project
244 and install it manually by running:
249 # <userinput>db-XXX scons-*.deb</userinput>
257 <title>Installing &SCons; on Windows Systems</title>
261 &SCons; provides a Windows installer
262 that makes installation extremely easy.
263 Download the <filename>scons-0.95.win32.exe</filename>
264 file from the &SCons; download page at
265 <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
266 Then all you need to do is execute the file
267 (usually by clicking on its icon in Windows Explorer).
268 These will take you through a small
269 sequence of windows that will install
270 &SCons; on your system.
273 Things are a little more complicated
274 if you are using the Cygwin version of Python.
275 This is because Cygwin
276 tries to make a Windows system look more
277 POSIX-like (or UNIX-like or Linux-like, if you prefer)
278 by having the Cygwin utilities,
279 including Cygwin Python,
280 interpret file name arguments on the command line
281 using the forward-slash (<filename>/</filename>)
282 as the directory separator,
283 instead of the normal Windows behavior of the
284 backslash (<filename>\</filename>) as the directory separator.
292 <title>Installing &SCons; on Windows Systems Without Cygwin Python</title>
303 <title>Installing &SCons; on Windows Systems With Cygwin Python</title>
317 XXX - don't have the kinks worked out on how to
318 get these to display properly in all formats,
319 so comment them out for now.
324 <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center">
332 <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center">
340 <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center">
348 <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
360 <title>Building and Installing &SCons; on Any System</title>
364 If a pre-built &SCons; package is not available for your system,
365 then you can still easily build and install &SCons; using the native
366 Python <filename>distutils</filename> package.
372 The first step is to download either the
373 <filename>scons-__VERSION__.tar.gz</filename>
374 or <filename>scons-__VERSION__.zip</filename>,
375 which are available from the SCons download page at
376 <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
382 Unpack the archive you downloaded,
383 using a utility like <application>tar</application>
385 or <application>WinZip</application> on Windows.
386 This will create a directory called
387 <filename>scons-__VERSION__</filename>,
388 usually in your local directory.
389 Then change your working directory to that directory
390 and install &SCons; by executing the following commands:
395 # <userinput>cd scons-__VERSION__</userinput>
396 # <userinput>python setup.py install</userinput>
401 This will build &SCons;,
402 install the <application>scons</application> script
403 in the default system scripts directory
404 (<filename>/usr/local/bin</filename> or
405 <filename>C:\Python2.2\Scripts</filename>),
406 and will install the &SCons; build engine
407 in an appropriate stand-alone library directory
408 (<filename>/usr/local/lib/scons</filename> or
409 <filename>C:\Python2.2\scons</filename>).
410 Because these are system directories,
411 you may need root (on Linux or UNIX) or Administrator (on Windows)
412 privileges to install &SCons; like this.
419 <title>Building and Installing &SCons; in the Standard Python Library Directories</title>
432 <title>Building and Installing Multiple Versions of &SCons; Side-by-Side</title>
436 The &SCons; <filename>setup.py</filename> script
437 has some extensions that support
438 easy installation of multiple versions of &SCons;
439 in side-by-side locations.
440 This makes it easier to download and
441 experiment with different versions of &SCons;
442 before moving your official build process to a new version,
449 To install &SCons; in a version-specific location,
450 add the <option>--version-lib</option> option
451 when you call <filename>setup.py</filename>:
456 # <userinput>python setup.py install --version-lib</userinput>
461 This will install the &SCons; build engine
463 <filename>/usr/lib/scons-__VERSION__</filename>
465 <filename>C:\Python2.2\scons-__VERSION__</filename>
466 directory, for example.
472 If you use the <option>--version-lib</option> option
473 the first time you install &SCons;,
474 you do not need to specify it each time you install
476 The &SCons; <filename>setup.py</filename> script
477 will detect the version-specific directory name(s)
478 and assume you want to install all versions
479 in version-specific directories.
480 You can override that assumption in the future
481 by explicitly specifying the <option>--standalone-lib</option> option.
488 <title>Installing &SCons; in Other Locations</title>
492 You can install &SCons; in locations other than
493 the default by specifying the <option>--prefix=</option> option:
498 # <userinput>python setup.py install --prefix=/opt/scons</userinput>
504 install the <application>scons</application> script in
505 <filename>/opt/scons/bin</filename>
506 and the build engine in
507 <filename>/opt/scons/lib/scons</filename>,
513 Note that you can specify both the <option>--prefix=</option>
514 and the <option>--version-lib</option> options
516 in which case <filename>setup.py</filename>
517 will install the build engine
518 in a version-specific directory
519 relative to the specified prefix.
520 Adding <option>--version-lib</option> to the
521 above example would install the build engine in
522 <filename>/opt/scons/lib/scons-__VERSION__</filename>.
529 <title>Building and Installing &SCons; Without Administrative Privileges</title>
533 If you don't have the right privileges to install &SCons;
534 in a system location,
535 simply use the <literal>--prefix=</literal> option
536 to install it in a location of your choosing.
538 to install &SCons; in appropriate locations
539 relative to the user's <literal>$HOME</literal> directory,
540 the <application>scons</application> script in
541 <filename>$HOME/bin</filename>
542 and the build engine in
543 <filename>$HOME/lib/scons</filename>,
549 $ <userinput>python setup.py install --prefix=$HOME</userinput>
554 You may, of course, specify any other location you prefer,
555 and may use the <option>--version-lib</option> option
556 if you would like to install version-specific directories
557 relative to the specified prefix.
568 <title>Python Basics</title>
572 This section will provide a brief overview of
573 the Python programming language.
574 Skip this section if you are already familiar with Python
575 (or you're really intent on diving into &SCons;
576 and just picking up things as you go).
582 Python has a lot of good
583 documentation freely available on-line
584 to help you get started.
585 The standard tutorial is available at XXX.
592 Python is very easy to pick up.
598 Python variables must be assigned to before they can be referenced.
604 Assignment is like most programming languages:
613 Function calls look like most language function calls:
621 Define functions like so:
623 def func(arg1, arg2):
626 The number of parameters
632 Strings can be enclosed in single quotes or double quotes,
633 backslashes are used to escape characters,
634 triple-quote syntax lets you include quotes and newlines,
635 raw strings begin with 'r'.
641 Lists are enclosed in square brackets,
642 list items are separated by commas.
643 List references use square brackets and integer index values,
644 slice notation lets you select, delete or replace a range.
650 Dictionaries (hashes) are enclosed in curly brackets,
651 : separates keys from values,
653 Dictionary values are referenced using square brackets.
659 Access class attributes (including methods) using a '.'.
665 if: statements look like
667 elif: statements look like
669 else: statements look like
675 for: statements look like
677 while: statements look like
679 break statements look like
681 continue statements look like