Add Wireshark Lua dissector backend
Adds a parallel back end at compiler/back_end/lua/ that turns an Emboss
.emb into a runnable Wireshark Lua dissector. Mirrors the C++ backend's
shape: a py_binary driver, a starlark rule (lua_emboss_library) exposed
from the root build_defs.bzl, a (wireshark)-qualified attribute set, and
golden tests parallel to cpp_golden_test.
Generator highlights:
* One Proto per .emb, one local function per struct/bits, one value
strings table per enum.
* Nested structs dissected via forward-declared dispatch.
* Bit-addressable (`bits`) blocks emitted as masked ProtoFields against
a single container read.
* `--` doc comments become the ProtoField description; `#` hash
comments are ignored.
* Endianness honored via `subtree:add` vs `subtree:add_le`.
Module-level attributes:
* `[(wireshark) protocol: "name"]` name of the generated Proto
* `[(wireshark) root: "Struct"]` which struct dispatches the top
* `[(wireshark) register_on: "..."]` Wireshark-display-filter-style
string of `<table> == <pattern>`
terms separated by `or` / `||`.
Each term becomes a
DissectorTable.get(...):add(...)
call so Wireshark routes packets
from Ethernet/IP/UDP/TCP layers
into the generated dissector.
Struct- and field-level:
* `[(wireshark) filter: "name"]` overrides the auto-generated
Wireshark filter-name segment.
Plumbing:
* New `emboss_lua_library` macro + `lua_emboss_library` rule + aspect
in the root build_defs.bzl, modelled on cc_emboss_library.
* `embossc --generate lua` (in addition to the existing `cc`).
* scripts/regenerate_goldens.py also refreshes the Lua goldens.
Tests:
* compiler/back_end/lua/dissector_generator_test.py — 27 unit tests
covering identifier sanitization, integer-width mapping, register_on
parsing, enum value-strings emission, filter composition, doc-text
extraction, attribute validation, root-struct selection, and nested
struct dispatch.
* lua_golden_test targets in compiler/back_end/lua/BUILD covering
enum, nested_structure, uint_sizes, int_sizes, and the new
wireshark.emb fixture.
Emboss is a tool for generating code that reads and writes binary data structures. It is designed to help write code that communicates with hardware devices such as GPS receivers, LIDAR scanners, or actuators.
Emboss takes specifications of binary data structures, and produces code that will efficiently and safely read and write those structures.
Currently, Emboss only generates C++ code, but the compiler is structured so that writing new back ends is relatively easy -- contact emboss-dev@google.com if you think Emboss would be useful, but your project uses a different language.
If you're sitting down with a manual that looks something like this or this, Emboss is meant for you.
Emboss is not designed to handle text-based protocols; if you can use minicom or telnet to connect to your device, and manually enter commands and see responses, Emboss probably won't help you.
Emboss is intended for cases where you do not control the data format. If you are defining your own format, you may be better off using Protocol Buffers or Cap'n Proto or BSON or some similar system.
In C++, packed structs are most common method of dealing with these kinds of structures; however, they have a number of drawbacks compared to Emboss views:
Emboss does not help you transmit data over a wire -- you must use something else to actually transmit bytes back and forth. This is partly because there are too many possible ways of communicating with devices, but also because it allows you to manipulate structures independently of where they came from or where they are going.
Emboss does not help you interpret your data, or implement any kind of higher-level logic. It is strictly meant to help you turn bit patterns into something suitable for your programming language to handle.
Emboss is currently under development. While it should be entirely ready for many data formats, it may still be missing features. If you find something that Emboss can't handle, please contact emboss-dev@google.com to see if and when support can be added.
Emboss is not an officially supported Google product: while the Emboss authors will try to answer feature requests, bug reports, and questions, there is no SLA (service level agreement).
Head over to the User Guide to get started.