Please note:The SCons wiki is now restored from the attack in March 2013. All old passwords have been invalidated. Please reset your password if you have an account. If you note missing pages, please report them to webmaster@scons.org. Also, new account creation is currently disabled due to an ongoing spam flood (2013/08/27).
Differences between revisions 62 and 63
Revision 62 as of 2012-11-22 11:50:01
Size: 4790
Editor: mm-127-247-57-86
Comment: you don't have to know what make is
Revision 63 as of 2012-11-22 12:39:29
Size: 4808
Editor: mm-127-247-57-86
Comment: try to avoid Python lexicon (import)
Deletions are marked like this. Additions are marked like this.
Line 6: Line 6:
When running scons it will automatically import an environment that makes an '''Environment''' class available. You must first instantiate this class (this is not strictly required, but you'll need it sooner or later, so best do it right away) : When running scons it will automatically make all its API available for usage from SConstruct, including '''Environment''' class. You must first instantiate this class (this is not strictly required, but you'll need it sooner or later, so best do it right away) :

If you're familiar with make utility, SCons is a replacement for it. As the make utility looks for a Makefile, SCons looks for a SConstruct file by default. SConstruct file is a Python script. Note that you do not have to know Python or make for basic operation with this build tool.

See SconsProcessOverview for a high level view of SCons processing.

When running scons it will automatically make all its API available for usage from SConstruct, including Environment class. You must first instantiate this class (this is not strictly required, but you'll need it sooner or later, so best do it right away) :

   1 env = Environment()

This sets up a basic environment. Afterwards, you can set up targets.

   1 env.Program(target='bar', source=['foo.c'])

This will make a program 'bar' from 'foo.c'.

For more complex programs you must set up a more specialized environment. For example, setting up the flags the compiler will use, include directories, etc.

To do that you can specify named parameters such as CCFLAGS for C files or CPPFLAGS for the C++ Preprocessor. More of these can be seen below in this article and also in the Configuration File Reference section of the man page.

   1 # directly when constructing your Environment
   2 env = Environment(CCFLAGS='-O3')
   3 
   4 # ... or appending it later
   5 env.Append(CCFLAGS='-O3')

Some parameters require specific lists, such as the source list. Reading the Configuration File Reference should be very helpful.

Specifying A Default Target

An important note is the Default command. It tells scons what to build by default. It will not build anything unless you specify a target otherwise.

   1 t = env.Program(target='bar', source=['foo.c'])
   2 Default(t)

http://upload.wikimedia.org/wikipedia/commons/thumb/6/69/Im-jabber.svg/48px-Im-jabber.svg.png Tip

You can pass the target name to Default(), but Steven Knight (author of SCons) recommends that you use the return value from your target as the default value instead of specifying the name. He explains it best: "The only stylistic suggestion I'll make is that if you use the object returned by env.Program as the input to Default(), then you'll be more portable, since you won't have to worry about whether the generated program will have a .exe suffix or not."

You can call Default many times to add to the default target list.

Some Common tasks

A few common tasks are shown below. (Note that, although these examples mostly use 'Append', you can also specify the same information by using the same flags when calling e.g. Program())

Add flags from a config

   1 env.ParseConfig( 'pkg-config --cflags glib-2.0' )

Add header search path

   1 env.Append(CPPPATH = ['/usr/local/include/'])

Add compile-time flags

   1 env.Append(CCFLAGS = ['-g','-O3'])

Add define

   1 env.Append(CPPDEFINES=['BIG_ENDIAN'])

Add define with value (e.g. -DRELEASE_BUILD=1)

   1 env.Append(CPPDEFINES={'RELEASE_BUILD' : '1'})

Add library search path

   1 env.Append(LIBPATH = ['/usr/local/lib/'])

Add libraries to link against

   1 env.Append(LIBS = ['SDL_image','GL'])

Link time flags

   1 env.Append(LINKFLAGS = ['-Wl,--rpath,/usr/local/lib/'])

Building a more complex program that the example outlined above can be done the following way :

   1 sources = Split("""
   2 main.cpp
   3 utils.cpp
   4 gui.cpp
   5 """)
   6 object_list = env.Object(source = sources)
   7 env.Program( target = 'a.out', source = object_list )

SConscript and build dir

To avoid struggle, make sure you create at least two scripts - SConstruct and SConscript. This will allow you to build into a separate folder from your source files, and eventually this will allow you to harness more of the power of scons. Example: SConscript('SConscript', build_dir='.build', duplicate=0)  And then you put all the usual stuff from the examples inside SConscript instead of SConstruct. I was hammering at this for an hour trying to do it all in one file, but the build_dir functionality just wouldn't cooperate until I did this, now I'm in heaven. Now that you've done it this way, you can pass some values into your SConscript and call it multiple times:

   1 SConscript('SConscript', build_dir='.build_release', duplicate=0, exports={'MODE':'release'})
   2 SConscript('SConscript', build_dir='.build_debug', duplicate=0, exports={'MODE':'debug'})

SConsCrashCourse (last edited 2012-11-22 12:39:29 by mm-127-247-57-86)