Framewave Build System


Compiler Flags Setup



Prerequisite Documents


Framewave Build System - Architecture.doc





Due to its multi-pass compilation feature, Framewave has some unique requirements from its build system. Driven by these requirements, Framewave uses a custom build system, implemented in Python using the SCons build tool.


Developers of Framewave don’t need to know the internal details of the build system. What is essential is the ability to add and modify flags for the various different compilers supported by this build system. This document presents the structure of the compiler flags setup for this build system and how users can modify it for their individual needs.





Currently three different toolsets are supported by the build system. These are,

  • Microsoft Visual C++
    •  Flags for this compiler are defined in the file
    •  Verified with Visual studio 2005
  • GNU C++
    •  Flags for this compiler are defined in the file
    •  Verified with GCC 4.1.2 ( and with GCC 4.0.2 on MacOS)
  • Sun Studio C++
    •  Flags for this compiler are defined in the file
    •  Verified with Sun studio 12 (Patch 124864-01 2007/07/18)


Compiler flags are indexed by the toolset, to allow for the possibility of the same toolset on multiple platforms. For example, compiler flags defined for GCC are used on Linux, Soalris, and Mac OS Darwin.


Before we talk about how the flags are set up, we need to go over the concept of ‘build factors’, in Framewave’s context.


The Framewave build system defines a list of ‘build factors’. The ‘build factors’ contain properties defined for a given build and a given source file.  The Framewave build system generates flags for every single source file based on different build factors that are defined. For example, when building Add.cpp in fwImage, some of the build factors would be,

·         Which variant are we building? Debug or release.

·         Which operating system are we building for?

·         Which optimization level are we building this file for?


Based on these various factors, different flags would apply. For example, when building the release build for the SSE2 code path, the ‘-O2’ and ‘-msse2’ flags need to be specified.  For the same build configuration but for the reference code path, only the ‘-O2’ flag needs to be specified.


So, this is how we define our flags.


There are two dictionaries in each of the flags files that need to be populated with flags. They are,

  • dctCCFlags: This dictionary contains the compiler flags for the toolset
  • dctLDFlags: This dictionary contains the linker flags for the toolset


Each of these dictionaries hold the following key/value pair;


key: The actual string for the flag

value: The list of build factors for which this flag is to be applied


So to define an example flag rule for ‘-O2’, which is included on release builds but only when compiled on Linux, we would have to have the following line in the file;


dctCCFlags[r'-O2'] = [rel, lin]


The more build factors you specify in the value, the more restrictive the application of the flag. To apply a flag to every single file, in every build on that toolset, the value needs to be an empty list.


Using this technique, a user can specify flags with a great deal of flexibility. A flag can be defined multiple times for mutually exclusive combinations of build flags. Using the above example, the example flag rule can be specified without using nested lists, but by defining two separate build rules.  Each build rule would specifying the ‘rel’ build factor and the platform:


dctCCFlags[r'-O2'] = [rel, mac]

dctCCFlags[r'-O2'] = [rel, sol]



This build factors list defines an “and” relation between the build factors for a particular flag. There are circumstances though, where an “or” relation is useful. To specify an “or” relation, the build factors need to be in a nested list inside the main list. Like in the previous example, if we want to use ‘-O2’ only for release builds but for either Darwin or Solaris builds, we’d use;


dctCCFlags[r'-O2'] = [rel, [mac,sol]]


This feature, though not essential, makes flag definitions much less cumbersome.


As of now, the build system provides the user with the following build factors to use;


  • dbg, rel
    • These define which variant we are building
  • b32, b64
    • These define whether we’re building 32 or 64 bit
  • shr, stc, exe
    • These define whether we’re building a shared library, static library or an executable
  • lin, win, sol, mac
    • These define which OS we are building on
  • ref, ss2, ss3, f10, spc
    • These define what optimization level we are compiling for. “spc” stands for a single pass compile, i.e., a file being compiled without using the multi-pass system
  • gcc, msv, scc
    • These define which toolset we are compiling with. Using these with flags is useless. They are used in the build exceptions process
  • source filename [with full absolute path]
    • The filename of the source file with the complete absolute path is also a build factor. This can be used to super-specify a flag to apply only to a particular file


If there is a flag you want to put in the flags file for now but don’t wish it to be used, set it’s value to “None”.





These examples are all currently being used in the Framewave builds and are present in the various flags files


Rule:    [gcc] Use the ‘-m64’ flag for all 64 bit builds


Entry:   dctCCFlags[r'-m64'] = [b64]



Rule:    [gcc] Use the ‘-O2’ flag for all release builds on Mac and Solaris and for 32 bit release builds on Linux


Entry:   dctCCFlags[r'-O2'] = [rel,b32,lin]

      dctCCFlags[r'-O2'] = [rel,[mac,sol]]


Rule:    [suncc] Use the ‘-xtarget=opteron’ flag for all sseX optimized builds


Entry:   dctCCFlags[r'-xtarget=opteron'] = [[ss2,ss3,f10]]



Rule:    [msvc] Use the ‘/favor:AMD64’ flag for all 64 bit release builds for the optimized paths


Entry:   dctCCFlags[r'/favor:AMD64'] = [rel, b64, [ss2, ss3, f10]]



You can specify arbitrarily more build factors if and when needed. Look at the various flags files for more examples.





These are some of the known issues and limitations with the flags system;


  • Adding additional build factors isn’t trivial
  • There is no GUI available to assist flags setup
  • The flags system does not process wildcards (the build exceptions system does)