|Project owner:||Scott Jenkins|
In very advanced situations, you may wish to have certain source code excluded from the built version of the file, based on some condition that is evaluated during the build itself.
This is somewhat analogous to the use of
#ifdef pragmas within the C pre-processor.
For example, you might wish to strip a profiling module from a release build but include it in a development build.
This feature is implemented by creating exclusion regions bracketed by start and end pragmas, as follows:
//>>excludeStart("Tag", kwArgs.layers.length > 1) ... code within the region here //>>excludeEnd("Tag")
Lines 1 and 5, beginning with
//>> are the pragmas. The
//>> is the symbol that the builder is looking for to tell it there is a pragma.
stopExclude work together to create the exclusion region: the region begins with the excludeStart, and ends with the matching excludeEnd pragma.
, `` *condition* ``)
- tag is a string (usually a string literal) naming the pair. This permits matching excludeStart and excludeEnd tags to be determined.
Note: the tag for the excludeStart pragma must be equal to the tag for the excludeEnd pragma.
The builder evaluates the condition in the excludeStart pramga at build time to determine whether or not to exclude the region from the as-built file.
The object you most commonly will evaluate against is
kwArgs which is where the builder stores its profile (it actually stores all of its parameters there, whether they originate in the profile, on the build command line, or from the builders’ built in defaults).
It is technically possible to nest conditional excludes. However, this is discouraged.
If you do nest, the exclusion regions must be fully and properly nested. Thus, the following would be illegal because the named regions overlap:
//>>excludeStart("AAA", kwArgs.layers.length > 1) ... //>>excludeStart("BBB", kwArgs.layers.indexOf("dojo") == 1) ... //>>excludeEnd("AAA") //>>excludeEnd("BBB")