%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> The single most important thing you do when writing a build system for your project is to describe the "what": what you want to build, and which files you want to build it from. And, in fact, simpler builds may need no more. In this chapter, you will see several examples of very simple build configurations using &SCons;, which will demonstrate how easy &SCons; makes it to build programs on different types of systems.

Here's the ubiquitous "Hello, World!" program in C: #include <stdio.h> int main() { printf("Hello, world!\n"); } And here's how to build it using &SCons;. Save the code above into hello.c, and enter the following into a file named &SConstruct;: Program('hello.c') int main() { printf("Hello, world!\n"); } This minimal build file gives &SCons; three key pieces of information: what you want to build (a program); what you want to call that program (its base name will be hello), and the source file you want it built from (the hello.c file). &b-link-Program; is a &Builder;, an &SCons; function that you use to instruct &SCons; about the "what" of your build. That's it. Now run the &scons; command to build the program. On a POSIX-compliant system like Linux or UNIX, you'll see something like: scons On a Windows system with the &MSVC; compiler, you'll see something like: scons Notice that &SCons; deduced quite a bit here: it figured out the name of the program to build, including operating system specific suffixes (&hello; or &hello_exe;), based off the basename of the source file; it knows an intermediate object file should be built (&hello_o; or &hello_obj;); and it knows how to build those things using the compiler that is appropriate on the system you're using. It was not necessary to instruct &SCons; about any of those details. This is an example of how &SCons; makes it easy to write portable software builds. For the programming languages &SCons; already knows about, it will mostly just figure it out. Here's the "Hello, World!" example in Fortran: program hello print *, 'Hello, World!' end program hello Program('hello', 'hello.f90') $ scons scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... gfortran -o hello.o -c hello.f90 gfortran -o hello hello.o scons: done building targets.

The &b-link-Program; builder is only one of many builders (also called a &builder_method;) that &SCons; provides to build different types of files. Another is the &b-link-Object; builder method, which tells &SCons; to build an object file from the specified source file: Object('hello.c') int main() { printf("Hello, world!\n"); } Now when you run the &scons; command to build the program, it will build just the &hello_o; object file on a POSIX system: scons And just the &hello_obj; object file on a Windows system (with the &MSVC; compiler): scons (Note that this guide will not continue to provide duplicate side-by-side POSIX and Windows output for all of the examples. Just keep in mind that, unless otherwise specified, any of the examples should work equally well on both types of systems.)

&SCons; also makes building with Java extremely easy. Unlike the &b-link-Program; and &b-link-Object; builder methods, however, the &b-link-Java; builder method requires that you specify the name of a destination directory in which you want the class files placed, followed by the source directory in which the .java files live: Java('classes', 'src') public class Example1 { public static void main(String[] args) { System.out.println("Hello Java world!\n"); } } If the src directory contains a single hello.java file, then the output from running the &scons; command would look something like this (on a POSIX system): scons Java builds will be covered in much more detail, including building a Java archive (.jar) and other types of files, in .

For cleaning up your build tree, &SCons; provides a "clean" mode, selected by the -c or --clean option when you invoke &SCons;. &SCons; selects the same set of targets it would in build mode, but instead of building, removes them. That means you can control what is cleaned in exactly the same way as you control what gets built. If you build the C example above and then invoke scons -c afterwards, the output on POSIX looks like: Program('hello.c') int main() { printf("Hello, world!\n"); } scons scons -c And the output on Windows looks like: scons scons -c Notice that &SCons; changes its output to tell you that it is Cleaning targets ... and done cleaning targets.

If you're used to build systems like &Make; you've already figured out that the &SConstruct; file is the &SCons; equivalent of a &Makefile;. That is, the &SConstruct; file is the input file that &SCons; reads to control the build.

There is, however, an important difference between an &SConstruct; file and a &Makefile;: the &SConstruct; file is actually a &Python; script. If you're not already familiar with &Python;, don't worry. This User's Guide will introduce you step-by-step to the relatively small amount of &Python; you'll need to know to be able to use &SCons; effectively. And &Python; is very easy to learn. One aspect of using &Python; as the scripting language is that you can put comments in your &SConstruct; file using &Python;'s commenting convention: everything between a # character and the end of the line will be ignored (unless the character appears inside a string constant). # Arrange to build the "hello" program. Program("hello.c") # "hello.c" is the source file. Program("#goodbye.c") # the # in "#goodbye" does not indicate a comment You'll see throughout the remainder of this Guide that being able to use the power of a real scripting language can greatly simplify the solutions to complex requirements of real-world builds.

One important way in which the &SConstruct; file is not exactly like a normal &Python; script, and is more like a &Makefile;, is that the order in which the &SCons; Builder functions are called in the &SConstruct; file does not affect the order in which &SCons; actually builds the programs and object files you want it to build. In programming parlance, the &SConstruct; file is declarative, meaning you tell &SCons; what you want done and let it figure out the order in which to do it, rather than strictly imperative, where you specify explicitly the order in which to do things. . In other words, when you call the &b-link-Program; builder (or any other builder method), you're not telling &SCons; to build the program at that moment. Instead, you're telling &SCons; what you want accomplished, and it's up to &SCons; to figure out how to do that, and to take those steps if/when it's necessary. you'll learn more about how &SCons; decides when building or rebuilding a target is necessary in , below. &SCons; reflects this distinction between calling a builder method like &b-Program; and actually building the program by printing the status messages that indicate when it's "just reading" the &SConstruct; file, and when it's actually building the target files. This is to make it clear when &SCons; is executing the &Python; statements that make up the &SConstruct; file, and when &SCons; is actually executing the commands or other actions to build the necessary files. Let's clarify this with an example. &Python; has a print function that prints a string of characters to the screen. If you put print calls around the calls to the &b-Program; builder method: print("Calling Program('hello.c')") Program('hello.c') print("Calling Program('goodbye.c')") Program('goodbye.c') print("Finished calling Program()") int main() { printf("Hello, world!\n"); } int main() { printf("Goodbye, world!\n"); } Then, when you execute &SCons;, you will see the output from calling the print function in between the messages about reading the &SConscript; files, indicating that is when the &Python; statements are being executed: scons Notice that &SCons; built the &goodbye; program first, even though the "reading &SConscript;" output shows that Program('hello.c') was called first in the &SConstruct; file.

You've already seen how &SCons; prints some messages about what it's doing, surrounding the actual commands used to build the software: scons These messages emphasize the order in which &SCons; does its work: all of the configuration files (generically referred to as &SConscript; files) are read and executed first, and only then are the target files built. Among other benefits, these messages help to distinguish between errors that occur while the configuration files are read, and errors that occur while targets are being built. One drawback, of course, is that these messages clutter the output. Fortunately, they're easily disabled by using the &Q; option when invoking &SCons;: scons -Q So this User's Guide can focus on what &SCons; is actually doing, the &Q; option will be used to remove these messages from the output of all the remaining examples in this Guide.