SCons User Guide 1.1.0

Steven Knight

version 1.1.0

Table of Contents
Preface
SCons Principles
A Caveat About This Guide's Completeness
Acknowledgements
Contact
Building and Installing SCons
Installing Python
Installing SCons From Pre-Built Packages
Installing SCons on Red Hat (and Other RPM-based) Linux Systems
Installing SCons on Debian Linux Systems
Installing SCons on Windows Systems
Building and Installing SCons on Any System
Building and Installing Multiple Versions of SCons Side-by-Side
Installing SCons in Other Locations
Building and Installing SCons Without Administrative Privileges
Simple Builds
Building Simple C / C++ Programs
Building Object Files
Simple Java Builds
Cleaning Up After a Build
The SConstruct File
SConstruct Files Are Python Scripts
SCons Functions Are Order-Independent
Making the SCons Output Less Verbose
Less Simple Things to Do With Builds
Specifying the Name of the Target (Output) File
Compiling Multiple Source Files
Making a list of files with Glob
Specifying Single Files Vs. Lists of Files
Making Lists of Files Easier to Read
Keyword Arguments
Compiling Multiple Programs
Sharing Source Files Between Multiple Programs
Building and Linking with Libraries
Building Libraries
Building Libraries From Source Code or Object Files
Building Static Libraries Explicitly: the StaticLibrary Builder
Building Shared (DLL) Libraries: the SharedLibrary Builder
Linking with Libraries
Finding Libraries: the $LIBPATH Construction Variable
Node Objects
Builder Methods Return Lists of Target Nodes
Explicitly Creating File and Directory Nodes
Printing Node File Names
Using a Node's File Name as a String
Dependencies
Deciding When an Input File Has Changed: the Decider Function
Using MD5 Signatures to Decide if a File Has Changed
Using Time Stamps to Decide If a File Has Changed
Deciding If a File Has Changed Using Both MD Signatures and Time Stamps
Writing Your Own Custom Decider Function
Mixing Different Ways of Deciding If a File Has Changed
Older Functions for Deciding When an Input File Has Changed
The SourceSignatures Function
The TargetSignatures Function
Implicit Dependencies: The $CPPPATH Construction Variable
Caching Implicit Dependencies
The --implicit-deps-changed Option
The --implicit-deps-unchanged Option
Explicit Dependencies: the Depends Function
Dependencies From External Files: the ParseDepends Function
Ignoring Dependencies: the Ignore Function
Order-Only Dependencies: the Requires Function
The AlwaysBuild Function
Environments
Using Values From the External Environment
Construction Environments
Creating a Construction Environment: the Environment Function
Fetching Values From a Construction Environment
Expanding Values From a Construction Environment: the subst Method
Controlling the Default Construction Environment: the DefaultEnvironment Function
Multiple Construction Environments
Making Copies of Construction Environments: the Clone Method
Replacing Values: the Replace Method
Setting Values Only If They're Not Already Defined: the SetDefault Method
Appending to the End of Values: the Append Method
Appending Unique Values: the AppendUnique Method
Appending to the Beginning of Values: the Prepend Method
Prepending Unique Values: the PrependUnique Method
Controlling the Execution Environment for Issued Commands
Propagating PATH From the External Environment
Adding to PATH Values in the Execution Environment
Merging Options into the Environment: the MergeFlags Function
Separating Compile Arguments into their Variables: the ParseFlags Function
Finding Installed Library Information: the ParseConfig Function
Controlling Build Output
Providing Build Help: the Help Function
Controlling How SCons Prints Build Commands: the $*COMSTR Variables
Providing Build Progress Output: the Progress Function
Printing Detailed Build Status: the GetBuildFailures Function
Controlling a Build From the Command Line
Command-Line Options
Not Having to Specify Command-Line Options Each Time: the SCONSFLAGS Environment Variable
Getting Values Set by Command-Line Options: the GetOption Function
Setting Values of Command-Line Options: the SetOption Function
Strings for Getting or Setting Values of SCons Command-Line Options
Adding Custom Command-Line Options: the AddOption Function
Command-Line variable=value Build Variables
Controlling Command-Line Build Variables
Providing Help for Command-Line Build Variables
Reading Build Variables From a File
Pre-Defined Build Variable Functions
Adding Multiple Command-Line Build Variables at Once
Handling Unknown Command-Line Build Variables: the UnknownVariables Function
Command-Line Targets
Fetching Command-Line Targets: the COMMAND_LINE_TARGETS Variable
Controlling the Default Targets: the Default Function
Fetching the List of Build Targets, Regardless of Origin: the BUILD_TARGETS Variable
Installing Files in Other Directories: the Install Builder
Installing Multiple Files in a Directory
Installing a File Under a Different Name
Installing Multiple Files Under Different Names
Platform-Independent File System Manipulation
Copying Files or Directories: The Copy Factory
Deleting Files or Directories: The Delete Factory
Moving (Renaming) Files or Directories: The Move Factory
Updating the Modification Time of a File: The Touch Factory
Creating a Directory: The Mkdir Factory
Changing File or Directory Permissions: The Chmod Factory
Executing an action immediately: the Execute Function
Controlling Removal of Targets
Preventing target removal during build: the Precious Function
Preventing target removal during clean: the NoClean Function
Removing additional files during clean: the Clean Function
Hierarchical Builds
SConscript Files
Path Names Are Relative to the SConscript Directory
Top-Level Path Names in Subsidiary SConscript Files
Absolute Path Names
Sharing Environments (and Other Variables) Between SConscript Files
Exporting Variables
Importing Variables
Returning Values From an SConscript File
Separating Source and Build Directories
Specifying a Variant Directory Tree as Part of an SConscript Call
Why SCons Duplicates Source Files in a Variant Directory Tree
Telling SCons to Not Duplicate Source Files in the Variant Directory Tree
The VariantDir Function
Using VariantDir With an SConscript File
Using Glob with VariantDir
Variant Builds
Writing Your Own Builders
Writing Builders That Execute External Commands
Attaching a Builder to a Construction Environment
Letting SCons Handle The File Suffixes
Builders That Execute Python Functions
Builders That Create Actions Using a Generator
Builders That Modify the Target or Source Lists Using an Emitter
Where To Put Your Custom Builders and Tools
Not Writing a Builder: the Command Builder
Pseudo-Builders: the AddMethod function
Writing Scanners
A Simple Scanner Example
Building From Code Repositories
The Repository Method
Finding source files in repositories
Finding #include files in repositories
Limitations on #include files in repositories
Finding the SConstruct file in repositories
Finding derived files in repositories
Guaranteeing local copies of files
Multi-Platform Configuration (Autoconf Functionality)
Configure Contexts
Checking for the Existence of Header Files
Checking for the Availability of a Function
Checking for the Availability of a Library
Checking for the Availability of a typedef
Adding Your Own Custom Checks
Not Configuring When Cleaning Targets
Caching Built Files
Specifying the Shared Cache Directory
Keeping Build Output Consistent
Not Using the Shared Cache for Specific Files
Disabling the Shared Cache
Populating a Shared Cache With Already-Built Files
Minimizing Cache Contention: the --random Option
Alias Targets
Java Builds
Building Java Class Files: the Java Builder
How SCons Handles Java Dependencies
Building Java Archive (.jar) Files: the Jar Builder
Building C Header and Stub Files: the JavaH Builder
Building RMI Stub and Skeleton Class Files: the RMIC Builder
Miscellaneous Functionality
Verifying the Python Version: the EnsurePythonVersion Function
Verifying the SCons Version: the EnsureSConsVersion Function
Explicitly Terminating SCons While Reading SConscript Files: the Exit Function
Searching for Files: the FindFile Function
Handling Nested Lists: the Flatten Function
Finding the Invocation Directory: the GetLaunchDir Function
Troubleshooting
Why is That Target Being Rebuilt? the --debug=explain Option
What's in That Construction Environment? the Dump Method
What Dependencies Does SCons Know About? the --tree Option
How is SCons Constructing the Command Lines It Executes? the --debug=presub Option
Where is SCons Searching for Libraries? the --debug=findlibs Option
Where is SCons Blowing Up? the --debug=stacktrace Option
How is SCons Making Its Decisions? the --taskmastertrace Option
Construction Variables
Builders
Tools
Handling Common Tasks