doc/user/build-install.in

   1 <!--
   2
   3   __COPYRIGHT__
   4
   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:
  12
  13   The above copyright notice and this permission notice shall be included
  14   in all copies or substantial portions of the Software.
  15
  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.
  23
  24 -->
  25
  26   <para>
  27
  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.
  39
  40   </para>
  41
  42   <!--
  43
  44   <para>
  45
  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.
  58
  59   </para>
  60
  61   -->
  62
  63   <section>
  64   <title>Installing Python</title>
  65
  66     <para>
  67
  68     Because &SCons; is written in Python,
  69     you must obviously have Python installed on your system
  70     to use &SCons;.
  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>
  75     (capital 'V')
  76     or
  77     <userinput>python --version</userinput>
  78     at your system's command-line prompt.
  79
  80     </para>
  81
  82     <screen>
  83        $ <userinput>python -V</userinput>
  84        Python 2.5.1
  85     </screen>
  86
  87     <para>
  88
  89     And on a Windows system with Python installed:
  90
  91     </para>
  92
  93     <screen>
  94        C:\><userinput>python -V</userinput>
  95        Python 2.5.1
  96     </screen>
  97
  98     <para>
  99
 100     If Python is not installed on your system,
 101     you will see an error message
 102     stating something like "command not found"
 103     (on UNIX or Linux)
 104     or "'python' is not recognized
 105     as an internal or external command, operable progam or batch file"
 106     (on Windows).
 107     In that case, you need to install Python
 108     before you can install &SCons;.
 109
 110     </para>
 111
 112     <para>
 113
 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
 117     you may see an
 118     <literal>"Unknown option: -V"</literal>
 119     error message.)
 120
 121     </para>
 122
 123     <para>
 124
 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.
 130
 131     </para>
 132
 133     <para>
 134
 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     the help speed up the performance of &SCons;.
 140
 141     </para>
 142
 143   </section>
 144
 145   <section>
 146   <title>Installing &SCons; From Pre-Built Packages</title>
 147
 148     <para>
 149
 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.
 155
 156     </para>
 157
 158     <section>
 159     <title>Installing &SCons; on Red Hat (and Other RPM-based) Linux Systems</title>
 160
 161       <para>
 162
 163       &SCons; comes in RPM (Red Hat Package Manager) format,
 164       pre-built and ready to install on Red Hat Linux,
 165       Fedora,
 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>.
 175
 176       </para>
 177
 178       <para>
 179
 180       If your distribution supports installation via
 181       <application>yum</application>,
 182       you should be able to install &SCons; by running:
 183
 184       </para>
 185
 186       <screen>
 187         # <userinput>yum install scons</userinput>
 188       </screen>
 189
 190       <para>
 191
 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>.
 200
 201       </para>
 202
 203       <para>
 204
 205       To install from the command line, simply download the
 206       appropriate <filename>.rpm</filename> file,
 207       and then run:
 208
 209       </para>
 210
 211       <screen>
 212         # <userinput>rpm -Uvh scons-__VERSION__-1.noarch.rpm</userinput>
 213       </screen>
 214
 215       <para>
 216
 217       Or, you can use a graphical RPM package manager
 218       like <application>gnorpm</application>.
 219       See your package manager application's documention
 220       for specific instructions about
 221       how to use it to install a downloaded RPM.
 222
 223       </para>
 224
 225     </section>
 226
 227     <section>
 228     <title>Installing &SCons; on Debian Linux Systems</title>
 229
 230       <para>
 231
 232       Debian Linux systems use a different package management
 233       format that also makes it very easy to install &SCons;.
 234
 235       </para>
 236
 237       <para>
 238
 239       If your system is connected to the Internet,
 240       you can install the latest official Debian package
 241       by running:
 242
 243       </para>
 244
 245       <screen>
 246         # <userinput>apt-get install scons</userinput>
 247       </screen>
 248
 249       <!--
 250
 251       <para>
 252
 253       Alternatively,
 254       you can download the Debian package built
 255       by the &SCons; project
 256       and install it manually by running:
 257
 258       </para>
 259
 260       <screen>
 261         # <userinput>db-XXX scons-*.deb</userinput>
 262       </screen>
 263
 264       -->
 265
 266     </section>
 267
 268     <section>
 269     <title>Installing &SCons; on Windows Systems</title>
 270
 271       <para>
 272
 273       &SCons; provides a Windows installer
 274       that makes installation extremely easy.
 275       Download the <filename>scons-__VERSION__.win32.exe</filename>
 276       file from the &SCons; download page at
 277       <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>.
 278       Then all you need to do is execute the file
 279       (usually by clicking on its icon in Windows Explorer).
 280       These will take you through a small
 281       sequence of windows that will install
 282       &SCons; on your system.
 283
 284       <!--
 285       Things are a little more complicated
 286       if you are using the Cygwin version of Python.
 287       This is because Cygwin
 288       tries to make a Windows system look more
 289       POSIX-like (or UNIX-like or Linux-like, if you prefer)
 290       by having the Cygwin utilities,
 291       including Cygwin Python,
 292       interpret file name arguments on the command line
 293       using the forward-slash (<filename>/</filename>)
 294       as the directory separator,
 295       instead of the normal Windows behavior of the
 296       backslash (<filename>\</filename>) as the directory separator.
 297       -->
 298
 299       </para>
 300
 301       <!--
 302
 303       <section>
 304       <title>Installing &SCons; on Windows Systems Without Cygwin Python</title>
 305
 306         <para>
 307
 308         XXX
 309
 310         </para>
 311
 312       </section>
 313
 314       <section>
 315       <title>Installing &SCons; on Windows Systems With Cygwin Python</title>
 316
 317         <para>
 318
 319         XXX
 320
 321         </para>
 322
 323       </section>
 324
 325       -->
 326
 327       <!--
 328
 329       XXX - don't have the kinks worked out on how to
 330       get these to display properly in all formats,
 331       so comment them out for now.
 332
 333       <screenshot>
 334       <mediaobject>
 335         <imageobject>
 336           <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center">
 337         </imageobject>
 338       </mediaobject>
 339       </screenshot>
 340
 341       <screenshot>
 342       <mediaobject>
 343         <imageobject>
 344           <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center">
 345         </imageobject>
 346       </mediaobject>
 347       </screenshot>
 348
 349       <screenshot>
 350       <mediaobject>
 351         <imageobject>
 352           <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center">
 353         </imageobject>
 354       </mediaobject>
 355       </screenshot>
 356
 357       <screenshot>
 358       <mediaobject>
 359         <imageobject>
 360           <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
 361         </imageobject>
 362       </mediaobject>
 363       </screenshot>
 364
 365       -->
 366
 367     </section>
 368
 369   </section>
 370
 371   <section>
 372   <title>Building and Installing &SCons; on Any System</title>
 373
 374     <para>
 375
 376     If a pre-built &SCons; package is not available for your system,
 377     then you can still easily build and install &SCons; using the native
 378     Python <filename>distutils</filename> package.
 379
 380     </para>
 381
 382     <para>
 383
 384     The first step is to download either the
 385     <filename>scons-__VERSION__.tar.gz</filename>
 386     or <filename>scons-__VERSION__.zip</filename>,
 387     which are available from the SCons download page at
 388     <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
 389
 390     </para>
 391
 392     <para>
 393
 394     Unpack the archive you downloaded,
 395     using a utility like <application>tar</application>
 396     on Linux or UNIX,
 397     or <application>WinZip</application> on Windows.
 398     This will create a directory called
 399     <filename>scons-__VERSION__</filename>,
 400     usually in your local directory.
 401     Then change your working directory to that directory
 402     and install &SCons; by executing the following commands:
 403
 404     </para>
 405
 406     <screen>
 407       # <userinput>cd scons-__VERSION__</userinput>
 408       # <userinput>python setup.py install</userinput>
 409     </screen>
 410
 411     <para>
 412
 413     This will build &SCons;,
 414     install the <application>scons</application> script
 415     in the default system scripts directory
 416     (<filename>/usr/local/bin</filename> or
 417     <filename>C:\Python25\Scripts</filename>),
 418     and will install the &SCons; build engine
 419     in an appropriate stand-alone library directory
 420     (<filename>/usr/local/lib/scons</filename> or
 421     <filename>C:\Python25\scons</filename>).
 422     Because these are system directories,
 423     you may need root (on Linux or UNIX) or Administrator (on Windows)
 424     privileges to install &SCons; like this.
 425
 426     </para>
 427
 428     <!--
 429
 430     <section>
 431     <title>Building and Installing &SCons; in the Standard Python Library Directories</title>
 432
 433       <para>
 434
 435       XXX
 436
 437       </para>
 438
 439     </section>
 440
 441     -->
 442
 443     <section>
 444     <title>Building and Installing Multiple Versions of &SCons; Side-by-Side</title>
 445
 446       <para>
 447
 448       The &SCons; <filename>setup.py</filename> script
 449       has some extensions that support
 450       easy installation of multiple versions of &SCons;
 451       in side-by-side locations.
 452       This makes it easier to download and
 453       experiment with different versions of &SCons;
 454       before moving your official build process to a new version,
 455       for example.
 456
 457       </para>
 458
 459       <para>
 460
 461       To install &SCons; in a version-specific location,
 462       add the <option>--version-lib</option> option
 463       when you call <filename>setup.py</filename>:
 464
 465       </para>
 466
 467       <screen>
 468         # <userinput>python setup.py install --version-lib</userinput>
 469       </screen>
 470
 471       <para>
 472
 473       This will install the &SCons; build engine
 474       in the
 475       <filename>/usr/lib/scons-__VERSION__</filename>
 476       or
 477       <filename>C:\Python25\scons-__VERSION__</filename>
 478       directory, for example.
 479
 480       </para>
 481
 482       <para>
 483
 484       If you use the <option>--version-lib</option> option
 485       the first time you install &SCons;,
 486       you do not need to specify it each time you install
 487       a new version.
 488       The &SCons; <filename>setup.py</filename> script
 489       will detect the version-specific directory name(s)
 490       and assume you want to install all versions
 491       in version-specific directories.
 492       You can override that assumption in the future
 493       by explicitly specifying the <option>--standalone-lib</option> option.
 494
 495       </para>
 496
 497     </section>
 498
 499     <section>
 500     <title>Installing &SCons; in Other Locations</title>
 501
 502       <para>
 503
 504       You can install &SCons; in locations other than
 505       the default by specifying the <option>--prefix=</option> option:
 506
 507       </para>
 508
 509       <screen>
 510         # <userinput>python setup.py install --prefix=/opt/scons</userinput>
 511       </screen>
 512
 513       <para>
 514
 515       This would
 516       install the <application>scons</application> script in
 517       <filename>/opt/scons/bin</filename>
 518       and the build engine in
 519       <filename>/opt/scons/lib/scons</filename>,
 520
 521       </para>
 522
 523       <para>
 524
 525       Note that you can specify both the <option>--prefix=</option>
 526       and the <option>--version-lib</option> options
 527       at the same type,
 528       in which case <filename>setup.py</filename>
 529       will install the build engine
 530       in a version-specific directory
 531       relative to the specified prefix.
 532       Adding <option>--version-lib</option> to the
 533       above example would install the build engine in
 534       <filename>/opt/scons/lib/scons-__VERSION__</filename>.
 535
 536       </para>
 537
 538     </section>
 539
 540     <section>
 541     <title>Building and Installing &SCons; Without Administrative Privileges</title>
 542
 543       <para>
 544
 545       If you don't have the right privileges to install &SCons;
 546       in a system location,
 547       simply use the <literal>--prefix=</literal> option
 548       to install it in a location of your choosing.
 549       For example,
 550       to install &SCons; in appropriate locations
 551       relative to the user's <literal>$HOME</literal> directory,
 552       the <application>scons</application> script in
 553       <filename>$HOME/bin</filename>
 554       and the build engine in
 555       <filename>$HOME/lib/scons</filename>,
 556       simply type:
 557
 558       </para>
 559
 560       <screen>
 561         $ <userinput>python setup.py install --prefix=$HOME</userinput>
 562       </screen>
 563
 564       <para>
 565
 566       You may, of course, specify any other location you prefer,
 567       and may use the <option>--version-lib</option> option
 568       if you would like to install version-specific directories
 569       relative to the specified prefix.
 570
 571       </para>
 572
 573     </section>
 574
 575   </section>
 576
 577   <!--
 578
 579   <section>
 580   <title>Python Basics</title>
 581
 582     <para>
 583
 584     This section will provide a brief overview of
 585     the Python programming language.
 586     Skip this section if you are already familiar with Python
 587     (or you're really intent on diving into &SCons;
 588     and just picking up things as you go).
 589
 590     </para>
 591
 592     <para>
 593
 594     Python has a lot of good
 595     documentation freely available on-line
 596     to help you get started.
 597     The standard tutorial is available at XXX.
 598
 599
 600     </para>
 601
 602     <para>
 603
 604     Python is very easy to pick up.
 605
 606     </para>
 607
 608     <para>
 609
 610     Python variables must be assigned to before they can be referenced.
 611
 612     </para>
 613
 614     <para>
 615
 616     Assignment is like most programming languages:
 617
 618     x = 1 + 2
 619     z = 3 * x
 620
 621     </para>
 622
 623     <para>
 624
 625     Function calls look like most language function calls:
 626
 627     a = f(g)
 628
 629     </para>
 630
 631     <para>
 632
 633     Define functions like so:
 634
 635         def func(arg1, arg2):
 636             return arg1 * arg 2
 637
 638     The number of parameters
 639
 640     </para>
 641
 642     <para>
 643
 644     Strings can be enclosed in single quotes or double quotes,
 645     backslashes are used to escape characters,
 646     triple-quote syntax lets you include quotes and newlines,
 647     raw strings begin with 'r'.
 648
 649     </para>
 650
 651     <para>
 652
 653     Lists are enclosed in square brackets,
 654     list items are separated by commas.
 655     List references use square brackets and integer index values,
 656     slice notation lets you select, delete or replace a range.
 657
 658     </para>
 659
 660     <para>
 661
 662     Dictionaries (hashes) are enclosed in curly brackets,
 663     : separates keys from values,
 664     , separates items.
 665     Dictionary values are referenced using square brackets.
 666
 667     </para>
 668
 669     <para>
 670
 671     Access class attributes (including methods) using a '.'.
 672
 673     </para>
 674
 675     <para>
 676
 677     if: statements look like
 678
 679     elif: statements look like
 680
 681     else: statements look like
 682
 683     </para>
 684
 685     <para>
 686
 687     for: statements look like
 688
 689     while: statements look like
 690
 691     break statements look like
 692
 693     continue statements look like
 694
 695     </para>
 696
 697     <para>
 698
 699     pass
 700
 701     </para>
 702
 703   </section>
 704
 705   -->