SCons User Guide 0.97

Steven Knight

version 0.97

Table of Contents
SCons Principles
A Caveat About This Guide's Completeness
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
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 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
Deciding When a Source File Has Changed: the SourceSignatures Function
MD5 Source File Signatures
Source File Time Stamps
Deciding When a Target File Has Changed: the TargetSignatures Function
Build Signatures
File Contents
Implicit Dependencies: The $CPPPATH Construction Variable
Caching Implicit Dependencies
The --implicit-deps-changed Option
The --implicit-deps-unchanged Option
Ignoring Dependencies: the Ignore Method
Explicit Dependencies: the Depends Method
The AlwaysBuild Method
Construction Environments
Multiple Construction Environments
Copying Construction Environments
Fetching Values From a Construction Environment
Expanding Values From a Construction Environment
Modifying a Construction Environment
Replacing Values in a Construction Environment
Appending to the End of Values in a Construction Environment
Appending to the Beginning of Values in a Construction Environment
Controlling the External Environment Used to Execute Build Commands
Propagating PATH From the External Environment
Controlling a Build From the Command Line
Not Having to Specify Command-Line Options Each Time: the SCONSFLAGS Environment Variable
Getting at Command-Line Targets
Controlling the Default Targets
Getting at the List of Default Targets
Getting at the List of Build Targets, Regardless of Origin
Command-Line variable=value Build Options
Controlling Command-Line Build Options
Providing Help for Command-Line Build Options
Reading Build Options From a File
Canned Build Options
True/False Values: the BoolOption Build Option
Single Value From a List: the EnumOption Build Option
Multiple Values From a List: the ListOption Build Option
Path Names: the PathOption Build Option
Enabled/Disabled Path Names: the PackageOption Build Option
Adding Multiple Command-Line Build Options at Once
Providing Build Help: the Help Function
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
Preventing 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 Build Directory as Part of an SConscript Call
Why SCons Duplicates Source Files in a Build Directory
Telling SCons to Not Duplicate Source Files in the Build Directory
The BuildDir Function
Using BuildDir With an SConscript File
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
Not Writing a Builder: the Command Builder
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
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
Handling Common Tasks