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.
29 you will see several examples of
30 very simple build configurations using &SCons;,
31 which will demonstrate how easy
32 it is to use &SCons; to
33 build programs from several different programming languages
34 on different types of systems.
39 <title>Building Simple C / C++ Programs</title>
43 Here's the famous "Hello, World!" program in C:
51 printf("Hello, world!\n");
57 And here's how to build it using &SCons;.
58 Enter the following into a file named &SConstruct;:
62 <scons_example name="ex1">
63 <file name="SConstruct" printme="1">
67 int main() { printf("Hello, world!\n"); }
73 This minimal configuration file gives
74 &SCons; two pieces of information:
75 what you want to build
76 (an executable program),
77 and the input file from
78 which you want it built
79 (the <filename>hello.c</filename> file).
80 &b-link-Program; is a <firstterm>builder_method</firstterm>,
81 a Python call that tells &SCons; that you want to build an
88 That's it. Now run the &scons; command to build the program.
89 On a POSIX-compliant system like Linux or UNIX,
90 you'll see something like:
94 <scons_output example="ex1" os="posix">
95 <scons_output_command>scons</scons_output_command>
100 On a Windows system with the Microsoft Visual C++ compiler,
101 you'll see something like:
105 <scons_output example="ex1" os="win32">
106 <scons_output_command>scons</scons_output_command>
111 First, notice that you only need
112 to specify the name of the source file,
113 and that &SCons; correctly deduces the names of
114 the object and executable files to be built
115 from the base of the source file name.
121 Second, notice that the same input &SConstruct; file,
123 generates the correct output file names on both systems:
124 <filename>hello.o</filename> and <filename>hello</filename>
126 <filename>hello.obj</filename> and <filename>hello.exe</filename>
128 This is a simple example of how &SCons;
129 makes it extremely easy to
130 write portable software builds.
136 (Note that we won't provide duplicate side-by-side
137 POSIX and Windows output for all of the examples in this guide;
138 just keep in mind that, unless otherwise specified,
139 any of the examples should work equally well on both types of systems.)
146 <title>Building Object Files</title>
150 The &b-link-Program; builder method is only one of
151 many builder methods that &SCons; provides
152 to build different types of files.
153 Another is the &b-link-Object; builder method,
154 which tells &SCons; to build an object file
155 from the specified source file:
159 <scons_example name="Object">
160 <file name="SConstruct" printme="1">
163 <file name="hello.c">
164 int main() { printf("Hello, world!\n"); }
170 Now when you run the &scons; command to build the program,
171 it will build just the &hello_o; object file on a POSIX system:
175 <scons_output example="Object" os="posix">
176 <scons_output_command>scons</scons_output_command>
181 And just the &hello_obj; object file
182 on a Windows system (with the Microsoft Visual C++ compiler):
186 <scons_output example="Object" os="win32">
187 <scons_output_command>scons</scons_output_command>
193 <title>Simple Java Builds</title>
197 &SCons; also makes building with Java extremely easy.
198 Unlike the &b-link-Program; and &b-link-Object; builder methods,
199 however, the &b-link-Java; builder method
200 requires that you specify
201 the name of a destination directory in which
202 you want the class files placed,
203 followed by the source directory
204 in which the <filename>.java</filename> files live:
208 <scons_example name="java">
209 <file name="SConstruct" printme="1">
210 Java('classes', 'src')
212 <file name="src/hello.java">
213 public class Example1
215 public static void main(String[] args)
217 System.out.println("Hello Java world!\n");
225 If the <filename>src</filename> directory
226 contains a single <filename>hello.java</filename> file,
227 then the output from running the &scons; command
228 would look something like this
233 <scons_output example="java" os="posix">
234 <scons_output_command>scons</scons_output_command>
239 We'll cover Java builds in more detail,
240 including building Java archive (<filename>.jar</filename>)
241 and other types of file,
242 in <xref linkend="chap-java"></xref>.
249 <title>Cleaning Up After a Build</title>
253 When using &SCons;, it is unnecessary to add special
254 commands or target names to clean up after a build.
255 Instead, you simply use the
256 <literal>-c</literal> or <literal>--clean</literal>
257 option when you invoke &SCons;,
258 and &SCons; removes the appropriate built files.
259 So if we build our example above
260 and then invoke <literal>scons -c</literal>
261 afterwards, the output on POSIX looks like:
265 <scons_example name="clean">
266 <file name="SConstruct">
269 <file name="hello.c">
270 int main() { printf("Hello, world!\n"); }
274 <scons_output example="clean" os="posix">
275 <scons_output_command>scons</scons_output_command>
276 <scons_output_command>scons -c</scons_output_command>
281 And the output on Windows looks like:
285 <scons_output example="clean" os="win32">
286 <scons_output_command>scons</scons_output_command>
287 <scons_output_command>scons -c</scons_output_command>
292 Notice that &SCons; changes its output to tell you that it
293 is <literal>Cleaning targets ...</literal> and
294 <literal>done cleaning targets.</literal>
301 <title>The &SConstruct; File</title>
305 If you're used to build systems like &Make;
306 you've already figured out that the &SConstruct; file
307 is the &SCons; equivalent of a &Makefile;.
308 That is, the &SConstruct; file is the input file
309 that &SCons; reads to control the build.
314 <title>&SConstruct; Files Are Python Scripts</title>
318 There is, however, an important difference between
319 an &SConstruct; file and a &Makefile;:
320 the &SConstruct; file is actually a Python script.
321 If you're not already familiar with Python, don't worry.
322 This User's Guide will introduce you step-by-step
323 to the relatively small amount of Python you'll
324 need to know to be able to use &SCons; effectively.
325 And Python is very easy to learn.
331 One aspect of using Python as the
332 scripting language is that you can put comments
333 in your &SConstruct; file using Python's commenting convention;
334 that is, everything between a '#' and the end of the line
340 # Arrange to build the "hello" program.
341 Program('hello.c') # "hello.c" is the source file.
346 You'll see throughout the remainder of this Guide
347 that being able to use the power of a
348 real scripting language
349 can greatly simplify the solutions
350 to complex requirements of real-world builds.
357 <title>&SCons; Functions Are Order-Independent</title>
361 One important way in which the &SConstruct;
362 file is not exactly like a normal Python script,
363 and is more like a &Makefile,
364 is that the order in which
365 the &SCons; functions are called in
366 the &SConstruct; file
367 does <emphasis>not</emphasis>
368 affect the order in which &SCons;
369 actually builds the programs and object files
370 you want it to build.<footnote>
371 <para>In programming parlance,
372 the &SConstruct; file is
373 <emphasis>declarative</emphasis>,
374 meaning you tell &SCons; what you want done
375 and let it figure out the order in which to do it,
376 rather than strictly <emphasis>imperative</emphasis>,
377 where you specify explicitly the order in
381 In other words, when you call the &b-link-Program; builder
382 (or any other builder method),
383 you're not telling &SCons; to build
384 the program at the instant the builder method is called.
385 Instead, you're telling &SCons; to build the program
386 that you want, for example,
387 a program built from a file named &hello_c;,
388 and it's up to &SCons; to build that program
389 (and any other files) whenever it's necessary.
390 (We'll learn more about how
391 &SCons; decides when building or rebuilding a file
392 is necessary in <xref linkend="chap-depends"></xref>, below.)
398 &SCons; reflects this distinction between
399 <emphasis>calling a builder method like</emphasis> &b-Program;
400 and <emphasis>actually building the program</emphasis>
401 by printing the status messages that indicate
402 when it's "just reading" the &SConstruct; file,
403 and when it's actually building the target files.
404 This is to make it clear when &SCons; is
405 executing the Python statements that make up the &SConstruct; file,
406 and when &SCons; is actually executing the
407 commands or other actions to
408 build the necessary files.
414 Let's clarify this with an example.
415 Python has a <literal>print</literal> statement that
416 prints a string of characters to the screen.
417 If we put <literal>print</literal> statements around
418 our calls to the &b-Program; builder method:
422 <scons_example name="declarative">
423 <file name="SConstruct" printme="1">
424 print "Calling Program('hello.c')"
426 print "Calling Program('goodbye.c')"
428 print "Finished calling Program()"
430 <file name="hello.c">
431 int main() { printf("Hello, world!\n"); }
433 <file name="goodbye.c">
434 int main() { printf("Goodbye, world!\n"); }
440 Then when we execute &SCons;,
441 we see the output from the <literal>print</literal>
442 statements in between the messages about
443 reading the &SConscript; files,
444 indicating that that is when the
445 Python statements are being executed:
449 <scons_output example="declarative" os="posix">
450 <scons_output_command>scons</scons_output_command>
455 Notice also that &SCons; built the &goodbye; program first,
456 even though the "reading &SConscript" output
457 shows that we called <literal>Program('hello.c')</literal>
458 first in the &SConstruct; file.
467 <title>Making the &SCons; Output Less Verbose</title>
471 You've already seen how &SCons; prints
472 some messages about what it's doing,
473 surrounding the actual commands used to build the software:
477 <scons_output example="ex1" os="win32">
478 <scons_output_command>scons</scons_output_command>
483 These messages emphasize the
484 order in which &SCons; does its work:
485 all of the configuration files
486 (generically referred to as &SConscript; files)
487 are read and executed first,
488 and only then are the target files built.
489 Among other benefits, these messages help to distinguish between
490 errors that occur while the configuration files are read,
491 and errors that occur while targets are being built.
497 One drawback, of course, is that these messages clutter the output.
498 Fortunately, they're easily disabled by using
499 the &Q; option when invoking &SCons;:
503 <scons_output example="ex1" os="win32">
504 <scons_output_command>scons -Q</scons_output_command>
509 Because we want this User's Guide to focus
510 on what &SCons; is actually doing,
511 we're going to use the &Q; option
512 to remove these messages from the
513 output of all the remaining examples in this Guide.