Skip to content

CreatingRollupFiles

[email protected] edited this page Apr 5, 2010 · 14 revisions
  1. summary How to create a roll-up file of all or part of the library.
  2. labels Component-Tools,Type-HowTo
Deploying as few files as possible to your web server dramatically speeds up performance, and so improves the experience for your users. This section shows how to create roll-up files for one or more of the modules in backplanejs.

Table of Contents

Tools

The tool used to create modules is Sprockets, a Ruby library that preprocesses and concatenates JS source files. The site contains full instructions on how to obtain and install the library.

The main reason for using Sprockets is that each file can contain a reference to the files it depends upon, rather than having to have a central list of dependencies, as with the YUI loader.

The Sprockets tool is invoked from Ant, details of which are in UsingTools.

Source and build layout

Modules are defined in the `build` directory, and each one has a Sprockets file that indicates the source files to be loaded. This determines the files that will be concatenated.

Each source file can in turn contain further Sprockets `require` instructions, listing any dependencies that it has. This will determine the order in which the files are concatenated.

When the concatenation process is run, two files are created -- one JS and one CSS. These files are copied to the `deploy` directory, along with any assets that will be needed at run-time.

A module loader file

Module files are located in the `build` directory. An example is build\rdfa.js:

In Sprockets, any comments of the form `/* ... */` will be passed through to the output file, but any comments that begin `//` will not. This allows us to control the comments that will appear in the final scripts.

Note also that the paths are relative to the file itself, when using quotes, and relative to a predefined list of 'load paths', when using angle brackets. Since both the core module and the `rdfa` module are in the `build` directory, quotes are used for the first reference. However, all of the references that follow in the module file, use the angle bracket syntax, because the location of source files may change.

Specifying paths in require directives

To illustrate, the file file.js, which is in the `io` directory, relies on the uri.js script, which is in the `uri` directory. This dependency is indicated in `file.js` as follows:

The alternative would be to simply make the path relative to the current file:





but this would hard-code the relationships between the files in terms of the directories.

Source files

_Note: Source files are currently located in various directories, but this will change._

The source files referred to in module files can optionally contain further `require` statements, which are then used to create the dependencies.

For example, in the backplane module, the tokmap.js script makes use of the objects in the array.js script, so a `require` statement is be added:

This ensures that Sprockets will place `array.js` before `tokmap.js` in the resulting file. It also automatically causes `array.js` to be loaded, even if it's not referenced in the top-level loader list. This allows us to reduce the number of top-level references, if the functionality in a script is only ever used by some other script.

Referring to assets

The Sprockets tool is also capable of copying assets to a directory, during the concatenation process. This means that images and CSS files can be kept with their associated source code during the development cycle, but then copied to a single directory when deploying.

To make these assets available, Sprocketize supports the `provide` directive. For example:

The results in the entire contents of the UXF assets directory being copied to the `assets` directory, within the `deploy` directory.

Creating and deploying the roll-up files

To create the JS and CSS files for testing, the following Ant command is run:

The result is a directory called `output` in the `target` directory, which contains the rolled-up JS file, and then a sub-directory called `assets` that contains the rolled-up CSS file, and all other assets. These files can be used directly, during the development process and also as the raw material for compressing, and ultimately packaging up for distribution.

Testing

Unit-tests

Using a similar approach to keeping assets 'local', each module also has its own unit-tests. These test files are also concatenated, and then copied to the corresponding sub-directory, in the `target/unit-tests` directory.

For example, all of the XForms unit tests will be concatenated together, and then copied to `target/unit-tests/xforms`.

In addition, an HTML driver file is copied to this test directory, and a JS 'test runner' file is copied to the parent directory. The HTML and JS files are located in tools/test.

The tests are created and copied using the following Ant command:

The unit-tests can be run as a group, by using the following Ant command:

This will set a Selenium RC server running, and then use it to run each of the sets of tests. The actual tests to run are defined in the test-list.xml file.

To run the entire sequence of combining the source, generating the tests and running them, simply use this command:

The results of the tests will be in the `target/reports` directory.

_Note: Currently not all tests pass._

To run the unit-tests individually, you'll need a local web server. Assuming that you have followed the steps for InstallingTools then you can launch a web-server with the following Ant command:

This launches a Python server (the Google App Engine), and sets a number of paths to various parts of your development environment (see app.yaml for more information on the paths). You can then run a particular module's unit-tests by navigating to the appropriate link:

TDD

The `app.yaml` file also contains a TDD reference which can be used to point to a directory containing 'work in progress'. Set the path in `my.ant.properties`, and then restart the web-server for the change to be applied to the `app.yaml` file.

Once this change is in place you can access your development area like this:

To change the host name, IP address and/or port number that the server launches on -- for example, so that you can run the server on one machine and the tests on another -- set the Ant variables `gae.host` and `gae.port` in your `my.ant.properties` file, and restart.

<wiki:comment>

Compressing

The compile task will run the YUI Compressor on both the rolled-up JS file, and the rolled-up CSS file. Note that the YUI Compressor is referenced directly from the Ant tasks, so there is no need to install it.

The resulting files are placed in the same directories as the originals, and can be used as described in DeployingBackplanejs. </wiki:comment>

Packaging

To create a zip file of the compressed files and assets -- either to pass to someone for deployment, or for uploading to the Google Code downloads area -- run the following Ant command:

A zip file will be created in the `target\deploy` directory, containing all of the files from the deployment directory. The filename will contain the backplanejs version number, the platform, and the platform version number. For example:

Deploying the package

To deploy the zip file to the Google Code downloads area, run the following Ant command:

Note that this Ant task requires a file called `my.ant.properties` to be in the same directory as the main `build.xml` file, and for it to contain your Google Code account details:

This file is ignored in .hgignore, so your password is safe.