Skip to content

SconsProcessOverview

Mats Wichmann edited this page Sep 26, 2021 · 13 revisions

SCons processes the commands in the SConstruct in order as they appear. These commands build a dependency tree. The dependency tree contains Node Objects that correspond to some sort of object to be built. Which Nodes to build in the dependency tree is determined by the command line arguments given by the user.

We now have a family of trees (a forest) that represent the topmost files to build. All of the files that are out of date are built. This process recurses to ensure all subsequent Nodes are built as needed.

Note that this gives the appearance of SCons being two-pass. If the commands don't contribute directly to building up the dependency tree, such as pure Python code that does not use the API, they can be executed right away, while commands which instruct SCons about targets, dependencies and other such matters are deferred until the full dependency picture is complete. As SCons is running it will tell you when it switches to the build phase:

scons: done reading SConscript files.
scons: Building targets ...

The following is pseudo code for the overall process that SCons follows:

Pseudo Code

Read SConstruct as a Python script:
# Default Environment object is created.
# Tools do their checks and modify the Environment object.
# Regular Python code is executed as usual.
# SConscript() calls cause referenced SConscript files to be
#   read/executed immediately.
# Methods of Environment object are used to update the dependency
#   tree and manipulate SCons state.

# After the file is read, we have:
#    a global dependency tree of the entire system,
#    consisting of a tree of Node objects. A Node is usually a
#    filesystem object, but can be an Alias or a Value node.
#    Each Node contains:
#         - a pointer to the corresponding Environment object
#         - a command to execute to build that node,
#         - a list of dependencies.
# Note the dependency tree may not be complete at this point;
#    for example, source files which are generated as part of the build
#    will be scanned for more dependencies before building the targets that depend on them.

command line arguments are "expanded" into a list of Nodes that we want built
      # if the argument is a file, then a single file is built
      # if the argument is a directory, then everything within that directory is built
      # if an argument is an Alias, then everything the Alias names is built
      # There are also default targets; ones specified with Default() and -u/-U and if nothing else, '.'.

if there is nothing to build, we're done

foreach Node:
      recursively build all of its dependencies
      check source dependencies for the Node
          # check the .sconsign file
          # use MD5 or signature method
      if out of date, or MD5 mismatch
           build the target using its associated command(s) and Environment
           # The commands in the Node do the actual work in the build phase,
           # normally by expanding an Env variable and passing it to a shell.

Categories of Commands

The commands you can use in the SConstruct or SConscript files can be categorized in by their intent:

  • Node Commands
  • Admin/Bookkeeping Commands
  • Actions

A complete reference of commands in on the Man page.

Node Commands

These commands are used to create Nodes. They all return a Node or a list of Nodes.

Nodes are created by:

  • building a target
  • naming an existing target
  • specifying a pseudo target
  • composition of other existing targets

These commands actually build stuff. They can affect files and directories on the file-system. Note they only define how to build, but don't actually do anything (i.e. on the filesystem) at the time they are called. The actual building is only done if the target is part of the final target Node list (see the process above).

File system Description
Dir() a node representing a directory
File() a node representing a file
Pseudo targets Description
Alias() creates one or more phony targets that expand to one or more other targets
Value() creates a node based on a string. If the string changes then the Value node is "out of date"
Common build objects Description
Program() build an executable from one or more object files, or C, C++, D or Fortran source files
StaticLibrary() builds a library file; .a in POSIX or .lib in Win32
StaticObject() or Object() builds an object file; .o in POSIX or .obj in Win32
SharedLibrary() builds a shared library; a .so on Posix, a .dll in Win32
Win32 specific Description
MSVSProject() generates MS Visual Studio project (.vcproj and .sln) files
RES() build an MS Visual C++ resource .res file from a .rc file
TypeLibrary() builds Win32 type library .tlb from an input .idl file
Java specific Description
Java() builds a java class file
JavaH() builds a C header and source file for building Java native methods
RMIC() builds stub and skeleton files for remote objects from Java .class files
Lex/Yacc specific Description
CFile() builds a C source file given a lex or yacc input file
CXXFile() builds a C++ source file given a lex or yacc input file
Moc specific Description
M4() builds an output file from an M4 input file
Moc() builds an output file from an moc input file
Uic() builds a header, an implemenation and a moc file from a .ui file
Documentation specific Description
DVI() builds a .dvi file
PDF() builds a .pdf file from a .dvi, .tex, .ltx or .latex input file
PostScript() builds a .ps from a .dvi, .tex, .ltx or .latex input file
Archive specific Description
Tar() builds a tar archive from files and/or directories
Zip() builds a zip file from files and/or directories
Install Description
Install() installs one or more files in a destination directory
InstallAs() installs one or more files as specific file names

Admin/Bookkeeping Commands

These commands are for "admin" or bookkeeping purposes. They provide the "glue" between the various bits of the build system. Or from another perspective, they allow the entire build system to be decomposed into separate but coordinated parts.

Environment Description
Environment() Creates a new scons environment
Clone() Return a separate copy of a construction environment.
Append() Appends the specified keyword arguments to the end of construction variables in the environment.
AppendUnique() Appends the specified keyword arguments to the end of construction variables in the environment.
Prepend() Prepends the specified keyword arguments to the beginning of construction variables in the environment.
PrependUnique() Prepends the specified keyword arguments to the beginning of construction variables in the environment.
Platform() Returns a callable object that can be used to initialize a construction environment using the platform keyword of the Environment() method
Tool() Returns a callable object that can be used to initialize a construction environment using the tools keyword of the Environment() method.
Command-line and invocation Description
Default() specifies one or more targets to build if not targets are specified on the command line
Help() indicates what to display when -h is used on the command line
Return() what to return when scons exits
Exit() exit from scons
GetLaunchDir() Returns the absolute path name of the directory from which scons was initially invoked.
GetOption() This function provides a way to query a select subset of the scons command line options from a SConscript file.
SetOption() This function provides a way to set a select subset of the scons command line options from a SConscript file.
Run time environment Description
SConsignFile() store the scons db in the given file
EnsurePythonVersion() Ensure that the Python version is at least x.y
EnsureSConsVersion() Ensure that the SCons version is at least x.y
AppendENVPath() Appends new path elements to the given path in the specified external environment (ENV by default)
PrependENVPath() Prepends new path elements to the given path in the specified external environment (ENV by default)
GetBuildPath() Returns the scons path name (or names) for the specified file (or files)
SourceSignatures() This function tells SCons what type of signature to use for source files: MD5 or timestamp.
TargetSignatures() This function tells SCons what type of signatures to use for target files: build or content.
Decomposition Description
SConscript() reads another scons file
Export() makes variables available to sconscript files
Import() pulls in the values of exported variables
VariantDir() indicates a variant build directory for a target
SConscriptChdir() Enable/Disable changing working directory when in an SConscript file
Caching functions Description
CacheDir() Specifies that scons will maintain a cache of derived files in cache_dir
Local() The specified targets will have copies made in the local tree, even if an already up-to-date copy exists in a repository.
Repository() Specifies that directory is a repository to be searched for files.
Utility functions Description
Dictionary() Returns a dictionary object containing copies of all of the construction variables in the environment.
FindFile() Search for file in the path specified by dirs. file may be a list of file names or a single file name.
WhereIs() Searches for the specified executable program, returning the full path name to the program if it is found, and returning None if not.
Flatten() Takes a sequence (that is, a Python list or tuple) that may contain nested sequences and returns a flattened list containing all of the individual elements in any sequence.
Split() Returns a list of file names or other objects.
Literal() The specified string will be preserved as-is and not have construction variables expanded

Action Commands

These commands are used to perform actions, to specify when an action occurs, to prevent an action from occuring, affect the dependency tree, etc.

Dependency tree functions Description
Depends() Specifies an explicit dependency; the target file(s) will be rebuilt whenever the dependency file(s) has changed.
Clean() This specifies a list of files or directories which should be removed whenever the targets are specified with the -c command line option.
AlwaysBuild() Marks each given target so that it is always assumed to be out of date, and will always be rebuilt if needed.
Ignore() The specified dependency file(s) will be ignored when deciding if the target file(s) need to be rebuilt.
Precious() Marks each given target as precious so it is not deleted before it is rebuilt. Normally scons deletes a target before building it.
SideEffect() Declares side_effect as a side effect of building target.
Generic command objects Description
Scanner() Creates a Scanner object for the specified function. You can use the Scanner function to define objects to scan new file types for implicit dependencies.
Builder() Creates a Builder object for the specified action. In general, you should only need to add a new Builder object when you want to build a new type of file or other external target.
Action() Creates an Action object for the specified action. These are similar in concept to "tasks" in the Ant build tool, although the implementation is slightly different. These functions do not actually perform the specified action at the time the function is called, but instead return an Action object that can be executed at the appropriate time.
Execute() Executes an Action object immediately (at the time the command is read)
AddPostAction() Arranges for the specified action to be performed after the specified target has been built.
AddPreAction() Arranges for the specified action to be performed before the specified target is built.
Actions Description
Chmod() Returns an Action object that changes the permissions on the specified dest file or directory to the specified mode.
Copy() Returns an Action object that will copy the src source file or directory to the dest destination file or directory.
Delete() Returns an Action that deletes the specified entry, which may be a file or a directory tree.
Mkdir() Returns an Action that creates the specified directory dir
Move() Returns an Action that moves the specified src file or directory to the specified dest file or directory.
Touch() Returns an Action that updates the modification time on the specified file
** Uncategorized** Description
Configure() Creates a Configure object for integrated functionality similar to GNU autoconf
ParseConfig() Calls the specified function to modify the environment as specified by the output of command.
Clone this wiki locally