SCons Developer Guide

This is the SCons Developer's Guide. Start here to learn how to add to SCons and learn how it works under the hood.

• Introduction
• Getting the source

  • Mercurial checkout

  • Branch structure

  • Source tree organization

• Getting the source (2011, after we transition to Mercurial)

  • hg clone https://bitbucket.org/scons/scons

  • See SconsMercurialWorkflows for more

• Hacking on the source
  • META: do you really need to?
    • Writing builders, wrappers, and subclassing (don't need to change source)
    • Using scons_dir for extensions
  • Running from the source tree

  • DebuggingScons

• Contributing

  • Development model

  • Mailing lists (hammering out an idea before jumping in)

  • Easy issues to fix from our Tigris bug tracker

  • Documentation

  • Writing and debugging tests

  • Performance

  • Submitting patches (using the issue tracker)

  • Preparing a patch for review on the developer ML

  • Packaging

  • Getting write access (for serious developers)

• Architecture

  • Installation (the way SCons is meant to be found)

  • Initialization (processing the command line and option files)

  • Nodes (Dir, File, Value, ...)

  • Signatures

  • Determining configuration
  • Environments and what they encapsulate
  • Tools
  • Building blocks for scripting (Commands, Actions, Builders, Emitters, ...)
  • Parsing the SConscripts
  • Node management (building the DAG)

  • TaskMaster

    • Running the DAG
    • Scanning for implicit dependencies
    • Dealing with signatures

  • Statistics (for debugging and performance measurement)

• Overview of Modules and Classes

• Improvement ideas

  • SummerOfCodeIdeas

Other resources:

• The man page, especially the Extending SCons section.

• Be sure to check out the developer guidelines

• "Use the source, Luke"

• DevelopingTests - tips on writing and debugging tests.

• SconsBuildRequirements

• JavaSupport

• LatexSupport (and TeX)

• VisualizeDependencies - display of large source graphs (DOT format) with yEd

?

This is a work in progress. Click on the "Edit(Text)" link below, and let's start discussing what needs to go in this guide.

• There is a chmod Action Function. We could use a chgrp one as well, for doing installations on a network drive. That should be easy to add, but would it be portable? Maybe it could be a no-op on some systems.
• Why is the previous item here? Should it be removed? [JGN 19 Jan 2007]
• Known topic with no place to live yet: .sconsign. The architecture section is organized more-or-less in time order and this topic doesn't fit that particularly well. [JGN 19 Jan 2007]
• I put in links for sections that I thought were pretty solid, but there are a number of areas where the topics are still flexible. Someone with more knowledge of the internals should clarify those aspects. [JGN 19 Jan 2007]