SCons User Guide 0.96

Steven Knight

version 0.96

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 SCons Without Administrative Privileges
Building and Installing Multiple Versions of SCons Side-by-Side

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

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

Preventing Removal of Targets: the Precious 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 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

Caching Built Files

Specifying the Shared Cache Directory
Keeping Build Output Consistent
Not Retrieving Files From a Shared Cache
Populating a Shared Cache With Already-Built Files

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

Handling Common Tasks

		Next >>>
		Preface