SCons 4.2.0a0
   Next

SCons 4.2.0a0

User Guide

The SCons Development Team

Version 4.2.0a0

Copyright © 2004 - 2023 The SCons Foundation

Released: Mon, 06 Mar 2023 23:58:40 -0400

Table of Contents

Preface
1. SCons Principles
2. How to Use this Guide
3. A Caveat About This Guide's Completeness
4. Acknowledgements
5. Contact
1. Building and Installing SCons
1.1. Installing Python
1.2. Installing SCons
1.3. Using SCons Without Installing
1.4. Running Multiple Versions of SCons Side-by-Side
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
5.5. GetBuildPath: Getting the Path From a Node or String
6. Dependencies
6.1. Deciding When an Input File Has Changed: the Decider Function
6.1.1. Using Content 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. Extending SCons: Writing Your Own Custom Decider Function
6.1.5. Mixing Different Ways of Deciding If a File Has Changed
6.2. Implicit Dependencies: The $CPPPATH Construction Variable
6.3. Caching Implicit Dependencies
6.3.1. The --implicit-deps-changed Option
6.3.2. The --implicit-deps-unchanged Option
6.4. Explicit Dependencies: the Depends Function
6.5. Dependencies From External Files: the ParseDepends 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. Handling Problems With Value Expansion
7.2.5. Controlling the Default Construction Environment: the DefaultEnvironment Function
7.2.6. Multiple Construction Environments
7.2.7. Making Copies of Construction Environments: the Clone Method
7.2.8. Replacing Values: the Replace Method
7.2.9. Setting Values Only If They're Not Already Defined: the SetDefault Method
7.2.10. Appending to the End of Values: the Append Method
7.2.11. Appending Unique Values: the AppendUnique Method
7.2.12. Prepending to the Beginning of Values: the Prepend Method
7.2.13. Prepending Unique Values: the PrependUnique Method
7.2.14. Overriding Construction Variable Settings
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
7.4. Using the toolpath for external Tools
7.4.1. The default tool search path
7.4.2. Providing an external directory to toolpath
7.4.3. Nested Tools within a toolpath
7.4.4. Using sys.path within the toolpath
7.4.5. Using the PyPackageDir function to add to the toolpath
8. Automatically Putting Command-line Options into their Construction Variables
8.1. Merging Options into the Environment: the MergeFlags Function
8.2. Merging Options While Creating Environment: the parse_flags Parameter
8.3. Separating Compile Arguments into their Variables: the ParseFlags Function
8.4. Finding Installed Library Information: the ParseConfig Function
9. Controlling Build Output
9.1. Providing Build Help: the Help Function
9.2. Controlling How SCons Prints Build Commands: the $*COMSTR Variables
9.3. Providing Build Progress Output: the Progress Function
9.4. Printing Detailed Build Status: the GetBuildFailures Function
10. Controlling a Build From the Command Line
10.1. Command-Line Options
10.1.1. Not Having to Specify Command-Line Options Each Time: the SCONSFLAGS Environment Variable
10.1.2. Getting Values Set by Command-Line Options: the GetOption Function
10.1.3. Setting Values of Command-Line Options: the SetOption Function
10.1.4. Strings for Getting or Setting Values of SCons Command-Line Options
10.1.5. Adding Custom Command-Line Options: the AddOption Function
10.2. Command-Line variable=value Build Variables
10.2.1. Controlling Command-Line Build Variables
10.2.2. Providing Help for Command-Line Build Variables
10.2.3. Reading Build Variables From a File
10.2.4. Pre-Defined Build Variable Functions
10.2.5. Adding Multiple Command-Line Build Variables at Once
10.2.6. Handling Unknown Command-Line Build Variables: the UnknownVariables Function
10.3. Command-Line Targets
10.3.1. Fetching Command-Line Targets: the COMMAND_LINE_TARGETS Variable
10.3.2. Controlling the Default Targets: the Default Function
10.3.3. Fetching the List of Build Targets, Regardless of Origin: the BUILD_TARGETS Variable
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
11.4. Installing a Shared Library
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. Controlling 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-Relative 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 Trees: Variant Directories
15.1. Specifying a Variant Directory Tree as Part of an SConscript Call
15.2. Why SCons Duplicates Source Files in a Variant Directory Tree
15.3. Telling SCons to Not Duplicate Source Files in the Variant Directory Tree
15.4. The VariantDir Function
15.5. Using VariantDir With an SConscript File
15.6. Using Glob with VariantDir
15.7. Variant Build Examples
16. Building From Code Repositories
16.1. The Repository Method
16.2. Finding source files in repositories
16.3. Finding #include files in repositories
16.3.1. Limitations on #include files in repositories
16.4. Finding the SConstruct file in repositories
16.5. Finding derived files in repositories
16.6. Guaranteeing local copies of files
17. Extending SCons: 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
17.7. Modifying a Builder by adding an Emitter
17.8. Where To Put Your Custom Builders and Tools
18. Not Writing a Builder: the Command Builder
19. Extending SCons: Pseudo-Builders and the AddMethod function
20. Extending SCons: Writing Your Own Scanners
20.1. A Simple Scanner Example
20.2. Adding a search path to a scanner: FindPathDirs
20.3. Using scanners with Builders
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. Checking the size of a datatype
21.7. Checking for the Presence of a program
21.8. Extending SCons: Adding Your Own Custom Checks
21.9. Not Configuring When Cleaning Targets
22. Caching Built Files
22.1. Specifying the Derived-File Cache Directory
22.2. Keeping Build Output Consistent
22.3. Not Using the Derived-File Cache for Specific Files
22.4. Disabling the Derived-File Cache
22.5. Populating a Derived-File Cache With Already-Built Files
22.6. Minimizing Cache Contention: the --random Option
22.7. Using a Custom CacheDir Class
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. Internationalization and localization with gettext
25.1. Prerequisites
25.2. Simple project
26. Miscellaneous Functionality
26.1. Verifying the Python Version: the EnsurePythonVersion Function
26.2. Verifying the SCons Version: the EnsureSConsVersion Function
26.3. Explicitly Terminating SCons While Reading SConscript Files: the Exit Function
26.4. Searching for Files: the FindFile Function
26.5. Handling Nested Lists: the Flatten Function
26.6. Finding the Invocation Directory: the GetLaunchDir Function
26.7. Declaring Additional Outputs: the SideEffect Function
26.8. Virtual environments (virtualenvs)
27. Using SCons with other build tools
27.1. Creating a Compilation Database
27.2. Ninja Build Generator
28. Troubleshooting
28.1. Why is That Target Being Rebuilt? the --debug=explain Option
28.2. What's in That Construction Environment? the Dump Method
28.3. What Dependencies Does SCons Know About? the --tree Option
28.4. How is SCons Constructing the Command Lines It Executes? the --debug=presub Option
28.5. Where is SCons Searching for Libraries? the --debug=findlibs Option
28.6. Where is SCons Blowing Up? the --debug=stacktrace Option
28.7. How is SCons Making Its Decisions? the --taskmastertrace Option
28.8. Watch SCons prepare targets for building: the --debug=prepare Option
28.9. Why is a file disappearing? the --debug=duplicate Option
28.10. Keep it simple
A. Construction Variables
B. Builders
C. Tools
D. Functions and Environment Methods
E. Handling Common Tasks

List of Examples

E.1. Wildcard globbing to create a list of filenames
E.2. Filename extension substitution
E.3. Appending a path prefix to a list of filenames
E.4. Substituting a path prefix with another one
E.5. Filtering a filename list to exclude/retain only a specific set of extensions
E.6. The "backtick function": run a shell command and capture the output
E.7. Generating source code: how code can be generated and used by SCons
   Next
   Preface