The SConstruct File

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.[1] In other words, when you call the Program builder (or any other builder method), you're not telling SCons to build the program at the instant the builder method is called. Instead, you're telling SCons to build the program that you want, for example, a program built from a file named hello.c, and it's up to SCons to build that program (and any other files) whenever it's necessary. (We'll learn more about how SCons decides when building or rebuilding a file is necessary in the chapter called Dependencies, below.)

SCons reflects this distinction between calling a builder method like 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 statement that prints a string of characters to the screen. If we put print statements around our calls to the Program builder method:

       print "Calling Program('hello.c')"
       Program('hello.c')
       print "Calling Program('goodbye.c')"
       Program('goodbye.c')
       print "Finished calling Program()"
     

Then when we execute SCons, we see the output from the print statements in between the messages about reading the SConscript files, indicating that that is when the Python statements are being executed:

       % scons
       scons: Reading SConscript files ...
       Calling Program('hello.c')
       Calling Program('goodbye.c')
       Finished calling Program()
       scons: done reading SConscript files.
       scons: Building targets ...
       cc -c -o goodbye.o goodbye.c
       cc -o goodbye goodbye.o
       cc -c -o hello.o hello.c
       cc -o hello hello.o
       scons: done building targets.
     

Notice also 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.