ccbuild

ccbuild offers a thin layer on top of the google-closure-compiler package to set up a VERY LIGHTWEIGHT make system for Node.js. The main idea behind ccbuild is a set of configuration files that define compilation units of JavaScript sources and are also able to reference child configuration files and to inherit particular values.

ccbuild options

Usage: ccbuild [-h|--help] [-v|--version] [--closure-help]
           [--config-help] [--closure-version] [--compiler-path]
           [--contrib-path] [--ignore-warnings] [-ignore-errors]
           [-c|--config PATH]... [--ignore-compiled-code] [--stop-on-error]
           [--stop-on-warning] [-u|--unit UNIT_NAME]... [--ignore-check-fs]
           [-n|--next NEXT_ENTRY]... [--cache-location PATH]
           [--disable-caching]

Checks and compiles JavaScript files via the Closure Compiler.

  -h|--help               Display this message and exit.
  -v|--version            Display version information and exit.
  --closure-help          Display the usage for the Closure Compiler and exit.
  --closure-version       Display the version of the Closure Compiler and exit.
  --compiler-path         Display the path to the Closure Compiler and exit.
  --contrib-path          Display the path to the contrib directory of the
                          Closure Compiler and exit.
  -c|--config PATH        Path to the configuration file ccbuild should
                          use. If no configuration is specified ccbuild
                          checks the current directory for all files with the
                          file extension ".ccbuild". For every matched
                          configuration file ccbuild performs a run.
                          You may specify multiple configurations.
 --config-help            Display a help message for the configuration file
                          format and exit.
 --ignore-warnings        Compilation warnings are not shown on stderr.
 --ignore-errors          Compilation errors are not shown on stderr.
 --ignore-compiled-code   The compiled code is not shown on stdout.
 --stop-on-error          All compilation processes are stopped in case a
                          compilation error occurs. ccbuild will
                          exit with the exit code 1.
 --stop-on-warning        All compilation processes are stopped in case a
                          compilation warning occurs. ccbuild will
                          exit with the exit code 1.
 -u|--unit UNIT_NAME      Filter the compilation units that are taken into
                          account for the compilation process. All other units
                          are ignored.
                          You may specify multiple compilation units.
                          If no compilation unit is specified, all units
                          defined in the configuration files will be processed.
 -n|--next NEXT_ENTRY     Filter the configuration files that are defined in the
                          "next" property and are taken into account to be
                          processed as next ccbuild configuration.
                          All other configuration files listed in the "next"
                          properties are ignored.
                          You may specify multiple next entries.
                          If no "next" property is specified, all configuration
                          files defined in any "next" property of any processed
                          configuration file will be processed.
 --ignore-check-fs        Ignore the processing of the configuration property
                          "checkFs" which is responsible for checking whether
                          specified files are included in the defined
                          compilation units.
 --disable-caching        Don't cache results of compilation units. Using this
                          option may increase the run time of the ccbuild
                          process.
 --cache-location PATH    Set the location of the caching data. The default path
                          is $CWD/.ccbuild/.

ccbuild exits with the return code 0 in case of successful compilation(s) this
includes warnings as well. In case of compilation errors and file verification
errors the return code is 1.

Configuration Files

ccbuild operates on configuration files, i.e. without any configuration file nothing will happen. Usually the configuration files should be named in the form of *.ccbuild. If no configuration file is specified via CLI, the $CWD is searched for all files of the form *.ccbuild. If at least one is found, it will be processed. In case multiple files are found, all of them are processed. To specify any configuration file via CLI, the option -c or --config must be used. It is possible to specify multiple configuration files. In case at least one configuration file is specified via CLI, $CWD is not searched for any default configuration file. A configuration file may reference another configuration file. In case circular references are found, a second run on a configuration file that was already processed will not be started. All relative paths in the fields sources, externs and the next property are resolved against the __dirname of the configuration file in which they are defined. Any file paths that are defined via the buildOptions property must be defined relative to the location of the configuration file.

Configuration files may use the variables ${CWD} and ${CONTRIB_PATH}. ${CWD} is the path to the working directory of the calling node process. ${CONTRIB_PATH} is the contribution path of the Closure Compiler where for example externs are located. Both variables may be used in any location inside the configuration file.

A configuration file is of the following form:

{
  "checkFs": {
    "check": [
      "<GLOB paths to files to be checked whether they are included in any compilation unit defined in the same config file as this rule>"
    ],
    "fileExtensions": [
      "<file extensions of files to be checked. This filter is applied on files resulting from \"check\". If nothing is specified, the default is set to \".js\" and \".json\">"
    ],
    "ignore": [
      "<GLOB paths to files that are ignored from checking>"
    ]
  },
  "sources": [
    "<source file paths to be included in all compilation units defined in this config>",
    "${CWD}/file.js"
  ],
  "externs": [
    "<extern file paths to be included in all compilation units defined in this config>",
    "${CONTRIB_PATH}/nodejs/os.js"
  ],
  "buildOptions": [
    "<options to be used for all compilation units defined in this config>"
  ],
  "warningsFilterFile": "<file path to a warnings filter file>",
  "compilationUnits": {
    "unit 1": {
      "externs": [
        "<source file paths to be used only for this compilation unit>"
      ],
      "sources": [
        "<extern file paths to be used only for this compilation unit>"
      ],
      "buildOptions": [
        "<options to be used only for this compilation unit>"
      ],
      "warningsFilterFile": "<file path to a local warnings filter file>"
    },
    "unit 2": {
      "externs": [
        "<source file paths to be used only for this compilation unit>"
      ],
      "sources": [
        "<extern file paths to be used only for this compilation unit>"
      ],
      "outputFile": "file path to resulting code",
      "buildOptions": [
        "<options to be used only for this compilation unit>"
      ]
    }
  },
  "next": {
    "<file path to the next config relative to this config>": {
      "inheritSources": "<boolean>",
      "inheritExterns": "<boolean>",
      "inheritBuildOptions": "<boolean>",
      "inheritWarningsFilterFile": "<boolean>"
    },
    "<file path to another config relative to this config>": {
      "inheritSources": "<boolean>"
    }
  }
}

Note: buildOptions can be either an array of strings or an object as specified at https://www.npmjs.com/package/google-closure-compiler#specifying-options.

Use ccbuild programmatically

In addition to use ccbuild as an executable, you may also use it directly from your code. Therefore it offers the type CCBuild that implements the events.EventEmitter interface of Node.js. You may specify all supported arguments as an array of strings and pass it to the constructor of CCBuild. Afterwards CCBuild starts processing and emits the following events:

• argsError
• help
• version
• configHelp
• closureHelp
• closureVersion
• compilerPath
• contribPath
• configError
• circularDependencyError
• compilationError
• compiled
• done

The following example illustratest how you can use CCBuild in your code:

    var ccbuild = new CCBuild(process.argv);
    ccbuild.on('compilerPath', function (compilerPath) {
        console.log(compilerPath);
        process.exit(0);
    });
    ccbuild.on('configError', function (err) {
        console.error(err);
        process.exit(2);
    });
    ccbuild.on('compilationError', function (compilationUnit, err) {
        console.error(compilationUnit + ': ' + err);
        process.exit(1);
    });
    ccbuild.on('compiled', function (compilationUnit, stdout, stderr) {
        console.log(compilationUnit + ': ' + stdout + '\n');
        console.error('warnings: ' + stderr);
    });

    // ...

To check whether certain files are used in any of the compilation unit you may use the following code:

    var ccfc = new CCFileCheck(process.argv);
    ccbuild.on('configError', function (err) {
        console.error(err);
        process.exit(2);
    });
    ccfc.on('verificationError', function (filePath, configFilePath) {
        console.error('The file "' + filePath + '" is not used in any compilation unit of "' + configFilePath + '"');
        process.exit(1);
    });
    ccfc.on('verificationSuccess', function (filePath, configFilePath) {
        console.log('The file "' + filePath + '" is used in a compilation unit of "' + configFilePath + '"');
        process.exit(1);
    });
    ccfc.on('done', function () {
        process.exit();
    });

    // ...

The class CCFileCheck fires the following events:

• CCFileCheck#argsError
• CCFileCheck#help
• CCFileCheck#version
• CCFileCheck#configHelp
• CCFileCheck#closureHelp
• CCFileCheck#closureVersion
• CCFileCheck#argsParsed
• CCFileCheck#compilerPath
• CCFileCheck#contribPath
• CCFileCheck#configError
• CCFileCheck#circularDependencyError
• CCFileCheck#verificationSuccess
• CCFileCheck#verificationError
• CCFileCheck#done
• CCFileCheck#error

License

This project is released under MIT license. Note: that each referenced npm package that is used has its own license and potentially it has further dependencies. Please check each package individually whether it confirms to your OSS licensing rules.