Builders are components which actually build the packages.

A builder takes a package configuration, and builds its corresponding output file from the specified set of input files. Please refer to the configuration article for more information about the packages specifications.

All builders can potentially expect a configuration object.

There are built-in builders, but you can also create custom ones or use custom builders from other libraries.

Built-in builders

General purpose builders:

JavaScript specific builders:

Aria Templates specific builders:

Copy files: Copy

No configuration expected

Creates the output content by copying the content of one single file. This means that if the package is configured with more than 1 source file the builder will log an error with grunt (grunt.log.error).

The copy of the content is done in two steps: first the content is retrieved from the source file, then it is written to the output file. This split allows to hook the process with visitors, with possible modification of the content or output options. Here is the full process:

  1. visitors: onWriteInputFile
  2. content retrieved
  3. visitors: onWriteOutputFile
  4. content written

Concatenate files: Concat

Creates the output content by concatenating its source files' contents together, optionally adding a header at the beginning and a footer at the end.

Configuration

  • outputEncoding, String, defaults to grunt.file.defaultEncoding: the encoding of the output file.
  • header, String, optional: the header to put at the beginning of the output file.
  • footer, String, optional: the footer to put at the end of the file.

Build process

The parts of the content are queued before being actually written to the output file, allowing for hooking with visitors.

  1. header queued (if specified)
  2. for each source file
    1. visitors: onWriteInputFile
    2. content retrieved and queued
  3. footer queued (if specified)
  4. content generated from the queue
  5. visitors: onWriteOutputFile
  6. content written

Concatenate JavaScript files: JSConcat

This builder works similarly to Concat, however the content is considered as JavaScript, allowing for more specific processing.

The content is not represented as a string but rather as an AST, until the end when it is generated back to a string, applying the given options.

Before the content is generated, it is possible to wrap it with some JavaScript code. This holds for each input file individually and also for the output file afterwards.

Configuration

  • The options outputEncoding, header and footer are the same as for Concat
  • jsOutputOptions, Object, defaults to {beautify : true, ascii_only : true, comments : true}: options to be passed to UglifyJS when converting the AST to a string.

Wrappers, String, default to "$CONTENT$" (the content is not wrapped): this should be some JS code containing the special $CONTENT$ keyword which will be replaced by the content of the concerned file. Here are the possible wrappers:

  • inputFileWrapper: wrapper for each input file.
  • outputFileWrapper: wrapper for the output file.

Build process

The parts of the content are queued before being actually written to the output file, allowing for hooking with visitors.

  1. for each source file
    1. visitors: onWriteInputFile
    2. AST content retrieved
    3. AST content wrapped using inputFileWrapper
    4. AST content queued
  2. full AST content generated from the queue
  3. full AST content wrapped using outputFileWrapper
  4. visitors: onWriteJSOutputFile
  5. final content generated
  6. final content wrapped with header and footer (if specified)
  7. visitors: onWriteOutputFile
  8. final content written

Create an Aria Templates Multi-part file: ATMultipart

This builder creates files in the Aria Templates multi-part format. It extends the Concat builder, so please refer to it as well.

Configuration

  • multipartBoundary, String, defaults to '*******************': specifies the separator to use between files. This sequence should not appear in any of the files.

Build process

Note that nothing specific is done by this builder if there is only one source file configured for the package currently being built. Thus, in this case it would behave exactly as the Concat builder.

Otherwise, here are the specificities added by this builder:

  • after letting the initial Concat's implementation write the provided header, this builder adds the following text: //***MULTI-PART
  • before letting the initial Concat's implementation write the content of an input file, this builder adds the multi-part header, which has the following format:

//{multipartBoundary}
//LOGICAL-PATH:{path}
//{multipartBoundary}

where:

  • {multipartBoundary} is the one provided in configuration
  • {path} is the logical path of the input file, with backslashes replaced by normal slashes

For the full process, please refer to the Concat builder.

Create an Aria Templates cache update package file: ATFillCache

This builder creates packages which can be used to fill the cache of Aria Templates. It extends the Concat builder, so please refer to it as well. The packages created with this builder can be loaded with a script tag to make some classes available synchronously.

Configuration

There is no extra configuration parameter (only the parameters inherited from Concat)

Build process

For each input file, the builder generates a line in the output package with the following format:

aria.core.DownloadMgr.loadFileContent("{path}","{content}");

where:

  • "{path}" is the "stringified" logical path of the input file, with backslashes replaced by normal slashes
  • "{content}" is the "stringified" content of the input file

For the full process, please refer to the Concat builder.

Create custom builders

It is possible to create custom builders and use them in your packages configurations. As an example, you can take a look at the custom builders created for noderJS.

How to declare a custom builder

You simply need to create file atpackager.js at the root of your project which looks like this

module.exports = function(atpackager) {
    require("./atpackager").init(atpackager);
    atpackager.builders.MyFirstBuilder = require("./myBuilderPath/MyFirstBuilder");
    atpackager.builders.MySecondBuilder = require("./myBuilderPath/MySecondBuilder");
};

This is what we call a plugin for atpackager. It is important that you put the plugin file at the root of your project if you want external projects to use the custom builders declared therein. Plugins allow you also to declare custom visitors.

How to use a custom builder

If you have created a custom builder and declared it in a plugin, you can use it within your project by loading the plugin

require('atpackager').loadPlugin('./atpackager');

If you want to load atpackager plugins defined in a dependency (for example in noderJS) in order to use the custom builders they declare, you can use

require('atpackager').loadNpmPlugin('noder-js');

This will load plugin atpackager.js at the root of noder-js dependency.