Framewave Build System

Build Exceptions Rules

Prerequisite Documents

Framewave Build System - Architecture.doc

Framewave Build System - Compiler Flags Setup.doc

Introduction

There are various situations that exist due to which when compiling Framewave, we need to compile certain files in a different way than others. In some cases, we do not want to compile some files on particular platforms, or compile files with a different set of flags.

Setting up flags to handle these exceptions would become tedious, since flags are meant to deal with a general case. For example, if we want to ‘not’ use a flag on certain files on a particular platform, we’d have to add that flag n – x number of times (where n is the total number of files we are compiling and x is the number of files we do not want to compile) with an additional build factor of the filenames of the files we DO want to compile.

This would be a totally unfeasible approach; hence, the build exception system.

Description

The build exceptions system is similar to the flags system. We specify a set of build exception rules, which help narrow down what we wish to handle differently. It provides the negative specification for the final build.

All the build exception rules are specified in a single file: fwbuildexceptionsrules.py

The rules are specified via a dictionary, which holds the following key value pairs;

[ compiler, list of exceptions rules ]

The list of exceptions rules contains exception rules. Exception rules are a defined as a two element list, the elements of which are;

[ list of build factors, exception action ]

The possible build factors are the same as what we use in the flags setup with one exception. When we specify a filename as a build factor here, we have the ability to use wildcards. We can also specify a path with a filename if required.

Note: If a path is specified, it needs to be relative to the Framewave base directory, where the SConstruct file lives

Exception actions can be one of two: They can be the None value, which specifies, “do not build this file”, or they can be the name of a function pointer.

If the exception action is a function pointer, it needs to point to a function that returns an object of the type fwFlagsBase. Any import’s needed to get access to this function pointer need to be specified in the fwbuildexceptionsrules.py file (ideally near the top where the rest of the imports are).

Once the rule is set up, the Framewave build system will automatically pick up the rules, and apply them for every object, changing its build behavior as required.

Examples

These examples are all currently being used in the Framewave builds and are present in the fwbuildexceptionsrules.py and fwbuildexceptionshandlers.py files

Exception: [scc] Do not build the FilterMedian.cpp file

Rule entry: dctExceptionRules[scc] +=

[[[r'domain/aplImage/src/FilterMedian.cpp'], None]]

Exception: [gcc] Use a special flags handler class when building any Add files on Linux when compiling for the reference path

Rule entry: dctExceptionRules[gcc] +=

[[[r'*Add*.cpp', lin, ref], _gcc_AddSubFix]]

Errata

There is no limit on the number of exceptions but keep in mind that wildcards are expanded to all their possible variants when we run the build. Specifying a wildcard that maps to a very large set of files may slow down the build and/or use a lot of memory.