Building And Testing

Getting Traceur

You can clone the git repo directly or use the github workflow.

Direct Clone

$ git clone git://github.com/google/traceur-compiler.git

You'll know it's working when computer gets nice and warm and you see a bunch of text spew by. Once it's done, you've got it!

github workflow

Login into github and open https://github.com/google/traceur-compiler, then fork the repo into your account. Then on your computer clone your fork. See github instructions on pull-request for more info.

To see if everything works, build and run the tests...

Build

Traceur is self-hosted: the compiler is written in ES6 and built by compiling down to standard ES5. To build:

$ make clean
$ make

After the first pass you don't need make clean unless you are working on the build system or self-hosting module system. The make clean removes built files created by older compilers you may have run.

The build requires Node.js and npm install. We use node_modules/traceur, our compiler from a previous build, to build ourselves anew. The compiler has three parts, compiled bin/traceur.js, src/runtime/*, and node adapters src/node/*. These files are copied from node_modules/traceur into build the used to compile the current source into a new bin/traceur.js. Then this intermediate bin/traceur.js is used to recompile with current src/node/* and src/runtime/* to complete the self-hosting work.

During the first pass of the self-build, the new Traceur code is compiled with older Traceur logic. The result is a JS program with new logic and new runtime files but in the format generated by the older Traceur. The second pass runs the new logic to create code in the new format. Consequently the runtime has to work for both old and new formats and the old-format dependent code can only be removed once the new build is committed.

Running the Tests

Traceur has two kinds of tests: unit tests validate that various classes within Traceur do what they're supposed to do. Feature tests are small standalone chunks of ES6 code. The feature test suite compiles these chunks and runs them, then validates that they do what they're supposed to. Our tests are based on mocha

The feature tests are likely the most interesting. They show what kinds of extensions to JavaScript we support, both what they look like and how they behave. If you want a quick introduction to what kinds of stuff Traceur supports, hunt through the feature/ directory and see.

We have two ways to run the tests:

1. make test runs tests via node on the command line. To run part of the suite for debugging, use the pattern make test/unit/%-run where % matches one of the unit test file name, eg make test/unit/codegeneration/HoistVariablesTransformer.js-run.
2. open testRunner.html in a web browser. Run node expressServer.js from ./http, then open http://localhost:8090/testRunner.html. (See below to allow file:// access). To run part of the suite, click on the arrow-circle thing on the right side of the page.

The node tests are 10x faster; the browser test are easier to debug because you can use the browser devtools.

In addition to these tests, Traceur is a self-compiling compiler. The previous version of traceur in npm is used to compile Traceur first, then the result is used on the source again. The second pass may result in errors that, occasionally, cannot be solved without splitting the patch into two parts.

Running specific tests from the command line

make bin/traceur.js && node_modules/.bin/mocha --ignore-leaks --ui tdd --require test/node-env.js --grep Spread test/node-feature-test.js

And s/"Spread"/whatever-you-want-to-test/

Allowing File Access

Since the test scripts access other local files, you'll need to tweak your browser a bit to tell it you want to allow that before you can run the tests in a browser:

Configuring Chrome

You'll need to launch Chrome with an argument to let scripts load other scripts from disk: --allow-file-access-from-files. On Mac OS X, you can do this from the Terminal using:

$ /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --allow-file-access-from-files &> /dev/null &

Configuring Firefox

To run this in Firefox you need to change a preference so that the scripts can load other files outside of their directory (strict_origin_policy). To do that:

  # Navigate to `about:config`. (Accept the warning if shown.)
  # In the "Filter" box, enter: `security.fileuri.strict_origin_policy` and hit enter.
  # If it's value is currently `true`, double-click the result line to toggle it to `false`.