SCons Users Guidei Recommended Readings

This list looks like it's a lot, but if you drop 7.2 and chapter 16, the average length of each linked section is probably about 1/3 the length of this list. So it's not as bad as all that.

More important topics

• 2.1, 2.2, 3.1, 3.2, 3.5. These sections show some extremely simple targets. (3.5 is less important because it's probably pretty clear what's going on anyway, but we use this shortcut all over the place, so I'll stick it in here.)
• 2.4. This shows that SCons "infers" something like a clean target automatically, based on what targets you provide, when you run scons -c. (It is also possible to specify additional files to be cleaned and instruct SCons to not remove a file. Good to know these exist but those sections aren't "required reading".)
• 4.2, 4.3. These two sections show you how to link against libraries. The first shows you how to tell SCons to pass -l to the linker and the second shows you how to tell SCons to pass -L flags. (In both cases, using these mechanisms rather than putting -lfoo in the LINKFLAGS variable directly is better. First, it it abstracts away platform-specific information (e.g. -Lfoo/bar or /LIBPATH:foo/bar?). Second, it allows SCons to track whether the library that's being linked in changed, so you don't have to say "pass -lfoo when linking, and also this target depends on foo.so". Less important for system libraries, but is very nice if you are building a library then linking against it in one script.)
• 5.1. If you have one target that produces a file that is then used as an input in a later build step, you can just use the same name for both. This is cleaner, for a couple reasons. We use this all over the place in both builds.
• Chapter 7's intro, for the definition of the three kinds of environments. However, you should ignore the last two paragraphs; that bit about SCons doesn't passing environment variables from SCons's parent shell to the programs it runs doesn't apply to either of our builds. (SCons's goal of builds that are more easily reproduced because they don't need the user's environment set just-so is admirable, but it introduces a whole host of other problems in some environments. Especially for the regression scripts, it's way more reasonable to just import it, so we do.)
• 7.2. This is a long one, but it's the first of two really key parts. Only the most trivial builds can reasonably be done without explicit construction environments. In particular, you should read:
  • The section introduction for, well, an introduction
  • 7.2.1, 7.2.2 for the basics
  • 7.2.6, 7.2.7. Talks about copying construction environments. In the regression scripts, we make a copy of the main construction environment each time we call an SConscript in a test directory. (That last bit may not make sense until you read the next recommended chapter.)
  • 7.2.10. Sort of a convenience method that we use in the McVeto build.
• 12.3.2. This discusses how to tell SCons what targets to build when the user doesn't explicitly specify any on the command line. By default, SCons builds all of them. (This is in contrast to make, which builds only the first.)
• Chapter 16, the whole thing. (You'll have to follow the links there to the subsequent sections.) Another longer one, but it's the other key item in this list. It discusses how to do builds that span directories. (It's like either recursive make or make %include directives, except... better.) The one exception is that we don't use absolute paths as discussed in 16.4, not that it's exactly a complex topic.
• Chapter 20 (there's only one section). SCons provides "builders" for a lot of common tasks that save you from specifying some boilerplate command lines; probably all the build scripts you've seen so far use these. (This is somewhat similar in concept to make's built-in implicit rules, except that which rule you use is determined by which builder function you call rather than by file extension and they don't automatically apply to any file of the appropriate name.) If you want to run a command that there's no pre-build builder for, you can use the command builder to specify an actual command to run. You can also pass a Python function to call as the command, or even a list of things to do (any mix of command strings and Python functions).
• 23.1 and 23.2 describe the Repository function, which is pretty central to the way that the McVeto build operates. Unfortunately, through a combination of us probably not using the feature exactly as intended, the docs not being super clear, and the name Repository not being particularly clear, this will probably just serve to confuse you more. Instead, you should read section 4.3.1 of this description of make's VPATH variable. Now go read those two sections about Repository with the mindset that we are using it like VPATH. (Note: it's possible that the post-reorg changes will allow us to remove our use of Repository.)

Less important topics

After going through this list you'll have sufficient background to understand almost anything we're doing that has to do with SCons. (There's a lot of raw Python in there too for parsing assembly listings, getting keywords, and a bunch of other stuff like that. There are also a couple things from SCons that we use that won't have been covered.)

• Chapter 6 intro through the end of 6.1.1. This doesn't discuss anything that has to do with our scripts really, but explains behavior. In particular, it talks about the fact that SCons uses MD5 sums of files instead of timestamps to determine whether a target is out of date or not. In practice I rather like this better, but if you're used to make and being able to just touch a file to get it to rebuild everything that depends on it, this explains why that won't work.
• 6.3. One of the big benefits that you get with SCons over make is automatic and implicit tracking of #include files. (No more make depends in other words, with all the problems those solutions bring.) This section explains that, and explains how you can tell SCons where it can find the files that are included (so it can both determine whether the headers have changed as well as scan the headers for transitive dependencies itself).
• 6.5. Occasionally, you have to tell SCons that one target depends on another target or a file if it doesn't have a way of knowing that itself. The Depends function does this.
• 6.9. The AlwaysBuild function allows you to make pseudo-targets; that is, targets that don't actually produce any files as output. (It's very much like make's .PSEUDO pseudo-target.) The name is slightly misleading; these targets aren't always built, just whenever they appear on the dependency path to whatever the user wanted. A more accurate description is to say that it tells SCons to always consider the given target out of date.
• 7.3.1. Discusses how to make sure that SCons's parent shell's environment makes its way to the processes SCons spawns to do the actual work. (In particular, we do the second thing in that section.)
• 12.2 through the end of 12.2.2. This explains how SCons lets you introduce command line options, like keyword=cav10 or arch=ppc32. (Note however that the options that eventually are passed to McVeto itself, e.g. dash_break or dash_ubt, are wrapped in an extra layer of abstraction because they are used multiple times.)
• 12.1.5. This is an alternative command line option mechanism. It's used instead of the previous one in the McVeto build script.
• 14's intro and 14.1, 14.2, 14.3, 14.5. These show you how you can do file system operatons (copy, delete, move, mkdir, respectively) in a system-independent way. Simple stuff, but we use them in the regression scripts and there's at least one somewhat unintutive interface characteristic.
• Chapter 19's intro and 19.1, 19.2, 19.4, 19.7. These describe how to write your own builders. Remember how you could use the Command builder to actually execute a shell command if none of the built-in builders worked? If you're going to be executing that command a lot (i.e. from several static places in the code) then you should consider wrapping it in a builder. This shows you how.
• Chapter 21 (just one section). This describes how to create "pseudo-builders", which are environment functions that "look like" builders but technically aren't. In the regression scripts, we create several of these, including the all-important AllMcdashTargets function that you call from the test-specific SConscript files.
• Chapter 26 (just one section). This describes alias targets, which let you give a friendly name to, one or more target. (Something like the "all" or "doc" targets from make would be translated to an alias in scons.) We use them in the regressions to create a few names for user consumption, including the typical "listings" and "report" targets.