lua-protobuf

# Google protobuf support for Lua

[![Build Status](https://img.shields.io/github/actions/workflow/status/starwing/lua-protobuf/test.yml?branch=master)](https://github.com/starwing/lua-protobuf/actions?query=branch%3Amaster)[![Coverage Status](https://img.shields.io/coveralls/github/starwing/lua-protobuf)](https://coveralls.io/github/starwing/lua-protobuf?branch=master)

English | [中文](https://github.com/starwing/lua-protobuf/blob/master/README.zh.md)

---

This project offers a C module for Lua (5.1, 5.2, 5.3, 5.4, 5.5 and LuaJIT) manipulating Google's protobuf protocol, both for version 2 and 3 syntax and semantics. It splits to the lower-level and the high-level parts for different goals.

For converting between binary protobuf data with Lua tables, using `pb.load()` loads the compiled protobuf schema content (`*.pb` file) generated by Google protobuf's compiler named `protoc` and call `pb.encode()`/`pb.decode()`.

Or use these modules to manipulate the raw wire format in lower-level way:

  - `pb.slice`: a wire format decoding module.
  - `pb.buffer`: a buffer implement that use to encode basic types into protobuf's wire format.  It can be used to support streaming decode protobuf data.
  - `pb.conv`: a module converting integers in the protobuf wire format.
  - `pb.io`: a module access `stdin/stdout` or other files in binary mode.

If you don't want to depend Google's protobuf compiler, `protoc.lua` is a pure Lua module translating text-based protobuf schema content into the `*.pb` binary format.

## Install

To install, you could just use `luarocks`:

```shell
luarocks install lua-protobuf
```

If you want to build it from source, just clone the repo and use luarocks:

```shell
git clone https://github.com/starwing/lua-protobuf
luarocks make rockspecs/lua-protobuf-scm-1.rockspec
```

If you don't have luarocks, use `hererocks` to install Lua and luarocks:

```shell
pip install hererocks
git clone https://github.com/starwing/lua-protobuf
hererocks -j 2.0 -rlatest .
bin/luarocks make lua-protobuf/rockspecs/lua-protobuf-scm-1.rockspec CFLAGS="-fPIC -Wall -Wextra" LIBFLAGS="-shared"
cp protoc.lua pb.so ..
```

Or you can build it by hand, it only has a pure Lua module `protoc.lua` and a pair of C source: `pb.h` and `pb.c`. *Notice* that in order to build the `pb` C module, you need Lua header file and/or libary file installed. replace `$LUA_HEADERS` and `$LUA_LIBS` below to real install locations.

To build it on macOS, use your favor compiler:

```shell
gcc -O2 -shared -undefined dynamic_lookup -I "$LUA_HEADERS" pb.c -o pb.so
```

On Linux, use the nearly same command:

```shell
gcc -O2 -shared -fPIC -I "$LUA_HEADERS" pb.c -o pb.so
```

On Windows, you could use MinGW or MSVC, create a `*.sln` project or build it on the command line (notice the `Lua_BUILD_AS_DLL` flag):

```shell
cl /O2 /LD /Fepb.dll /I "$LUA_HEADERS" /DLUA_BUILD_AS_DLL pb.c "$LUA_LIBS"
```

Or use the bundled `build.bat` to build a release `pb.dll` with MSVC (static CRT, no V