Overview

Lush is a lightweight modernized Lua runtime written in Rust, configured entirely in Lua. It gives the Lua language a modern API to allow its capabilities to soar in potential. Its API is still in development, its structure & features may minimally or drastically.

Lush is - although - intended to be a Lua based task runner. By default, Lush uses LuaJIT for maximum preformance and its C interop. To use other versions of Lua (e.g 5.4), you will have to build it with the corresponding mlua flag.

Command options

Building

# Clone the Repo
git clone https://github.com/zkiwiko/lush

# Cd into it
cd lush

# Build
cargo build --release

# install (optional)
cp ./target/release/lush /usr/bin/lush

Quick Examples

C File Compilation (Build API)

main.c

#include <stdio.h>

int main(int argc, char* argv[]) {
    printf("Hello, World!\n");
    return 0;
}

lush.lua

lush.task("build", function()
    local result = build.c()
                    :compiler(build.c.GCC) -- Default
                    :optimize(build.c.OPTIMIZE.O2)
                    :files( {"main.c"} )   -- Glob pattern
                    :output("main")
                    :run()

    if result.success then
        print(result.output)
    else
        print(result.error)
    end
end)

lush.task("run", { "build" }, function()
    sys.exec("./main")
end)

Use with: lush run

Expected Output: Hello, World!

API

Lush exposes global Lua modules:

• lush for task registration
• fmt for formatting helpers
• sys for system/shell helpers
• json for JSON conversion and I/O
• build for C-family build pipelines

lush

Core runtime methods for task registration.

task

Registers a named task.

Signatures

lush.task(name, handler)
lush.task(name, opts, handler)

Parameters

Returns

None

Example

lush.task("build", function()
  sys.exec("gcc main.c -o main")
end)

lush.task("run", { depends = { "build" } }, function()
  sys.exec("./main")
end)

rule

Placeholder API (currently no-op).

Signature

lush.rule(output, input, handler)

target

Placeholder API (currently no-op).

Signature

lush.target(files, opts)

Constants

VERSION

Current Lush version string.

fmt - Format

fmt provides formatting helpers, path joining, and numeric base conversion.

print

Prints a formatted string to stdout.

Parameters

Returns

None

Notes

• {{ prints { and }} prints }.
• Returns a runtime error if placeholder count and argument count do not match.

Example

fmt.print("Value: {}", 42)
fmt.print("Braces: {{}}")

string

Returns a formatted string (same formatting rules as fmt.print).

Parameters

Returns

Formatted string.

Example

local msg = fmt.string("{} + {} = {}", 1, 2, 3)

path_join

Joins path segments with / and removes duplicate surrounding slashes.

Parameters

Returns

Joined path string.

Example

local p = fmt.path_join("/usr/", "local", "bin")
-- "usr/local/bin"

to_hex

Converts a number to uppercase hexadecimal with 0x prefix.

Parameters

Returns

Hex string.

Example

fmt.print("{}", fmt.to_hex(255)) -- 0xFF

to_bin

Converts a number to binary with 0b prefix.

Parameters

Returns

Binary string.

Example

fmt.print("{}", fmt.to_bin(10)) -- 0b1010

to_oct

Converts a number to octal with 0o prefix.

Parameters

Returns

Octal string.

Example

fmt.print("{}", fmt.to_oct(8)) -- 0o10

sys

System and shell helpers.

exec

Executes a shell command.

Parameters

Returns

None

getenv

Gets an environment variable value.

Parameters

Returns

String value, or runtime error if missing.

setenv

Sets an environment variable.

Parameters

Returns

None

find

Checks whether a path exists and matches a requested type.

Parameters

Returns

true if path exists and matches type, else false.

mkdir

Creates a directory recursively.

rm

Removes a file or directory recursively.

cp

Copies a file from src to dst.

mv

Renames or moves path from src to dst.

cwd

Returns current working directory as a string.

envs

Returns a table of all environment variables.

os

Returns OS name string.

arch

Returns architecture string.

which

Returns executable path for command, or runtime error if not found.

grep

Regex search over multiline text.

Parameters

Returns

Array table of matching lines.

popen

Runs command and returns captured stdout as a string.

Constants

• sys.FILE = 0
• sys.DIRECTORY = 1
• sys.SYMLINK = 2

Example

local out = sys.popen("echo hello")
fmt.print("{}", out)

if sys.find(sys.FILE, "lush.lua") then
  fmt.print("found lush.lua")
end

json

Methods for reading and writing JSON from files or strings.

read_file

Reads a JSON file and converts it to Lua values.

Parameters

Returns

Lua value (usually a table) representing the parsed JSON.

Example

local data = json.read_file("data.json")
fmt.print("{}", data)

read_string

Parses a JSON string into Lua values.

Parameters

Returns

Lua value (usually a table).

Example

local data = json.read_string('{"name":"lush","ok":true}')

write_file

Serializes a Lua value to pretty JSON and writes it to a file.

Parameters

Returns

None

Example

json.write_file("./data.json", {
  user = "aria",
  id = 1
})

write_string

Serializes a Lua value into a pretty-printed JSON string.

Parameters

Returns

JSON string.

Example

local serialized = json.write_string({ user = "aria", id = 1 })
fmt.print("{}", serialized)

Conversion Notes

• Lua arrays map to JSON arrays only when keys are contiguous numeric indices starting at 1.
• Lua tables with string keys map to JSON objects.
• Unsupported Lua types (like functions/userdata) raise an error.

build

Build API for C-family targets. build.c is callable and returns a chainable task object.

Quick Start

local result = build.c()
  :compiler(build.c.GCC)
  :language(build.c.LANGUAGE.C)
  :std(build.c.STD.C11)
  :files({ "src/*.c" })
  :include_dirs({ "include" })
  :defines({ "APP_NAME=\"lush\"" })
  :optimize(build.c.OPTIMIZE.O2)
  :warnings(build.c.WARNINGS.ALL)
  :output("app")
  :run()

fmt.print("{}", result)

Chain Methods

All methods return the same task object.

compiler(compiler)

Compiler constant: build.c.GXX, build.c.GCC, build.c.CLANG.

language(language)

Language constant: build.c.LANGUAGE.C, build.c.LANGUAGE.CPP, build.c.LANGUAGE.OBJC.

std(std)

Language standard constant, e.g. build.c.STD.C11, build.c.STD.CXX20.

files(files)

Array of source file paths or glob patterns.

output(name)

Output binary name. Defaults to a.out.

optimize(level)

Optimization constant from build.c.OPTIMIZE (O0, O1, O2, O3, OS, OZ).

debug(enabled)

Boolean flag for debug symbols (-g in raw mode).

warnings(level)

Warning constant from build.c.WARNINGS (NONE, NORMAL, ALL, EXTRA, PEDANTIC).

include_dirs(dirs)

Array of include directories.

defines(defs)

Array of preprocessor defines (without -D).

link_libs(libs)

Array of library names (without -l).

frameworks(frameworks)

Array of framework names (used for Objective-C style linking).

flags(flags)

Array of extra raw compiler flags.

find_library(name)

Resolves a system library and appends include dirs/lib paths/link libs/flags to the task.

generator(gen)

Build generator: build.c.GENERATOR.RAW, build.c.GENERATOR.CMAKE, build.c.GENERATOR.NINJA.

generate()

Generates build files for the selected generator (CMAKE or NINJA).

run()

Executes the build and returns a result table.

Result Table

generate() and run() return a table with fields:

• success (boolean)
• output (string)
• error (string or nil)
• exit_code (number or nil)

Constants

Compiler

• build.c.GXX
• build.c.GCC
• build.c.CLANG

build.c.OPTIMIZE

• O0, O1, O2, O3, OS, OZ

build.c.STD

• C: C89, C99, C11, C17, C2X
• C++: CXX98, CXX03, CXX11, CXX14, CXX17, CXX20, CXX23

build.c.WARNINGS

• NONE, NORMAL, ALL, EXTRA, PEDANTIC

build.c.GENERATOR

• RAW, CMAKE, NINJA

build.c.LANGUAGE

• C, CPP, OBJC