From 00b93fd541b1a182799079a2930aad9bb9e16680 Mon Sep 17 00:00:00 2001 From: Eugene Blikh Date: Sun, 17 May 2026 06:36:27 +0300 Subject: [PATCH] docs: install path, prefix= plugin param, int64 migration patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * README: add an "Install" section recommending `tt rocks make` from a local clone until the canonical remote is published, plus a note in the rockspec flagging source.url as aspirational (the URL today resolves to "no such repository"). * README: document the `--tarantool_opt=prefix=` plugin parameter alongside `(tarantool.lua_package)` — the on-disk + require-string semantics and how the two compose were previously only discoverable from main.go and docs/howto/02-module-layout.md. * README: add "Migrating from a Lua proto library that auto-down-casts int64" listing the four places cdata int64 needs a tonumber() wrapper (log format verbs, numeric for-loop bounds, string.format, table keys) and the 2^53 precision caveat. --- README.md | 66 ++++++++++++++++++++++++++++++- tarantool-protobuf-scm-1.rockspec | 6 +++ 2 files changed, 71 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index aa93f0f4efcafcf51ddfc9a61a2854564a08a7d6..3df3bd2d22cc1e2c41d7e4dd484ed151805a4945 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,22 @@ both the binary+JSON and text-format suites passes. | Microbenchmark + alloc regression gate (`just bench`) | ✅ | | proto2 / editions | ❌ deferred (separate slice; see [docs/codegen.md](docs/codegen.md)) | +## Install + +Until the repository is published on its canonical remote, the +`source.url` in `tarantool-protobuf-scm-1.rockspec` is aspirational and +`tt rocks install ` will fail. Install from a local checkout +instead: + +```bash +git clone && cd tarantool-protobuf +tt rocks make tarantool-protobuf-scm-1.rockspec +``` + +That puts the `pb.*` runtime modules under `.rocks/share/tarantool/`. +The Go plugin still has to be built separately — see "Quick start" +below. + ## Quick start ```bash @@ -64,13 +80,30 @@ just test The plugin emits one `.lua` file per `.proto`. By default the output path mirrors the proto package (`package foo.bar; baz.proto` → `foo/bar/baz_pb.lua`), -required as `foo.bar.baz_pb`. Override the Lua module path with a file option: +required as `foo.bar.baz_pb`. Two ways to override: ```proto +// 1. Per-file, via a proto option: import "tarantool/tarantool.proto"; option (tarantool.lua_package) = "myapp.proto.foo"; ``` +```bash +# 2. Plugin-wide, via the `prefix=` plugin parameter. Every generated +# module is prepended with this namespace and cross-file imports rewrite +# to match. Equivalent to applying `option (tarantool.lua_package)` to +# every input file, but without touching the .proto. +protoc --tarantool_out=out \ + --tarantool_opt=prefix=myapp.proto \ + file.proto +# -> out/myapp/proto//_pb.lua, required as +# "myapp.proto.._pb" +``` + +`prefix=` and `(tarantool.lua_package)` compose: when both are set, the +prefix is prepended to the option's value. See +[docs/reference/cli.md](docs/reference/cli.md) for the full mapping. + For a full walk-through that takes a fresh `.proto` to a Tarantool process encoding and decoding it, see **[docs/howto/01-first-message.md](docs/howto/01-first-message.md)**. @@ -114,6 +147,37 @@ Repeated fields are Lua arrays (1-based, contiguous). 64-bit integers `uint64_t` cdata — lossless and the same convention used by Tarantool's `net.box`, `msgpack`, and built-in `protobuf` modules. +### Migrating from a Lua proto library that auto-down-casts int64 + +If you're moving from a library that hands back Lua numbers (silently +losing precision past 2^53), expect a sweep wherever a cdata value +crosses into a primitive that doesn't accept it. The four patterns +that catch out every migrator: + +```lua +local id = msg.user_id -- cdata: uint64_t + +-- 1. log / printf format verbs: %d on cdata raises an error. +log.info('user %d signed in', tonumber(id)) + +-- 2. numeric for-loop bounds: `for i = 1, n` requires a Lua number. +for i = 1, tonumber(msg.row_count) do ... end + +-- 3. string.format with %d / %x: same as log. +local hex = string.format('%016x', tonumber(id)) + +-- 4. table keys: cdata is hashed by identity, not value, so two +-- distinct cdata for the same number won't collide. Either convert +-- to number (if it fits) or use tostring(id) as the key. +cache[tonumber(id)] = row +``` + +`box.tuple` / `net.box` / `msgpack` / Tarantool's `protobuf` all accept +cdata int64 directly — those paths don't need a `tonumber()`. The +boundary is *Lua primitives that expect a number*. Past 2^53 (≈ 9e15), +`tonumber()` silently truncates; if your IDs can be that large, keep +them as cdata or stringify with `tostring(id):gsub('U?LL$', '')`. + **Three API modes live side-by-side.** Same descriptor, three call shapes — the inline (full) generated API is the default, the descriptor-driven runtime API is for dynamic schemas, and the lazy API is a zero-copy view for sparse diff --git a/tarantool-protobuf-scm-1.rockspec b/tarantool-protobuf-scm-1.rockspec index 45e9c087b7df9182cf7e6b08521adc02d296d4aa..f96a01b0f977f13654f8ad3a242fa9cfb8fbda06 100644 --- a/tarantool-protobuf-scm-1.rockspec +++ b/tarantool-protobuf-scm-1.rockspec @@ -1,6 +1,12 @@ package = "tarantool-protobuf" version = "scm-1" +-- NOTE: the canonical public remote is not yet published. The URL below +-- is aspirational (points where the repo will live on sourcecraft.dev). +-- Until then, install from a local clone: +-- tt rocks make tarantool-protobuf-scm-1.rockspec +-- A fresh `tt rocks install` against the URL below will fail with +-- "no such repository" — see README "Install" section. source = { url = "git+https://sourcecraft.dev/bigbes/tarantool-protobuf.git", branch = "master",