src/README.md

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