SCons User Guide 2.3.0 Steven Knight SCons User Guide 2.3.0 by Steven Knight Revision (2013/03/03 09:48:35) Edition Published 2004, 2005, 2006, 2007, 2008, 2009, 2010 Copyright © 2004, 2005, 2006, 2007, 2008, 2009, 2010 Steven Knight SCons User’s Guide Copyright (c) 2004, 2005, 2006, 2007 Steven Knight Table of Contents Preface.......................................................................................................................................................ix 1. SCons Principles...........................................................................................................................ix 2. A Caveat About This Guide’s Completeness................................................................................ix 3. Acknowledgements........................................................................................................................x 4. Contact..........................................................................................................................................xi 1. Building and Installing SCons..............................................................................................................1 1.1. Installing Python.........................................................................................................................1 1.2. Installing SCons From Pre-Built Packages.................................................................................1 1.2.1. Installing SCons on Red Hat (and Other RPM-based) Linux Systems..........................2 1.2.2. Installing SCons on Debian Linux Systems...................................................................2 1.2.3. Installing SCons on Windows Systems..........................................................................2 1.3. Building and Installing SCons on Any System...........................................................................3 1.3.1. Building and Installing Multiple Versions of SCons Side-by-Side................................3 1.3.2. Installing SCons in Other Locations...............................................................................4 1.3.3. Building and Installing SCons Without Administrative Privileges................................4 2. Simple Builds..........................................................................................................................................5 2.1. Building Simple C / C++ Programs............................................................................................5 2.2. Building Object Files..................................................................................................................6 2.3. Simple Java Builds......................................................................................................................7 2.4. Cleaning Up After a Build..........................................................................................................7 2.5. The SConstruct File.................................................................................................................8 2.5.1. SConstruct Files Are Python Scripts..........................................................................8 2.5.2. SCons Functions Are Order-Independent.......................................................................8 2.6. Making the SCons Output Less Verbose...................................................................................10 3. Less Simple Things to Do With Builds..............................................................................................11 3.1. Specifying the Name of the Target (Output) File......................................................................11 3.2. Compiling Multiple Source Files..............................................................................................11 3.3. Making a list of files with Glob................................................................................................12 3.4. Specifying Single Files Vs. Lists of Files.................................................................................13 3.5. Making Lists of Files Easier to Read........................................................................................14 3.6. Keyword Arguments.................................................................................................................15 3.7. Compiling Multiple Programs..................................................................................................15 3.8. Sharing Source Files Between Multiple Programs...................................................................16 4. Building and Linking with Libraries.................................................................................................18 4.1. Building Libraries.....................................................................................................................18 4.1.1. Building Libraries From Source Code or Object Files.................................................18 4.1.2. Building Static Libraries Explicitly: the StaticLibrary Builder.............................19 4.1.3. Building Shared (DLL) Libraries: the SharedLibrary Builder................................19 4.2. Linking with Libraries..............................................................................................................20 4.3. Finding Libraries: the $LIBPATH Construction Variable.........................................................21 iii 5. Node Objects........................................................................................................................................23 5.1. Builder Methods Return Lists of Target Nodes........................................................................23 5.2. Explicitly Creating File and Directory Nodes...........................................................................24 5.3. Printing Node File Names.........................................................................................................24 5.4. Using a Node’s File Name as a String......................................................................................25 5.5. GetBuildPath: Getting the Path From a Node or String........................................................26 6. Dependencies........................................................................................................................................27 6.1. Deciding When an Input File Has Changed: the Decider Function.......................................27 6.1.1. Using MD5 Signatures to Decide if a File Has Changed.............................................27 6.1.2. Using Time Stamps to Decide If a File Has Changed..................................................29 6.1.3. Deciding If a File Has Changed Using Both MD Signatures and Time Stamps..........30 6.1.4. Writing Your Own Custom Decider Function...........................................................31 6.1.5. Mixing Different Ways of Deciding If a File Has Changed.........................................33 6.2. Older Functions for Deciding When an Input File Has Changed.............................................33 6.2.1. The SourceSignatures Function.............................................................................34 6.2.2. The TargetSignatures Function.............................................................................34 6.3. Implicit Dependencies: The $CPPPATH Construction Variable...............................................35 6.4. Caching Implicit Dependencies................................................................................................37 6.4.1. The --implicit-deps-changed Option.................................................................38 6.4.2. The --implicit-deps-unchanged Option.............................................................38 6.5. Explicit Dependencies: the Depends Function........................................................................39 6.6. Dependencies From External Files: the ParseDepends Function..........................................39 6.7. Ignoring Dependencies: the Ignore Function.........................................................................41 6.8. Order-Only Dependencies: the Requires Function................................................................42 6.9. The AlwaysBuild Function....................................................................................................44 7. Environments.......................................................................................................................................46 7.1. Using Values From the External Environment..........................................................................46 7.2. Construction Environments.......................................................................................................47 7.2.1. Creating a Construction Environment: the Environment Function..................47 7.2.2. Fetching Values From a Construction Environment ...........................................48 7.2.3. Expanding Values From a Construction Environment: the subst Method........49 7.2.4. Handling Problems With Value Expansion..................................................................50 7.2.5. Controlling the Default Construction Environment: the DefaultEnvironment Function........................................................................................................................51 7.2.6. Multiple Construction Environments .................................................................52