MortalBuild

A simple, straightforward build tool implemented in JavaScript.

This tool was designed to be the build system for MortalSim libraries and modules, which are generally written in C++, but the tool is generic enough that it could theoretically work with several other languages as well.

Requires Node version >= 6.5

Installation

npm install mortalbuild

Usage

const MortalBuild = require('mortalbuild');

// MortalBuild simply runs commands on a subprocess. For this it provides a simple
// execution pool to run these commands in parallel. By creating one and providing
// it to each of the build calls, the ExecPool can optimize CPU utilization for
// the build process
var pool = new MortalBuild.ExecPool();

// Create a build definition object (this one uses GCC to build C++ object files)
var buildDef = {
      // File extension for the target file(s) (this will be appended
      // automatically to the target, don't add it to the TPL string!)
      ext: '.o'
      // Command to invoke
      cmd: 'g++'
      // Any includes for various builds
      includes:
        // Included for all builds
        all:
          - 'include/',
          - 'my/other/include/'
        // Included only for dev builds
        dev: 'src/include',
        // Included only for production builds
        prod: 'prod/include',
        // Included only for test builds
        test:
          - 'test/include/',
          - 'dep/Catch2/single_include'
      // Any necessary flags for the command
      args:
        // Optionally, FLAGS can be defined with ALL:, DEV:, and/or
        // PROD: properties which will cause it to change depending
        // on whether it's a development or production build.

        // These flags will be used for all builds
        all: '-std=c++14 -Iinclude/'
        // These will be used only for dev builds
        dev: '-Wall -Weffc++ -g'
        // These will be used only for production builds
        prod: '-O3'
        // These will be used only for test builds
        test: ''
      // ECMAScript template for the build command. Use ${source}
      // for the source file(s) and ${target} for the target file
      tpl: '${cmd} ${args} -c -o ${target} ${source}'
};

// Run the build! This returns a promise so you can use it to be
// notified when all build commands are complete
MortalBuild.build({
  execPool: pool,
  buildDef: buildDef,
  dev: true, // use the dev settings
  src: 'src/*',
  targetDir: 'build/'
}).then(() => {
  console.log('Build complete!')
});

Options

| Option | Type | Default | Description
| -------------- | ------------------ | ---------------------------- | ------------------------------------------------------- | execPool | ExecPool | ExecPool(os.cpus().length()) | ExecPool object for running commands in parallel | buildDef | Object | | Required build definition object (see below) | dev | Boolean | False | Whether to use dev arguments | src | String or [String] | | Source file(s) | target | String | | Target file (if no targetDir provided) | targetDir | String or [String] | | Target file directory (if no target provided) | forceRun | Boolean | False | Forces a run, even if the target is newer than source | execOpts | Object | {} | Options passed to child_process.exec

Build Definition Object

The Build definition object (buildDef in the options above) defines the command to be run. These commands are run via child_process.exec. The options to define these commands are as follows:

| Option | Type | Description
| -------------- | ------------------ | ------------------------------------------------------- | ext | String | Target file extension | cmd | String | Command to execute | incl | string | Include flag string (ex. "-I" for gcc or "/I" for msvc) | includes | String or Object | Includes to pass to the cmd | args | String or Object | Arguments to pass to the cmd | tpl | String | ECMAScript template string for the command.

The tpl template will be compiled at runtime with ${target} set to the target file and ${source} set to the source file(s). The target extension (designated by ext) will be added internally. ${ext} should never be in the template string.