Lua interpreter - chung-leong/zigar GitHub Wiki
In this example we're going to build a Lua interpreter. The main purpose is to demonstrate how to use the Zig package manager to include third-party code in a project. Electron is going to be our JavaScript platform. We'll be using React for our app's interface and Electron-vite as the build tool.
We'll start by creating an Electron-Vite boilerplate app:
npm create @quick-start/electron@latest
Need to install the following packages:
@quick-start/[email protected]
Ok to proceed? (y)
✔ Project name: … lua
✔ Select a framework: › react
✔ Add TypeScript? … [No] / Yes
✔ Add Electron updater plugin? … [No] / Yes
✔ Enable Electron download mirror proxy? … [No] / Yes
We'll then add the node-zigar module:
cd lua
npm install
npm install node-zigar
After that we'll install ziglua, a Zig package that provides the Lua language engine. As there is currently no central repository for Zig packages, you'll need to obtain ziglua from the source. First, go to the project's Github page. Click on the SHA of the last commit:
Then click the "Browse files" button:
Then click the "Code" button, right-click on "Download ZIP", and select "Copy link address":
Go back to the terminal, create the sub-directory zig
, and cd to it:
mkdir zig
cd zig
Create an empty build.zig
:
touch build.zig
Enter "zig fetch --save " then paste the copied URL and press ENTER:
zig fetch --save https://github.com/natecraddock/ziglua/archive/486f51d3acc61d805783f5f07aee34c75ab59a25.zip
If you're still using Zig 0.12.0, you would need to replace the .zip
extension with .tar.gz
:
zig fetch --save https://github.com/natecraddock/ziglua/archive/486f51d3acc61d805783f5f07aee34c75ab59a25.tar.gz
That'll fetch the package and create a build.zig.zon
listing it as a dependency. We'll then fill
in build.zig
:
const std = @import("std");
const cfg = @import("./build-cfg.zig");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
const lib = b.addSharedLibrary(.{
.name = cfg.module_name,
.root_source_file = .{ .cwd_relative = cfg.stub_path },
.target = target,
.optimize = optimize,
});
const ziglua = b.dependency("ziglua", .{
.target = target,
.optimize = optimize,
});
const imports = .{
.{ .name = "ziglua", .module = ziglua.module("ziglua") },
};
const mod = b.createModule(.{
.root_source_file = .{ .cwd_relative = cfg.module_path },
.imports = &imports,
});
mod.addIncludePath(.{ .cwd_relative = cfg.module_dir });
lib.root_module.addImport("module", mod);
if (cfg.use_libc) {
lib.linkLibC();
}
const wf = switch (@hasDecl(std.Build, "addUpdateSourceFiles")) {
true => b.addUpdateSourceFiles(),
false => b.addWriteFiles(),
};
wf.addCopyFileToSource(lib.getEmittedBin(), cfg.output_path);
wf.step.dependOn(&lib.step);
b.getInstallStep().dependOn(&wf.step);
}
In the same directory create lua.zig
:
const std = @import("std");
const ziglua = @import("ziglua");
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
const allocator = gpa.allocator();
const LuaOpaque = opaque {};
const LuaOpaquePtr = *align(@alignOf(ziglua.Lua)) LuaOpaque;
pub fn createLua() !LuaOpaquePtr {
const lua = try ziglua.Lua.init(&allocator);
lua.openLibs();
return @ptrCast(lua);
}
pub fn runLuaCode(opaque_ptr: LuaOpaquePtr, code: [:0]const u8) !void {
const lua: *ziglua.Lua = @ptrCast(opaque_ptr);
try lua.loadString(code);
try lua.protectedCall(0, 0, 0);
}
pub fn freeLua(opaque_ptr: LuaOpaquePtr) void {
const lua: *ziglua.Lua = @ptrCast(opaque_ptr);
lua.deinit();
}
createLua()
creates an instance of the Lua interpreter. The interpreter is returned as an opaque
pointer so that implementation details are hidden from the JavaScipt side.runLuaCode()
makes it
run the given code, casting the opaque pointer it receives back into *Lua
first. freeLua()
frees memory allocated for the interpreter.
To test that our Zig code is working as expected, insert the following code into
src/main/index.js
:
require('node-zigar/cjs')
const { createLua, freeLua, runLuaCode } = require('../../zig/lua.zig')
const lua = createLua()
runLuaCode(lua, 'print "Hello world"')
freeLua(lua)
Note: Do not try to translate the require statements above into ESM import statements. Electron-Vite would just muck everything up when it translates them back into require statements again.
Start Electron-Vite in dev mode
npm run dev
A message should appear informing you that the "lua" module is being compiled. The Electron window will open when that is finished. Behind it, in the terminal window, "Hello world" should appear. That verifies that the interpreter is working.
Now let us provide a proper UI for our interpreter. First, we'll move the freeLua()
call to a
more appropriate place:
app.on('quit', () => freeLua(lua))
Then we're going to make runLuaCode()
accessible from the frontend. Replace the following
line:
ipcMain.on('ping', () => console.log('pong'))
with
ipcMain.on('run', (_, code) => runLuaCode(lua, code))
Finally, we need to redirect text written to stdout to the frontend. In createWindow()
, add the
following line at the bottom:
__zigar.connect({ log: line => mainWindow.webContents.send('log', line) })
And __zigar
to the list of symbols obtain from the module:
const { __zigar, createLua, freeLua, runLuaCode } = require('../../zig/lua.zig')
With the basic plumbing complete, we'll move onto the React frontend. Open
src/renderer/src/App.jsx
and replace its content with the following:
import { useCallback, useEffect, useRef, useState } from 'react';
function App() {
const [ code, setCode ] = useState('')
const [ output, setOutput ] = useState('')
const linesRef = useRef([])
useEffect(() => {
window.electron.ipcRenderer.on('log', (_, text) => {
const lines = linesRef.current
lines.push(...text.split('\n'))
while (lines.length > 200) {
lines.shift()
}
setOutput(lines.join('\n') + '\n')
})
return () => window.electron.ipcRenderer.removeAllListeners('log')
}, [])
const onRunClick = useCallback(evt => window.electron.ipcRenderer.send('run', code), [ code ])
const onCodeChange = useCallback(evt => setCode(evt.target.value), [])
return (
<>
<div className="code-section">
<textarea value={code} onChange={onCodeChange}/>
<button onClick={onRunClick}>Run</button>
</div>
<div className="output-section">
<textarea value={output} readOnly={true} />
</div>
</>
)
}
export default App
Our UI is basically two textareas and a button. When the component mounts, we listen for the log
event from the backend. When the button is clicked, we send the run
event to the backend.
We still need CSS classes for our UI. Open src/renderer/src/assets/main.css
and replace its
content with the following:
@import './base.css';
body {
display: flex;
align-items: center;
justify-content: center;
overflow: hidden;
background-image: url('./wavy-lines.svg');
background-size: cover;
user-select: none;
box-sizing: border-box;
}
#root {
position: absolute;
left: 0.5em;
top: 0.5em;
right: 0.5em;
bottom: 0.5em;
display: flex;
flex-direction: column;
}
.code-section {
flex: 0 0 10em;
display: flex;
flex-direction: row;
width: 100%;
padding: 0.5em 0.5em 0.5em 0.5em;
}
.code-section TEXTAREA {
flex: 1 1 auto;
background-color: transparent;
color: #ffffff;
font-family: 'Courier New', Courier, monospace;
white-space: pre;
}
.code-section BUTTON {
flex: 0 0 auto;
font-size: 1.5em;
font-weight: bold;
text-transform: uppercase;
padding: 0 1em 0 1em;
}
.output-section {
flex: 1 1 auto;
display: flex;
flex-direction: row;
padding: 0.5em 0.5em 0.5em 0.5em;
}
.output-section TEXTAREA {
flex: 1 1 auto;
background-color: transparent;
color: #cccccc;
font-family: 'Courier New', Courier, monospace;
white-space: pre;
}
One final detail is the window title. Open src/renderer/index.html
and change the <title>
tag:
<title>Lua interpretor</title>
And here's the app running a code example from Wikipedia:
Because we're using Electron-Vite in this project, the deployments steps are somewhat different
from previous examples. The basic ideas are the same though. First,
we need to change our require statement so it loads a .zigar
instead:
const { __zigar, createLua, freeLua, runLuaCode } = require('../lib/lua.zigar')
Since our app is running from the out/main
sub-directory, we need to put our library files
in out/lib
. This is the node-zigar.config.json
we need:
{
"optimize": "ReleaseSmall",
"sourceFiles": {
"out/lib/lua.zigar": "zig/lua.zig"
},
"targets": [
{ "platform": "win32", "arch": "x64" },
{ "platform": "win32", "arch": "arm64" },
{ "platform": "win32", "arch": "ia32" },
{ "platform": "linux", "arch": "x64" },
{ "platform": "linux", "arch": "arm64" },
{ "platform": "darwin", "arch": "x64" },
{ "platform": "darwin", "arch": "arm64" }
]
}
Run the following command to generate library files for the desired platforms:
npx node-zigar build
The project is set up to use Electron-Builder. We need to
make certain changes to electron-builder.yml
. First add the following rules to the files
section:
files:
# ...
- '!zig/*'
- '!zig-cache/*'
- '!node-zigar.config.json'
Then add an additional rule to the asarUnpacked
section:
asarUnpack:
# ...
- out/lib/**
And finally, because we want to create packages supporting different CPU architectures, we want
the arch
variable in the package name:
nsis:
artifactName: ${name}-${version}-${arch}-setup.${ext}
dmg:
artifactName: ${name}-${version}-${arch}.${ext}
appImage:
artifactName: ${name}-${version}-${arch}.${ext}
To build for Linux, run the following commands:
npm run build:linux --x64
npm run build:linux --arm64
For Windows:
npm run build:win --ia32
npm run build:win --x64
npm run build:win --arm64
And Mac OS:
npm run build:mac --x64
npm run build:mac --arm64
Note: You can only create a DMG install package on a Mac.
Zig's package manager makes it incredibly easy to make use of C libraries. While this example ultimately relies on the Lua C API, at no point did you need to think about it. There was no autoconf script to run. You didn't need to build any static library. All you had to do is ask Zig to fetch the module from the right URL. Work done by the maintainer of ziglua took care of everything, including issues related to cross-platform support. Using a Zig package is almost as easy as using something from npm.
The Zig package manager is still under heavy development. Currently there aren't so many ready-to-use packages and is no central package directory where you can quickly find something you need. I hope you can see the ease-of-use that it promises though. The ability to easily use native code makes Electron a much more powerful platform.