# Native Python Interface

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.

## Configuration files

&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;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; or &sconstruct.py; (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.

## Python syntax

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.

## Subsidiary configuration Files

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.

## Variable scoping in subsidiary 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).

## Hierarchical builds

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.

## Sharing &consenvs;

&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.

## Help

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.

## Debug

&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.