%scons; ]> The "Native Python" interface is the interface that the actual &SCons; utility will present to users. Because it exposes the Python Build Engine API, &SCons; users will have direct access to the complete functionality of the Build Engine. In contrast, a different user interface such as a GUI may choose to only use, and present to the end-user, a subset of the Build Engine functionality.

&SCons; configuration files are simply Python scripts that invoke methods to specify target files to be built, rules for building the target files, and dependencies. Common build rules are available by default and need not be explicitly specified in the configuration files. By default, the &SCons; utility searches for a file named &SConstruct;, &Sconstruct; or &sconstruct; (in that order) in the current directory, and reads its configuration from the first file found. A -f command-line option exists to read a different file name.

Because &SCons; configuration files are Python scripts, normal Python syntax can be used to generate or manipulate lists of targets or dependencies: sources = ['aaa.c', 'bbb.c', 'ccc.c'] env.Make('bar', sources) Python flow-control can be used to iterate through invocations of build rules: objects = ['aaa.o', 'bbb.o', 'ccc.o'] for obj in objects: src = replace(obj, '.o', '.c') env.Make(obj, src) or to handle more complicated conditional invocations: # only build 'foo' on Linux systems if sys.platform == 'linux1': env.Make('foo', 'foo.c') Because &SCons; configuration files are Python scripts, syntax errors will be caught by the Python parser. Target-building does not begin until after all configuration files are read, so a syntax error will not cause a build to fail half-way.

A configuration file can instruct &SCons; to read up subsidiary configuration files. Subsidiary files are specified explicitly in a configuration file via the &SConscript; method. As usual, multiple file names may be specified with white space separation, or in an array: SConscript('other_file') SConscript('file1 file2') SConscript(['file3', 'file4']) SConscript(['file name with white space']) An explicit sconscript keyword may be used: SConscript(sconscript = 'other_file') Including subsidiary configuration files is recursive: a configuration file included via &SConscript; may in turn &SConscript; other configuration files.

When a subsidiary configuration file is read, it is given its own namespace; it does not have automatic access to variables from the parent configuration file. Any variables (not just &SCons; objects) that are to be shared between configuration files must be explicitly passed in the &SConscript; call using the &Export; method: env = Environment() debug = Environment(CCFLAGS = '-g') installdir = '/usr/bin' SConscript('src/SConscript', Export(env=env, debug=debug, installdir=installdir)) Which may be specified explicitly using a keyword argument: env = Environment() debug = Environment(CCFLAGS = '-g') installdir = '/usr/bin' SConscript(sconscript = 'src/SConscript', export = Export(env=env, debug=debug, installdir=installdir)) Explicit variable-passing provides control over exactly what is available to a subsidiary file, and avoids unintended side effects of changes in one configuration file affecting other far-removed configuration files (a very hard-to-debug class of build problem).

The &SConscript; method is so named because, by convention, subsidiary configuration files in subdirectories are named &SConscript;: SConscript('src/SConscript') SConscript('lib/build_me') When a subsidiary configuration file is read from a subdirectory, all of that configuration file's targets and build rules are interpreted relative to that directory (as if &SCons; had changed its working directory to that subdirectory). This allows for easy support of hierarchical builds of directory trees for large projects.

&SCons; will allow users to share &consenvs;, as well as other &SCons; objects and Python variables, by importing them from a central, shared repository using normal Python syntax: from LocalEnvironments import optimized, debug optimized.Make('foo', 'foo.c') debug.Make('foo-d', 'foo.c') The expectation is that some local tool-master, integrator or administrator will be responsible for assembling environments (creating the &Builder; objects that specify the tools, options, etc.) and make these available for sharing by all users. The modules containing shared &consenvs; (LocalEnvironments in the above example) can be checked in and controlled with the rest of the source files. This allows a project to track the combinations of tools and command-line options that work on different platforms, at different times, and with different tool versions, by using already-familiar revision control tools.

The &SCons; utility provides a &Help; function to allow the writer of a &SConstruct; file to provide help text that is specific to the local build tree: Help(""" Type: scons . build and test everything scons test build the software scons src run the tests scons web build the web pages """) This help text is displayed in response to the -h command-line option. Calling the &Help; function more than once is an error.

&SCons; supports several command-line options for printing extra information with which to debug build problems. See the -d, -p, -pa, and -pw options in the , below. All of these options make use of call-back functions to printed by the Build Engine.