# Simple Builds

In this chapter, you will see several examples of very simple build configurations using &SCons;, which will demonstrate how easy it is to use &SCons; to build programs from several different programming languages on different types of systems.

## Building Simple C / C++ Programs

Here's the famous "Hello, World!" program in C:

    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 configuration file gives &SCons; two pieces of information: what you want to build (an executable program), and the input file from which you want it built (the `hello.c` file). &b-link-Program; is a &builder_method;, a Python call that tells &SCons; that you want to build an executable program.

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 Microsoft Visual C++ compiler, you'll see something like:

scons

First, notice that you only need to specify the name of the source file, and that &SCons; correctly deduces the names of the object and executable files to be built from the base of the source file name.

Second, notice that the same input &SConstruct; file, without any changes, generates the correct output file names on both systems: &hello_o; and &hello; on POSIX systems, &hello_obj; and &hello_exe; on Windows systems. This is a simple example of how &SCons; makes it extremely easy to write portable software builds.

(Note that we won't provide duplicate side-by-side POSIX and Windows output for all of the examples in this guide; just keep in mind that, unless otherwise specified, any of the examples should work equally well on both types of systems.)

## Building Object Files

The &b-link-Program; builder method is only one of many builder methods 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 Microsoft Visual C++ compiler):

scons

## Simple Java Builds

&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

We'll cover Java builds in more detail, including building Java archive (`.jar`) and other types of file, in .

## Cleaning Up After a Build

When using &SCons;, it is unnecessary to add special commands or target names to clean up after a build. Instead, you simply use the `-c` or `--clean` option when you invoke &SCons;, and &SCons; removes the appropriate built files. So if we build our 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.`

## The &SConstruct; File

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.

### &SConstruct; Files Are Python Scripts

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; that is, everything between a '#' and the end of the line will be ignored:

    # Arrange to build the "hello" program.
    Program('hello.c')    # "hello.c" is the source file.

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.

### &SCons; Functions Are Order-Independent

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; 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. We'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 we put `print` calls around our 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 we execute &SCons;, we 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 we called `Program('hello.c')` first in the &SConstruct; file.

Notice also that &SCons; was able to infer a lot of information from the two &Program; calls. Because &hello_c; and `goodbye.c` were recognized as C-language source files, it knew to build the intermediate target files &hello_o; and &goodbye_o; and the final files &hello; and &goodbye; It was not necessary to program &scons; beyond just calling &Program;.

## Making the &SCons; Output Less Verbose

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

Because we want this User's Guide to focus on what &SCons; is actually doing, we're going to use the &Q; option to remove these messages from the output of all the remaining examples in this Guide.