SCons User Guide 1.0.0

Steven Knight

Copyright © 2004, 2005, 2006, 2007, 2008 Steven Knight

SCons User's Guide Copyright (c) 2004, 2005, 2006, 2007 Steven Knight

Table of Contents
Preface
1. SCons Principles
2. A Caveat About This Guide's Completeness
3. Acknowledgements
4. Contact
1. Building and Installing SCons
1.1. Installing Python
1.2. Installing SCons From Pre-Built Packages
1.2.1. Installing SCons on Red Hat (and Other RPM-based) Linux Systems
1.2.2. Installing SCons on Debian Linux Systems
1.2.3. Installing SCons on Windows Systems
1.3. Building and Installing SCons on Any System
1.3.1. Building and Installing Multiple Versions of SCons Side-by-Side
1.3.2. Installing SCons in Other Locations
1.3.3. Building and Installing SCons Without Administrative Privileges
2. Simple Builds
2.1. Building Simple C / C++ Programs
2.2. Building Object Files
2.3. Simple Java Builds
2.4. Cleaning Up After a Build
2.5. The SConstruct File
2.5.1. SConstruct Files Are Python Scripts
2.5.2. SCons Functions Are Order-Independent
2.6. Making the SCons Output Less Verbose
3. Less Simple Things to Do With Builds
3.1. Specifying the Name of the Target (Output) File
3.2. Compiling Multiple Source Files
3.3. Making a list of files with Glob
3.4. Specifying Single Files Vs. Lists of Files
3.5. Making Lists of Files Easier to Read
3.6. Keyword Arguments
3.7. Compiling Multiple Programs
3.8. Sharing Source Files Between Multiple Programs
4. Building and Linking with Libraries
4.1. Building Libraries
4.1.1. Building Libraries From Source Code or Object Files
4.1.2. Building Static Libraries Explicitly: the StaticLibrary Builder
4.1.3. Building Shared (DLL) Libraries: the SharedLibrary Builder
4.2. Linking with Libraries
4.3. Finding Libraries: the $LIBPATH Construction Variable
5. Node Objects
5.1. Builder Methods Return Lists of Target Nodes
5.2. Explicitly Creating File and Directory Nodes
5.3. Printing Node File Names
5.4. Using a Node's File Name as a String
6. Dependencies
6.1. Deciding When an Input File Has Changed: the Decider Function
6.1.1. Using MD5 Signatures to Decide if a File Has Changed
6.1.2. Using Time Stamps to Decide If a File Has Changed
6.1.3. Deciding If a File Has Changed Using Both MD Signatures and Time Stamps
6.1.4. Writing Your Own Custom Decider Function
6.1.5. Mixing Different Ways of Deciding If a File Has Changed
6.2. Older Functions for Deciding When an Input File Has Changed
6.2.1. The SourceSignatures Function
6.2.2. The TargetSignatures Function
6.3. Implicit Dependencies: The $CPPPATH Construction Variable
6.4. Caching Implicit Dependencies
6.4.1. The --implicit-deps-changed Option
6.4.2. The --implicit-deps-unchanged Option
6.5. Explicit Dependencies: the Depends Function
6.6. Ignoring Dependencies: the Ignore Function
6.7. Order-Only Dependencies: the Requires Function
6.8. The AlwaysBuild Function
7. Environments
7.1. Using Values From the External Environment
7.2. Construction Environments
7.2.1. Creating a Construction Environment: the Environment Function
7.2.2. Fetching Values From a Construction Environment
7.2.3. Expanding Values From a Construction Environment: the subst Method
7.2.4. Controlling the Default Construction Environment: the DefaultEnvironment Function
7.2.5. Multiple Construction Environments
7.2.6. Making Copies of Construction Environments: the Clone Method
7.2.7. Replacing Values: the Replace Method
7.2.8. Setting Values Only If They're Not Already Defined: the SetDefault Method
7.2.9. Appending to the End of Values: the Append Method
7.2.10. Appending Unique Values: the AppendUnique Method
7.2.11. Appending to the Beginning of Values: the Prepend Method
7.2.12. Prepending Unique Values: the PrependUnique Method
7.3. Controlling the Execution Environment for Issued Commands
7.3.1. Propagating PATH From the External Environment
7.3.2. Adding to PATH Values in the Execution Environment
8. Merging Options into the Environment: the MergeFlags Function
9. Separating Compile Arguments into their Variables: the ParseFlags Function
10. Finding Installed Library Information: the ParseConfig Function
11. Controlling Build Output
11.1. Providing Build Help: the Help Function
11.2. Controlling How SCons Prints Build Commands: the $*COMSTR Variables
11.3. Providing Build Progress Output: the Progress Function
11.4. Printing Detailed Build Status: the GetBuildFailures Function
12. Controlling a Build From the Command Line
12.1. Command-Line Options
12.1.1. Not Having to Specify Command-Line Options Each Time: the SCONSFLAGS Environment Variable
12.1.2. Getting Values Set by Command-Line Options: the GetOption Function
12.1.3. Setting Values of Command-Line Options: the SetOption Function
12.1.4. Strings for Getting or Setting Values of SCons Command-Line Options
12.1.5. Adding Custom Command-Line Options: the AddOption Function
12.2. Command-Line variable=value Build Variables
12.2.1. Controlling Command-Line Build Variables
12.2.2. Providing Help for Command-Line Build Variables
12.2.3. Reading Build Variables From a File
12.2.4. Pre-Defined Build Variable Functions
12.2.5. Adding Multiple Command-Line Build Variables at Once
12.2.6. Handling Unknown Command-Line Build Variables: the UnknownVariables Function
12.3. Command-Line Targets
12.3.1. Fetching Command-Line Targets: the COMMAND_LINE_TARGETS Variable
12.3.2. Controlling the Default Targets: the Default Function
12.3.3. Fetching the List of Build Targets, Regardless of Origin: the BUILD_TARGETS Variable
13. Installing Files in Other Directories: the Install Builder
13.1. Installing Multiple Files in a Directory
13.2. Installing a File Under a Different Name
13.3. Installing Multiple Files Under Different Names
14. Platform-Independent File System Manipulation
14.1. Copying Files or Directories: The Copy Factory
14.2. Deleting Files or Directories: The Delete Factory
14.3. Moving (Renaming) Files or Directories: The Move Factory
14.4. Updating the Modification Time of a File: The Touch Factory
14.5. Creating a Directory: The Mkdir Factory
14.6. Changing File or Directory Permissions: The Chmod Factory
14.7. Executing an action immediately: the Execute Function
15. Controlling Removal of Targets
15.1. Preventing target removal during build: the Precious Function
15.2. Preventing target removal during clean: the NoClean Function
15.3. Removing additional files during clean: the Clean Function
16. Hierarchical Builds
16.1. SConscript Files
16.2. Path Names Are Relative to the SConscript Directory
16.3. Top-Level Path Names in Subsidiary SConscript Files
16.4. Absolute Path Names
16.5. Sharing Environments (and Other Variables) Between SConscript Files
16.5.1. Exporting Variables
16.5.2. Importing Variables
16.5.3. Returning Values From an SConscript File
17. Separating Source and Build Directories
17.1. Specifying a Variant Directory Tree as Part of an SConscript Call
17.2. Why SCons Duplicates Source Files in a Variant Directory Tree
17.3. Telling SCons to Not Duplicate Source Files in the Variant Directory Tree
17.4. The VariantDir Function
17.5. Using VariantDir With an SConscript File
17.6. Using Glob with VariantDir
18. Variant Builds
19. Writing Your Own Builders
19.1. Writing Builders That Execute External Commands
19.2. Attaching a Builder to a Construction Environment
19.3. Letting SCons Handle The File Suffixes
19.4. Builders That Execute Python Functions
19.5. Builders That Create Actions Using a Generator
19.6. Builders That Modify the Target or Source Lists Using an Emitter
19.7. Where To Put Your Custom Builders and Tools
20. Not Writing a Builder: the Command Builder
21. Pseudo-Builders: the AddMethod function
22. Writing Scanners
22.1. A Simple Scanner Example
23. Building From Code Repositories
23.1. The Repository Method
23.2. Finding source files in repositories
23.3. Finding #include files in repositories
23.3.1. Limitations on #include files in repositories
23.4. Finding the SConstruct file in repositories
23.5. Finding derived files in repositories
23.6. Guaranteeing local copies of files
24. Multi-Platform Configuration (Autoconf Functionality)
24.1. Configure Contexts
24.2. Checking for the Existence of Header Files
24.3. Checking for the Availability of a Function
24.4. Checking for the Availability of a Library
24.5. Checking for the Availability of a typedef
24.6. Adding Your Own Custom Checks
24.7. Not Configuring When Cleaning Targets
25. Caching Built Files
25.1. Specifying the Shared Cache Directory
25.2. Keeping Build Output Consistent
25.3. Not Using the Shared Cache for Specific Files
25.4. Disabling the Shared Cache
25.5. Populating a Shared Cache With Already-Built Files
25.6. Minimizing Cache Contention: the --random Option
26. Alias Targets
27. Java Builds
27.1. Building Java Class Files: the Java Builder
27.2. How SCons Handles Java Dependencies
27.3. Building Java Archive (.jar) Files: the Jar Builder
27.4. Building C Header and Stub Files: the JavaH Builder
27.5. Building RMI Stub and Skeleton Class Files: the RMIC Builder
28. Miscellaneous Functionality
28.1. Verifying the Python Version: the EnsurePythonVersion Function
28.2. Verifying the SCons Version: the EnsureSConsVersion Function
28.3. Explicitly Terminating SCons While Reading SConscript Files: the Exit Function
28.4. Handling Nested Lists: the Flatten Function
29. Troubleshooting
29.1. Why is That Target Being Rebuilt? the --debug=explain Option
29.2. What's in That Construction Environment? the Dump Method
29.3. What Dependencies Does SCons Know About? the --tree Option
29.4. How is SCons Constructing the Command Lines It Executes? the --debug=presub Option
29.5. Where is SCons Searching for Libraries? the --debug=findlibs Option
29.6. Where is SCons Blowing Up? the --debug=stacktrace Option
29.7. How is SCons Making Its Decisions? the --taskmastertrace Option
A. Construction Variables
B. Builders
C. Tools
D. Handling Common Tasks
List of Examples
D-1. Wildcard globbing to create a list of filenames
D-2. Filename extension substitution
D-3. Appending a path prefix to a list of filenames
D-4. Substituting a path prefix with another one
D-5. Filtering a filename list to exclude/retain only a specific set of extensions
D-6. The "backtick function": run a shell command and capture the output
  Next
  Preface