SCons User Guide 0.97.0d20070809

Steven Knight

Copyright © 2004, 2005, 2006, 2007 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. Specifying Single Files Vs. Lists of Files
3.4. Making Lists of Files Easier to Read
3.5. Keyword Arguments
3.6. Compiling Multiple Programs
3.7. 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 a Source File Has Changed: the SourceSignatures Function
6.1.1. MD5 Source File Signatures
6.1.2. Source File Time Stamps
6.2. Deciding When a Target File Has Changed: the TargetSignatures Function
6.2.1. Build Signatures
6.2.2. File Contents
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. Ignoring Dependencies: the Ignore Method
6.6. Explicit Dependencies: the Depends Method
6.7. The AlwaysBuild Method
7. Construction Environments
7.1. Multiple Construction Environments
7.2. Copying Construction Environments
7.3. Fetching Values From a Construction Environment
7.4. Expanding Values From a Construction Environment
7.5. Modifying a Construction Environment
7.5.1. Replacing Values in a Construction Environment
7.5.2. Appending to the End of Values in a Construction Environment
7.5.3. Appending to the Beginning of Values in a Construction Environment
8. Controlling the External Environment Used to Execute Build Commands
8.1. Propagating PATH From the External Environment
9. Controlling a Build From the Command Line
9.1. Not Having to Specify Command-Line Options Each Time: the SCONSFLAGS Environment Variable
9.2. Getting at Command-Line Targets
9.3. Controlling the Default Targets
9.3.1. Getting at the List of Default Targets
9.4. Getting at the List of Build Targets, Regardless of Origin
9.5. Command-Line variable=value Build Options
9.6. Controlling Command-Line Build Options
9.7. Providing Help for Command-Line Build Options
9.8. Reading Build Options From a File
9.9. Canned Build Options
9.9.1. True/False Values: the BoolOption Build Option
9.9.2. Single Value From a List: the EnumOption Build Option
9.9.3. Multiple Values From a List: the ListOption Build Option
9.9.4. Path Names: the PathOption Build Option
9.9.5. Enabled/Disabled Path Names: the PackageOption Build Option
9.10. Adding Multiple Command-Line Build Options at Once
10. Providing Build Help: the Help Function
11. Installing Files in Other Directories: the Install Builder
11.1. Installing Multiple Files in a Directory
11.2. Installing a File Under a Different Name
11.3. Installing Multiple Files Under Different Names
12. Platform-Independent File System Manipulation
12.1. Copying Files or Directories: The Copy Factory
12.2. Deleting Files or Directories: The Delete Factory
12.3. Moving (Renaming) Files or Directories: The Move Factory
12.4. Updating the Modification Time of a File: The Touch Factory
12.5. Creating a Directory: The Mkdir Factory
12.6. Changing File or Directory Permissions: The Chmod Factory
12.7. Executing an action immediately: the Execute Function
13. Preventing Removal of Targets
13.1. Preventing target removal during build: the Precious Function
13.2. Preventing target removal during clean: the NoClean Function
13.3. Removing additional files during clean: the Clean Function
14. Hierarchical Builds
14.1. SConscript Files
14.2. Path Names Are Relative to the SConscript Directory
14.3. Top-Level Path Names in Subsidiary SConscript Files
14.4. Absolute Path Names
14.5. Sharing Environments (and Other Variables) Between SConscript Files
14.5.1. Exporting Variables
14.5.2. Importing Variables
14.5.3. Returning Values From an SConscript File
15. Separating Source and Build Directories
15.1. Specifying a Build Directory as Part of an SConscript Call
15.2. Why SCons Duplicates Source Files in a Build Directory
15.3. Telling SCons to Not Duplicate Source Files in the Build Directory
15.4. The BuildDir Function
15.5. Using BuildDir With an SConscript File
16. Variant Builds
17. Writing Your Own Builders
17.1. Writing Builders That Execute External Commands
17.2. Attaching a Builder to a Construction Environment
17.3. Letting SCons Handle The File Suffixes
17.4. Builders That Execute Python Functions
17.5. Builders That Create Actions Using a Generator
17.6. Builders That Modify the Target or Source Lists Using an Emitter
18. Not Writing a Builder: the Command Builder
19. Writing Scanners
19.1. A Simple Scanner Example
20. Building From Code Repositories
20.1. The Repository Method
20.2. Finding source files in repositories
20.3. Finding #include files in repositories
20.3.1. Limitations on #include files in repositories
20.4. Finding the SConstruct file in repositories
20.5. Finding derived files in repositories
20.6. Guaranteeing local copies of files
21. Multi-Platform Configuration (Autoconf Functionality)
21.1. Configure Contexts
21.2. Checking for the Existence of Header Files
21.3. Checking for the Availability of a Function
21.4. Checking for the Availability of a Library
21.5. Checking for the Availability of a typedef
21.6. Adding Your Own Custom Checks
21.7. Not Configuring When Cleaning Targets
22. Caching Built Files
22.1. Specifying the Shared Cache Directory
22.2. Keeping Build Output Consistent
22.3. Not Using the Shared Cache for Specific Files
22.4. Disabling the Shared Cache
22.5. Populating a Shared Cache With Already-Built Files
22.6. Minimizing Cache Contention: the --random Option
23. Alias Targets
24. Java Builds
24.1. Building Java Class Files: the Java Builder
24.2. How SCons Handles Java Dependencies
24.3. Building Java Archive (.jar) Files: the Jar Builder
24.4. Building C Header and Stub Files: the JavaH Builder
24.5. Building RMI Stub and Skeleton Class Files: the RMIC Builder
25. Troubleshooting
25.1. Why is That Target Being Rebuilt? the --debug=explain Option
25.2. What's in That Construction Environment? the Dump Method
25.3. What Dependencies Does SCons Know About? the --tree Option
25.4. How is SCons Constructing the Command Lines It Executes? the --debug=presub Option
25.5. Where is SCons Searching for Libraries? the --debug=findlibs Option
25.6. Where is SCons Blowing Up? the --debug=stacktrace Option
25.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