summaryrefslogtreecommitdiff
path: root/doc/design/native.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:27 +0100
committerLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:27 +0100
commit72c578fd4b0b4a5a43e18594339ac4ff26c376dc (patch)
treecadaf3abe37a1066ceae933bc8fe7b75c85f56d2 /doc/design/native.xml
parent548ed1064f327bccc6e538806740d41ea2d928a1 (diff)
Imported Upstream version 1.2.0.d20091224upstream/1.2.0.d20091224
Diffstat (limited to 'doc/design/native.xml')
-rw-r--r--doc/design/native.xml364
1 files changed, 364 insertions, 0 deletions
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 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003 Steven Knight
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<para>
+
+ 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.
+
+</para>
+
+<section id="sect-config">
+ <title>Configuration files</title>
+
+ <para>
+
+ &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.
+
+ </para>
+
+ <para>
+
+ 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 <option>-f</option> command-line option exists to read a
+ different file name.
+
+ </para>
+
+</section>
+
+
+
+<section id="sect-syntax">
+ <title>Python syntax</title>
+
+ <para>
+
+ Because &SCons; configuration files are Python scripts, normal Python
+ syntax can be used to generate or manipulate lists of targets or
+ dependencies:
+
+ </para>
+
+ <programlisting>
+ sources = ['aaa.c', 'bbb.c', 'ccc.c']
+ env.Make('bar', sources)
+ </programlisting>
+
+ <para>
+
+ Python flow-control can be used to iterate through invocations of
+ build rules:
+
+ </para>
+
+ <programlisting>
+ objects = ['aaa.o', 'bbb.o', 'ccc.o']
+ for obj in objects:
+ src = replace(obj, '.o', '.c')
+ env.Make(obj, src)
+ </programlisting>
+
+ <para>
+
+ or to handle more complicated conditional invocations:
+
+ </para>
+
+ <programlisting>
+ # only build 'foo' on Linux systems
+ if sys.platform == 'linux1':
+ env.Make('foo', 'foo.c')
+ </programlisting>
+
+ <para>
+
+ 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.
+
+ </para>
+
+</section>
+
+
+
+<section id="sect-subsidiary">
+ <title>Subsidiary configuration Files</title>
+
+ <para>
+
+ 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:
+
+ </para>
+
+ <programlisting>
+ SConscript('other_file')
+ SConscript('file1 file2')
+ SConscript(['file3', 'file4'])
+ SConscript(['file name with white space'])
+ </programlisting>
+
+ <para>
+
+ An explicit <literal>sconscript</literal> keyword may be used:
+
+ </para>
+
+ <programlisting>
+ SConscript(sconscript = 'other_file')
+ </programlisting>
+
+ <para>
+
+ Including subsidiary configuration files is recursive: a configuration
+ file included via &SConscript; may in turn &SConscript; other
+ configuration files.
+
+ </para>
+
+</section>
+
+
+
+<section id="sect-scoping">
+ <title>Variable scoping in subsidiary files</title>
+
+ <para>
+
+ 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.
+
+ </para>
+
+ <para>
+
+ 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:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ debug = Environment(CCFLAGS = '-g')
+ installdir = '/usr/bin'
+ SConscript('src/SConscript', Export(env=env, debug=debug, installdir=installdir))
+ </programlisting>
+
+<!--
+The <literal>env=env</literal> stuff bugs me
+because it imposes extra work on the normal
+case where you <emphasis>don't</emphasis> rename
+the variables.
+Can we simplify the &Export; method
+so that a string
+without a keyword assignment
+is split into variables that are passed
+through transparently?
+Equivalent to the above example:
+<literal>SConscript('src/SConscript', Export('env debug installdir'))</literal>
+-->
+
+ <para>
+
+ Which may be specified explicitly using a keyword argument:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ debug = Environment(CCFLAGS = '-g')
+ installdir = '/usr/bin'
+ SConscript(sconscript = 'src/SConscript',
+ export = Export(env=env, debug=debug, installdir=installdir))
+ </programlisting>
+
+ <para>
+
+ 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).
+
+ </para>
+
+</section>
+
+
+
+<section id="sect-hierarchy">
+ <title>Hierarchical builds</title>
+
+ <para>
+
+ The &SConscript; method is so named because, by convention, subsidiary
+ configuration files in subdirectories are named &SConscript;:
+
+ </para>
+
+ <programlisting>
+ SConscript('src/SConscript')
+ SConscript('lib/build_me')
+ </programlisting>
+
+ <para>
+
+ 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.
+
+ </para>
+
+</section>
+
+
+
+<section id="sect-sharing">
+ <title>Sharing &consenvs;</title>
+
+ <para>
+
+ &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:
+
+ </para>
+
+ <programlisting>
+ from LocalEnvironments import optimized, debug
+
+ optimized.Make('foo', 'foo.c')
+ debug.Make('foo-d', 'foo.c')
+ </programlisting>
+
+ <para>
+
+ 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.
+
+ </para>
+
+ <para>
+
+ The modules containing shared &consenvs;
+ (<literal>LocalEnvironments</literal> 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.
+
+ </para>
+
+</section>
+
+
+
+<section id="sect-help">
+ <title>Help</title>
+
+ <para>
+
+ 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:
+
+ </para>
+
+ <programlisting>
+ Help("""
+ Type:
+ scons . build and test everything
+ scons test build the software
+ scons src run the tests
+ scons web build the web pages
+ """)
+ </programlisting>
+
+ <para>
+
+ This help text is displayed in response to the <option>-h</option>
+ command-line option. Calling the &Help; function more than once is an
+ error.
+
+ </para>
+
+</section>
+
+
+
+<section id="sect-debug">
+ <title>Debug</title>
+
+ <para>
+
+ &SCons; supports several command-line options for printing extra
+ information with which to debug build problems.
+
+ </para>
+
+<!--
+These need to be specified and explained
+beyond what the man page will have.
+-->
+
+ <!-- BEGIN HTML -->
+
+ <para>
+
+ See the -d, -p, -pa, and -pw options
+ in the <!--<A HREF="#sccons_Man_page">man page</A>-->, below.
+ All of these options make use of call-back functions to
+ <!--<A HREF="reference.html#Customizing_output">control the output</A>-->
+ printed by the Build Engine.
+
+ </para>
+
+ <!-- END HTML -->
+
+</section>