Getting Started

Installation

The recommended way to install is through luarocks:

luarocks install erde

Alternatively you can clone this repo and update your LUA_PATH accordingly:

git clone https://github.com/erde-lang/erde.git
ERDE_ROOT="$(pwd)/erde"
export LUA_PATH="$ERDE_ROOT/?.lua;$ERDE_ROOT/?/init.lua;$LUA_PATH"

# To use the CLI:
alias erde="lua $ERDE_ROOT/cli/init.lua"

You can check whether Erde is installed correctly by running:

erde -h

Erde CLI

Running Programs

Create an Erde file, which uses the .erde extension:

touch fibonacci.erde

And add some code to it:

local function fibonacci(n) {
  local a, b = 0, 1

  for i = 1, n {
    a, b = b, a + b
    print(b)
  }
}

fibonacci(10)

We can then run the file from the command line using the erde command:

erde fibonacci.erde

Compiling Programs

Running Erde files directly is great for development, but for production code we generally want to distribute Lua files instead. We can compile our previous file into Lua using the erde compile command:

erde compile fibonacci.erde

This will create a fibonacci.lua file in the same directory.

info

You can run the compiled file with the lua interpreter as a sanity check to make sure the output is the same:

lua fibonacci.lua

Cleaning Projects

By default, Lua files are generated next to their Erde counterparts in order to ensure require resolutions are consistent. While this is great for distribution, it clutters the directory and can feel somewhat noisy during development.

Erde keeps track of which files it has generated by injecting a special comment at the end of the file. This allows us to clean all generated files using:

erde clean .

This will recursively clean all generated files under the current directory.

Erde Package Loader

Most of the time, you will want to load Erde files directly from Lua scripts to avoid having to constantly recompile your code. To achieve this, Erde ships with a custom package loader that can be injected and configured from Lua:

require('erde').load()

-- You can also specify the Lua target manually. By default, this is inferred
-- from the current Lua version (`_VERSION`)
require('erde').load('5.1+')

Now we can use require to load any Erde files in our package.path:

my-erde-module.erde

local name = 'world'
print("hello {name}!")

my-lua-module.lua

require('erde').load()
require('my-erde-module') -- hello world!

info

Erde injects its package loader before the default Lua package loader, which means that modules with the same name will prefer Erde files over Lua files. This prevents (potentially outdated) compiled files from taking priority.

caution

When Erde injects its package loader, it also replaces the native debug.traceback function with one that handles error rewriting. The native debug.traceback is restored when calling require('erde').unload(). This behavior can be prevented using the load options.