README.md
1Protocol Buffers - Google's data interchange format
2===================================================
3
4Copyright 2008 Google Inc.
5
6https://developers.google.com/protocol-buffers/
7
8CMake Installation
9-----------------------
10
11To compile or install protobuf from source using CMake, see
12[cmake/README.md](../cmake/README.md).
13
14C++ Protobuf - Unix
15-----------------------
16
17To build protobuf from source, the following tools are needed:
18
19 * bazel
20 * git
21 * g++
22 * Abseil
23
24On Ubuntu/Debian, for example, you can install them with:
25
26 sudo apt-get install g++ git bazel
27
28On other platforms, please use the corresponding package managing tool to
29install them before proceeding. See https://bazel.build/install for further
30instructions on installing Bazel, or to build from source using CMake, see
31[cmake/README.md](../cmake/README.md). See https://github.com/abseil/abseil-cpp
32for instructions on installing Abseil.
33
34To get the source, download the release .tar.gz or .zip package in the
35release page:
36
37 https://github.com/protocolbuffers/protobuf/releases/latest
38
39You can also get the source by "git clone" our git repository. Make sure you
40have also cloned the submodules and generated the configure script (skip this
41if you are using a release .tar.gz or .zip package):
42
43 git clone https://github.com/protocolbuffers/protobuf.git
44 cd protobuf
45 git submodule update --init --recursive
46
47To build the C++ Protocol Buffer runtime and the Protocol Buffer compiler
48(protoc) execute the following:
49
50 bazel build :protoc :protobuf
51
52The compiler can then be installed, for example on Linux:
53
54 cp bazel-bin/protoc /usr/local/bin
55
56For more usage information on Bazel, please refer to http://bazel.build.
57
58**Compiling dependent packages**
59
60To compile a package that uses Protocol Buffers, you need to setup a Bazel
61WORKSPACE that's hooked up to the protobuf repository and loads its
62dependencies. For an example, see [WORKSPACE](../examples/WORKSPACE).
63
64**Note for Mac users**
65
66For a Mac system, Unix tools are not available by default. You will first need
67to install Xcode from the Mac AppStore and then run the following command from
68a terminal:
69
70 sudo xcode-select --install
71
72To install Unix tools, you can install "port" following the instructions at
73https://www.macports.org . This will reside in /opt/local/bin/port for most
74Mac installations.
75
76 sudo /opt/local/bin/port install bazel
77
78Alternative for Homebrew users:
79
80 brew install bazel
81
82Then follow the Unix instructions above.
83
84
85C++ Protobuf - Windows
86--------------------------
87
88If you only need the protoc binary, you can download it from the release
89page:
90
91 https://github.com/protocolbuffers/protobuf/releases/latest
92
93In the downloads section, download the zip file protoc-$VERSION-win32.zip.
94It contains the protoc binary as well as public proto files of protobuf
95library.
96
97Protobuf and its dependencies can be installed directly by using `vcpkg`:
98
99 >vcpkg install protobuf protobuf:x64-windows
100
101If zlib support is desired, you'll also need to install the zlib feature:
102
103 >vcpkg install protobuf[zlib] protobuf[zlib]:x64-windows
104
105See https://github.com/Microsoft/vcpkg for more information.
106
107To build from source using Microsoft Visual C++, see [cmake/README.md](../cmake/README.md).
108
109To build from source using Cygwin or MinGW, follow the Unix installation
110instructions, above.
111
112Binary Compatibility Warning
113----------------------------
114
115Due to the nature of C++, it is unlikely that any two versions of the
116Protocol Buffers C++ runtime libraries will have compatible ABIs.
117That is, if you linked an executable against an older version of
118libprotobuf, it is unlikely to work with a newer version without
119re-compiling. This problem, when it occurs, will normally be detected
120immediately on startup of your app. Still, you may want to consider
121using static linkage. You can configure this in your `cc_binary` Bazel rules
122by specifying:
123
124 linkstatic=True
125
126Usage
127-----
128
129The complete documentation for Protocol Buffers is available via the
130web at:
131
132https://protobuf.dev/
133