Framewave Build System
Compiler Flags Setup
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,
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,
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 fwflags_gcc.py 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]
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
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;
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;