3 Copyright (c) 2001, 2002, 2003 Steven Knight
5 Permission is hereby granted, free of charge, to any person obtaining
6 a copy of this software and associated documentation files (the
7 "Software"), to deal in the Software without restriction, including
8 without limitation the rights to use, copy, modify, merge, publish,
9 distribute, sublicense, and/or sell copies of the Software, and to
10 permit persons to whom the Software is furnished to do so, subject to
11 the following conditions:
13 The above copyright notice and this permission notice shall be included
14 in all copies or substantial portions of the Software.
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
17 KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
18 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 The "Native Python" interface is the interface
29 that the actual &SCons; utility will present to users.
30 Because it exposes the Python Build Engine API,
31 &SCons; users will have direct access to the complete
32 functionality of the Build Engine.
33 In contrast, a different user interface such as a GUI
34 may choose to only use, and present to the end-user,
35 a subset of the Build Engine functionality.
39 <section id="sect-config">
40 <title>Configuration files</title>
44 &SCons; configuration files are simply Python scripts that invoke
45 methods to specify target files to be built, rules for building the
46 target files, and dependencies. Common build rules are available by
47 default and need not be explicitly specified in the configuration
54 By default, the &SCons; utility searches for a file named
55 &SConstruct;, &Sconstruct; or &sconstruct (in that order) in the
56 current directory, and reads its configuration from the first file
57 found. A <option>-f</option> command-line option exists to read a
66 <section id="sect-syntax">
67 <title>Python syntax</title>
71 Because &SCons; configuration files are Python scripts, normal Python
72 syntax can be used to generate or manipulate lists of targets or
78 sources = ['aaa.c', 'bbb.c', 'ccc.c']
79 env.Make('bar', sources)
84 Python flow-control can be used to iterate through invocations of
90 objects = ['aaa.o', 'bbb.o', 'ccc.o']
92 src = replace(obj, '.o', '.c')
98 or to handle more complicated conditional invocations:
103 # only build 'foo' on Linux systems
104 if sys.platform == 'linux1':
105 env.Make('foo', 'foo.c')
110 Because &SCons; configuration files are Python scripts, syntax errors
111 will be caught by the Python parser. Target-building does not begin
112 until after all configuration files are read, so a syntax error will
113 not cause a build to fail half-way.
121 <section id="sect-subsidiary">
122 <title>Subsidiary configuration Files</title>
126 A configuration file can instruct &SCons; to read up subsidiary
127 configuration files. Subsidiary files are specified explicitly in a
128 configuration file via the &SConscript; method. As usual, multiple
129 file names may be specified with white space separation, or in an
135 SConscript('other_file')
136 SConscript('file1 file2')
137 SConscript(['file3', 'file4'])
138 SConscript(['file name with white space'])
143 An explicit <literal>sconscript</literal> keyword may be used:
148 SConscript(sconscript = 'other_file')
153 Including subsidiary configuration files is recursive: a configuration
154 file included via &SConscript; may in turn &SConscript; other
163 <section id="sect-scoping">
164 <title>Variable scoping in subsidiary files</title>
168 When a subsidiary configuration file is read, it is given its own
169 namespace; it does not have automatic access to variables from the parent
176 Any variables (not just &SCons; objects) that are to be shared between configuration files must be
177 explicitly passed in the &SConscript; call
178 using the &Export method:
184 debug = Environment(CCFLAGS = '-g')
185 installdir = '/usr/bin'
186 SConscript('src/SConscript', Export(env=env, debug=debug, installdir=installdir))
190 The <literal>env=env</literal> stuff bugs me
191 because it imposes extra work on the normal
192 case where you <emphasis>don't</emphasis> rename
194 Can we simplify the &Export; method
196 without a keyword assignment
197 is split into variables that are passed
198 through transparently?
199 Equivalent to the above example:
200 <literal>SConscript('src/SConscript', Export('env debug installdir'))</literal>
205 Which may be specified explicitly using a keyword argument:
211 debug = Environment(CCFLAGS = '-g')
212 installdir = '/usr/bin'
213 SConscript(sconscript = 'src/SConscript',
214 export = Export(env=env, debug=debug, installdir=installdir))
219 Explicit variable-passing provides control over exactly what is available
220 to a subsidiary file, and avoids unintended side effects of changes in
221 one configuration file affecting other far-removed configuration files
222 (a very hard-to-debug class of build problem).
230 <section id="sect-hierarchy">
231 <title>Hierarchical builds</title>
235 The &SConscript; method is so named because, by convention, subsidiary
236 configuration files in subdirectories are named &SConscript;:
241 SConscript('src/SConscript')
242 SConscript('lib/build_me')
247 When a subsidiary configuration file is read from a subdirectory, all
248 of that configuration file's targets and build rules are interpreted
249 relative to that directory (as if &SCons; had changed its working
250 directory to that subdirectory). This allows for easy support of
251 hierarchical builds of directory trees for large projects.
259 <section id="sect-sharing">
260 <title>Sharing &consenvs;</title>
264 &SCons; will allow users to share &consenvs, as well as other &SCons;
265 objects and Python variables, by importing them from a central, shared
266 repository using normal Python syntax:
271 from LocalEnvironments import optimized, debug
273 optimized.Make('foo', 'foo.c')
274 debug.Make('foo-d', 'foo.c')
279 The expectation is that some local tool-master, integrator or
280 administrator will be responsible for assembling environments (creating
281 the &Builder; objects that specify the tools, options, etc.) and make
282 these available for sharing by all users.
288 The modules containing shared &consenvs;
289 (<literal>LocalEnvironments</literal> in the above example) can be
290 checked in and controlled with the rest of the source files. This
291 allows a project to track the combinations of tools and command-line
292 options that work on different platforms, at different times, and with
293 different tool versions, by using already-familiar revision control
302 <section id="sect-help">
307 The &SCons; utility provides a &Help; function to allow the writer
308 of a &SConstruct; file to provide help text that is specific to
309 the local build tree:
316 scons . build and test everything
317 scons test build the software
318 scons src run the tests
319 scons web build the web pages
325 This help text is displayed in response to the <option>-h</option>
326 command-line option. Calling the &Help; function more than once is an
335 <section id="sect-debug">
340 &SCons; supports several command-line options for printing extra
341 information with which to debug build problems.
346 These need to be specified and explained
347 beyond what the man page will have.
354 See the -d, -p, -pa, and -pw options
355 in the <!--<A HREF="#sccons_Man_page">man page</A>-->, below.
356 All of these options make use of call-back functions to
357 <!--<A HREF="reference.html#Customizing_output">control the output</A>-->
358 printed by the Build Engine.