README.md
1# protozero
2
3Minimalistic protocol buffer decoder and encoder in C++.
4
5Designed for high performance. Suitable for writing zero copy parsers and
6encoders with minimal need for run-time allocation of memory.
7
8Low-level: this is designed to be a building block for writing a very
9customized decoder for a stable protobuf schema. If your protobuf schema is
10changing frequently or lazy decoding is not critical for your application then
11this approach offers no value: just use the C++ API that can be generated with
12the Google Protobufs `protoc` program.
13
14[](https://travis-ci.org/mapbox/protozero)
15[](https://ci.appveyor.com/project/Mapbox/protozero)
16[](https://codecov.io/gh/mapbox/protozero)
17[](https://repology.org/metapackage/protozero)
18
19## Depends
20
21* C++11 compiler
22* CMake
23* Some tests depend on the Google Protobuf library, but use of Protozero
24 doesn't need it
25
26
27## How it works
28
29The protozero code does **not** read `.proto` files used by the usual Protobuf
30implementations. The developer using protozero has to manually "translate" the
31`.proto` description into code. This means there is no way to access any of the
32information from the `.proto` description. This results in a few restrictions:
33
34* The names of the fields are not available.
35* Enum names are not available, you'll have to use the values they are defined
36 with.
37* Default values are not available.
38* Field types have to be hardcoded. The library does not know which types to
39 expect, so the user of the library has to supply the right types. Some checks
40 are made using `assert()`, but mostly the user has to take care of that.
41
42The library will make sure not to overrun the buffer it was given, but
43basically all other checks have to be made in user code!
44
45
46## Documentation
47
48You have to have a working knowledge of how
49[protocol buffer encoding works](https://developers.google.com/protocol-buffers/docs/encoding).
50
51* Read the [tutorial](doc/tutorial.md) for an introduction on how to use
52 Protozero.
53* Some advanced topics are described in an [extra document](doc/advanced.md).
54* There is a table of all types and functions in the
55 [cheat sheet](doc/cheatsheet.md).
56* Read the [upgrading instructions](UPGRADING.md) if you are upgrading from
57 an older version of Protozero.
58
59The build process will also build the Doxygen-based reference documentation if
60you have Doxygen installed. Then open `doc/html/index.html` in your browser to
61read it.
62
63
64## Endianness
65
66Protozero uses a very simplistic test to check the byte order of the system it
67compiles on. If this check is wrong, you'll get test failures. If this is the
68case, please [open an issue](https://github.com/mapbox/protozero/issues) and
69tell us about your system.
70
71
72## Building tests
73
74Extensive tests are included. Build them using CMake:
75
76 mkdir build
77 cd build
78 cmake ..
79 make
80
81Call `ctest` to run the tests.
82
83The unit and reader tests are always build, the writer tests are only build if
84the Google Protobuf library is found when running CMake.
85
86See `test/README.md` for more details about the test.
87
88
89## Coverage report
90
91To get a coverage report set `CXXFLAGS` and `LDFLAGS` before calling CMake:
92
93 CXXFLAGS="--coverage" LDFLAGS="--coverage" cmake ..
94
95Then call `make` as usual and run the tests using `ctest`.
96
97If you are using `g++` use `gcov` to generate a report (results are in `*.gcov`
98files):
99
100 gcov -lp $(find test/ -name '*.o')
101
102If you are using `clang++` use `llvm-cov` instead:
103
104 llvm-cov gcov -lp $(find test/ -name '*.o')
105
106If you are using `g++` you can use `gcovr` to generate nice HTML output:
107
108 mkdir -p coverage
109 gcovr . -r SRCDIR --html --html-details -o coverage/index.html
110
111Open `coverage/index.html` in your browser to see the report.
112
113
114## Clang-tidy
115
116After the CMake step, run
117
118 make clang-tidy
119
120to check the code with [clang-tidy](https://clang.llvm.org/extra/clang-tidy/).
121You might have to set `CLANG_TIDY` in CMake config.
122
123
124## Cppcheck
125
126For extra checks with [Cppcheck](http://cppcheck.sourceforge.net/) you can,
127after the CMake step, call
128
129 make cppcheck
130
131
132## Installation
133
134After the CMake step, call `make install` to install the include files in
135`/usr/local/include/protozero`.
136
137If you are using CMake to build your own software, you can copy the file
138`cmake/FindProtozero.cmake` and use it in your build. See the file for
139details.
140
141
142## Who is using Protozero?
143
144* [Carmen](https://github.com/mapbox/carmen-cache)
145* [Libosmium](https://github.com/osmcode/libosmium)
146* [Mapbox GL Native](https://github.com/mapbox/mapbox-gl-native)
147* [Mapbox Vector Tile library](https://github.com/mapbox/vector-tile)
148* [Mapnik](https://github.com/mapbox/mapnik-vector-tile)
149* [OSRM](https://github.com/Project-OSRM/osrm-backend)
150* [Tippecanoe](https://github.com/mapbox/tippecanoe)
151* [Vtzero](https://github.com/mapbox/vtzero)
152
153Are you using Protozero? Tell us! Send a pull request with changes to this
154README.
155
156
157
){kind=link}
){kind=link}
){kind=link}