Home

Awesome

CAST(L): compile JavaScript to Lua

CASTL (Compile Abstract Syntax Tree to Lua) is a free and open source project that allows you to "compile" some JavaScript (ES5 and ES6 through Babel transformation) code to Lua 5.2 or LuaJIT 2 code and run it. (I never tested on Lua 5.3 VM)

Installation

In a terminal:

git clone https://github.com/PaulBernier/castl
cd castl
npm install
sudo npm link

CASTL has one dependency called Lrexlib to handle regular expressions: you'll most likely need it, but if your JS code doesn't contain any regexp this dependency is not required. The easy way to install this dependency is to use Luarocks package manager:

sudo luarocks-5.2 install lrexlib-pcre
sudo luarocks-5.1 install lrexlib-pcre

You'll need to have libpcre installed on your system (lrexlib-pcre is only a binding to the libpcre API). On an Ubuntu system for instance you could do: sudo apt-get install libpcre3 libpcre3-dev

And then you may want to test:

castl code.js
npm test

Note that you can also directly install CASTL globally via npm repository:

sudo npm install castl -g

Usage:

$ castl -v <file.js>
$ castl file.js -o
$ castl file.js --babel

The options of the command line are:

OptionDescription
-h, --helpoutput usage information
-v, --verboseVerbose, print the compiled code to be run
-o, --output [name]Output the generated Lua code in a file. The default output name is filename.lua
-b, --bytecodeIf -o option is active the outputted code is in Lua/LuaJIT bytecode
-n, --linenumberPrint line numbers if -v or --cat options are active
-a, --annotationUse annotations to optimize generated code
-g, --heuristicEnable heuristic compilation
--babelRun Babel on the code to transform ES6 code to ES5 code compatible with castl transpiler
--catDon't execute, just print the code that would be run
--jitCompile for LuaJIT (and execute with LuaJIT instead of Lua 5.2 interpreter)
--miniMinify AST using Esmangle before compiling. Size of outputted file is shrunk
--debugAdd comments in the Lua code referring to the line number of the original statement in the JS file
--acornuse Acorn parser. If not specified Esprima is used
--strictMake Esprima and Acorn not error-tolerant
--nodeAdd a very basic support of NodeJS 'require' system

Annotations

Annotations are useful to optimize the generated code. Please refer to the file doc/annotations.md for more information.

Heuristic

Heuristic compilation is an attempt to optimize the generated code by guessing program behavior at execution time. Thus this option may increase the speed of execution of your program ; but as it is based on guessing it may also be wrong sometimes and break you program in some weird cases.

For now heuristic only applies to numeric for loops. It tries to identify and optimize the following pattern:

for(i = 0; i<length ; ++i) {
}

You should try to enable heuristic if you have a lot of numeric for loops. If it breaks you code you may want to consider annotations instead.

CASTL components

CASTL is made of two parts:

There is also a useful command line tool bin/castl.js to easily both compile and execute JS files.

CASTL has one dependency, Lrexlib, which provides a binding of PCRE regular expression library API.

CASTL also needs a JavaScript parser able to produce an AST (Abstract Syntax Tree) compliant with the SpiderMonkey AST structure. You can use Esprima or Acorn for instance (if you installed CASTL as stated above Esprima and Acorn are automatically downloaded as dependencies, you don't need to do anything).

ES6

CASTL transpiler is not able to parse ES6 code. If you try to do so you'll get a SyntaxError like 'Error: let instruction is not supported yet'. Luckily thanks to the great Babel library you can transform your code from ES6 to ES5 that will be understood by CASTL transpiler. As a convenience I added an option --babel to the command line tool that'll invoke Babel transform for you before transpiling to Lua.

Not Supported yet

Q&A

What could it be useful for?!

CASTL lets you execute JS scripts on Lua 5.2 VM. Lua VM is known to be fast and lightweight, and especially it is often used in embedded systems. Thus it could allow you to execute your JS scripts on micro-controllers for example.

The probably best known example is Tessel which sells a board that "runs JavaScript". In fact they do the same as CASTL, the JS code is converted to Lua and then executed in a specific environment. They call it Colony.

Note that CASTL will always be slower than a native Lua script, so take time to learn Lua :).

So what's the differences between CASTL and Tessel Colony?

I have definitively been inspired on many points by Colony. Nonetheless there is some important points of divergence:

I'd prefer a version of CASTL written in Lua

Easy, just compile CASTL by itself (and also Esprima for the parsing)! By the way you can find a version already compiled in folder lua/castl/jscompile/ which is used for the eval() function.

Info

Developed and maintained by Paul Bernier.

Released under the LGPLv3 license.