Introduction

The GULP module µBuildFilter allows you to define different source code variations within a single source code and to switch between these variations by commenting out or commenting in areas according to the specifications.

Installation

npm install gulp-mu-build-filter

Usage

import µBuildFilter from 'gulp-mu-build-filter';

gulp.task('SET_SOURCES_TO_V1_7', function (cb) {
    console.log('Set sources to V1.7...');
    gulp.src(["./src/*.js"])
       .pipe(µBuildFilter({
				release: 'Development', 
				client: 'MyCompany', 
				version: '1.7', 
				mode: "setupComments", 
				protocol:true}))
       .pipe(gulp.dest('./eMPClient/js/'));
    gulp.src(["./index.html"])
       .pipe(µBuildFilter({
				release: 'Development', 
				client: '*', 
				version: '1.7', 
				mode: "setupComments", 
				protocol:true}))
       .pipe(gulp.dest('./src/'));
    cb();
})

or

const µBuildFilter = require('gulp-mu-build-filter');

gulp.task('SET_SOURCES_TO_V1_7', function (cb) {
    console.log('Set sources to V1.7...');
    gulp.src(["./src/*.js"])
       .pipe(µBuildFilter({
				release: 'Development', 
				client: 'MyCompany', 
				version: '1.7', 
				mode: "setupComments", 
				protocol:true}))
       .pipe(gulp.dest('./eMPClient/js/'));
    gulp.src(["./index.html"])
       .pipe(µBuildFilter({
				release: 'Development', 
				client: '*', 
				version: '1.7', 
				mode: "setupComments", 
				protocol:true}))
       .pipe(gulp.dest('./src/'));
    cb();
})

Preparing the source code

Comments can be used to define parts of the source code for the various installation packages. The source code is filtered under Gulp using the https://www.npmjs.com/package/gulp-mu-build-filter module. This makes it possible to show or hide code areas for certain target systems, clients or with certain versions. The definition is carried out with the help of special comments, whereby the different comment notations are supported:

Notation <!--- ---> (HTML)
active parentheses: <!--- @<X ----\nCode\n---- @>X --->
inner parentheses -!--- @<X ----\nCode\n---- @>X ----\

Notation : /*-- --*/ (C#, Javascript, TypeScript, PHP, C, C++)
**active parentheses: /*-- @<X ----\nCode\n---- @>X --*/
inner parentheses //--@<X ----\nCode\n ---- @>X ----\

Notation <%-- --%> (ASPX)
**active parentheses: <%-- @<X ----\nCode\n ---- @>X --%>
inner parentheses -%--- @<X ----\nCode\n ---- @>X ----\

An inactive parenthesis is present if the bracketed area is to be active, an active parenthesis is present if the enclosed area is to be inactive and an inner parenthesis is present if an area is excluded by nesting.

The variation commands are inserted within the single-line comment, each framed by a space:

/*-- @<BUILD_NEVER_AT_RELEASES:Test --*/

@< opens a code area, @> closes a code area. A code area for a build can, for example, be excluded with BUILD_NEVER_AT_RELEASES or included with BUILD_ONLY_AT_RELEASES. Code areas can also be nested.

All comment commands must be on a separate line, leading spaces or tabs are possible.

A colon separates the variation command from the parameters.

Optionally, the closing comment command can also contain the parameters of the opening comment command. In this case, the system also checks the correct nesting with regard to the parameters. Example:

/*-- @<BUILD_NEVER_AT_RELEASES:Production,Test --*/
var thisVariableIsNeverDefinedInReleasePackage=true;
/*-- @>BUILD_NEVER_AT_RELEASES:Production,Test --*/

The following variation commands are permitted:

Variation Command BUILD_ONLY_AT_RELEASES

Parameter: Comma-separated designations of the package creation determined by this variation area. These are usually Production, Test or Development.

Variation Command BUILD_NEVER_AT_RELEASES

Parameter: Comma-separated designations of the package creation excluded from this variation area. These are usually „Production", „Test" or „Development".

Variation Command BUILD_ONLY_AT_CLIENTS

Parameter: Comma-separated designations of client designations of the package creation determined by this variation area. These designations depend on the respective project.

Variation Command BUILD_NEVER_AT_CLIENTS

Parameter: Comma-separated designations of client designations of the package creation excluded from this variation range. These designations depend on the respective project.

Variation Command BUILD_ONLY_AT_VERSIONS

Parameter: Comma-separated designations (without spaces) of version numbers of the package creation determined by this variation range. These version numbers must be specified in the form main.minor. An optional following plus sign determines all version numbers equal to or greater than the specified version, a following minus sign determines all version numbers less than the specified version number.

Variation Command BUILD_NEVER_AT_VERSIONS

Parameter: Comma-separated designations (without spaces) of version numbers of the package creation excluded from this variation range. These version numbers must be specified in the form main.minor. An optional following plus sign determines all version numbers equal to or greater than the specified version, a following minus sign determines all version numbers less than the specified version number.

Variation Command BUILD_ONLY_AT_PLATFORMS

Parameter: Comma-separated names (without spaces) of platforms (Windows, MacOS, Andorid etc.) of the package creation determined by this variation area.

Variation Command BUILD_NEVER_AT_PLATFORMS

Parameter: Comma-separated designations (without spaces) of platforms (Windows, MacOS, Andorid etc.) of the package creation excluded from this variation area. These designations depend on the respective project.

Variation Command BUILD_ONLY_AT_ANY_VARIANTS

Parameter: Comma-separated variant names (without spaces). For this comment area to be deactivated, one of the specified parameters must match.

Variation Command BUILD_NEVER_AT_ANY_VARIANTS

Parameter: Comma-separated variant names (without spaces). For this comment area to be activated, one of the specified parameters must match.

Variation Command BUILD_ONLY_AT_ALL_VARIANTS

Parameter: Comma-separated variant names (without spaces). For this comment area to be deactivated, all transferred parameters must match the specified parameters.

Variation Command BUILD_NEVER_AT_ALL_VARIANTS

Parameter: Comma-separated variant names (without spaces). For this comment area to be activated, all transferred parameters must match the specified parameters.

Examples:

Javascript/PHP/C#:

/*-- @<BUILD_NEVER_AT_RELEASES:Production,Test --*/
thisVariableIsNeverDefinedInReleasePackage=1;
/*-- @>BUILD_NEVER_AT_RELEASES --*/
/*-- @<BUILD_NEVER_AT_RELEASES:Production,Test --*/
thisVariableIsNeverDefinedInReleasePackage=1;
/*-- @>BUILD_NEVER_AT_RELEASES:Production,Test --*/
/*-- @<BUILD_ONLY_AT_RELEASES:Production,Test ----
thisVariableIsOnlyDefinedInReleaseAndDebugPackage=1;
---- @>BUILD_ONLY_AT_RELEASES --*/

HTML:

<!-- @<BUILD_NEVER_AT_RELEASES:Production --->
 <div>This text is never available in production release version.</div>
<!-- @>BUILD_NEVER_AT_RELEASES --->
<!-- @BUILD_ONLY_AT_RELEASES:Production,Test ----
 <div>This text is never available in development version.</div>
---- @>BUILD_ONLY_AT_RELEASES --->

ASPX:

<%-- @<BUILD_NEVER_ON_RELEASES:Production --%>
<%@ Page Language="C#" CodeFile="MyProgram.cs" Inherits="MyProgram" Debug="true" Async="true"%>
<%-- @>BUILD_NEVER_ON_RELEASES --%>

Functions

The module only has one function.

µBuildFilter(_options);

Parameter "option"**

The options parameter is a Javascript object that specifies the options for the processing to be carried out:

Property Default Value Description

Property „release"

String with the release to be created.

Default value: "*" (comment always active)

Property „client"

String of the client to be created.

Default value: "*" (comment always active)

Property „version"

Version to be created. This have to be a string of form "main.minor".

Default value: "*" (comment always active)

Property „platform"

Platform that is to be created.

Default value: "*" (comment always active)

Property „variants"

An array of strings that specify the variants to be set.

Default value: "*" (comment always active)

Property „mode"
„remove": Default value. All areas of inactive comments are removed.

„setupComment": The entire source text is retained, the comments are activated or deactivated according to their results.

Property „text"

Optional: Text (String) which have to use instead of the standard pipe stream.

Property „protocol"

Boolean value: Output of the touched file names.

Default value: false

Property „debug" Boolean value: Output of debug information (e.g. lines with comment commands)

Default value: false