#CLI reference

How to drive protoc-gen-tarantool and the sibling protoc-gen-tarantool-doc from protoc.

#Building the plugins

just build           # builds ./protoc-gen-tarantool
just build-doc       # builds ./protoc-gen-tarantool-doc

Or directly:

go build -o protoc-gen-tarantool     ./cmd/protoc-gen-tarantool
go build -o protoc-gen-tarantool-doc ./cmd/protoc-gen-tarantool-doc

Place both binaries on PATH (or pass --plugin= to protoc) and they become available as the tarantool and tarantool-doc outputs.

#protoc-gen-tarantool — the Lua codegen

#Invocation

protoc \
    -I. \
    -Ioptions \
    --tarantool_out=<output_dir> \
    --tarantool_opt=<key>=<value>,<key>=<value> \
    path/to/file.proto

output_dir is the root the plugin writes under. Per-file output path follows the Lua require path (see prefix and (tarantool.lua_package) below).

-Ioptions is needed when any input proto uses the custom (tarantool.lua_package) option — it imports tarantool/tarantool.proto from options/tarantool/.

#--tarantool_opt

Comma-separated key=value pairs:

#prefix

prefix=foo.bar rewrites every generated module name from <orig_path> to foo.bar.<orig_path>. Affects both the require path and the on-disk location.

The Justfile uses this to emit full/ and runtime/ copies side by side for the parametrized test suite:

protoc --tarantool_opt=mode=full,prefix=full         ...   # examples/expected/full/...
protoc --tarantool_opt=mode=runtime,prefix=runtime   ...   # examples/expected/runtime/...

#(tarantool.lua_package) — per-file override

Defined in options/tarantool/tarantool.proto. Overrides the require path for a single .proto:

syntax = "proto3";
package my.app;

import "tarantool/tarantool.proto";
option (tarantool.lua_package) = "myapp.proto.foo";

message Foo { ... }

prefix= and (tarantool.lua_package) compose: prefix is prepended to the final per-file path regardless of which scheme produced it.

#Path-resolution rules

For each input .proto, the plugin picks a Lua require path in this order:

1. option (tarantool.lua_package) = "pkg"; — wins outright. The plugin writes pkg as a /-joined path with _pb.lua appended (or just pkg if pkg already ends in _pb).
2. package declaration + filename — package my.app; and a file foo.proto produce my/app/foo_pb.lua, require('my.app.foo_pb').
3. No package — the filename alone: foo.proto → foo_pb.lua, require('foo_pb').

WKT proto files (google/protobuf/*.proto) are not generated as Lua modules. References to WKT types route to pb.wkt.<Name>_descriptor at codegen time; the runtime side ships them in runtime/pb/wkt.lua.

#What gets emitted

See generated-api.md for the per-message / per-enum / per-service surface. Both modes always emit:

• M.<Msg>_descriptor, M.<Msg>_fields, M.<Msg>_oneofs (when applicable)
• M.<Msg>_new, M.<Msg>_encode, M.<Msg>_decode
• M.<Msg>_decode_lazy, M.<Msg>_text (mode-independent wrappers)
• M.<Msg>_has_<field> / M.<Msg>_clear_<field> (proto3 explicit-optional)
• M.<Enum>_descriptor, M.<Enum> (alias for by_name)
• M.<Service>_service, M.<Service>_client, M.<Service>_server
• EmmyLua / lua-language-server annotations
• Reserved-name table (reserved_names) for the text-format parser

#Stdin/stdout protocol

The plugin reads a CodeGeneratorRequest from stdin and writes a CodeGeneratorResponse to stdout, per protoc's standard plugin interface. It advertises FEATURE_PROTO3_OPTIONAL so protoc surfaces explicit-optional fields; without this flag, protoc omits them.

Proto2 input is rejected at the top of GenerateFile. See codegen.md → proto2 deferral.

#protoc-gen-tarantool-doc — the Markdown reference generator

Same input as the Lua codegen; emits one Markdown file per input .proto summarizing messages, enums, services.

protoc \
    -I. \
    -Ioptions \
    --tarantool-doc_out=<output_dir> \
    path/to/file.proto

Example: examples/docs/hello.md is produced by just gen-docs from examples/proto/hello.proto.

No options today. The output template is minimal:

• Per message: a table of fields (number, name, type, label, description from the leading comment).
• Per enum: a table of values.
• Per service: a table of methods with streaming kind.

Lua call signatures (Foo_encode, Foo_decode_lazy, etc.) are not yet in the doc template — they're documented in generated-api.md for now.

#Driving from make

The Justfile is the canonical entry point for development:

just build         # build the codegen plugin
just build-doc     # build the doc plugin
just gen           # build + regen examples/expected/{full,runtime}/...
just gen-docs      # build-doc + regen examples/docs/hello.md
just test          # run the luatest suite (parametrized over both modes)
just goldens       # regenerate test/interop/fixtures/*.bin via protoc --encode
just bench         # alloc + throughput per op
just jit-trace     # assert hot paths stay on the JIT trace

For end-user projects not using this repo's Makefile, see the planned howto 12: Build integration (protoc, Justfile, buf, CMake recipes).