Module: hcjeTools/build/build

Script for building the source and intended to be run under Node.js. The size of the resulting script is reduced by removing comments and leading and trailing spaces.

Usage:

  • build configFile [--nozip]
    • configFile: the configuration file; see below.
    • --nozip: if present, no zip file is created.

Configuration file

The script should be passed the path to a configuration file as the only command line argument. This is used to control the output. The configuration file is a JSON representation of a ConfigurationOptions object.

Template strings

When html, js, or md files are processed, the following predefined template strings are replaced. They are all case-sensitive.

  • %%_AUTHOR_%% replaced by author field from package.json
  • %%_BUILD_DATE_ISO_%% replaced by date of the build in ISO format.
  • %%_BUILD_YEAR_%% replaced by year of the build.
  • %%_BUILD_ID_%% replaced by a short code based on the date and time of the build.
  • %%_DESCRIPTION_%% replaced by the description property from package.json.
  • %%_DISPLAY_NAME_%% replaced by the _customHcje.displayName property from package.json
  • %%_LICENCE_%% or %%_LICENSE_%% replaced by the license property from package.json.
  • %%_NAME_%% replaced by the name property from package.json
  • %%_VERSION_%% replaced by the version property from package.json.

Custom template variables can be created by adding custom template values to the package's _customHcje.templateVariables property. This property should be an array of replacement objects, each with a name and value. The name is converted to a template name by adding %%_ at the front and _%% at the end. For example:

"customHcje" {
 "templateVariables": [
   {"name": "MY_NAME", "value": "John Doe"}
 ]
}

The entry above would result in %%_MY_NAME_%% being replaced with John Doe.

Source:

Type Definitions

ConfigurationOptions

Configuration object.

Type:
  • Object
Properties:
Name Type Description
outputDir string

Path to where the resulting files will be copied. Only ./build or ./docs are permitted.
subDir string

If provided, the build will be placed in outputDir/subDir.
zippedOutputDir string

Path to where a zipped copy of the build output will be placed. This will include the version from package.json in the file name. Note, if a subdir is provided, this will contain the contents of outputDir/subDir not outputDir. This directory is relative to the package.
readme string

Path to a readme file that is written to the outputDir. This is written pre-build, so if the source folder (root) also contains a readme file, and the subDir option is not set, the readme will be overwritten. It will be renamed to README.md when copied.
root string

Path to the source folder containing the files to copy to the outputDir.
filter Object

Detail of filters to restrict the files copied to the output.

Properties
Name Type Description
includeFiles Object

Regular expression detail. Only file names matching the regular expression are included. The regular expression is created as new RegExp(regex, flags).

Properties
Name Type Description
regex string

The string that forms the regular expression.
flags string

Any flags to use with the regular expression.
excludeFiles Object

Regular expression detail. Any file names matching the regular expression are excluded.

Properties
Name Type Description
regex string

The string that forms the regular expression.
flags string

Any flags to use with the regular expression.
excludeDirs Object

Regular expression detail. Any directory names matching the regular expression are excluded.

Properties
Name Type Description
regex string

The string that forms the regular expression.
flags string

Any flags to use with the regular expression.
parserConfig Object

Additional detail added to the output for specific file types:

Properties
Name Type Description
html Object

Additional text for html files:

Properties
Name Type Description
prefix string

Text added at the beginning of the output.
parseConfig.html.replacements Array.<module:hcjeTools/build/build/ReplacementDefn>

text replacements.
parserConfig.js Object

Additional text for JavaScript files:

Properties
Name Type Description
prefix string

Text added at the beginning of the output.
parseConfig.js.replacements Array.<module:hcjeTools/build/build/ReplacementDefn>

text replacements.
parserConfig.md Object

Additional text for Markdown files:

Properties
Name Type Description
prefix string

Text added at the beginning of the output.
parseConfig.md.replacements Array.<module:hcjeTools/build/build/ReplacementDefn>

text replacements.
zipOptions module:hcjeTools/build/build/ZipOptions

Zip options for different platforms.
Source:

ReplacementDefn

Type:
  • Object
Properties:
Name Type Description
pattern RegExp | string

regular expression or string to match.
replacement string

replacement text which can include capture groups. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
Source:

ZipDetail

Type:
  • Object
Properties:
Name Type Description
cmd string

The command to create the zip file. The text values ${zipOutputFile} and ${zipSourceFiles} are respectively replaced by the path to the resulting zip file and the path to the files that should be zipped.
cd boolean

Should the current working directory be changed to the location of the source files to be zipped when running the zip command.
Source: