Penguin
Recent Changes
Annotated edit history of MakeToSCons version 11, including all changes. View license author blame.
Rev Author # Line
7 SamJansen 1 SamJansen's work in progress.
10 JohnMcPherson 2
11 AristotlePagaltzis 3 !!! What?
7 SamJansen 4
5 This document describes moving from the traditional make(1) build system to the [Python]-based [SCons] replacement.
6
11 AristotlePagaltzis 7 !!! Why?
7 SamJansen 8
9 make(1) is not for everyone. I've had to maintain the build system for a reasonably large and complex project and using makefiles has been more and more of a headache as time has passed. I have found almost no redeeming features in make - the only thing I can say for it is that most people who wish to compile software will have it installed.
10
11 AristotlePagaltzis 11 !!! Who?
7 SamJansen 12
11 AristotlePagaltzis 13 Should you use [SCons] too? Maybe. [SCons] requires that whoever has to compile the software has both [Python] and [SCons] installed. If this is an acceptable requirement, then the answer is probably "yes".
7 SamJansen 14
9 AristotlePagaltzis 15 The worst thing about [SCons] is that it does take some time to learn. It is not hard to learn; being based on the simple but powerful programming language [Python] helps here, but it can be hard to make the leap from a system you already know to a new one, even if the old system is inferior, simply because of the extra time it takes to learn the new system. However, I recommend learning modern build systems that don't employ make.
7 SamJansen 16
17 !!! The simple stuff
18
11 AristotlePagaltzis 19 [SCons] does a few things for free. Dependency tracking is the first one that springs to mind. Consider the following makefile and its [SCons] equivalent:
20
21 '''':
7 SamJansen 22
11 AristotlePagaltzis 23 MakeFile::
9 AristotlePagaltzis 24 <verbatim>
25 program: main.o sam.o johno.o
26 gcc -o $@ $^
27 </verbatim>
7 SamJansen 28
9 AristotlePagaltzis 29 SConstruct::
30 <verbatim>
31 Program(source = ["main.c", "sam.c", "johno.c"], target = "program")
32 </verbatim>
7 SamJansen 33
11 AristotlePagaltzis 34 Both of these work the same at the first glance, though I believe the SConstruct file (yes, SConstruct is the name of the file that replaces your MakeFile) to be a lot more readable. However the [SCons] file has the following extra features:
7 SamJansen 35
9 AristotlePagaltzis 36 * Proper dependency tracking. [SCons] scans the source file for headers so it knows when each file needs to be compiled. Make has no knowledge of this by default, and doing proper dependency tracking in make is quite a nightmare (but possible).
11 AristotlePagaltzis 37 * [MD5] checksum based checking of the source files to see which ones need to be recompiled. Make uses timestamps, which is also an option for [SCons].
9 AristotlePagaltzis 38 * No explicit rules needed for this simple example. In this particular MakeFile the linking line is still necessary, along with strange syntax: a casual reader has no idea what <tt>$@</tt> and <tt>$^</tt> mean. To be fair, make has a lot of implicit rules, and the command wouldn't be necessary here if there was a dependency with the same basename as the target, ie something like <tt>foo: foo.o bar.o</tt>.
39 * You can automatically clean the build with <tt>scons -c</tt>. This cleans only the files generated in the build. Clean rules have to be specified by the programmer in MakeFile~s.
11 AristotlePagaltzis 40 * Even works in [Windows] with the MicrosoftVisualStudio [C] Compiler.
7 SamJansen 41
9 AristotlePagaltzis 42 !! Setting <tt>CFLAGS</tt> and similar
7 SamJansen 43
9 AristotlePagaltzis 44 You generally create an construction environment to set environment variables in [SCons] like so:
7 SamJansen 45
11 AristotlePagaltzis 46 <verbatim>
47 env = Environment(CCFLAGS = '-Wall -pipe', LIBS = ['m', 'jpeg'])
48 env.Program('sam', ["lib.c", "sam.cc"], CPPPATH = ['include', 'common/include'])
49 env.SharedLibrary('testlib', ["source1.cc", "source2.c"])
50 </verbatim>
7 SamJansen 51
9 AristotlePagaltzis 52 This also sets the variable <tt>CPPPATH</tt>, which specifies which directories are to be searched for include files that are scanned during depency tracking. These are also passed to the compiler with the <tt>-I</tt> flag in the case of [GCC]. The flags can also be passed in the <tt>Program</tt> or <tt>Library</tt> line, constructing and <tt>Environment</tt> is usually done so multiple things can be built with the same environment.
53
54 A full list of the possible options can be found in [the SCons manual | http://www.scons.org/doc/HTML/scons-man.html].
7 SamJansen 55
56 !!! Intermediate steps
57
9 AristotlePagaltzis 58 In many cases the above will be enough: often you just want to build a directory of files into a library, shared library, or executable with a specific set of flags and dependencies. Of course, [SCons] lets you do a lot more, and at little to no extra cost in complexity.
7 SamJansen 59
60 !! Globbing multiple source files
61
9 AristotlePagaltzis 62 It is simplicity itself to include multiple files in the build. Remember that [SCons] is [Python]-based?
7 SamJansen 63
11 AristotlePagaltzis 64 <verbatim>
65 import glob
66 Library(glob.glob('*.c') + glob.glob('source_dir_2/*.cc'), 'sam')
67 </verbatim>
7 SamJansen 68
9 AristotlePagaltzis 69 [Python]'s <tt>glob</tt> module does all the hard work. Again, full dependency tracking and all other features of [SCons] work correctly.
7 SamJansen 70
71 !! Hierarchical builds
72
9 AristotlePagaltzis 73 [SCons] supports hierarchical builds with the use of the <tt>SConscript</tt> directive. These scripts will be read and their information processed. No new [SCons] is forked for the <tt>SConscript</tt> directives, unlike the usual recursive make solution.
8 SamJansen 74
75 Including other directories in the build is as simple as:
76
11 AristotlePagaltzis 77 <verbatim>
78 SConscript("dir1/")
79 SConscript("dir2/")
80 </verbatim>
8 SamJansen 81
9 AristotlePagaltzis 82 This will read in the <tt>SConscript</tt> files in <tt>dir1</tt> and <tt>dir2</tt>. It is possible to export environments to these other scripts if need be.