From 72c578fd4b0b4a5a43e18594339ac4ff26c376dc Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 2 Jan 2010 20:56:27 +0100 Subject: Imported Upstream version 1.2.0.d20091224 --- doc/design/native.xml | 364 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 364 insertions(+) create mode 100644 doc/design/native.xml (limited to 'doc/design/native.xml') diff --git a/doc/design/native.xml b/doc/design/native.xml new file mode 100644 index 0000000..8cdd867 --- /dev/null +++ b/doc/design/native.xml @@ -0,0 +1,364 @@ + + + + + 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; or &sconstruct (in that order) in the + current directory, and reads its configuration from the first file + found. A 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 + 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. + + + + + +
-- cgit v1.2.3