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 id="sect-principles">
 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 id="sect-using-guide">
 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     If you are viewing an html version of this Guide, there are many
 227     hyperlinks present that you can follow to get more details
 228     if you want them, as the User Guide intentionally does not attempt
 229     to provide every detail, to allow smoother study of the basics.
 230     It may also be useful to keep the &SCons; man page open in a separate
 231     browser tab or window to refer to as a complement to this Guide,
 232     which can avoid some jumping back and forth.
 233     The four important manpage sections describiing the
 234     of &consvars;, builders, tools and environment methods
 235     are actually duplicated as appendices in the User Guide,
 236     to avoid inter-document links.
 237
 238     </para>
 239
 240   </section>
 241
 242   <section id="sect-completeness">
 243   <title>A Caveat About This Guide's Completeness</title>
 244
 245   <para>
 246
 247   &SCons; is a volunteer-run open source project.
 248   As such, the &SCons; documentation isn't always
 249   completely up-to-date with all the available features -
 250   somehow it's almost harder to write high quality, easy to
 251   use documentation than it is to implement a feature in software.
 252   In other words, there may be  a lot that &SCons; can do that
 253   isn't yet covered in this User's Guide.
 254
 255   </para>
 256
 257   <para>
 258
 259   Although this User's Guide may not be as complete as it could be,
 260   the development process does emphasize
 261   making sure that the &SCons; man page is kept up-to-date
 262   with new features.
 263   So if you're trying to figure out how to do something
 264   that &SCons; supports
 265   but can't find enough (or any) information here,
 266   it would be worth your while to look
 267   at the man page to see if the information is covered there.
 268   And if you do,
 269   maybe you'd even consider contributing
 270   a section to the User's Guide
 271   so the next person looking for
 272   that information won't have to
 273   go through the same thing...?
 274
 275   </para>
 276
 277   </section>
 278
 279   <section id="sect-acknowledgements">
 280   <title>Acknowledgements</title>
 281
 282     <para>
 283
 284     &SCons; would not exist without a lot of help
 285     from a lot of people,
 286     many of whom may not even be aware
 287     that they helped or served as inspiration.
 288     So in no particular order,
 289     and at the risk of leaving out someone:
 290
 291     </para>
 292
 293     <para>
 294
 295     First and foremost,
 296     &SCons; owes a tremendous debt to Bob Sidebotham,
 297     the original author of the classic Perl-based &Cons; tool
 298     which Bob first released to the world back around 1996.
 299     Bob's work on Cons classic provided the underlying architecture
 300     and model of specifying a build configuration
 301     using a real scripting language.
 302     My real-world experience working on Cons
 303     informed many of the design decisions in SCons,
 304     including the improved parallel build support,
 305     making Builder objects easily definable by users,
 306     and separating the build engine from the wrapping interface.
 307
 308     </para>
 309
 310     <para>
 311
 312     Greg Wilson was instrumental in getting
 313     &SCons; started as a real project
 314     when he initiated the Software Carpentry design
 315     competition in February 2000.
 316     Without that nudge,
 317     marrying the advantages of the Cons classic
 318     architecture with the readability of Python
 319     might have just stayed no more than a nice idea.
 320
 321     </para>
 322
 323     <para>
 324
 325     The entire &SCons; team have been
 326     absolutely wonderful to work with,
 327     and &SCons; would be nowhere near as useful a
 328     tool without the energy, enthusiasm
 329     and time people have contributed over the past few years.
 330     The "core team"
 331     of Chad Austin, Anthony Roach,
 332     Bill Deegan, Charles Crain, Steve Leblanc, Greg Noel,
 333     Gary Oberbrunner, Greg Spencer and Christoph Wiedemann
 334     have been great about reviewing my (and other) changes
 335     and catching problems before they get in the code base.
 336     Of particular technical note:
 337     Anthony's outstanding and innovative work on the tasking engine
 338     has given &SCons; a vastly superior parallel build model;
 339     Charles has been the master of the crucial Node infrastructure;
 340     Christoph's work on the Configure infrastructure
 341     has added crucial Autoconf-like functionality;
 342     and Greg has provided excellent support
 343     for Microsoft Visual Studio.
 344
 345     </para>
 346
 347     <para>
 348
 349     Special thanks to David Snopek for contributing
 350     his underlying "Autoscons" code that formed
 351     the basis of Christoph's work with the Configure functionality.
 352     David was extremely generous in making
 353     this code available to &SCons;,
 354     given that he initially released it under the GPL
 355     and &SCons; is released under a less-restrictive MIT-style license.
 356
 357     </para>
 358
 359     <!--
 360
 361     <para>
 362
 363     &SCons; has received contributions
 364     from many other people, of course:
 365     Matt Balvin (extending long command-line support on Windows),
 366     Allen Bierbaum (extensions and fixes to Options),
 367     Steve Christensen (help text sorting and function action signature fixes),
 368     Michael Cook (avoiding losing signal bits from executed commands),
 369     Derrick 'dman' Hudson (),
 370     Alex Jacques (work on the Windows scons.bat file),
 371     Stephen Kennedy (performance enhancements),
 372     Lachlan O'Dea (SharedObject() support for masm
 373     and normalized paths for the WhereIs() function),
 374     Damyan Pepper (keeping output like Make),
 375     Jeff Petkau (significant fixes for CacheDir and other areas),
 376     Stefan Reichor (Ghostscript support),
 377     Zed Shaw (Append() and Replace() environment methods),
 378     Terrel Shumway (build and test fixes, as well as the SCons Wiki)
 379     and
 380     sam th (dynamic checks for utilities).
 381
 382     </para>
 383
 384     -->
 385
 386     <para>
 387
 388     Thanks to Peter Miller
 389     for his splendid change management system, &Aegis;,
 390     which has provided the &SCons; project
 391     with a robust development methodology from day one,
 392     and which showed me how you could
 393     integrate incremental regression tests into
 394     a practical development cycle
 395     (years before eXtreme Programming arrived on the scene).
 396
 397     </para>
 398
 399     <para>
 400
 401     And last, thanks to Guido van Rossum
 402     for his elegant scripting language &Python;,
 403     which is the basis not only for the &SCons; implementation,
 404     but for the interface itself.
 405
 406     </para>
 407
 408   </section>
 409
 410   <section id="sect-contact">
 411   <title>Contact</title>
 412
 413     <para>
 414
 415     The best way to contact people involved with SCons,
 416     is through the SCons mailing lists.
 417
 418     </para>
 419
 420     <para>
 421
 422     If you want to ask general questions about how to use &SCons;
 423     send email to &scons-users;.
 424
 425     </para>
 426
 427     <para>
 428
 429     If you want to contact the &SCons; development community directly,
 430     send email to &scons-devel;.
 431
 432     </para>
 433
 434     <para>
 435
 436     For quicker, informal questions, discussion, etc. the project
 437     operated a Discord server at
 438     <ulink url="https://discord.gg/bXVpWAy"/>
 439     and a Libera.chat IRC channel at
 440     <ulink url="https://web.libera.chat/#scons"/>
 441     (the former channel at irc.freenode.net is now unused).
 442     Certain discussions may also be moved by administrators from
 443     mailing list or chat to
 444     <ulink url="https://github.com/SCons/scons/discussions">
 445     GitHub Discussions</ulink> for greater permanence and easier
 446     finding.
 447
 448     </para>
 449
 450   </section>
 451
 452 </preface>