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 Thank you for taking the time to read about &SCons;.
29 &SCons; is a next-generation
30 software construction tool,
31 or make tool--that is, a software utility
32 for building software (or other files)
33 and keeping built software up-to-date
34 whenever the underlying input files change.
40 The most distinctive thing about &SCons;
41 is that its configuration files are
42 actually <emphasis>scripts</emphasis>,
43 written in the &Python; programming language.
44 This is in contrast to most alternative build tools,
45 which typically invent a new language to
47 &SCons; still has a learning curve, of course,
48 because you have to know what functions to call
49 to set up your build properly,
50 but the underlying syntax used should be familiar
51 to anyone who has ever looked at a Python script.
58 using Python as the configuration file format
60 <emphasis>easier</emphasis>
61 for non-programmers to learn
62 than the cryptic languages of other build tools,
63 which are usually invented by programmers for other programmers.
64 This is in no small part due to the
65 consistency and readability that are hallmarks of Python.
66 It just so happens that making a real, live
67 scripting language the basis for the
69 makes it a snap for more accomplished programmers
70 to do more complicated things with builds,
78 <title>Why &SCons;?</title>
82 &SCons; is a response to a perennial problem:
83 building software is harder than it should be.
84 In a nutshell: the old, reliable model of the
85 venerable and ubiquitous &Make; program
86 has had a hard time keeping up with
87 how complicated building software has become.
88 The fact that &Make; has kept up as well as it has is impressive,
89 and a testament to how the simplicity.
90 But anyone who has wrestled with &Automake; and &Autoconf;
91 to try to guarantee that a bit of software
92 will build correctly on multiple platforms
93 can tell you that it takes a lot of work to get right.
102 <title>&SCons; Principles</title>
106 There are a few overriding principles
107 we try to live up to in designing and implementing &SCons:
114 <term>Correctness</term>
120 by default, &SCons; guarantees a correct build
121 even if it means sacrificing performance a little.
122 We strive to guarantee the build is correct
123 regardless of how the software being built is structured,
124 how it may have been written,
125 or how unusual the tools are that build it.
132 <term>Performance</term>
137 Given that the build is correct,
138 we try to make &SCons; build software
139 as quickly as possible.
140 In particular, wherever we may have needed to slow
141 down the default &SCons; behavior to guarantee a correct build,
142 we also try to make it easy to speed up &SCons;
143 through optimization options that let you trade off
144 guaranteed correctness in all end cases for
145 a speedier build in the usual cases.
152 <term>Convenience</term>
157 &SCons; tries to do as much for you out of the box as reasonable,
158 including detecting the right tools on your system
159 and using them correctly to build the software.
169 In a nutshell, we try hard to make &SCons; just
170 "do the right thing" and build software correctly,
171 with a minimum of hassles.
180 <title>History</title>
184 &SCons; originated with a design
185 that was submitted to the Software Carpentry
186 design competition in 2000.
192 &SCons; is the direct descendant
193 of a Perl utility called &Cons;.
194 &Cons; in turn based some of its ideas on &Jam;,
195 a build tool from Perforce Systems.
212 <title>Conventions</title>
216 XXX conventions used in this manual
225 <title>A Caveat About This Guide's Completeness</title>
229 One word of warning as you read through this Guide:
230 Like too much Open Source software out there,
231 the &SCons; documentation isn't always
232 kept up-to-date with the available features.
234 there's a lot that &SCons; can do that
235 isn't yet covered in this User's Guide.
236 (Come to think of it,
237 that also describes a lot of proprietary software, doesn't it?)
243 Although this User's Guide isn't as complete as we'd like it to be,
244 our development process does emphasize
245 making sure that the &SCons; man page is kept up-to-date
247 So if you're trying to figure out how to do something
248 that &SCons; supports
249 but can't find enough (or any) information here,
250 it would be worth your while to look
251 at the man page to see if the information is covered there.
253 maybe you'd even consider contributing
254 a section to the User's Guide
255 so the next person looking for
256 that information won't have to
257 go through the same thing...?
264 <title>Acknowledgements</title>
268 &SCons; would not exist without a lot of help
269 from a lot of people,
270 many of whom may not even be aware
271 that they helped or served as inspiration.
272 So in no particular order,
273 and at the risk of leaving out someone:
280 &SCons; owes a tremendous debt to Bob Sidebotham,
281 the original author of the classic Perl-based &Cons; tool
282 which Bob first released to the world back around 1996.
283 Bob's work on Cons classic provided the underlying architecture
284 and model of specifying a build configuration
285 using a real scripting language.
286 My real-world experience working on Cons
287 informed many of the design decisions in SCons,
288 including the improved parallel build support,
289 making Builder objects easily definable by users,
290 and separating the build engine from the wrapping interface.
296 Greg Wilson was instrumental in getting
297 &SCons; started as a real project
298 when he initiated the Software Carpentry design
299 competition in February 2000.
301 marrying the advantages of the Cons classic
302 architecture with the readability of Python
303 might have just stayed no more than a nice idea.
309 The entire &SCons; team have been
310 absolutely wonderful to work with,
311 and &SCons; would be nowhere near as useful a
312 tool without the energy, enthusiasm
313 and time people have contributed over the past few years.
315 of Chad Austin, Anthony Roach,
316 Bill Deegan, Charles Crain, Steve Leblanc, Greg Noel,
317 Gary Oberbrunner, Greg Spencer and Christoph Wiedemann
318 have been great about reviewing my (and other) changes
319 and catching problems before they get in the code base.
320 Of particular technical note:
321 Anthony's outstanding and innovative work on the tasking engine
322 has given &SCons; a vastly superior parallel build model;
323 Charles has been the master of the crucial Node infrastructure;
324 Christoph's work on the Configure infrastructure
325 has added crucial Autoconf-like functionality;
326 and Greg has provided excellent support
327 for Microsoft Visual Studio.
333 Special thanks to David Snopek for contributing
334 his underlying "Autoscons" code that formed
335 the basis of Christoph's work with the Configure functionality.
336 David was extremely generous in making
337 this code available to &SCons;,
338 given that he initially released it under the GPL
339 and &SCons; is released under a less-restrictive MIT-style license.
347 &SCons; has received contributions
348 from many other people, of course:
349 Matt Balvin (extending long command-line support on Windows),
350 Allen Bierbaum (extensions and fixes to Options),
351 Steve Christensen (help text sorting and function action signature fixes),
352 Michael Cook (avoiding losing signal bits from executed commands),
353 Derrick 'dman' Hudson (),
354 Alex Jacques (work on the Windows scons.bat file),
355 Stephen Kennedy (performance enhancements),
356 Lachlan O'Dea (SharedObject() support for masm
357 and normalized paths for the WhereIs() function),
358 Damyan Pepper (keeping output like Make),
359 Jeff Petkau (significant fixes for CacheDir and other areas),
360 Stefan Reichor (Ghostscript support),
361 Zed Shaw (Append() and Replace() environment methods),
362 Terrel Shumway (build and test fixes, as well as the SCons Wiki)
364 sam th (dynamic checks for utilities).
372 Thanks to Peter Miller
373 for his splendid change management system, &Aegis;,
374 which has provided the &SCons; project
375 with a robust development methodology from day one,
376 and which showed me how you could
377 integrate incremental regression tests into
378 a practical development cycle
379 (years before eXtreme Programming arrived on the scene).
385 And last, thanks to Guido van Rossum
386 for his elegant scripting language,
387 which is the basis not only for the &SCons; implementation,
388 but for the interface itself.
395 <title>Contact</title>
399 The best way to contact people involved with SCons,
400 including the author,
401 is through the SCons mailing lists.
407 If you want to ask general questions about how to use &SCons;
408 send email to &scons-users;.
414 If you want to contact the &SCons; development community directly,
415 send email to &scons-devel;.
421 If you want to receive announcements about &SCons,
422 join the low-volume &scons-announce; mailing list.