Quickstart¶
Bitproto comes with a proto-to-code compiler and language-specific libraries.
The compiler parses the bitproto file and generates code files in target languages, which contains the structure definitions, encoding and decoding function entries.
The language-specific libraries provide the underlying serialization implementation. For different languages, it’s required to install the corresponding serialization library to make bitproto work.
This document will introduce how to start with using bitproto.
An example bitproto¶
Suppose that we have a bitproto named pen.bitproto
, with the following content:
proto pen
enum Color : uint3 {
COLOR_UNKNOWN = 0
COLOR_RED = 1
COLOR_BLUE = 2
COLOR_GREEN = 3
}
type Timestamp = int64
message Pen {
Color color = 1
Timestamp produced_at = 2
}
In the bitproto file above:
proto
declares the name of this bitproto, this statement is required for every bitproto.Color
is an enum onuint3
, it occupies 3 bits (meaning its value ranges up to 7).Timestamp
is a custom type defined by user, aliasing to builtin typeint64
, like what the keywordtypedef
does in C.Pen
is a message that contains 2 fields. A message field consists of a type on the left, a following name and a unique field number on the right. Bitproto encodes a message by the order of the field number. So that the field numbers shouldn’t be modified once they are in use.
In bitproto, we can determine how long the encoded buffer will be just from the proto defined,
for instance, the message Pen
will occupy 3 + 64
bits, that’s 9
bytes.
You may want to checkout a larger example on github.
Next, we will introduce how to use bitproto with this simple bitproto file in different languages.