Pallene is a statically typed, ahead-of-time-compiled sister language to Lua, with a focus on performance. It is also a friendly fork of the Titan language.
Pallene is intended for writing performance sensitive code that interacts with Lua, a space that is currently filled by C modules and by LuaJIT. Compared to C, Pallene should offer better support for interacting with Lua data types, bypassing the unfriendly syntax and performance overhead of the Lua-C API. Compared to LuaJIT, Pallene aims to offer more predictable run-time performance.
In order to use this source distribution of the Pallene compiler, you need to install its Lua library dependencies and compile its run-time library.
Before you build Pallene, you need to install a C compiler (e.g. gcc
) and make
on your system.
Ubuntu users can run the following commands to install these tools.
sudo apt update
sudo apt install build-essential
If you are on Linux, we also recommend that you install the Readline library.
sudo apt install libreadline-dev # for Ubuntu & Debian-based distros
sudo dnf install readline-devel # for Fedora
Another optional dependency is GNU parallel, which speeds up how long it takes to run the test suite.
sudo apt install parallel # for Ubuntu & Debian-based distros
sudo dnf install parallel # for Fedora
Pallene requires Lua 5.3 or newer to be installed on your system. You can either install it from source or via the package manager for your Linux distro. If you install via the package manager then make sure to also install the Lua headers, which are often in a separate "development" package.
After Lua 5.3 is installed, download the source code of LuaRocks from https://github.com/luarocks/luarocks/releases. Follow the build instructions appropriate for your platform and install it on your system.
If LuaRocks is configured to use older versions of Lua, you may not be able to
install the dependencies as described in the next section. Therefore, please
configure LuaRocks to use Lua 5.3. You can use the following command to configure
LuaRocks to use Lua 5.3 when compiling it:
./configure --lua-version=5.3
The easiest way to install these dependencies is with the LuaRocks package manager:
$ luarocks install --local --only-deps pallene-dev-1.rockspec
If you use the --local flag when installing packages from Luarocks, you may
also need to configure the appropriate environment variables on your terminal configuration file.
If you are using bash you can do (as stated in luarocks --help path
):
$ echo 'eval `luarocks path`' >> ~/.bashrc
For further information, consult the Luarocks documentation.
Pallene must be run against a custom-built version of the Lua interpreter. This custom version of Lua 5.4 doesn't have to be the same one that you will use to run the compiler itself, or to install the Luarocks packages.
To compile the custom version of Lua, follow the instructions found the Lua README, also found in the vm/doc/readme.html file.
For Linux, these are the commands you need to run:
cd vm
make linux-readline -j
To compile a foo.pln
file to a foo.so
module call pallenec
as follows.
Note: Your current working directory must be the root of this repository, due to Bug #16.
$ ./pallenec foo.pln
To run Pallene, you must currently use the bundled version of the Lua interpreter (again, see Bug #16).
$ ./vm/src/lua -l foo
It is possible to change compiler optimization level, for the Pallene compiler and C compiler. Here are some examples:
# execute no optimization (Pallene and C compiler)
$ ./pallenec test.pln -O0
# execute Pallene compiler optimizations and C compiler level 3 optimizations
$ ./pallenec test.pln -O3
# execute no optimizations for Pallene compiler but executes C compiler level 2 optimizations
$ env CFLAGS="-O2" ./pallenec test.pln -O0
# execute all default optimizations (same as -O2)
$ ./pallenec test.pln
Note: For the C compiler only, the setting set using CFLAGS
override the setting set by flag -O
.
For more compiler options, see ./pallenec --help
If you want to develop Pallene, it is helpful to know how to configure your editor to preserve our style standards, and to know how to run the test suite.
The easiest way to make sure you are indenting things correctly is to install the EditorConfig plugin in your favorite text editor.
This project uses 4 spaces for indentation, and tries to limit each line to at most 80 columns.
We use Luacheck to lint our Lua source
code. We recommend running it at least once before each pull-request or, even
better, integrating it to your text editor. For instructions on how to install
and use Luacheck, see our .luacheckrc
file.
We use Busted to run our test suite. It can be installed using LuaRocks:
$ luarocks install --local busted
To run the test suite, run the ./run-tests script in this project's root directory. (Tip: if GNU parallel is installed in your system, running the full test suite will be much faster.)
$ ./run-tests # Run all tests
$ ./run-tests spec/parser_spec.lua # Run just one of the test suite files
The ./run-tests script accepts the same command-line flags as busted
.
If you are debugging an unhandled exception in a test case, the following ones might help:
Flag | Effect |
---|---|
./run-tests -v | Verbose output, including the stack trace |
./run-tests -k | Run all tests even if some tests are failing |
./run-tests -o gtest | Changes the output formatting. This may be clearer if you are using print statements for debugging. |
To run of the benchmarks in the benchmarks directory, run the benchmarks/run
script from the root project directory:
./benchmarks/run benchmarks/sieve/pallene.pln
By default, the benchmark runner just outputs the running time, as measured by
/usr/bin/time
, but it also supports other measurements. For example,
--mode=perf
shows perf output and --mode=none
shows the stdout produced by
the benchmark, without measuring anything.
./benchmarks/run benchmarks/sieve/pallene.pln --mode=none
To run Pallene's benchmarks you need to have /usr/bin/time installed in your system. Some Linux distributions may have only the Bash time builtin function but not the /usr/bin/time executable. If that is the case you will need to install time with $ sudo apt install time or equivalent.
To run benchmarks with LuaJIT, use the --lua
option:
./benchmarks/run benchmarks/sieve/lua.lua --lua=luajit
Please run
./benchmarks/generate_lua
to translate all the benchmarks written in Pallene to Lua whenever changes are made to the translator.