SCons User Guide 0.97

Steven Knight

version 0.97

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
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

Dependencies

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

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

		Next >>>
		Preface