zeekay
91103511be
Rename the Cap'n Proto Lua port to ZAP, brand-neutral throughout: - capnp.lua -> zap.lua, capnp/ -> zap/, *.capnp -> *.zap, compiler bins capnpc-* -> zapc-*, schema/handwritten modules -> *_zap.lua. Zero capnp/Cap'n Proto leftovers in zap-native source/build (upstream-fork Kenton Varda copyright headers in proto/c++.zap and bin/schema.zap stay). Generated-code header and doc links point at github.com/zap-proto/lua and zap-proto.io. Tests now run with no extra install: - Vendor the lunitx test framework (Michael Roth / Doug Currie, MIT) under vendor/ (lunit, lunit.console, lunitx, lunitx.atexit). Its __gc atexit hook drives each test file under LuaJIT and exits nonzero on any failure. - tests/run_tests.sh and test.sh are self-contained (set LUA_PATH incl vendor/), generate proto/example_zap.lua via the `zap` compiler when present, and skip 01/10 with a clear note (never a false pass) when it is absent. 02-util and 03-compile are pure-Lua and always run. - Verified under LuaJIT 2.1: 01(20) + 02(7) + 03(1) + 10(31) = 59 tests pass, 0 failed; runner returns nonzero on an injected failure. Decouple optional cjson so the runtime/compiler load under a bare LuaJIT: - zap/compile.lua loads cjson lazily and only for debug logging (guarded by the debug flag); bin/zapc-llua makes the schema JSON dump optional. Rockspec: bump lua-zap to 0.1.3-4, declare lua-cjson >= 2.1.0, and install the vendored lunitx modules. .gitignore: scope the rockspec-pack ignore to repo root so rockspec/ specs are tracked; ignore the `dump` test artifact. TODO trimmed to the genuinely remaining items (AnyPointer set/decode, packed serialization, schema_zap regeneration, multi-file compile, perf).
2.5 KiB
Docs: ZAP Lua SDK · part of the ZAP Protocol
lua-zap
ZAP is an insanely fast data interchange format and capability-based RPC system.
Lua-zap is a pure lua implementation of ZAP based on LuaJIT.
This project is still under early development and is not production-ready.
Synopsis
Suppose you have a ZAP file called example.zap. You can compile this file like this:
$zap compile -olua example.zap
The default output file is example_zap.lua
local example_zap = require "example_zap"
Check out example/AddressBook.zap and example/main.lua for how to use generated lua file.
Installation
To install lua-zap, you need to install ZAP https://zap-proto.io, LuaJIT http://luajit.org/install.html and luarocks http://luarocks.org/en/Download first.
Currently, lua-zap only works with LuaJIT v2.1. You can install LuaJIT v2.1 using the following commands:
$git clone http://luajit.org/git/luajit-2.0.git
$git checkout v2.1
$make && sudo make install
$sudo ln -sf luajit-2.1.0-alpha /usr/local/bin/luajit
Then you can install lua-zap using the following commands:
$sudo luarocks install lua-zap
Let's compile an example file to test whether lua-zap was installed successfully:
$zap compile -olua proto/example.zap proto/enums.zap proto/lua.zap proto/struct.zap
Normally, you should see no errors and a file named "proto/example_zap.lua" is generated.
How to use
Please see the ZAP Lua SDK guide here.
Testing
The test framework (lunitx) is vendored under vendor/, so no extra install is
needed to run the unit tests:
$tests/run_tests.sh
Tests 01-sanity and 10-encode-decode need the generated module
proto/example_zap.lua. The runner generates it with the zap schema compiler
if one is on PATH; otherwise it skips those two and runs the pure-Lua tests
(02-util, 03-compile). lua-cjson is optional — it is only used for debug
output; install it with luarocks install lua-cjson if you want the schema
dumps.
Limitations
- Currently, lua-zap only works with LuaJIT v2.1. This is because lua-zap needs 64 bit integer support and 64bit number bit operations, but only LuaJIT v2.1 provides a decent way to do all these. I'm working on LuaJIT 2.0/ Lua 5.1 / Lua 5.2 support, hopefully you can use lua-zap with your favorite lua soon.
- ZAP RPC is not implemented yet