doc/user/preface.xml

   1 <?xml version='1.0'?>
   2
   3 <!--
   4 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   5 SPDX-License-Identifier: MIT
   6 SPDX-FileType: DOCUMENTATION
   7
   8 This file is processed by the bin/SConsDoc.py module.
   9 -->
  10
  11 <!DOCTYPE sconsdoc [
  12     <!ENTITY % scons SYSTEM "../scons.mod">
  13     %scons;
  14
  15     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
  16     %builders-mod;
  17     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
  18     %functions-mod;
  19     <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
  20     %tools-mod;
  21     <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
  22     %variables-mod;
  23 ]>
  24
  25 <preface id="chap-preface"
  26          xmlns="http://www.scons.org/dbxsd/v1.0"
  27          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  28          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  29 <title>Preface</title>
  30
  31 <para>
  32
  33   Thank you for taking the time to read about &SCons;.
  34   &SCons; is a modern
  35   software construction tool - a software utility
  36   for building software (or other files)
  37   and keeping built software up-to-date
  38   whenever the underlying input files change.
  39
  40   </para>
  41
  42   <para>
  43
  44   The most distinctive thing about &SCons;
  45   is that its configuration files are
  46   actually <emphasis>scripts</emphasis>,
  47   written in the &Python; programming language.
  48   This is in contrast to most alternative build tools,
  49   which typically invent a new language to
  50   configure the build.
  51   &SCons; still has a learning curve, of course,
  52   because you have to know what functions to call
  53   to set up your build properly,
  54   but the underlying syntax used should be familiar
  55   to anyone who has ever looked at a Python script.
  56
  57   </para>
  58
  59   <para>
  60
  61   Paradoxically,
  62   using Python as the configuration file format
  63   makes &SCons;
  64   <emphasis>easier</emphasis>
  65   for non-programmers to learn
  66   than the cryptic languages of other build tools,
  67   which are usually invented by programmers for other programmers.
  68   This is in no small part due to the
  69   consistency and readability that are hallmarks of Python.
  70   It just so happens that making a real, live
  71   scripting language the basis for the
  72   configuration files
  73   makes it a snap for more accomplished programmers
  74   to do more complicated things with builds,
  75   as necessary.
  76
  77   </para>
  78
  79   <!--
  80
  81   <section>
  82   <title>Why &SCons;?</title>
  83
  84     <para>
  85
  86     &SCons; is a response to a perennial problem:
  87     building software is harder than it should be.
  88     In a nutshell:  the old, reliable model of the
  89     venerable and ubiquitous &Make; program
  90     has had a hard time keeping up with
  91     how complicated building software has become.
  92     The fact that &Make; has kept up as well as it has is impressive,
  93     and a testament to how the simplicity.
  94     But anyone who has wrestled with &Automake; and &Autoconf;
  95     to try to guarantee that a bit of software
  96     will build correctly on multiple platforms
  97     can tell you that it takes a lot of work to get right.
  98
  99     </para>
 100
 101   </section>
 102
 103   -->
 104
 105   <section>
 106   <title>&SCons; Principles</title>
 107
 108     <para>
 109
 110     There are a few overriding principles the &SCons; team
 111     tries to follow in the design and implementation.
 112
 113     </para>
 114
 115     <variablelist>
 116
 117       <varlistentry>
 118       <term>Correctness</term>
 119
 120       <listitem>
 121       <para>
 122
 123       First and foremost,
 124       by default, &SCons; guarantees a correct build
 125       even if it means sacrificing performance a little.
 126       We strive to guarantee the build is correct
 127       regardless of how the software being built is structured,
 128       how it may have been written,
 129       or how unusual the tools are that build it.
 130
 131       </para>
 132       </listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136       <term>Performance</term>
 137
 138       <listitem>
 139       <para>
 140
 141       Given that the build is correct,
 142       we try to make &SCons; build software
 143       as quickly as possible.
 144       In particular, wherever we may have needed to slow
 145       down the default &SCons; behavior to guarantee a correct build,
 146       we also try to make it easy to speed up &SCons;
 147       through optimization options that let you trade off
 148       guaranteed correctness in all end cases for
 149       a speedier build in the usual cases.
 150
 151       </para>
 152       </listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156       <term>Convenience</term>
 157
 158       <listitem>
 159       <para>
 160
 161       &SCons; tries to do as much for you out of the box as reasonable,
 162       including detecting the right tools on your system
 163       and using them correctly to build the software.
 164
 165       </para>
 166       </listitem>
 167       </varlistentry>
 168
 169     </variablelist>
 170
 171     <para>
 172
 173     In a nutshell, we try hard to make &SCons; just
 174     "do the right thing" and build software correctly,
 175     with a minimum of hassles.
 176
 177     </para>
 178
 179   </section>
 180
 181   <!--
 182
 183   <section>
 184   <title>Conventions</title>
 185
 186     <para>
 187
 188     XXX conventions used in this guide
 189
 190     </para>
 191
 192   </section>
 193
 194   -->
 195
 196   <section>
 197   <title>How to Use this Guide</title>
 198
 199     <para>
 200
 201     This guide intends to coach you how to use &SCons; effectively
 202     and efficiently, by providing a range of examples and usage scenarios.
 203     As such it is not exactly a tutorial (as usually those build
 204     a single example topic from start to finish), but if you are
 205     just starting with &SCons; it <emphasis>is</emphasis> recommended
 206     you step through the first 10 chapters
 207     in sequence as this will give a solid
 208     grounding in the principles of working with &SCons;.
 209     If you follow that trail, you can feel free to initially skip
 210     sections on extending &SCons;, such as
 211     <emphasis>Writing your own Decider Function</emphasis>,
 212     and come back to those if the need arises.
 213
 214     </para>
 215
 216     <para>
 217
 218     The remaining chapters cover more advanced topics that not all
 219     build systems will need, and can be used in more of a single-topic
 220     way, to read if you find you need that particular information.
 221
 222     </para>
 223
 224     <para>
 225
 226     It is often useful to keep &SCons; man page open in a separate
 227     browser tab or window to refer to as a complement to this Guide,
 228     as the User Guide does not attempt to provide every detail.
 229     While this Guide's Appendices A-D do duplicate information that appears
 230     in the man page (this is to allow intra-document links to
 231     definitions of &consvars;, builders, tools and environment methods
 232     to work), the rest of the man page is unique content.
 233
 234     </para>
 235
 236   </section>
 237
 238   <section>
 239   <title>A Caveat About This Guide's Completeness</title>
 240
 241   <para>
 242
 243   &SCons; is a volunteer-run open source project.
 244   As such, the &SCons; documentation isn't always
 245   completely up-to-date with all the available features -
 246   somehow it's almost harder to write high quality, easy to
 247   use documentation than it is to implement a feature in software.
 248   In other words, there may be  a lot that &SCons; can do that
 249   isn't yet covered in this User's Guide.
 250
 251   </para>
 252
 253   <para>
 254
 255   Although this User's Guide may not be as complete as it could be,
 256   the development process does emphasize
 257   making sure that the &SCons; man page is kept up-to-date
 258   with new features.
 259   So if you're trying to figure out how to do something
 260   that &SCons; supports
 261   but can't find enough (or any) information here,
 262   it would be worth your while to look
 263   at the man page to see if the information is covered there.
 264   And if you do,
 265   maybe you'd even consider contributing
 266   a section to the User's Guide
 267   so the next person looking for
 268   that information won't have to
 269   go through the same thing...?
 270
 271   </para>
 272
 273   </section>
 274
 275   <section>
 276   <title>Acknowledgements</title>
 277
 278     <para>
 279
 280     &SCons; would not exist without a lot of help
 281     from a lot of people,
 282     many of whom may not even be aware
 283     that they helped or served as inspiration.
 284     So in no particular order,
 285     and at the risk of leaving out someone:
 286
 287     </para>
 288
 289     <para>
 290
 291     First and foremost,
 292     &SCons; owes a tremendous debt to Bob Sidebotham,
 293     the original author of the classic Perl-based &Cons; tool
 294     which Bob first released to the world back around 1996.
 295     Bob's work on Cons classic provided the underlying architecture
 296     and model of specifying a build configuration
 297     using a real scripting language.
 298     My real-world experience working on Cons
 299     informed many of the design decisions in SCons,
 300     including the improved parallel build support,
 301     making Builder objects easily definable by users,
 302     and separating the build engine from the wrapping interface.
 303
 304     </para>
 305
 306     <para>
 307
 308     Greg Wilson was instrumental in getting
 309     &SCons; started as a real project
 310     when he initiated the Software Carpentry design
 311     competition in February 2000.
 312     Without that nudge,
 313     marrying the advantages of the Cons classic
 314     architecture with the readability of Python
 315     might have just stayed no more than a nice idea.
 316
 317     </para>
 318
 319     <para>
 320
 321     The entire &SCons; team have been
 322     absolutely wonderful to work with,
 323     and &SCons; would be nowhere near as useful a
 324     tool without the energy, enthusiasm
 325     and time people have contributed over the past few years.
 326     The "core team"
 327     of Chad Austin, Anthony Roach,
 328     Bill Deegan, Charles Crain, Steve Leblanc, Greg Noel,
 329     Gary Oberbrunner, Greg Spencer and Christoph Wiedemann
 330     have been great about reviewing my (and other) changes
 331     and catching problems before they get in the code base.
 332     Of particular technical note:
 333     Anthony's outstanding and innovative work on the tasking engine
 334     has given &SCons; a vastly superior parallel build model;
 335     Charles has been the master of the crucial Node infrastructure;
 336     Christoph's work on the Configure infrastructure
 337     has added crucial Autoconf-like functionality;
 338     and Greg has provided excellent support
 339     for Microsoft Visual Studio.
 340
 341     </para>
 342
 343     <para>
 344
 345     Special thanks to David Snopek for contributing
 346     his underlying "Autoscons" code that formed
 347     the basis of Christoph's work with the Configure functionality.
 348     David was extremely generous in making
 349     this code available to &SCons;,
 350     given that he initially released it under the GPL
 351     and &SCons; is released under a less-restrictive MIT-style license.
 352
 353     </para>
 354
 355     <!--
 356
 357     <para>
 358
 359     &SCons; has received contributions
 360     from many other people, of course:
 361     Matt Balvin (extending long command-line support on Windows),
 362     Allen Bierbaum (extensions and fixes to Options),
 363     Steve Christensen (help text sorting and function action signature fixes),
 364     Michael Cook (avoiding losing signal bits from executed commands),
 365     Derrick 'dman' Hudson (),
 366     Alex Jacques (work on the Windows scons.bat file),
 367     Stephen Kennedy (performance enhancements),
 368     Lachlan O'Dea (SharedObject() support for masm
 369     and normalized paths for the WhereIs() function),
 370     Damyan Pepper (keeping output like Make),
 371     Jeff Petkau (significant fixes for CacheDir and other areas),
 372     Stefan Reichor (Ghostscript support),
 373     Zed Shaw (Append() and Replace() environment methods),
 374     Terrel Shumway (build and test fixes, as well as the SCons Wiki)
 375     and
 376     sam th (dynamic checks for utilities).
 377
 378     </para>
 379
 380     -->
 381
 382     <para>
 383
 384     Thanks to Peter Miller
 385     for his splendid change management system, &Aegis;,
 386     which has provided the &SCons; project
 387     with a robust development methodology from day one,
 388     and which showed me how you could
 389     integrate incremental regression tests into
 390     a practical development cycle
 391     (years before eXtreme Programming arrived on the scene).
 392
 393     </para>
 394
 395     <para>
 396
 397     And last, thanks to Guido van Rossum
 398     for his elegant scripting language,
 399     which is the basis not only for the &SCons; implementation,
 400     but for the interface itself.
 401
 402     </para>
 403
 404   </section>
 405
 406   <section>
 407   <title>Contact</title>
 408
 409     <para>
 410
 411     The best way to contact people involved with SCons,
 412     is through the SCons mailing lists.
 413
 414     </para>
 415
 416     <para>
 417
 418     If you want to ask general questions about how to use &SCons;
 419     send email to &scons-users;.
 420
 421     </para>
 422
 423     <para>
 424
 425     If you want to contact the &SCons; development community directly,
 426     send email to &scons-devel;.
 427
 428     </para>
 429
 430     <para>
 431
 432     For quicker, informal questions, discussion, etc. the project
 433     operated a Discord server at
 434     <ulink url="https://discord.gg/bXVpWAy"/>
 435     and a Libera.chat IRC channel at
 436     <ulink url="https://web.libera.chat/#scons"/>
 437     (the former channel at irc.freenode.net is now unused).
 438     Certain discussions may also be moved by administrators from
 439     mailing list or chat to
 440     <ulink url="https://github.com/SCons/scons/discussions">
 441     GitHub Discussions</ulink> for greater permanence and easier
 442     finding.
 443
 444     </para>
 445
 446   </section>
 447
 448 </preface>